Monad REVM

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

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.

Constants (current MONAD_EIGHT implementation):

• 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:

• The Rust implementation currently targets MONAD_EIGHT constants.
• 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.

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.1"

Usage

Basic example

use monad_revm::{MonadBuilder, DefaultMonad};
use revm::{
    context::{Context, TxEnv},
    database::InMemoryDB,
    ExecuteEvm,
};

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

let tx = TxEnv::builder()
    .caller(caller_address)
    .to(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
│           ├── spec.rs
│           ├── cfg.rs
│           ├── handler.rs
│           ├── instructions.rs
│           ├── precompiles.rs
│           ├── evm.rs
│           ├── api/
│           │   ├── block.rs
│           │   ├── builder.rs
│           │   ├── exec.rs
│           │   └── default_ctx.rs
│           └── staking/
│               ├── 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

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.