docs(fast-inbox): correct node documentation to the implemented behavior - #186
Draft
spalladino wants to merge 2 commits into
Draft
spalladino wants to merge 2 commits into
spalladino wants to merge 2 commits into
Conversation
Describes what the streaming Inbox node actually does now that the bucketless cutover, the authenticated anchor search and the required prefix reference are all in place. The archiver README separates the scanned cursor from the certified syncpoint, states that an uncertified batch clears the syncpoint rather than advancing it, and rewrites the reorg section around the anchor rollback. Its recovery bullet loses two claims the code no longer supports: the lookup window is 100 L1 blocks around a message's recorded height, not five, and no anchor is accepted without a positive lookup. The sequencer README drops the checkpoint-wide completion target: an endpoint is resolved per block, a non-final block takes the further of that endpoint and its safe local step, and only the final block has to land exactly on a boundary. The validator README lists the checkpoint content check and the L1 endpoint gate that now run before an attestation. The node's message prediction is described as an estimate in both directions rather than a lower bound, with the case where a final block lands below it, and `selectSafeLocalEnd` and the automine comment say the same. A unit test pins that case. The two aztec.js readiness helpers say they answer about the chain as it stands, which is what a caller should use when a simulation is not enough. Range failures from `getL1ToL2MessageRange` are documented as untyped across JSON-RPC, and the kv-store range contract now states that bound inclusivity flips with direction.
spalladino
added this pull request to stack #188
September 12, 2026 04:52
… jsdoc The node documentation corrections rewrote the jsdoc on waitForL1ToL2MessageReady and isL1ToL2MessageReady, but the committed auto-generated aztec.js reference was not regenerated, so docs/bootstrap.sh's staleness check failed.
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.
Updates node-local documentation and one pinning test so they describe the Fast Inbox behavior implemented by the
stack. Twenty-two preceding implementation rungs rebuilt how this node reads the Inbox: messages are a plain ordered log addressed by
count, a block ends at an arbitrary message prefix, a checkpoint's final block resolves a live bucket
end for itself, recovery anchors on a message L1 positively re-emits inside a hundred-block window, and
every block proposal carries a signed prefix reference. The prose did not keep up. This rung is prose
only, apart from one unit test, and its job is to make the documentation describe what the code now
does.
It reconstructs the node-local half of old PR #25416 (head
0df3fa25de, commitsbccabc794dthrough0df3fa25deon top of90c928ec28), and then goes further where reading the whole stack showed thesource's own text was already wrong, or wrong for this tree.
What is corrected, and why each is true here
The archiver README's two message pointers. The scanned cursor says which L1 blocks were queried;
the certified syncpoint says the whole stored log was found equal to the Inbox's position at a canonical
head. An uncertified batch advances the cursor and clears the syncpoint, and the head batch is staged
until the position after it matches the captured one. That is the model N3c built in
inbox_message_synchronizer.ts, and the README still described the single pre-cutover pointer.The archiver README's anchor lookup. The recovery bullet claimed a five-L1-block window and an
inherited shortcut that accepted any message at or below the L1 finalized block without a lookup. FI-S12
replaced the window with
messageSentSearchWindow, an inclusive[h-49, h+50]clipped at L1 block 1and at the captured head, and N7 deleted the finalized-height short-circuit so every anchor is now a
message a bounded lookup positively placed. Neither claim survived the stack; #25416 never touched this
bullet, because upstream it did not exist in this form.
The archiver README's reorg section. It described walking backwards message by message and rolling
the syncpoint back. The rollback is now one store transaction that also prunes the proposed blocks that
consumed dropped messages (N3c), and it re-fetches unchanged messages the lookup could not place.
The sequencer README's consumption paragraph. It described the checkpoint-wide completion target:
one Inbox read resolving an end for all remaining blocks, with consumption frozen once reached. The
source carried the same stale paragraph at
90c928ec28and #25416 never fixed it. N3b implements90c928ec28's design instead — the endpoint is resolved per block, nothing is retained between blocks,a non-final block takes the further of the resolved endpoint and the safe local step, and only the final
block lands exactly on a boundary or the checkpoint is abandoned. FI-S11 later made that final block
reuse the range already read at the endpoint.
The validator README's checkpoint validation list. It stopped at the archive-root check, omitting
the checkpoint consumed-message content check N3a added and the L1 endpoint gate N6 added, both of which
run before an attestation. Both are now listed, the gate described with N6's actual policy.
Node public-call prediction. The class and method documentation called the appended bundle a lower
bound on what the next block consumes. It is not a bound in either direction: a final block lands on a
live bucket boundary that can sit below the local step, so a call consuming a message the simulation
covers can fail for real.
cb5b03d5bbmade exactly this correction and it holds here, since N3b'sselection is what the node reuses. The
checkpointStartBlockparameter doc was also wrong — it is thelast block of the parent checkpoint, not of the checkpoint being extended, as the code comment four
lines below it already said.
selectSafeLocalEndand the automine comment say the same thing from the sequencer side: thequalifier that only a non-final block may fall back to the safe local step, and that landing on a
boundary can leave observed messages behind.
A unit test in
inbox_message_selection.test.tspins the concrete case the prose describes: cursorat 0, 400 messages observed, live buckets ending at 200 and 400, safe local step 256, final block ending
at 200, message index 220 covered by the estimate and never inserted.
The bucket e2e header comment. It claimed co-timestamped anvil blocks were the only way a bucket
could span two L2 blocks. Since N3b, an ordinary block can stop anywhere inside a bucket it observed
whole; what the co-timestamped blocks actually buy those two scenarios is a bucket still open across the
split and a bucket growing past an already-selected endpoint.
Range-read failures across JSON-RPC.
InboxMessageRangeNotSyncedErrorand thegetL1ToL2MessageRangeinterface doc now state that the class does not survive a JSON-RPC hop and thatcallers must not branch on
instanceof. FI-S08 already depends on this: itsEXPECTED_RANGE_READ_FAILURESclassifier matches message text for precisely this reason.The kv-store range contract.
endwas documented as "the key of the last item to include", which iswrong in both directions. Going forwards the range is
[start, end); going in reverse the inclusivityflips to
(start, end]. The source's correction flatly calledendexclusive, which would have beenwrong here, so the wording states the direction dependence instead. It is pinned by
kv-store/src/interfaces/map_test_suite.tsand already documented in the sqlite-opfs backend.Stale claims deliberately not copied
resolve the bucket pinned to that height, and do not re-read the block hash afterwards. Any prose
describing a second refresh would be false here.
unverifiable) and is not implemented. N6maps its two new reasons onto the existing
unvalidatedoutcome, and the baseline sentinel stillcounts an unvalidated proposer duty against inactivity. Nothing in this rung claims otherwise.
[h-49, h+50]— exactly 100 heights beforeclipping, clipped at L1 block 1 and at the captured head. The README says 100.
on L1's own surface. No prose here describes the node tracking bucket lag.
Deliberately out of scope
validator-client/src/proposal_handler.ts: #25416's JSDoc-reordering hunk is already applied — N3amoved that comment back onto
awaitCheckpointConsumedMessageswhen it ported497132c332.docs/docs-developers/.../migration_notes.mdanddocs/docs-operate/.../changelog/v6.md(
8f2d79bfc7) are owned byaztec-packages.aztec.jsreference (0df3fa25de) lives in the docs site, not here.spartan/, root docs, Noir, L1 and bb files from old #25416.was recorded rather than made — see below.
Stack position
This is rung 23 of 25 in the Fast Inbox node stack, stacked on
spl/fi-n9-leila-cleanups.Tests
The diff is documentation and comments in every package except
sequencer-client, which gains one unittest. Red/green does not apply to prose and was not fabricated.
yarn build: green.yarn formatandyarn lint: clean.@aztec-labs/sequencer-clientfull suite: 12 suites, 306 passed / 1 skipped (base 305/1, soexactly the one added test).
inbox_message_selection.test.tsalone: 18/18 (base 17).@aztec-labs/kv-storetest:node: 289 passed, at base parity — the change there is a JSDoc, run onlyto confirm the direction-dependent bound semantics the new wording asserts.
archiver,aztec-node,aztec.js,stdlib,validator-clientandend-to-endchanges arecomment- or README-only; their suites were not re-run for show.
Recorded, not fixed
The new unit test is a pin, not red/green evidence: no production code changed, so it passes before and
after by construction. It would redden if
selectSafeLocalEndstarted consulting L1 or ifresolveEndpointstopped clamping a final block to the newest boundary at or below its bound.