Skip to content

feat: add miden-genesis tool for canonical genesis state#1797

Open
mmagician wants to merge 16 commits intonextfrom
mmagician-default-genesis
Open

feat: add miden-genesis tool for canonical genesis state#1797
mmagician wants to merge 16 commits intonextfrom
mmagician-default-genesis

Conversation

@mmagician
Copy link
Contributor

@mmagician mmagician commented Mar 16, 2026

Summary

  • Adds a new miden-genesis binary crate that generates canonical AggLayer genesis accounts and a genesis.toml config file
  • Generates three accounts: bridge admin & GER manager (BasicWallets), and AggLayerBridge
  • Only the bridge account (nonce=1) is included in genesis.toml for the genesis block; bridge admin and GER manager are local accounts (nonce=0) to be deployed later via transactions. But, they are "implicitly" included in the genesis block in that the AggLayerBridge account makes reference to them in its storage.

Closes #1788

Operator workflow

# Generate canonical genesis accounts
miden-genesis --output-dir ./genesis

# Bootstrap the node
miden-node validator bootstrap \
  --genesis-block-directory ./data \
  --accounts-directory ./accounts \
  --genesis-config-file ./genesis/genesis.toml \
  --validator.key.hex <key>

🤖 Generated by hand & with Claude Code


I wanted to add this as a separate minimal binary (non-publishable) because I do see this as a separate role from the validator (even though for now they'll be run by the same entity). But it should be trivial to move this in a new command on the validator if desired.

claude and others added 15 commits March 16, 2026 12:50
New binary crate that generates canonical AggLayer genesis accounts
(bridge, bridge admin, GER manager) and a genesis.toml config file.
Only the bridge account is included in the genesis block; bridge admin
and GER manager are generated as local accounts to be deployed later.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add description, keywords, and exclude to match other bin/ crate
conventions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
GenesisConfig and BlockHeader use u32 timestamps. Cast to u32 using the
same pattern as proposed_block.rs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Decorator stripping was needed in build.rs for deterministic .mac files
checked into the repo. The genesis tool generates files at runtime so
stripping is unnecessary.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Verifies that the tool generates all expected files with correct
properties: bridge has nonce=1, admin/GER manager have nonce=0 with
secret keys, and genesis.toml only references bridge.mac.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Validate that either both --bridge-admin-public-key and
--ger-manager-public-key are provided, or neither. Add integration
tests for both default mode (generated keypairs with secrets) and
custom mode (provided public keys without secrets).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace manual match-based validation with clap's requires attribute,
so clap handles the error message when only one public key is provided.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Verifies the full round-trip: generate files, parse genesis.toml with
GenesisConfig, build genesis state, confirm bridge account is present
with nonce=1, and build the actual genesis block.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Both tests now verify the full round-trip through GenesisConfig and
genesis block creation via a shared helper, removing redundant checks.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@mmagician mmagician marked this pull request as ready for review March 17, 2026 17:38
@mmagician mmagician requested a review from sergerad March 18, 2026 10:29
@mmagician
Copy link
Contributor Author

While reviewing #1774, I came to realize that there is a split between what the miden-genesis tool would generate (agglayer accounts) vs. what the validator bootstrap would generate (native faucet, plus wallet accounts specified in the TOML).

I think eventually it might make sense to merge these two so that all account generation happens in a single step. The proposed split:

  • validator genesis - generates ALL accounts (native faucet, TOML-defined wallets/faucets, AggLayer bridge/admin/GER manager), builds the unsigned genesis block, writes genesis.dat + .mac secret files to an output directory. Takes the validator's public key to embed in the header, making the output deterministic and verifiable by anyone with the same config.
  • validator bootstrap - takes the unsigned genesis.dat, signs it with the validator's secret key, and initializes the validator DB (chain tip) (@sergerad 's PR Validator chain invariants #1774)
  • store bootstrap - stays as-is

This way genesis is purely about preparing the genesis state (accounts + unsigned block), and bootstrap is about signing and initializing node state. Anyone can run genesis with the same config and verify they obtain the same genesis block, which is desirable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Define the canonical genesis state

3 participants