refactor(cli): refactor messaging-related CLI args by kariy · Pull Request #565 · dojoengine/katana

kariy · 2026-05-08T17:25:42Z

Summary

Replaces the standalone --messaging foo.json JSON config with chain-spec-driven settlement plus an opt-in --messaging.enabled CLI flag. Stacked on top of refactor/messaging.

The chain spec is now the canonical source of truth for settlement layer configuration. The CLI surface controls operational concerns (does this node consume L1 messages, how often, from where).

Why

Today there are two sources of settlement config:

The chain spec (--chain rollup.json, derives messaging via MessagingConfig::from_chain_spec)
A standalone JSON file (--messaging foo.json)

Source 2 was a leak — it duplicated info that already lives in the chain spec, required its own loader, and tied messaging to "is this JSON file present" rather than to an explicit operator decision. The previous review flagged this; the in-tree comment on args.rs already telegraphed removal ("temporary and the messaging config will eventually be removed slowly").

This PR delivers on that.

Behavior changes

Settlement is now read from chain.settlement() only. Existing rollup chain spec workflows continue to work — settlement details come from the chain spec.

Messaging is opt-in. Even if the chain spec defines a settlement layer, the messaging service does not run unless --messaging.enabled is passed. The chain spec describes the chain; the flag describes what this node does with it.

Dev / ad-hoc workflow (anvil + Katana, no chain spec file): use the new --chain.settlement-* override flags to inject settlement into the dev chain spec at startup.

New CLI flags

Flag	Purpose
`--messaging.enabled`	Opt in. Required for messaging to run.
`--messaging.interval <SECS>`	Polling interval (default: 2).
`--messaging.from-block <N>`	Override start block on the settlement chain (replay/debug).
`--chain.settlement-chain <ethereum\|starknet>`	Override settlement chain type.
`--chain.settlement-rpc-url <URL>`	Override settlement RPC URL.
`--chain.settlement-contract <ADDR>`	Override core contract address.

Removed

--messaging <PATH> JSON config flag.
MessagingConfig::load, MessagingConfig::parse, MessagingConfig::from_chain_spec.
SettlementChainConfig enum (the messaging crate now uses katana_chain_spec::SettlementLayer directly).

Migration

Rollup operators need to add --messaging.enabled to existing commands. Existing JSON config files are no longer loaded.

Example workflows

# Production rollup — sequencer that consumes L1 messages
katana --chain rollup.json --messaging.enabled

# Same chain, run as a non-messaging node (proving, indexing)
katana --chain rollup.json

# Local dev with anvil — no chain spec needed
katana \
  --chain.settlement-chain ethereum \
  --chain.settlement-rpc-url http://localhost:8545 \
  --chain.settlement-contract 0x... \
  --messaging.enabled

# Replay from earlier block
katana --chain rollup.json --messaging.enabled --messaging.from-block 1234

If --messaging.enabled is set but the chain spec has no settlement layer, the node fails fast at startup with a clear error message pointing to the override flags.

Test plan

cargo build --workspace --all-targets — clean
cargo nextest run -p katana-messaging — 5/5 pass
cargo nextest run -p katana-db -p katana-provider — 159/159 pass
cargo nextest run -p katana-rpc-server --test messaging — 4/4 pass (skipping anvil-only test_messaging)
cargo nextest run -p katana-cli — 17/17 pass
katana --help shows the 6 new flags and no longer shows --messaging <PATH>
Integration test (tests/messaging.rs) updated to mutate the dev chain spec settlement directly

Notes / decisions

The Ethereum settlement id field, when constructing settlement from --chain.settlement-* overrides on a chain spec without existing settlement, defaults to 1 (mainnet). For non-mainnet chain ids, use a chain spec file. No fourth --chain.settlement-id flag added in this pass.
--chain.settlement-from-block was intentionally not added; --messaging.from-block is the operational override and the chain spec's block field stays a deployment-time fact.
Sovereign settlement returns an explicit error if messaging is enabled — no behavior change there.

🤖 Generated with Claude Code

github-actions

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.30.

