registry

kona-registry

kona-registry is a no_std crate that exports rust type definitions for chains in the superchain-registry. Since it reads static files to read configurations for various chains into instantiated objects, the kona-registry crate requires serde as a dependency. To use the kona-registry crate, add the crate as a dependency to a Cargo.toml.

kona-registry = "0.1.0"

kona-registry declares lazy evaluated statics that expose ChainConfigs, RollupConfigs, and Chain objects for all chains with static definitions in the superchain registry. The way this works is the golang side of the superchain registry contains an "internal code generation" script that has been modified to output configuration files to the crates/registry directory in the etc folder that are read by the kona-registry rust crate. These static config files contain an up-to-date list of all superchain configurations with their chain configs. It is expected that if the commit hash of the superchain-registry pulled in as a git submodule has breaking changes, the tests in this crate (kona-registry) will break and updates will need to be made.

There are three core statics exposed by the kona-registry.

• CHAINS: A list of chain objects containing the superchain metadata for this chain.
• OPCHAINS: A map from chain id to ChainConfig.
• ROLLUP_CONFIGS: A map from chain id to RollupConfig.

kona-registry exports the complete list of chains within the superchain, as well as each chain's RollupConfigs and ChainConfigs.

Custom chain configurations

kona-registry embeds a frozen snapshot of the upstream superchain registry, but downstream users can extend that snapshot at build time. This is useful when you need bespoke test chains or partner networks that are not yet part of the public registry but still want to rely on the crate's lazy statics.

1. Produce JSON files that follow the same schema as the generated artifacts in etc/:
   • chainList.json containing additional Chain entries.
   • configs.json containing Superchain structures with matching ChainConfigs and RollupConfigs for the new chain ids.
2. Point the build to those files by setting the following environment variables during cargo build (or cargo test):

   export KONA_CUSTOM_CONFIGS=true
   export KONA_CUSTOM_CONFIGS_DIR=/absolute/path/to/custom-configs
   cargo build -p kona-registry

3. The build script merges the custom files into the generated etc/chainList.json and etc/configs.json before compiling the crate. Attempting to override existing chain ids will result in build failures.

Both JSON files must stay in lockstep: every chain listed in configs.json must also appear in chainList.json, and chain identifiers must map to a single chain id. The build script validates those invariants and will fail fast if it detects duplicates or mismatches. When publishing another crate that depends on kona-registry, you can check the custom artifacts into your workspace and set KONA_CUSTOM_CONFIGS_DIR via a build script or just recipe so that consumers automatically embed the additional definitions.

Usage

Add the following to your Cargo.toml.

[dependencies]
kona-registry = "0.1.0"

To make kona-registry no_std, toggle default-features off like so.

[dependencies]
kona-registry = { version = "0.1.0", default-features = false }

Below demonstrates getting the RollupConfig for OP Mainnet (Chain ID 10).

use kona_registry::ROLLUP_CONFIGS;

let op_chain_id = 10;
let op_rollup_config = ROLLUP_CONFIGS.get(&op_chain_id);
println!("OP Mainnet Rollup Config: {:?}", op_rollup_config);

A mapping from chain id to ChainConfig is also available.

use kona_registry::OPCHAINS;

let op_chain_id = 10;
let op_chain_config = OPCHAINS.get(&op_chain_id);
println!("OP Mainnet Chain Config: {:?}", op_chain_config);

Feature Flags

• std: Uses the standard library to pull in environment variables.

Credits

superchain-registry contributors for building and maintaining superchain types.

alloy and op-alloy for creating and maintaining high quality Ethereum and Optimism types in rust.