EVM execution on shared state

EVM contracts execute through CuEVM and publish their accepted effects into Singularity's common account state. They do not own a separate Ethereum database. Ethereum-shaped transactions and receipts are useful integration surfaces, but native-value representation, host calls, execution limits, and engine availability impose concrete compatibility boundaries.

A counter contract illustrates the path: a signed Ethereum transaction identifies the caller, the adapter loads code and storage from shared accounts, CuEVM computes the result, and the outer transaction stages the accepted storage change. A later local cross-VM call reads that journaled value. Composition workflow.

For exact RPC request and receipt shapes, use RPC and SDK contracts; for an existing signature after a timeout, use transaction inspection. This chapter follows the engine and shared-state mechanism.

Authenticate the Ethereum envelope

The native EVM instruction carries the complete raw Ethereum envelope. Its lookup hash is Keccak-256 of those bytes, including a typed discriminator when present. The decoder accepts legacy EIP-155 and typed transactions 0x01, 0x02, and 0x03; exact RLP framing and sender recovery are required.

The execution boundary repeats chain-id and nonce checks even for transactions arriving outside Ethereum RPC. It requires chain ID 17743, or 0x454f, rejects pre-EIP-155 legacy signatures, and requires the signed nonce to equal the latest visible sender nonce. The lookup checks the transaction changeset and ordered journal before base state, so consecutive transactions cannot all reuse a stale nonce. Admission, decoder.

Typed fee fields and retained blob metadata do not establish Ethereum fee-market economics or blob data availability. Gas is still an execution budget. The node caps declared transaction gas at 30 million, rejects values outside its supported integer range, and charges intrinsic execution cost before the body. Exact fee and limit semantics belong in fees and limits.

Represent Ethereum state without losing account ownership

These are domain-separated mappings, not reversible truncations. The helper projecting a public key to its last 20 bytes is not the inverse of the hashed EVM address mapping. An application must use the appropriate identity conversion rather than assume visually similar addresses share a balance. Key derivation, nonce codec and state adapter.

The adapter buffers dirty account, code, and storage updates. It can read through transaction and same-block views, then merge through the enclosing changeset. Directly publishing a completed child call to the base database would bypass parent rollback and cross-VM authorization.

CuEVM is the canonical engine

execute_v2 selects CuEVM for canonical execution and RPC simulation. Simulation differs in publication policy: its adapter is discarded. Disabled and shadow modes fail instead of invoking a CPU or PTX fallback. Names such as GevmCanonical and GevmBridge remain in implementation types; they do not select a second production engine. Mode contract.

Interactive state flow

The GPU ABI receives an explicit working set. It cannot discover a hashed storage slot's prestate by enumerating the account database, so the host uses demand paging:

1. Seed the caller and call target, or predicted deployment address.
2. Execute with access logging against fresh supplied state.
3. Add newly discovered addresses and slots from the ordered adapter view.
4. Repeat until the read set is stable.
5. Validate and stage only the converged result.

Early passes can read zero for an undeclared slot and therefore take a different branch. They are discovery passes, not accepted state transitions. The loop is bounded at 16 passes; nonconvergence returns an error without staging partial body writes. A process-wide lock covers the entire session because the native ABI uses global state and output buffers. Locking individual launches would still permit a concurrent RPC simulation to replace state between passes. Paging and locking.

Native-value support has a precise limit

Top-level CALL and CREATE can move representable native value. The host checks actual available lamports, stages an equal debit and credit, and preserves the recipient's nonce. Value must be a whole multiple of 1,000,000,000 wei and fit the u64 lamport range. Sub-lamport dust is rejected, not rounded away.

CuEVM receives synthetic balance headroom to satisfy its internal nonzero base-fee affordability rule. That headroom is never authoritative money. The host reconstructs the top-level transfer from real state rather than copying inflated device balances back. Value reconstruction.

Inner-frame native-value movements remain unsupported by this path. The host checks every exported account, including the caller and target, against the expected top-level balance change. A nested CALL that sends value back to the original caller is still an unsupported movement. Non-value storage/code/nonce effects have separate handling; do not generalize this restriction to every nested call. Inner-value guard.

For a contract that forwards native currency internally, this is an adoption blocker even if compilation, deployment, and a read-only call succeed. A token-storage transfer has different semantics and must be validated against its own execution and host-interface path.

Failures, nonces, and receipts

An explicit EVM REVERT retains its return bytes and a reverted flag. Out-of-gas, invalid opcode, host rejection, and engine defects are different outcomes. Failed body execution does not publish body storage or logs.

Included executed failures consume replay-protection nonce through the appropriate outer transaction/deployment path. Malformed envelopes, wrong chain IDs, nonce mismatch, unavailable engines, and other boundary errors must not be inferred to have produced a normal EVM receipt. When debugging, inspect both the outer transaction result and the EVM receipt projection.

Successful logs preserve committed frame-execution order. Export must be complete:

• Code-pool overflow rejects incomplete code.
• Account-export overflow rejects missing accounts; a missing capability signal also rejects an old native library.
• Committed log capture beyond 256 events or 4,096 bytes per event becomes an executed failure, rather than a truncated authoritative receipt.

The log-overflow path discards body effects and logs while preserving replay protection. Result validation. Receipt indexing and Ethereum-shaped views for non-EVM transactions are explained in RPC and SDK contracts.

Precompiles are an interface boundary

The runtime implements standard cryptographic precompiles and an interoperability range. The latter assigns 0x0100 through 0x0107 to the SVM bridge, System Program, token projection, associated token accounts, agent trigger, native bridge, HILSA read, and HILSA outbox respectively. Address registry.

A top-level target intercepted by the host is not evidence that every nested CALL-family instruction can suspend the GPU and invoke that same host service. Check the actual call path and activation requirement. HILSA outbox address registration, for example, does not remove its consensus activation gate. Use HILSA integration contracts before depending on it.

Build and test the real boundary

The cuevm feature is distinct from the historical, non-default gpu-evm PTX feature. The native dependency is libcuevm_state.so. Its build script resolves CUEVM_LIB_DIR, defaulting to /home/naman/CuEVM/build_state; CUDA_LIB_DIR defaults to /usr/local/cuda/lib64. If the shared library is absent, the FFI crate can build a stub. A successful Cargo build therefore does not establish that ordinary EVM execution is available. FFI build contract.

For an existing correctly linked GPU test artifact, the useful fixtures are cuevm_canonical_path, cuevm_value_transfer, and composition_kernel_cuevm. They cover SSTORE success/revert, simulation isolation, representable value, inner-value rejection, and cross-runtime rollback. Decoder and adapter unit tests cover useful CPU-only boundaries. These fixtures were inspected during this run; no expensive GPU/Cargo suite was executed.

Validate your contract against the exact engine/library and deployment combination you intend to use. The availability reference records the inspected release and live endpoint separately.