Benchmark suite	Current: `088c24e`	Previous: `2aa5b3e`	Ratio
`StorageEntry/compress`	`161` ns/iter (`± 6`)	`123` ns/iter (`± 3`)	`1.31`
`StorageEntry/decompress`	`159` ns/iter (`± 4`)	`118` ns/iter (`± 3`)	`1.35`
`ContractNonceChange/compress`	`160` ns/iter (`± 2`)	`122` ns/iter (`± 4`)	`1.31`
`ContractNonceChange/decompress`	`277` ns/iter (`± 7`)	`205` ns/iter (`± 3`)	`1.35`
`GenericContractInfo/decompress`	`114` ns/iter (`± 2`)	`86` ns/iter (`± 2`)	`1.33`
`Felt/decompress`	`64` ns/iter (`± 4`)	`47` ns/iter (`± 7`)	`1.36`
`BlockHash/decompress`	`63` ns/iter (`± 12`)	`47` ns/iter (`± 4`)	`1.34`
`TxHash/decompress`	`63` ns/iter (`± 7`)	`47` ns/iter (`± 6`)	`1.34`
`ClassHash/decompress`	`63` ns/iter (`± 6`)	`46` ns/iter (`± 4`)	`1.37`
`CompiledClassHash/decompress`	`63` ns/iter (`± 8`)	`46` ns/iter (`± 6`)	`1.37`
`TypedTransactionExecutionInfo/decompress`	`3819` ns/iter (`± 103`)	`2560` ns/iter (`± 72`)	`1.49`
`MigratedCompiledClassHash/decompress`	`162` ns/iter (`± 8`)	`119` ns/iter (`± 5`)	`1.36`
`ReceiptEnvelope/decompress`	`6698` ns/iter (`± 267`)	`4899` ns/iter (`± 314`)	`1.37`
`TrieHistoryEntry/decompress`	`278` ns/iter (`± 13`)	`190` ns/iter (`± 14`)	`1.46`

This comment was automatically generated by workflow using github-action-benchmark.

CC: @kariy

github-actions · 2026-05-08T18:21:54Z

Codec benchmark diff vs `main`

Benchmark	Baseline (ns)	Current (ns)	Δ
`CompiledClass(fixture)/compress`	2714068	2546979	-6.16%
`CompiledClass(fixture)/decompress`	2932598	2743536	-6.45%
`ExecutionCheckpoint/compress`	32	29	-9.38%
`ExecutionCheckpoint/decompress`	26	23	-11.54%
`PruningCheckpoint/compress`	32	29	-9.38%
`PruningCheckpoint/decompress`	26	23	-11.54%
`VersionedHeader/compress`	655	664	+1.37%
`VersionedHeader/decompress`	815	731	-10.31%
`StoredBlockBodyIndices/compress`	78	71	-8.97%
`StoredBlockBodyIndices/decompress`	36	36	+0.00%
`StorageEntry/compress`	148	119	-19.59%
`StorageEntry/decompress`	139	119	-14.39%
`ContractNonceChange/compress`	148	120	-18.92%
`ContractNonceChange/decompress`	230	205	-10.87%
`ContractClassChange/compress`	220	165	-25.00%
`ContractClassChange/decompress`	250	218	-12.80%
`ContractStorageEntry/compress`	159	127	-20.13%
`ContractStorageEntry/decompress`	316	276	-12.66%
`GenericContractInfo/compress`	137	122	-10.95%
`GenericContractInfo/decompress`	112	86	-23.21%
`Felt/compress`	83	70	-15.66%
`Felt/decompress`	55	46	-16.36%
`BlockHash/compress`	83	71	-14.46%
`BlockHash/decompress`	55	46	-16.36%
`TxHash/compress`	83	69	-16.87%
`TxHash/decompress`	55	46	-16.36%
`ClassHash/compress`	82	69	-15.85%
`ClassHash/decompress`	54	46	-14.81%
`CompiledClassHash/compress`	83	69	-16.87%
`CompiledClassHash/decompress`	55	45	-18.18%
`BlockNumber/compress`	47	42	-10.64%
`BlockNumber/decompress`	26	23	-11.54%
`TxNumber/compress`	47	42	-10.64%
`TxNumber/decompress`	25	23	-8.00%
`FinalityStatus/compress`	1	0	-100.00%
`FinalityStatus/decompress`	12	10	-16.67%
`TypedTransactionExecutionInfo/compress`	18662	14583	-21.86%
`TypedTransactionExecutionInfo/decompress`	3591	2528	-29.60%
`VersionedContractClass/compress`	365	350	-4.11%
`VersionedContractClass/decompress`	770	662	-14.03%
`MigratedCompiledClassHash/compress`	147	120	-18.37%
`MigratedCompiledClassHash/decompress`	139	118	-15.11%
`ContractInfoChangeList/compress`	1590	1517	-4.59%
`ContractInfoChangeList/decompress`	2442	2259	-7.49%
`BlockChangeList/compress`	667	641	-3.90%
`BlockChangeList/decompress`	964	886	-8.09%
`ReceiptEnvelope/compress`	30098	25026	-16.85%
`ReceiptEnvelope/decompress`	6209	5010	-19.31%
`TrieDatabaseValue/compress`	166	139	-16.27%
`TrieDatabaseValue/decompress`	227	244	+7.49%
`TrieHistoryEntry/compress`	292	257	-11.99%
`TrieHistoryEntry/decompress`	254	190	-25.20%

