20260710

Release Notes for mainnet operators

This release stages a mainnet protocol upgrade to distribute the block rewards per epoch, instead of once per block.

Actions for all nodes

• If you set ESPRESSO_SEQUENCER_STORAGE_PATH also set
  ESPRESSO_NODE_STORAGE_PATH to the same value.

• You're encouraged to send logs and/or metrics to Espresso by setting
  ESPRESSO_NODE_TELEMETRY_LOGS_ENABLE=true
ESPRESSO_NODE_TELEMETRY_METRICS_ENABLE=true

• Please set ESPRESSO_NODE_IDENTITY_COMPANY_NAME and ESPRESSO_NODE_IDENTITY_NODE_NAME,
  or --company-name and --node-name when using CLI arguments.

Actions for query nodes (query module enabled)

Enable the light-client module to allow other nodes to catchup via
the new Light Client catchup feature.

E.g. ... -- storage-sql -- http -- query -- light-client -- [other modules]

Actions for nodes with manually configured genesis file

• Stage upgrade by using this mainnet.toml genesis file:
  https://github.com/EspressoSystems/espresso-network/blob/20260710/data/genesis/mainnet.toml

  For the official docker image the correct file will be loaded by default.

Notes

• Environment variables have been renamed in a backwards compatible way.
  You will see startup warnings for the deprecated env vars but it is not
  necessary to set the new variables for this binary upgrade. The old
  env vars are still supported. We recommend not modifying env vars and
  grepping startup logs for WARNING: to see which env vars need to be
  migrated.

• A DB migration will run in the background for query nodes:

  • DB load will be slightly elevated, 10 - 20% temporary storage bloat.
  • You can check /database/migration-status for the migration status.
  • The migration can potentially take weeks.
    • If you encounter issues please reach out to us: rolling back the binary
      will not succeed to start up the node.

--

What's Changed

• Remove Coordinator/Cliquenet. by @twittner in #4664
• [Backport release-mainnet-1.2.0-rc] fix(clippy): resolve lints and bump rust-overlay by @github-actions[bot] in #4666
• [Backport release-mainnet-1.2.0-rc] fix: demote spammy warn log to debug by @github-actions[bot] in #4668

Full Changelog: 2026070...2026071

20260707

What's Changed

• [Backport release-mainnet-1.2.0-rc] fix(stake-table): quiet spammy stake table warnings by @github-actions[bot] in #4620
• [Backport release-mainnet-1.2.0-rc] feat: genesis in config API and metrics by @github-actions[bot] in #4627
• Fix stale config node response snapshot on release-mainnet-1.2.0-rc by @lukaszrzasik in #4633
• Backport 4624 to release mainnet 1.2.0 rc by @lukaszrzasik in #4630
• [Backport release-mainnet-1.2.0-rc] Improve serializable diag logs by @github-actions[bot] in #4629
• [Backport release-mainnet-1.2.0-rc] test(stake-table): pin registerValidatorV3 validation chain by @github-actions[bot] in #4639
• [Backport release-mainnet-1.2.0-rc] fix(audit): crossbeam-epoch 0.9.18 -> 0.9.20 by @github-actions[bot] in #4640
• [Backport release-mainnet-1.2.0-rc] chore: update solc 0.8.28 -> 0.8.35 by @github-actions[bot] in #4647
• [Backport release-mainnet-1.2.0-rc] fix(contracts): reject infinity BLS points and non-canonical x25519 keys by @github-actions[bot] in #4648
• [Backport release-mainnet-1.2.0-rc] fix(stake-table): soft-fail invalid x25519 keys instead of halting by @github-actions[bot] in #4645
• fix(audit): cargo audit fix by @sveitser in #4649

Full Changelog: 2026070...2026070

20260702

What's Changed

• [Backport release-mainnet-1.2.0-rc] Allow reading genesis file from URL by @github-actions[bot] in #4602
• [Backport release-mainnet-1.2.0-rc] genesis: decaf post v5 upgrade by @github-actions[bot] in #4604
• [Backport release-mainnet-1.2.0-rc] Fix a bug in light client fetching leaves from HotStuff1 by @github-actions[bot] in #4605
• [Backport release-mainnet-1.2.0-rc] genesis: mainnet v4 to v5 epoch reward upgrade by @github-actions[bot] in #4609

