EVM Module

Overview

The EVM module (modules/evm/) provides full Ethereum Virtual Machine execution on Paxeer. It runs as a Cosmos SDK module and integrates with the execution engine to process EVM transactions with chain ID 125.

The module handles:

• EVM Transaction Processing: Execute Ethereum-format transactions
• Address Association: Map Cosmos bech32 addresses to EVM hex addresses
• Receipt Generation: Create transaction receipts with logs and status
• Pointers: Link ERC-20 tokens to native Cosmos denoms
• Precompiles: Expose Cosmos modules via EVM precompiled contracts

Message Types

The EVM module handles MsgEVMTransaction, which wraps a standard Ethereum transaction:

• Legacy transactions (type 0)
• EIP-2930 access list transactions (type 1)
• EIP-1559 dynamic fee transactions (type 2)

Transactions are submitted via the JSON-RPC eth_sendRawTransaction endpoint or the Cosmos SDK MsgEVMTransaction message.

Address Association

Paxeer addresses exist in two formats:

• Cosmos: pax1... (bech32)
• EVM: 0x... (hex, 20 bytes)

The EVM module maintains a bidirectional mapping between these formats. When a Cosmos account sends an EVM transaction, the module associates its pax1... address with the derived 0x... address. This allows:

• Cosmos accounts to interact with EVM contracts
• EVM accounts to interact with native Cosmos denominations
• Unified balance queries across both address formats

State Management

The EVM module stores:

• Accounts: Nonce, balance (via bank module)
• Code: Contract bytecode (keeper/code.go)
• Storage: Contract storage slots (keeper/state.go)
• Receipts: Transaction receipts and logs (keeper/receipt.go)

EVM state is stored in the module's KVStore. Account balances are managed by the bank module to maintain consistency with native token operations.

Transaction Execution Flow

When an EVM transaction is submitted:

1. RPC receives eth_sendRawTransaction or SDK receives MsgEVMTransaction
2. Ante decorators under modules/evm/ante/ validate signatures, nonces, and transaction fees
3. Msg server routes to EVM module
4. Module calls engine executor with ExecuteTransactionFeeCharged
5. Executor runs EVM bytecode against state DB
6. Module generates receipt (keeper/receipt.go) with logs, gas used, status
7. Module emits events for indexing

Receipts

Transaction receipts include:

• Status: 1 (success) or 0 (revert)
• Gas Used: Total gas consumed
• Logs: Event logs emitted during execution
• Contract Address: For contract creation transactions
• Bloom Filter: For efficient log filtering

Execution stages receipts in a transient store and flushes them to the configured receipt store. GetReceipt delegates to that store; JSON-RPC exposes them through eth_getTransactionReceipt.

Pointers

Pointers are a Paxeer-specific feature that links ERC-20 token contracts to native Cosmos denoms. A pointer allows:

• ERC-20 transfer to move native tokens via bank module
• Native token transfers to appear as ERC-20 events
• Unified balance view across EVM and Cosmos APIs

Pointer contracts are deployed via the pointer precompile.

Precompile Integration

The EVM module registers custom precompiled contracts that expose Cosmos SDK modules to EVM callers. Paxeer-specific addresses are registered by the precompile package, including bank at 0x1001 and address conversion at 0x1004. Standard Ethereum precompiles occupy a separate address range.

See Precompiles documentation for the full list of Paxeer precompiles (bank, staking, oracle, IBC, etc.).

Fee Collection

EVM transaction fees are:

• Charged in PAX (native gas token)
• Reported using receipt gas usage and the effective gas price; estimation and charge settlement depend on the configured execution path
• Sent to the fee collector module
• Distributed to validators and stakers

EIP-1559 dynamic fees are supported with baseFee and priority fees.

Coinbase

The EVM block context sets COINBASE to the fee collector module’s associated EVM address through GetFeeCollectorAddress.

Chain ID

Paxeer uses EVM chain ID 125. This must match the chainId field in EIP-155 transaction signatures for replay protection. The Cosmos chain identifier is hyperpax_125-1.

Configuration

EVM module parameters include:

• Native units: PAX is the display currency; the implementation retains uhpx as its Cosmos base denomination and converts it to 18-decimal EVM units
• Fee bounds: Minimum and maximum fees per gas, target block gas, and dynamic adjustment parameters
• Storage gas: The default SSTORE set cost is 20,000 gas. Query the network’s EVM parameters when calculating costs for a deployment
• Chain Config: Fork activation times, including Cancun and Prague, and a configurable SSTORE cost

Genesis

Genesis state for the EVM module includes:

• Module parameters
• Pre-deployed contract code and storage
• Address associations

Logging

EVM event logs are emitted during transaction execution via the LOG0, LOG1, LOG2, LOG3, LOG4 opcodes. Logs are included in receipts and indexed for querying via eth_getLogs.

Deferred Operations

Some EVM operations (like balance updates from precompiles) are deferred and batched for commit. This avoids redundant state writes during execution and improves performance.

Next Steps

• Use the JSON-RPC API
• Explore Paxeer precompiles
• Deploy contracts