# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitplanet.ai/advanced-topics/blockchain-architecture/evm-compatibility.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.