Skip to content

docs(fast-inbox): document message-prefix consumption, count-addressed replay and the accepted limitations - #25416

Draft
spalladino wants to merge 6 commits into
spl/fi2-bucketless-node-cutoverfrom
spl/fi2-message-only-docs
Draft

docs(fast-inbox): document message-prefix consumption, count-addressed replay and the accepted limitations#25416
spalladino wants to merge 6 commits into
spl/fi2-bucketless-node-cutoverfrom
spl/fi2-message-only-docs

Conversation

@spalladino

Copy link
Copy Markdown
Contributor

Context

The bucketless Fast Inbox rebuild (#25413#25414#25415) changed what the node does with L1-to-L2 messages: every L2 block consumes the messages the proposer's archiver has observed, blocks may end at any message prefix, only a checkpoint's final position must be a live Inbox bucket end (resolved through Inbox.getBucketAtOrBeforeTotal and preflighted through Rollup.validateCheckpointHeaderAndInbox), validators authenticate content and never penalise a local prefix disagreement, and the archiver stores a plain message log with content-comparing reorg recovery. None of that was reflected in the developer docs, the migration notes or the operator changelog, and the two consumer-visible breaks carried over from the merged umbrella (MessageSent emitting the full message, getL1ToL2MessageCheckpointgetL1ToL2MessageIndex) were still undocumented. This is the P4 "normative docs" PR of the replacement stack; it contains no production code.

Approach

ethereum-aztec-messaging/inbox.md is rewritten around the current contract: the leaf index semantics, the MessageSent event, a "How messages reach L2" section (immediate greedy consumption, checkpoint-only bucket endpoints, mandatory consumption, content-only validation), the distinction between public same-block consumption and private consumption against a historical header, the accepted limitations (a final boundary lost to a reorg can cost the checkpoint, attestation does not prove publishability, a post-submission reorg can revert propose and spend gas, the inherited stale-finality shortcut is deferred), ring headroom and back pressure, and the full view-function table including getCurrentBucketSeq, getBucket, getBucketAtOrBeforeTotal, getProvenConsumedBucketSeq and getRingHeadroom. The portal overview, the aztec-nr messaging guide, the token-bridge, Uniswap and Aave tutorials and the operator glossary drop the descendant-wait and 12–30 s wording. Two stale reorg paragraphs in archiver/README.md are brought in line with the synchronizer section above them.

resources/migration_notes.md gains five ## TBD entries: the two umbrella carry-overs, the additive Inbox/Rollup views and errors, the count-addressed archiver API (removed bucket reads, InboxMessageRangeNotSyncedError, the new position/range reads, InboxBucketRefInboxMessagePrefixRef, addBlock(block, inboxPrefixRef), MessageSentLog.l1BlockTimestamp and InboxContract.getBlockTimestamps removed, MIN_BLOCKS_FOR_INBOX_CATCHUP 7 → 4) and the sequencer/validator internals (constructor and export changes, validateCheckpointHeadervalidateCheckpointHeaderAndInbox, the validator reason changes). A new operator page docs-operate/operators/reference/changelog/v6.md (the manifest is at 6.0.0) covers the automatic archiver store reset on ARCHIVER_DB_VERSION 10, the lowered maxBlocksPerCheckpoint floor, the behaviour changes, the non-punitive validator reasons, content-comparing recovery, the accepted limitations, the new L1 views and that no configuration changed; it is registered in the changelog index and the operator sidebar. Every claim was checked against the code on this branch. The reconciled message-only AZIP draft lives outside git (yarn-project/tmp/new-inbox/azip-22-fast_inbox-message-only.md).

Stacked on #25415 (spl/fi2-bucketless-node-cutover).

Part of A-1928
Fixes A-1926

@spalladino spalladino added the ci-draft Run CI on draft PRs. label Sep 5, 2026
@spalladino
spalladino force-pushed the spl/fi2-message-only-docs branch 3 times, most recently from 88218ce to d88196e Compare September 5, 2026 13:44
@spalladino
spalladino force-pushed the spl/fi2-message-only-docs branch from d88196e to 145907b Compare September 5, 2026 13:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci-draft Run CI on draft PRs.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant