Monad REVM

monad-revm extends revm with Monad-specific execution semantics: gas model changes, repriced precompiles, staking precompile support, and the Monad reserve-balance precompile.

EVM Compatibility

What Monad Changes

Gas model

Monad uses a different cold-access model and no gas refunds.

Repriced precompiles

Bytecode and transaction rules

Staking Precompile (0x1000)

Design overview

Monad staking uses three validator sets and two reward views to keep consensus transitions deterministic:

• execution set: real-time set updated by delegation/undelegation.
• consensus set: top validators selected at snapshot time.
• snapshot set: previous consensus image used during boundary-period rewards.

Validator state is split into:

• Execution state (stake, commission, accumulated_reward_per_token, flags, unclaimed rewards, keys/auth).
• Epoch views (consensus / snapshot stake+commission) used by reward paths.

Delegator state tracks active stake, pending stake windows (delta_stake, next_delta_stake), reward cursor (accRewardPerToken), and linked-list pointers used by getDelegations / getDelegators pagination.

Epoch lifecycle

1. syscallReward(blockAuthor) distributes the per-block reward to the active validator pool.
2. syscallSnapshot() enters boundary mode, copies consensus to snapshot, rebuilds consensus from execution sorted by stake.
3. syscallOnEpochChange(newEpoch) finalizes the transition, updates epoch, and clears boundary mode.

blockAuthor -> validatorId resolution is via ValIdSecp mapping; rewards use consensus view outside boundary and snapshot view during boundary.

Reward accounting

Pool rewards use an accumulator model:

• acc += reward * UNIT_BIAS / active_stake

• Delegator rewards are computed from accumulator deltas.

• Undelegation creates a WithdrawalRequest with an accumulator snapshot.

• (epoch, validator) accumulator snapshots are reference-counted to support delayed withdrawals and epoch-window correctness.

• ACTIVE_VALIDATOR_STAKE = 10_000_000 MON

• MIN_AUTH_ADDRESS_STAKE = 100_000 MON

• WITHDRAWAL_DELAY = 1 epoch

• MIN_EXTERNAL_REWARD = 1e9, MAX_EXTERNAL_REWARD = 1e25

• ACTIVE_VALSET_SIZE = 200

See implementation constants in src/staking/constants.rs.

Staking API surface in monad-revm

Read methods

User write methods

Syscalls

Execution semantics

• Only direct CALL is accepted. DELEGATECALL, CALLCODE, and STATICCALL are rejected.
• Unknown/short selectors route to fallback ("method not supported", 40k fallback cost).
• Read path is dispatch-first for payability, matching C++ behavior (unknown selector fallback bypasses payability guard).
• getDelegator is intentionally treated as a write selector in canonical execution because it settles delegator state via pull_delegator_up_to_date.

Important parity note

monad-revm tracks C++ staking behavior closely, but there are explicit implementation notes to keep in mind:

• addValidator currently skips signature verification and uses simplified key-to-address derivation in write.rs. This is intentional in the current implementation and should be considered when writing integration tests.

How staking is implemented in monad-revm

Core modules:

• src/staking/mod.rs: top-level precompile dispatcher (run_staking_precompile) and read handlers.
• src/staking/write.rs: all user write handlers + syscall handlers + selector/payability logic.
• src/staking/storage.rs: exact storage key derivation for all staking namespaces.
• src/staking/types.rs: validator/delegator/withdrawal/list node types.
• src/staking/interface.rs: ABI definitions and selectors.
• src/staking/constants.rs: gas-independent staking constants.

Block lifecycle helpers:

• src/api/block.rs exposes apply_syscall_reward, apply_syscall_snapshot, apply_syscall_on_epoch_change, and apply_epoch_boundary.
• syscallReward supports extended calldata (selector + blockAuthor + reward) for SystemCallEvm environments that cannot attach msg.value to system calls.

Reader integration path:

• run_staking_with_reader(...) supports environments that do not expose full ContextTr, and is used by alloy-monad-evm integration.