Full Changelog: 2026062...2026070

20260518-reward-prune-fix

What's Changed

• [Backport release-mainnet-1.1.0-rc] Remove deferrable from read transactions by @github-actions[bot] in #4282
• [Backport release-mainnet-1.1.0-rc] fix: Retain previous epoch trees for staking api startup by @github-actions[bot] in #4315

Full Changelog: 2026051...20260518-reward-prune-fix

20260512

What's Changed

• fix(libp2p): plumb advertise address to swarm.add_external_address #4261 by @sveitser in #4276
• [Backport release-mainnet-1.1.0-rc] fix(libp2p): make AutoNAT log messages actionable for operators by @github-actions[bot] in #4286

Full Changelog: 2026050...2026051

20260512-libp2p-fixes

What's Changed

• consolidate operations and prepare for multisig routing by @alysiahuggins in #3875
• fix(sequencer): disable default features in dependent crates by @sveitser in #3917
• feat(staking-cli): add OpenMetrics support and fix flaky tests by @sveitser in #3926
• refactor(staking-cli): simplify metadata args and add preview command by @sveitser in #3928
• fix(staking-cli): eliminate anvil port race condition in tests by @sveitser in #3929
• fix(staking-cli): improve metadata fetching robustness and error messages by @sveitser in #3933
• [Bot] Audit fixes by @github-actions[bot] in #3924
• refactor(staking-cli): move skip-metadata-validation to command args by @sveitser in #3937
• Nix shell changes by @ss-es in #3919
• Add .envrc sourcing .envrc.local by @ss-es in #3940
• staking cli: Limit parallel futures for tx receipts to 32 by @imabdulbasit in #3946
• increase catchup timeout to 2s and make it an env variable by @imabdulbasit in #3947
• Spawn membership catchup every 100 views by @ss-es in #3959
• fix(types): store unauthenticated validators by @sveitser in #3903
• Add vote participation api by @lukaszrzasik in #3916
• Fix Unnecessary Timeouts when View Change happens before Proposal Handling by @bfish713 in #3967
• Remove portpicker race condition by @sveitser in #3932
• fix(test): flaky CI fire fighting by @sveitser in #3972
• fix: process-compose fails for v1.90.0 by @mrain in #3974
• feat: mass (un)delegation in stake table contract by @sveitser in #3825
• Add tests for vote participation by @lukaszrzasik in #3973
• fix: disallow testing feature for release by @sveitser in #3982
• add --stake-table-only flag to reset-storage binary to clear stake table data only by @imabdulbasit in #3979
• fix(migrations): resolve duplicate migration version numbers after merge by @sveitser in #3985
• truncate legacy tables by @imabdulbasit in #3989
• make state query compatible with postgres 15 by @imabdulbasit in #3991
• versions by @twittner in #3943
• Use workspace dependencies everywhere. by @twittner in #3953
• chore: retry another flaky test by @sveitser in #3984
• CI: improve cargo audit fix bot by @sveitser in #3583
• refactor(utils): centralize build/version info in sequencer-utils by @sveitser in #3988
• Merge release candidate into main by @ss-es in #3993
• Remove useless retries from upsert by @jbearer in #3999
• expose ESPRESSO_SEQUENCER_LIBP2P_BOOTSTRAP_NODES in public env vars by @imabdulbasit in #4018
• Fix SignerConfig parsing by @lukaszrzasik in #4006
• Redesign sync_status and proactive scanner to minimize performance impact by @jbearer in #4017
• [Bot] Audit fixes by @github-actions[bot] in #4023
• Remove View and Epoch types from NodeTypes by @bfish713 in #3939
• feat: storage backed reward Merkle tree by @mrain in #3936
• Break sync_status query into multiple smaller transactions by @jbearer in #4029
• Backport: Use proposal chain_config on version change in state update loop by @imabdulbasit in #4033
• chore: batch friendly VID share validation by @mrain in #4038
• Update to 2024 edition by @twittner in #3952
• fix: activeness check before submitting light client state vote by @mrain in #4014
• fix: ubuntu install without nix by @mrain in #4045
• feat: deployment info tool for L1 deployments by @sveitser in #3795
• chore: fix cargo fmt by @sveitser in #4049
• Add an option to disable the scanner task by @jbearer in #4042
• Backport some fixes to cliquenet. by @twittner in #4009
• Use parking_lot::RwLock in UpgradeLock. by @twittner in #4050
• Remove upgrade from HotShotConfig by @ss-es in #4046
• feat(staking-cli): add --no-config flag to skip config file loading by @sveitser in #4057
• fix(staking-cli): don't require --account-index with --private-key by @sveitser in #4007
• Compatibility network layer and peer update handling. by @twittner in #3964
• doc: VID common consistency check by @mrain in #4061
• chore: update alloy and foundry by @sveitser in #4058
• Merge release-mainnet-1.0.1-rc into main by @ss-es in #4055
• fix: update rustls-webpki to 0.103.10 to resolve RUSTSEC-2026-0049 by @sveitser in #4066
• Deduplicate payloads and VID common in database by @jbearer in #4043
• Set default bind address for cliquenet by @jbearer in #4077
• fix(go-sdk): replace external network dependencies with local dev node in tests by @sveitser in #4081
• Support key generation from a mnemonic by @jbearer in #4078
• refactor: remove Node.js dependency, replace with Rust calldata export by @sveitser in #4051
• fix(test): use binary() filter for cross_tests! macro in nextest config by @sveitser in #4082
• ci: add Claude Code GitHub Actions for PR review and interactive @claude by @sveitser in #4073
• Initial Code Structure for Fast Finality RFC by @bfish713 in #4047
• Ensure cliquenet uses at least 1 for channel capacity by @jbearer in #4089
• doc: rephrase sequencer with proper words by @mrain in #4062
• Add Timeouts and ViewChange by @bfish713 in #4084
• Claude code review tweaks v1 by @sveitser in #4090
• [new-protocol]: Use the current thread runtime in tokio tests. by @twittner in #4093
• fix(ci): add GH_TOKEN to claude review fetch comments step by @sveitser in #4095
• Try all L1 providers when missing transaction receipts by @imabdulbasit in #4097
• fix(ci): correct bot login names in PR comment filter by @sveitser in #4098
• Make batch requests when backfilling old data in query service by @jbearer in #4064
• Add proposal validator by @twittner in #4102
• Add DRB fix to 0.5 upgrade by @ss-es in #4100
• Exclude VID shares from sync status by @jbearer in https://github...

