The Monorepo for OP Stack Types, Components, and Services built in Rust.

Changes vs facet-kona • What's Kona? • Overview • MSRV • Contributing • Credits • License

Note

This repo is a fork configured for Ethscriptions mainnet (chain id 0xeeee). See ETHSCRIPTIONS_MAINNET.md for chain-specific derivation rules, rollup config, and verification commands.

Changes vs facet-kona

This repo is a fork of facet-kona intended to prove/verify the Ethscriptions app-chain (not a general-purpose rollup).

Reference points (so “what changed” is well-defined):

• Facet fork HEAD: facet-kona@984a239484469aa598d284ca44da1723c8d41ed1
• This fork HEAD: ethscriptions-kona@9a0e542bc0d42e2340d375113a49e0c255babc3c

A) Ethscriptions-specific behavior changes (functional)

Facet-kona implements the standard OP Stack derivation pipeline (batch inbox → channels → frames → batches → attrs). Ethscriptions mainnet does not use a batch inbox; it derives blocks directly from L1 receipts/logs, producing:

• exactly one “L1 info” deposit tx per L2 block, plus
• zero or more Ethscriptions deposit txs (type 0x7d) to the Ethscriptions predeploy.

Ethscriptions mainnet parameters used by this fork (these do not exist in facet-kona):

• L2 chain id: 0xeeee (decimal 61166)
• L1 genesis block: 17478949
• Rollup config: configs/ethscriptions-mainnet-rollup.json
• L1 RPC (required): <L1_RPC> (bring your own; archive recommended)
• L2 RPC (verification default): https://mainnet.ethscriptions.com/

Scope difference vs facet-kona:

• This fork targets post-import / current chain behavior only (no historical ESIP/fork replay).

Concrete code-level differences:

1. New Ethscriptions derivation stage (no batch inbox)

• Added crates/protocol/derive/src/stages/ethscriptions.rs and wired it into the pipeline selection in crates/protocol/derive/src/stages/mod.rs.
• Updated the stateful attributes builder to support an Ethscriptions “epoch selection” rule (advance epoch when next_l2_time >= next_l1_time, otherwise produce filler blocks) in crates/protocol/derive/src/attributes/stateful.rs.

2. New Ethscriptions deposit derivation (type 0x7d, Ethscriptions predeploy)

• Added crates/protocol/derive/src/helpers/ethscriptions_deposits.rs (and module plumbing in crates/protocol/derive/src/helpers/mod.rs).
• Implemented derivation from L1 transactions/receipts:
  • Create: calldata data: URI (and gzip-wrapped data: URIs), and ESIP-3-style Create events.
  • Transfer: calldata bytes32 IDs (ESIP-5 batch form supported) and ESIP-1/ESIP-2 Transfer events.
  • Source hash: computed from L1 blockHash, selector, and either tx index or global log index (RPC logIndex semantics).
  • Envelope support: handles modern L1 tx types (notably EIP-7702 / type 0x04) so transfers aren’t missed.
• Ethscriptions deposit txs target 0x3300000000000000000000000000000000000001 with gas limit 1_000_000_000.

3. Ethscriptions protocol support (only what Ethscriptions chain uses)

• Added crates/protocol/derive/src/helpers/ethscriptions_protocol.rs to parse protocol “op” payloads from either:
  • JSON bodies, or
  • header params (p=...&op=...&d=<base64(json)>)
• Supported protocol families:
  • erc-20-fixed-denomination (deploy/mint)
  • erc-721-ethscriptions-collection (collection operations)

4. Chain config + derivation parity tooling

• Added configs/ethscriptions-mainnet-rollup.json and documented the chain parameters in ETHSCRIPTIONS_MAINNET.md.
• Added derivation-vs-live comparator example examples/ethscriptions-derivation-compare and wrapper scripts/compare_derivation.sh.
• Added a reproducible sampling suite scripts/verify_ethscriptions_mainnet_sample.sh and a full STF validation suite in VALIDATION_SUITE.md + scripts/validate*.sh.

5. Executor/provider hardening needed for Ethscriptions mainnet parity

• Providers: crates/providers/providers-alloy/src/chain_provider.rs falls back to per-tx receipts when eth_getBlockReceipts isn’t supported by the RPC.
• Executor validation harness: crates/proof/executor/src/test_utils.rs contains Ethscriptions chain handling so fixtures can be validated against https://mainnet.ethscriptions.com/.

B) Dependency + repo-structure changes (mechanical but important)

These are “what changed” vs facet-kona even when not Ethscriptions-specific:

1. Vendored patched dependencies for 0x7d deposits

• Added vendor/op-alloy and vendor/revm and switched Cargo.toml [patch.crates-io] to path patches.
• Added [workspace].exclude = ["vendor/*"] to keep the monorepo workspace clean.
• Path patches in Cargo.toml cover:
  • op-alloy-{network,provider,consensus,rpc-types,rpc-jsonrpsee,rpc-types-engine}
  • revm, op-revm, and the revm-* crate family used by revm/op-revm