github-actions · 2026-05-08T18:21:55Z

Runner: Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz (4 cores) · 15Gi RAM

…lement.* Re-apply CLI surface for messaging configuration on top of current main (which merged the messaging crate refactor in #564). The CLI now builds `Config.messaging: Option<MessagingConfig>` from `--messaging.enabled` plus chain-spec settlement plus optional `--settlement.*` override flags, instead of consuming an opaque JSON file via `--messaging`. Changes: - `crates/cli/src/options.rs`: add `MessagingOptions`, `ChainSpec`, `SettlementOptions`, `SettlementChainKind`; remove `chain_id` from `EnvironmentOptions` (now lives on `ChainSpec`). - `crates/cli/src/args.rs`: flatten `chain: ChainSpecArgs` and `messaging: MessagingOptions` onto `SequencerNodeArgs`; drop the top-level `--chain` and `--messaging` JSON fields; add `build_messaging_config` and the `apply_chain_overrides` / `build_settlement_from_overrides` / `apply_partial_overrides` helpers that fold `--settlement.*` overrides into the chain spec. - `crates/cli/src/file.rs`: swap `messaging: Option<MessagingConfig>` for `messaging: Option<MessagingOptions>` and add `chain: Option<ChainSpec>` to the TOML config file shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

codecov · 2026-05-12T17:20:02Z

Codecov Report

❌ Patch coverage is 77.39362% with 85 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.27%. Comparing base (9bde0ae) to head (8aed8aa).
⚠️ Report is 412 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/cli/src/args.rs	84.59%	51 Missing ⚠️
crates/cli/src/options.rs	25.58%	32 Missing ⚠️
crates/cli/src/file.rs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #565      +/-   ##
==========================================
- Coverage   73.32%   68.27%   -5.05%     
==========================================
  Files         209      320     +111     
  Lines       23132    44772   +21640     
==========================================
+ Hits        16961    30569   +13608     
- Misses       6171    14203    +8032

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

A zero polling interval panics deep inside `tokio::time::interval` construction in the messaging trigger. Reject it at both entry points: - CLI: `value_parser` range on `--messaging.interval` so clap fails with a standard out-of-range message. - TOML: explicit guard in `build_messaging_config` (the CLI parser doesn't run on values that came from a config file). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Adds unit tests for the settlement override resolver: short-circuit on no inputs, fresh construction (Ethereum + Starknet) with partial-input rejection, per-field patching on existing layers (Ethereum + Starknet), chain-kind swaps (and their all-three requirement), Sovereign replacement, and core-contract parse failures on both the fresh and partial paths. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

kariy changed the title ~~refactor(cli): drop --messaging json, add --messaging.enabled opt-in~~ refactor(cli): drop --messaging json, add --messaging.enabled opt-in May 8, 2026

github-actions Bot reviewed May 8, 2026

View reviewed changes

Base automatically changed from refactor/messaging to main May 12, 2026 15:24

kariy force-pushed the refactor/messaging-config-cli branch from 088c24e to fd5abcf Compare May 12, 2026 15:43

kariy changed the title ~~refactor(cli): drop --messaging json, add --messaging.enabled opt-in~~ refactor(cli): refactor messaging-related CLI args May 12, 2026

kariy and others added 3 commits May 12, 2026 15:24

fmt

8aed8aa

kariy merged commit c8d76b6 into main May 12, 2026
20 of 21 checks passed

kariy deleted the refactor/messaging-config-cli branch May 12, 2026 23:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(cli): refactor messaging-related CLI args#565

refactor(cli): refactor messaging-related CLI args#565
kariy merged 4 commits into
mainfrom
refactor/messaging-config-cli

kariy commented May 8, 2026

Uh oh!

github-actions Bot left a comment •

edited

Loading

Uh oh!

github-actions Bot commented May 8, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 8, 2026 •

edited

Loading

Uh oh!

codecov Bot commented May 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

kariy commented May 8, 2026

Summary

Why

Behavior changes

New CLI flags

Removed

Migration

Example workflows

Test plan

Notes / decisions

Uh oh!

github-actions Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

⚠️ Performance Alert ⚠️

Uh oh!

github-actions Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codec benchmark diff vs main

Uh oh!

github-actions Bot commented May 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot left a comment •

edited

Loading

github-actions Bot commented May 8, 2026 •

edited

Loading

Codec benchmark diff vs `main`

github-actions Bot commented May 8, 2026 •

edited

Loading

codecov Bot commented May 12, 2026 •

edited

Loading