20000101-test-release-workflow-3

What's Changed

• consolidate operations and prepare for multisig routing by @alysiahuggins in #3875
• fix(sequencer): disable default features in dependent crates by @sveitser in #3917
• feat(staking-cli): add OpenMetrics support and fix flaky tests by @sveitser in #3926
• refactor(staking-cli): simplify metadata args and add preview command by @sveitser in #3928
• fix(staking-cli): eliminate anvil port race condition in tests by @sveitser in #3929
• fix(staking-cli): improve metadata fetching robustness and error messages by @sveitser in #3933
• [Bot] Audit fixes by @github-actions[bot] in #3924
• refactor(staking-cli): move skip-metadata-validation to command args by @sveitser in #3937
• Nix shell changes by @ss-es in #3919
• Add .envrc sourcing .envrc.local by @ss-es in #3940
• staking cli: Limit parallel futures for tx receipts to 32 by @imabdulbasit in #3946
• increase catchup timeout to 2s and make it an env variable by @imabdulbasit in #3947
• Spawn membership catchup every 100 views by @ss-es in #3959
• fix(types): store unauthenticated validators by @sveitser in #3903
• Add vote participation api by @lukaszrzasik in #3916
• Fix Unnecessary Timeouts when View Change happens before Proposal Handling by @bfish713 in #3967
• Remove portpicker race condition by @sveitser in #3932
• fix(test): flaky CI fire fighting by @sveitser in #3972
• fix: process-compose fails for v1.90.0 by @mrain in #3974
• feat: mass (un)delegation in stake table contract by @sveitser in #3825
• Add tests for vote participation by @lukaszrzasik in #3973
• fix: disallow testing feature for release by @sveitser in #3982
• add --stake-table-only flag to reset-storage binary to clear stake table data only by @imabdulbasit in #3979
• fix(migrations): resolve duplicate migration version numbers after merge by @sveitser in #3985
• truncate legacy tables by @imabdulbasit in #3989
• make state query compatible with postgres 15 by @imabdulbasit in #3991
• versions by @twittner in #3943
• Use workspace dependencies everywhere. by @twittner in #3953
• chore: retry another flaky test by @sveitser in #3984
• CI: improve cargo audit fix bot by @sveitser in #3583
• refactor(utils): centralize build/version info in sequencer-utils by @sveitser in #3988
• Merge release candidate into main by @ss-es in #3993
• Remove useless retries from upsert by @jbearer in #3999
• expose ESPRESSO_SEQUENCER_LIBP2P_BOOTSTRAP_NODES in public env vars by @imabdulbasit in #4018
• Fix SignerConfig parsing by @lukaszrzasik in #4006
• Redesign sync_status and proactive scanner to minimize performance impact by @jbearer in #4017
• [Bot] Audit fixes by @github-actions[bot] in #4023
• Remove View and Epoch types from NodeTypes by @bfish713 in #3939
• feat: storage backed reward Merkle tree by @mrain in #3936
• Break sync_status query into multiple smaller transactions by @jbearer in #4029
• Backport: Use proposal chain_config on version change in state update loop by @imabdulbasit in #4033
• chore: batch friendly VID share validation by @mrain in #4038
• Update to 2024 edition by @twittner in #3952
• fix: activeness check before submitting light client state vote by @mrain in #4014
• fix: ubuntu install without nix by @mrain in #4045
• feat: deployment info tool for L1 deployments by @sveitser in #3795
• chore: fix cargo fmt by @sveitser in #4049
• Add an option to disable the scanner task by @jbearer in #4042
• Backport some fixes to cliquenet. by @twittner in #4009
• Use parking_lot::RwLock in UpgradeLock. by @twittner in #4050
• Remove upgrade from HotShotConfig by @ss-es in #4046
• feat(staking-cli): add --no-config flag to skip config file loading by @sveitser in #4057
• fix(staking-cli): don't require --account-index with --private-key by @sveitser in #4007
• Compatibility network layer and peer update handling. by @twittner in #3964
• doc: VID common consistency check by @mrain in #4061
• chore: update alloy and foundry by @sveitser in #4058
• Merge release-mainnet-1.0.1-rc into main by @ss-es in #4055
• fix: update rustls-webpki to 0.103.10 to resolve RUSTSEC-2026-0049 by @sveitser in #4066
• Deduplicate payloads and VID common in database by @jbearer in #4043
• Set default bind address for cliquenet by @jbearer in #4077
• fix(go-sdk): replace external network dependencies with local dev node in tests by @sveitser in #4081
• Support key generation from a mnemonic by @jbearer in #4078
• refactor: remove Node.js dependency, replace with Rust calldata export by @sveitser in #4051
• fix(test): use binary() filter for cross_tests! macro in nextest config by @sveitser in #4082
• ci: add Claude Code GitHub Actions for PR review and interactive @claude by @sveitser in #4073
• Initial Code Structure for Fast Finality RFC by @bfish713 in #4047
• Ensure cliquenet uses at least 1 for channel capacity by @jbearer in #4089
• doc: rephrase sequencer with proper words by @mrain in #4062
• Add Timeouts and ViewChange by @bfish713 in #4084
• Claude code review tweaks v1 by @sveitser in #4090
• [new-protocol]: Use the current thread runtime in tokio tests. by @twittner in #4093
• fix(ci): add GH_TOKEN to claude review fetch comments step by @sveitser in #4095
• Try all L1 providers when missing transaction receipts by @imabdulbasit in #4097
• fix(ci): correct bot login names in PR comment filter by @sveitser in #4098
• Make batch requests when backfilling old data in query service by @jbearer in #4064
• Add proposal validator by @twittner in #4102
• Add DRB fix to 0.5 upgrade by @ss-es in #4100
• Exclude VID shares from sync status by @jbearer in #4101
• Break Merkle proof GC into b...