Reserve Balance Precompile (0x1001)

Activation

• Active on MonadNine and above.
• Exposes reserve-balance state during transaction execution.

Solidity interface

interface IReserveBalance {
    function dippedIntoReserve() external returns (bool);
}

• Selector: 0x3a61584e
• Gas: 100

Semantics

• Returns true when the current transaction state would violate Monad reserve-balance rules if execution ended at that point.
• Intended for contracts that want to recover, branch, or revert early before transaction end.

Call restrictions

• Only direct CALL is accepted.
• STATICCALL, DELEGATECALL, and CALLCODE are rejected.
• Calldata must be exactly the 4-byte selector.
• Nonzero msg.value is rejected.

Error behavior matches the canonical Monad implementation:

• Unknown or short selector: "method not supported"
• Nonzero value: "value is nonzero"
• Extra calldata beyond the selector: "input is invalid"

Installation

Add to your Cargo.toml:

[dependencies]
monad-revm = { git = "https://github.com/category-labs/monad-revm", branch = "main" }

Or from crates.io:

[dependencies]
monad-revm = "0.3.0"

Usage

Basic example

use monad_revm::{MonadBuilder, DefaultMonad};
use revm::{
    context::{Context, TxEnv},
    primitives::{TxKind, U256},
    ExecuteEvm,
};

let ctx = Context::monad();
let mut evm = ctx.build_monad();

let tx = TxEnv::builder()
    .caller(caller_address)
    .kind(TxKind::Call(contract_address))
    .value(U256::from(1000))
    .gas_limit(100_000)
    .gas_price(1_000_000_000)
    .build_fill();

let result = evm.transact(tx).expect("Transaction failed");

With inspector

use monad_revm::{MonadBuilder, DefaultMonad};
use revm::{context::Context, inspector::NoOpInspector};

let ctx = Context::monad();
let mut evm = ctx.build_monad_with_inspector(NoOpInspector {});

With custom database

use monad_revm::{MonadBuilder, DefaultMonad};
use revm::context::Context;

let db = MyCustomDatabase::new();
let ctx = Context::monad().with_db(db);
let mut evm = ctx.build_monad();

Architecture

monad-revm/
├── crates/
│   └── monad-revm/
│       └── src/
│           ├── lib.rs
│           ├── chain.rs
│           ├── cfg.rs
│           ├── evm.rs
│           ├── handler.rs
│           ├── instructions.rs
│           ├── journal.rs
│           ├── memory/
│           │   ├── mod.rs
│           │   └── opcodes.rs
│           ├── precompiles.rs
│           ├── reserve_balance/
│           │   ├── abi.rs
│           │   ├── error.rs
│           │   ├── interface.rs
│           │   ├── mod.rs
│           │   └── tracker.rs
│           ├── spec.rs
│           ├── api/
│           │   ├── block.rs
│           │   ├── builder.rs
│           │   ├── exec.rs
│           │   └── default_ctx.rs
│           └── staking/
│               ├── constants.rs
│               ├── mod.rs
│               ├── write.rs
│               ├── abi.rs
│               ├── interface.rs
│               ├── storage.rs
│               └── types.rs
└── Cargo.toml

Feature flags

• serde: Enable serialization for MonadSpecId.
• alloy-evm: Enable integration with alloy_evm::precompiles::PrecompilesMap.

Integration layers

• alloy-monad-evm: Alloy Evm / EvmFactory wrapper over monad-revm.
• monad-foundry: Foundry integration (Forge/Anvil/Cast/Chisel).

References

• Monad opcode pricing
• Monad precompiles
• Monad staking precompile docs

Limitations

• monad-revm is not yet fully compatible with the C++ client for EIP-7702 accounts delegated to Monad-specific precompile addresses (staking and reserve balance), and those calls may succeed locally where the C++ client rejects them.

License

Revm is licensed under MIT License.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, shall be licensed as above, without any additional terms or conditions.