• Patched the vendored crates’ Cargo.toml files to set package.workspace = ... so *.workspace = true dependency inheritance continues to work inside this monorepo:
  • vendor/op-alloy/crates/{consensus,network,op-alloy,provider,rpc-jsonrpsee,rpc-types,rpc-types-engine}/Cargo.toml → workspace = "../.."
  • vendor/revm/crates/{bytecode,context,handler,inspector,interpreter,optimism,precompile,primitives,revm,state}/Cargo.toml → workspace = "../.."
  • vendor/revm/crates/{context/interface,database/interface}/Cargo.toml → workspace = "../../.."

2. Version/toolchain pinning vs facet-kona

• MSRV (rust-version): 1.86 → 1.85
• Alloy family: 1.0.x → 0.15.x (see Cargo.toml [workspace.dependencies])
• OP Alloy: 0.18.x → 0.15.4 (then patched via vendor/op-alloy)
• revm/op-revm: 24.x/5.x → 22.x/3.x (then patched via vendor/revm)
• Removed reth-* pins (they were only required by facet-kona’s supervisor storage crate)
• Binaries: kona-host/kona-client 1.0.2 → 1.0.1

3. Node/supervisor crate layout changes vs facet-kona

• Removed the standalone peers crate (crates/node/peers/*) and replaced it with an in-crate module tree under crates/node/p2p/src/peers/*.
• Removed crates/utilities/macros/* and replaced it with crates/node/macros/* (and updated call sites accordingly).
• Removed supervisor storage/types crates (crates/supervisor/storage/*, crates/supervisor/types/*) and their transitive reth pinning from the workspace.

4. Removed facet-kona-only files/tooling

• Removed USER_SEQUENCED_TRANSACTIONS_PLAN.md and the tests/ harness directory from facet-kona.
• Renamed/reshaped justfile → Justfile (and similarly in crates/protocol/registry/).
• Removed mise.toml.

What's Kona?

Originally a suite of portable implementations of the OP Stack rollup state transition, Kona has been extended to be the monorepo for OP Stack types, components, and services built in Rust. Kona provides an ecosystem of extensible, low-level crates that compose into components and services required for the OP Stack.

The book contains a more in-depth overview of the project, contributor guidelines, tutorials for getting started with building your own programs, and a reference for the libraries and tools provided by Kona.

Overview

Note

Ethereum (Alloy) types modified for the OP Stack live in op-alloy.

Binaries

• client: The bare-metal program that executes the state transition, to be ran on a prover.
• host: The host program that runs natively alongside the prover, serving as the Preimage Oracle server.
• node: [WIP] A Rollup Node implementation, backed by kona-derive.
• supervisor: [WIP] A Supervisor implementation.

Protocol

• genesis: Genesis types for OP Stack chains.
• protocol: Core protocol types used across OP Stack rust crates.
• derive: no_std compatible implementation of the derivation pipeline.
• driver: Stateful derivation pipeline driver.
• interop: Core functionality and primitives for the Interop feature of the OP Stack.
• registry: Rust bindings for the superchain-registry.
• comp: Compression types for the OP Stack.
• hardforks: Consensus layer hardfork types for the OP Stack including network upgrade transactions.

Proof

• mpt: Utilities for interacting with the Merkle Patricia Trie in the client program.
• executor: no_std stateless block executor for the OP Stack.
• proof: High level OP Stack state transition proof SDK.
• proof-interop: Extension of kona-proof with interop support.
• preimage: High level interfaces to the PreimageOracle ABI.
• std-fpvm: Platform specific Fault Proof VM kernel APIs.
• std-fpvm-proc: Proc macro for Fault Proof Program entrypoints.

Node

• engine: An extensible implementation of the OP Stack rollup node engine client
• rpc: OP Stack RPC types and extensions.
• p2p: OP Stack P2P Networking including Gossip and Discovery.
• service: The OP Stack rollup node service.
• sources: Data source types and utilities for the kona-node.

Providers

• providers-alloy: Provider implementations for kona-derive backed by Alloy.

Utilities

• serde: Serialization helpers.
• cli: Standard CLI utilities, used across kona's binaries.

Proof

Built on top of these libraries, this repository also features a proof program designed to deterministically execute the rollup state transition in order to verify an L2 output root from the L1 inputs it was derived from.

Kona's libraries were built with alternative backend support and extensibility in mind - the repository features a fault proof virtual machine backend for use in the governance-approved OP Stack, but it's portable across provers! Kona is also used by:

• op-succinct
• kailua

To build your own backend for kona, or build a new application on top of its libraries, see the SDK section of the book.

MSRV

The current MSRV (minimum supported rust version) is 1.85.

The MSRV is not increased automatically, and will be updated only as part of a patch (pre-1.0) or minor (post-1.0) release.

Crate Releases

kona releases are done using the cargo-release crate. A detailed guide is available in ./RELEASES.md.

Contributing

kona is built by open source contributors like you, thank you for improving the project!

A contributing guide is available that sets guidelines for contributing.

Pull requests will not be merged unless CI passes, so please ensure that your contribution follows the linting rules and passes clippy.

Credits

kona is inspired by the work of several teams, namely OP Labs and other contributors' work on the Optimism monorepo and BadBoiLabs's work on Cannon-rs.

kona is also built on rust types in alloy, op-alloy, and maili.

License

Licensed under the MIT license.

Note

Contributions intentionally submitted for inclusion in these crates by you shall be licensed as above, without any additional terms or conditions.