> For the complete documentation index, see [llms.txt](https://docs.bitplanet.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitplanet.ai/advanced-topics/blockchain-architecture/evm-compatibility.md).

# EVM Compatibility

Bitplanet integrates the Ethereum Virtual Machine (EVM) through BitEVM to enable full Ethereum smart contract compatibility. This page explains how the EVM layer works within Bitplanet's architecture.

## What is BitEVM?

BitEVM is Bitplanet's implementation of EVM compatibility, built on top of Cosmos EVM v1.0.0-rc2. It provides:

* Full Ethereum smart contract compatibility
* Web3 JSON-RPC API support
* Integration with BitSDK modules
* Custom precompiles for BitSDK-EVM interoperability

## EVM Integration Architecture

Bitplanet implements a complete EVM execution environment through the `x/vm` module (BitEVM), providing Ethereum compatibility while leveraging BitSDK infrastructure.

### How It Works

```
Ethereum Transaction → JSON-RPC (8545) → EVM Module → State Execution → BitSDK State
```

**Key Components:**

**EVM Execution Engine**

* Processes Ethereum bytecode
* Executes smart contract operations
* Manages contract state transitions

**State Mapping**

* EVM state stored in BitSDK KVStore
* Ethereum accounts mapped to Cosmos accounts
* Contract storage persisted in module store

**Transaction Bridge**

* Converts Ethereum transactions to Cosmos messages
* Handles both EIP-1559 and legacy transaction formats
* Routes transactions through BitSDK ante handlers

## Transaction Processing

### Ethereum Transaction Flow

1. **Submission**: User submits transaction via JSON-RPC (port 8545)
2. **Conversion**: Transaction converted to BitSDK message
3. **Validation**: AnteHandler validates signature and deducts fees
4. **Execution**: EVM executes bytecode against current state
5. **Commitment**: State changes committed to BitSDK store

### Supported Transaction Types

**EIP-1559 Dynamic Fee Transactions**

```
maxFeePerGas + maxPriorityFeePerGas
```

**Legacy Transactions**

```
gasPrice
```

**EIP-2930 Access List Transactions**

```
Pre-declared storage access for gas optimization
```

## State Management

### Account Model

Bitplanet uses the Ethereum account model:

```
Account {
  nonce:   uint64
  balance: uint256
  code:    bytes (for contracts)
  storage: map[bytes32]bytes32
}
```

### Storage Layer

**EVM State Storage:**

```
x/vm store
├── Accounts (address → account data)
├── Code (address → bytecode)
└── Storage (address + key → value)
```

**State Root:**

* Merkle tree of all EVM state
* Enables state proofs for light clients
* Consistent with BitSDK state commitment

### Address System

**Format:** 20-byte Ethereum addresses (0x...)

**Conversion:**

* Ethereum hex: `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb`
* Cosmos bech32: `cosmos142dvx7xxnsx2n2jfke9wvdz9ew4ahr7slnxtfr`

The chain automatically converts between formats as needed.

## Gas Mechanics

### Gas Model

Bitplanet implements Ethereum gas metering with custom modifications:

**Standard Opcodes:** Use Ethereum gas costs

**Modified Opcodes:**

* `CREATE` / `CREATE2`: 10× standard cost
* `CALL`: 10x standard cost
* `SSTORE`: Fixed 500 gas

**Reason:** Optimized for BitSDK state writes and prevent spam

### Fee Market

**EIP-1559 Implementation:**

```
baseFee: Dynamically adjusted per block
priorityFee: User-specified tip for validators
effectiveGasPrice = min(maxFeePerGas, baseFee + priorityFee)
```

**Fee Distribution:**

* Base fee: Burned (deflationary)
* Priority fee: Goes to validators
* Compatible with standard Ethereum fee estimation

## EVM Version and Opcodes

### Supported EVM Features

**Opcode Support:** Full Ethereum opcode compatibility

**Precompiled Contracts:**

* Standard Ethereum precompiles (`0x01`-`0x09`)
* Custom BitSDK precompiles (`0x0800`-`0x0805`)

**Smart Contract Standards:**

* ERC-20, ERC-721, ERC-1155
* All OpenZeppelin contracts
* Complex DeFi protocols (Uniswap, etc.)

### Contract Upgradeability

Bitplanet implements UUPS (Universal Upgradeable Proxy Standard) for contract upgrades:

**Architecture:**

* **User** → Proxy Contract (holds state) → Implementation Contract (holds logic)

**Key Components:**

* **Proxy Contract**: Stores all state and delegates calls to implementation
* **Implementation Contract**: Contains business logic, replaceable via governance
* **Upgrade Function**: Protected by access control, enables logic updates

**Benefits:**

* Preserve user balances and state during upgrades
* Fix bugs without redeploying entire system
* Add new features to existing contracts
* Maintain same contract addresses for users

**Used By:**

* GemCoreNFT Factory (Core/Gem token operations) - see [**Core Tokens**](/advanced-topics/token-economics-technical/core-tokens.md) and [**Gem Tokens**](/advanced-topics/token-economics-technical/gem-tokens.md)
* ERC20/ERC1155 token contracts
* Future protocol upgrades

### BitSDK Precompiles

Special precompiled contracts that bridge EVM to BitSDK:

```
0x0800 - Staking
0x0801 - Distribution
0x0802 - IBC Transfer
0x0804 - Bank
0x0805 - Governance
```

These enable smart contracts to interact with native BitSDK functionality.

## JSON-RPC Interface

### Available Endpoints

Bitplanet exposes standard Ethereum JSON-RPC on port 8545:

**Transaction Methods:**

* `eth_sendTransaction`
* `eth_sendRawTransaction`
* `eth_call`
* `eth_estimateGas`

**Query Methods:**

* `eth_getBalance`
* `eth_getCode`
* `eth_getStorageAt`
* `eth_getTransactionReceipt`

**Block Methods:**

* `eth_blockNumber`
* `eth_getBlockByNumber`
* `eth_getBlockByHash`

### WebSocket Support

Real-time event streaming on port 8546:

* Block subscriptions
* Transaction subscriptions
* Log subscriptions (contract events)

## Key Differences from Ethereum

### Consensus Layer

**Ethereum:** Proof of Stake with probabilistic finality **Bitplanet:** CometBFT consensus with instant finality

**Impact:**

* Transactions are final immediately (no reorgs)
* Block time is deterministic (\~6 seconds)
* No uncle blocks or chain reorganizations

### Block Structure

**Ethereum Block:**

```
Block {
  header: {...}
  transactions: [...]
  uncles: [...]
}
```

**Bitplanet Block:**

```
Block {
  header: {...}
  transactions: [...] (both Cosmos and EVM txs)
  evidence: [...] (validator misbehavior)
}
```

Bitplanet blocks can contain both EVM transactions and native BitSDK transactions.

### State Persistence

**Ethereum:** LevelDB/RocksDB with separate state trie **Bitplanet:** BitSDK KVStore with IAVL tree

EVM state is stored within the BitSDK state tree, enabling:

* Unified state commitment
* IBC state proofs
* BitSDK querying of EVM state

## Token Bridge

### Native Coin ↔ ERC-20 Conversion

The `x/erc20` module enables bidirectional conversion:

**Cosmos Coin → ERC-20:**

```
Native bplcoin → ERC-20 wrapped token on EVM
```

**ERC-20 → Cosmos Coin:**

```
ERC-20 token → Native coin in bank module
```

This allows seamless interaction between:

* BitSDK modules (staking, governance)
* EVM smart contracts
* Cross-chain IBC transfers

### BeaconFactory Pattern

Efficient multi-token deployment using beacon proxy architecture:

**Architecture:**

* **BeaconFactory**
  * Beacon (points to implementation)
    * Implementation Contract (shared logic)
  * Proxy 1 (AI\_1 tokens) → Beacon
  * Proxy 2 (AI\_2 tokens) → Beacon
  * Proxy 3 (AI\_3 tokens) → Beacon
  * ... (unlimited proxies)

**Deployment Flow:**

1. Deploy Implementation (once)
2. Deploy Beacon pointing to Implementation (once)
3. For each new AI token:
   * Factory.deploy() → new Proxy (minimal bytecode)

**Gas Savings:**

* **Traditional**: \~2.5M gas per full ERC20 deployment
* **BeaconProxy**: \~200K gas per proxy deployment
* **Savings**: \~90% reduction in deployment costs

**Benefits:**

* **Batch Upgrades**: Update beacon → all proxies upgraded
* **Gas Efficient**: Minimal proxy bytecode (\~200 bytes)
* **Unlimited Tokens**: Deploy thousands of AI tokens economically - see [**Gem Tokens**](/advanced-topics/token-economics-technical/gem-tokens.md)
* **Consistent Logic**: All tokens share same validated implementation

### Precision Banking

The `x/precisebank` module handles fractional token amounts:

* EVM uses 18 decimals (wei)
* BitSDK uses 6 decimals (micro)
* Precise tracking prevents rounding errors

## Integration Benefits

### Ethereum Compatibility

**For Developers:**

* Use familiar Ethereum tools (MetaMask, Hardhat, Foundry)
* Deploy existing Solidity contracts without modification
* Access standard libraries (ethers.js, web3.js)

**For Smart Contracts:**

* Full EVM bytecode compatibility
* All Solidity features supported
* Standard precompiles available

### BitSDK Features

**Additional Capabilities:**

* Instant transaction finality
* Access to BitSDK modules via precompiles
* IBC cross-chain communication
* On-chain governance for chain parameters

### Hybrid Architecture

Smart contracts can:

* Call BitSDK functions (staking, governance)
* Interact with IBC for cross-chain transfers
* Use both EVM and Cosmos state
* Benefit from both ecosystems