# Engine Paxeer's EVM execution engine, transaction processing, and state transition management. **Source:** `paxeer-network/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 **Source:** `paxeer-network/engine/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 **Source:** `paxeer-network/engine/executor/internal/` Internal execution utilities: - **HostContext:** EVMC host context for evmone integration - **Signer:** Transaction signature verification - **Interpreter:** EVM opcode interpreter wrapper ## Precompiles **Source:** `paxeer-network/engine/executor/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](https://docs.paxeer.app/precompiles) for the full list of Paxeer precompiles (bank, staking, oracle, pointer, etc.). ## Dependencies (xbank, xevm) **Source:** `paxeer-network/engine/deps/` 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 **Source:** `paxeer-network/engine/executor/config/` Executor configuration includes: - **EVM backend:** geth vs evmone - **Chain config:** Chain ID (125), fork heights, EVM rules - **Precompiles:** Custom precompile address map ## Testing **Source:** `paxeer-network/engine/tests/` 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 **Source:** `paxeer-network/engine/executor/utils/` 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](https://docs.paxeer.app/evm) for the full message handling flow. ## Next Steps [Design for Parallel Execution](https://docs.paxeer.app/parallelization) explains how application storage layout affects contention and how to measure a change without confusing gas usage with network throughput. - [Understand the EVM module](https://docs.paxeer.app/evm) - [Review Paxeer precompiles](https://docs.paxeer.app/precompiles) - [Use the JSON-RPC API](https://docs.paxeer.app/json-rpc)