Engine

Overview

The engine package provides EVM transaction execution for Paxeer. It wraps go-ethereum's EVM with Paxeer-specific precompiles, state management, and fee handling. The engine sits between the consensus layer (which orders transactions) and the EVM module (which manages on-chain state).

Executor

The executor is the core EVM execution wrapper. It provides two entry points:

Executor Types

The Executor struct in engine/executor/executor.go supports two backends:

• Geth Executor: Uses go-ethereum's native EVM interpreter
• Evmone Executor: Uses the evmone C++ VM via EVMC bindings for performance

// From engine/executor/executor.go
type Executor struct {
    evm *vm.EVM
}

func NewGethExecutor(blockCtx vm.BlockContext, stateDB vm.StateDB, 
    chainConfig *params.ChainConfig, config vm.Config, 
    customPrecompiles map[common.Address]vm.PrecompiledContract) *Executor

func NewEvmoneExecutor(evmoneVM *evmc.VM, blockCtx vm.BlockContext, 
    stateDB vm.StateDB, chainConfig *params.ChainConfig, config vm.Config, 
    customPrecompiles map[common.Address]vm.PrecompiledContract) *Executor

Transaction Execution

The executor provides two execution modes:

Standard Execution

func (e *Executor) ExecuteTransaction(tx *types.Transaction, 
    sender common.Address, baseFee *big.Int, 
    gasPool *core.GasPool) (*core.ExecutionResult, error)

Standard execution charges gas fees from the sender, executes the transaction, and refunds unused gas. This path is used for direct EVM transaction submission.

Fee-Already-Charged Execution

func (e *Executor) ExecuteTransactionFeeCharged(tx *types.Transaction, 
    sender common.Address, baseFee *big.Int, 
    gasPool *core.GasPool) (*core.ExecutionResult, error)

This mode assumes fees were already charged by the Cosmos SDK ante handler. It skips fee deduction/refund and only increments the sender nonce. This matches how EVM transactions flow through the SDK's msg_server path where the ante handler processes fees separately.

Internal Components

Internal execution utilities:

• HostContext: EVMC host context for evmone integration
• Signer: Transaction signature verification
• Interpreter: EVM opcode interpreter wrapper

Precompiles

Paxeer-specific precompiled contracts are registered with the executor at initialization. The executor passes the customPrecompiles map to the EVM, which routes calls to addresses like 0x00...01, 0x00...02, etc.

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

Dependencies (xbank, xevm)

The engine depends on Cosmos SDK modules via thin wrappers in engine/deps/:

xbank

engine/deps/xbank/ wraps the SDK bank module for balance operations:

• Send: Transfer tokens between accounts
• View: Query balances and supply
• Deferred Cache: Batch balance updates before commit

xevm

engine/deps/xevm/ wraps the EVM module keeper:

• State: EVM storage access (accounts, code, storage slots)
• Code: Contract bytecode storage and retrieval
• Receipt: Transaction receipt generation
• Address: Cosmos ↔ EVM address association
• Nonce: Account nonce management
• Fee: Gas price and fee collection
• Coinbase: Block reward recipient
• Precompile: Precompile address registration

Configuration

Executor configuration includes:

• EVM backend: geth vs evmone
• Chain config: Chain ID (125), fork heights, EVM rules
• Precompiles: Custom precompile address map

Testing

The engine includes comprehensive test suites:

• State Tests: state_test.go runs Ethereum state transition tests
• Harness: tests/harness/ provides test fixtures and builders
• Giga Test: giga_test.go for large-scale execution

Chain ID

The chain configuration maps the Cosmos identifier hyperpax_125-1 to EVM chain ID 125. Transactions on that network must use chain ID 125 for EIP-155 replay protection. Unknown Cosmos identifiers use the separate development fallback chain ID and must not be treated as Paxeer mainnet.

Utilities

Shared utilities for address conversion, gas calculation, and result formatting.

Integration with EVM Module

The engine is invoked by the EVM module's msg_server when processing MsgEthereumTx messages. The flow is:

1. Consensus orders transactions in a block
2. ABCI DeliverTx routes MsgEthereumTx to the EVM module
3. EVM module's ante handler charges fees
4. EVM module calls ExecuteTransactionFeeCharged on the engine
5. Engine executes EVM bytecode against the state DB
6. EVM module generates receipt and emits events

See EVM Module documentation for the full message handling flow.

Next Steps

Design for Parallel Execution explains how application storage layout affects contention and how to measure a change without confusing gas usage with network throughput.

• Understand the EVM module
• Review Paxeer precompiles
• Use the JSON-RPC API