Skip to content

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

Draft
spalladino wants to merge 8 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 8 commits into
spl/fi2-bucketless-node-cutoverfrom
spl/fi2-message-only-docs

Conversation

@spalladino

@spalladino spalladino commented Sep 5, 2026

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 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 (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, 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 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, 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

@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 4 times, most recently from d88196e to 145907b Compare September 5, 2026 13:58
… checks, stale heights and the leaf-index derivation
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
spalladino force-pushed the spl/fi2-message-only-docs branch from 145907b to f0d1f1b Compare September 8, 2026 00:55
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