docs(fast-inbox): document message-prefix consumption, count-addressed replay and the accepted limitations - #25416
Draft
spalladino wants to merge 6 commits into
Draft
Conversation
spalladino
force-pushed
the
spl/fi2-message-only-docs
branch
3 times, most recently
from
September 5, 2026 13:44
88218ce to
d88196e
Compare
… API and the accepted limitations
…etless node cutover
… checks, stale heights and the leaf-index derivation
…ecks and height refresh precisely
…en-tip assumption at an epoch boundary
spalladino
force-pushed
the
spl/fi2-message-only-docs
branch
from
September 5, 2026 13:58
d88196e to
145907b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.getBucketAtOrBeforeTotaland preflighted throughRollup.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 (MessageSentemitting the full message,getL1ToL2MessageCheckpoint→getL1ToL2MessageIndex) were still undocumented. This is the P4 "normative docs" PR of the replacement stack; it contains no production code.Approach
ethereum-aztec-messaging/inbox.mdis rewritten around the current contract: the leaf index semantics, theMessageSentevent, 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 revertproposeand spend gas, the inherited stale-finality shortcut is deferred), ring headroom and back pressure, and the full view-function table includinggetCurrentBucketSeq,getBucket,getBucketAtOrBeforeTotal,getProvenConsumedBucketSeqandgetRingHeadroom. 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 inarchiver/README.mdare brought in line with the synchronizer section above them.resources/migration_notes.mdgains five## TBDentries: 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,InboxBucketRef→InboxMessagePrefixRef,addBlock(block, inboxPrefixRef),MessageSentLog.l1BlockTimestampandInboxContract.getBlockTimestampsremoved,MIN_BLOCKS_FOR_INBOX_CATCHUP7 → 4) and the sequencer/validator internals (constructor and export changes,validateCheckpointHeader→validateCheckpointHeaderAndInbox, the validator reason changes). A new operator pagedocs-operate/operators/reference/changelog/v6.md(the manifest is at 6.0.0) covers the automatic archiver store reset onARCHIVER_DB_VERSION10, the loweredmaxBlocksPerCheckpointfloor, 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