20000101-test-release-workflow-2

What's Changed

• consolidate operations and prepare for multisig routing by @alysiahuggins in #3875
• fix(sequencer): disable default features in dependent crates by @sveitser in #3917
• feat(staking-cli): add OpenMetrics support and fix flaky tests by @sveitser in #3926
• refactor(staking-cli): simplify metadata args and add preview command by @sveitser in #3928
• fix(staking-cli): eliminate anvil port race condition in tests by @sveitser in #3929
• fix(staking-cli): improve metadata fetching robustness and error messages by @sveitser in #3933
• [Bot] Audit fixes by @github-actions[bot] in #3924
• refactor(staking-cli): move skip-metadata-validation to command args by @sveitser in #3937
• Nix shell changes by @ss-es in #3919
• Add .envrc sourcing .envrc.local by @ss-es in #3940
• staking cli: Limit parallel futures for tx receipts to 32 by @imabdulbasit in #3946
• increase catchup timeout to 2s and make it an env variable by @imabdulbasit in #3947
• Spawn membership catchup every 100 views by @ss-es in #3959
• fix(types): store unauthenticated validators by @sveitser in #3903
• Add vote participation api by @lukaszrzasik in #3916
• Fix Unnecessary Timeouts when View Change happens before Proposal Handling by @bfish713 in #3967
• Remove portpicker race condition by @sveitser in #3932
• fix(test): flaky CI fire fighting by @sveitser in #3972
• fix: process-compose fails for v1.90.0 by @mrain in #3974
• feat: mass (un)delegation in stake table contract by @sveitser in #3825
• Add tests for vote participation by @lukaszrzasik in #3973
• fix: disallow testing feature for release by @sveitser in #3982
• add --stake-table-only flag to reset-storage binary to clear stake table data only by @imabdulbasit in #3979
• fix(migrations): resolve duplicate migration version numbers after merge by @sveitser in #3985
• truncate legacy tables by @imabdulbasit in #3989
• make state query compatible with postgres 15 by @imabdulbasit in #3991
• versions by @twittner in #3943
• Use workspace dependencies everywhere. by @twittner in #3953
• chore: retry another flaky test by @sveitser in #3984
• CI: improve cargo audit fix bot by @sveitser in #3583
• refactor(utils): centralize build/version info in sequencer-utils by @sveitser in #3988
• Merge release candidate into main by @ss-es in #3993
• Remove useless retries from upsert by @jbearer in #3999
• expose ESPRESSO_SEQUENCER_LIBP2P_BOOTSTRAP_NODES in public env vars by @imabdulbasit in #4018
• Fix SignerConfig parsing by @lukaszrzasik in #4006
• Redesign sync_status and proactive scanner to minimize performance impact by @jbearer in #4017
• [Bot] Audit fixes by @github-actions[bot] in #4023
• Remove View and Epoch types from NodeTypes by @bfish713 in #3939
• feat: storage backed reward Merkle tree by @mrain in #3936
• Break sync_status query into multiple smaller transactions by @jbearer in #4029
• Backport: Use proposal chain_config on version change in state update loop by @imabdulbasit in #4033
• chore: batch friendly VID share validation by @mrain in #4038
• Update to 2024 edition by @twittner in #3952
• fix: activeness check before submitting light client state vote by @mrain in #4014
• fix: ubuntu install without nix by @mrain in #4045
• feat: deployment info tool for L1 deployments by @sveitser in #3795
• chore: fix cargo fmt by @sveitser in #4049
• Add an option to disable the scanner task by @jbearer in #4042
• Backport some fixes to cliquenet. by @twittner in #4009
• Use parking_lot::RwLock in UpgradeLock. by @twittner in #4050
• Remove upgrade from HotShotConfig by @ss-es in #4046
• feat(staking-cli): add --no-config flag to skip config file loading by @sveitser in #4057
• fix(staking-cli): don't require --account-index with --private-key by @sveitser in #4007
• Compatibility network layer and peer update handling. by @twittner in #3964
• doc: VID common consistency check by @mrain in #4061
• chore: update alloy and foundry by @sveitser in #4058
• Merge release-mainnet-1.0.1-rc into main by @ss-es in #4055
• fix: update rustls-webpki to 0.103.10 to resolve RUSTSEC-2026-0049 by @sveitser in #4066
• Deduplicate payloads and VID common in database by @jbearer in #4043
• Set default bind address for cliquenet by @jbearer in #4077
• fix(go-sdk): replace external network dependencies with local dev node in tests by @sveitser in #4081
• Support key generation from a mnemonic by @jbearer in #4078
• refactor: remove Node.js dependency, replace with Rust calldata export by @sveitser in #4051
• fix(test): use binary() filter for cross_tests! macro in nextest config by @sveitser in #4082
• ci: add Claude Code GitHub Actions for PR review and interactive @claude by @sveitser in #4073
• Initial Code Structure for Fast Finality RFC by @bfish713 in #4047
• Ensure cliquenet uses at least 1 for channel capacity by @jbearer in #4089
• doc: rephrase sequencer with proper words by @mrain in #4062
• Add Timeouts and ViewChange by @bfish713 in #4084
• Claude code review tweaks v1 by @sveitser in #4090
• [new-protocol]: Use the current thread runtime in tokio tests. by @twittner in #4093
• fix(ci): add GH_TOKEN to claude review fetch comments step by @sveitser in #4095
• Try all L1 providers when missing transaction receipts by @imabdulbasit in #4097
• fix(ci): correct bot login names in PR comment filter by @sveitser in #4098
• Make batch requests when backfilling old data in query service by @jbearer in #4064
• Add proposal validator by @twittner in #4102
• Add DRB fix to 0.5 upgrade by @ss-es in #4100
• Exclude VID shares from sync status by @jbearer in #4101
• Break Merkle proof GC into b...

20260203-staking-cli-mainnet

What's Changed

• fix: wait-for-header waits forever for version > 4 by @sveitser in #3918
• Update Push-CDN to 0.6.2-compat-patch2. by @twittner in #3921
• tw/tcp by @rob-maron in #3896
• feat(staking-cli): add mainnet support and metadata validation by @sveitser in #3922

Full Changelog: 20260130-mainnet-pos-contract-deploy...20260203-staking-cli-mainnet

20260130-mainnet-pos-contract-deploy

What's Changed

• Add fetch leaves by range in light client by @Sneh1999 in #3867
• Implement light client stake table fetching by @jbearer in #3858
• fix(ci): free disk space for test jobs by @sveitser in #3881
• feat(docs): publish smart contract docs to GitHub Pages by @sveitser in #3880
• Add support for fetching headers in range by @Sneh1999 in #3882
• Implement light client payload and namespace fetching and verification by @jbearer in #3876
• Implement light client block height method by @jbearer in #3886
• fix(docs): improve contract docs with custom landing page and fix links by @sveitser in #3888
• Add token API endpoint for total supply by @ss-es in #3877
• Fee contract upgrade by @alysiahuggins in #3850
• [Bot] Audit fixes by @github-actions[bot] in #3893
• Update L1 finalized block even when storing empty events list by @jbearer in #3900
• Implement a non-consensus query node that reads data using the light client by @jbearer in #3902
• feat(staking-cli): add private key signing and calldata export by @sveitser in #3894
• docs: add AGENTS.md for AI coding agent guidance by @sveitser in #3914
• Add testnet governance deployment and testing scripts by @alysiahuggins in #3870

Full Changelog: sdks/go/v0.3.4...20260130-mainnet-pos-contract-deploy