docs(fast-inbox): document message-prefix consumption, count-addressed replay and the accepted limitations - #25416
Draft
spalladino wants to merge 8 commits into
Draft
Conversation
spalladino
force-pushed
the
spl/fi2-message-only-docs
branch
4 times, most recently
from
September 5, 2026 13:58
d88196e to
145907b
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
Recovery no longer keeps unchanged messages and their proposed blocks until a content difference is found. The operator changelog, the developer Inbox page and the archiver README now say what actually happens: the log is rolled back to the newest message the node can still find on L1 near the height it recorded for it, proposed blocks that consumed anything past that point are dropped even when the same content comes straight back, and published checkpoints are never deleted by this path.
Replaces the completion-target wording in the developer Inbox page and the v6 operator changelog. Selection is local-only while a block's end stays at or below 768 messages into the checkpoint; above that line, and on every final block, the proposer resolves a live bucket end from the Inbox first. Nothing is retained between blocks and consumption is never frozen, so a bucket closing later in the slot can still be taken. The changelog also records the extra transaction-less block that ends a checkpoint whose sub-slot schedule ran out, its deadline derived from the timetable's last block build time rather than the attestation deadline, and drops inbox_completion_unreachable from the reason list.
spalladino
force-pushed
the
spl/fi2-message-only-docs
branch
from
September 8, 2026 00:55
145907b to
f0d1f1b
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 whose reorg recovery rolls back to the newest message still on L1 and refetches. 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, an endpoint lookup only on the final block or above 768 messages into the checkpoint, the extra transaction-less block when the schedule runs out, 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, rollback-and-refetch 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