Skip to content

Commit ff5965b

Browse files
committed
Revert "docs: document header body-size hints"
This reverts commit 1b7d873.
1 parent 1b7d873 commit ff5965b

1 file changed

Lines changed: 4 additions & 24 deletions

File tree

‎docs/design/verified-commitment-trees.md‎

Lines changed: 4 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -143,20 +143,15 @@ the header chain, servable only by a node holding the validated headers, and nee
143143
ahead of_ the committer. So they are **carried in-band on the header-sync `Headers` message**
144144
rather than over a separate stream. `GetHeaders` gains a `want_tree_aux_roots` flag, and a
145145
`Headers` response carries an **all-or-nothing** `tree_aux_roots` vector parallel to `headers`
146-
(§5.4). The same `Headers` response also carries a `body_sizes` vector, one advisory
147-
serialized-body-size hint per header. These size hints are not commitment roots and are used
148-
only to schedule block downloads (§5.4). The header-sync stream version is bumped (2 → 4) for
149-
the new field.
146+
(§5.4). The header-sync stream version is bumped (2 → 4) for the new field.
150147

151148
Roots are requested and accepted **only for finalized (checkpoint-verified) header ranges** — the
152149
reactor rejects roots on a non-finalized range, and rejects roots a request opted out of, as
153150
`MalformedMessage` (§8.1). When a finalized header range commits via `CommitHeaderRange`, its
154151
roots are **persisted into the `zakura_header_commitment_roots_by_height` column family ahead of
155152
body commit** (§5.3). The committer then reads them per height through the `PeerSource` seam.
156-
The same header commit stores non-zero advertised body-size hints in
157-
`zakura_header_body_size_by_height`, so block sync can later request realistic ranges even
158-
before the corresponding bodies are committed. Headers, body-size hints, and roots arrive
159-
together, so a range's root coverage is known before any of its roots can trigger the fast path.
153+
Headers and their roots arrive together, so a range's root coverage is known before any of its
154+
roots can trigger the fast path.
160155

161156
The one coupling to bodies: verifying a root via the ZIP-221 MMR leaf needs the block's
162157
tx-counts (from the body), so roots are **consumed** at commit time with bodies even though they
@@ -171,9 +166,7 @@ only ever looks up a root for a block it is about to commit, and persisted provi
171166
naturally bounded above by the header tip and cleaned up below it: each provisional root is
172167
**deleted from `zakura_header_commitment_roots_by_height` when its block body commits** (so the
173168
column family does not grow without bound), and header-store rollback also trims provisional
174-
roots above the rollback target (§5.3). Advertised body-size hints follow the same header-store
175-
lifecycle: header reorgs and rollbacks drop stale hints, and committed block sizes take
176-
precedence once the corresponding body is durable.
169+
roots above the rollback target (§5.3).
177170

178171
### 4.4 Mode selection: fast under checkpoint sync
179172

@@ -297,22 +290,9 @@ places (`zebra-network/src/zakura/header_sync/wire.rs`):
297290
- `Headers { headers, body_sizes, tree_aux_roots }` — `tree_aux_roots` is **all-or-nothing**:
298291
either empty, or exactly one `BlockCommitmentRoots` per header, in ascending height order
299292
aligned to `start_height`. A one-byte `has_roots` marker precedes the roots on the wire.
300-
`body_sizes` is always parallel to `headers`; each entry is an advisory serialized body size,
301-
with `0` meaning unknown.
302-
303-
Body-size hints are scheduling data, not consensus data. `CommitHeaderRange` persists non-zero
304-
advertised hints for header-ahead heights, preserving the maximum non-zero hint for the same
305-
header and clearing hints when a competing higher-work header chain replaces the range.
306-
`ReadRequest::BlockSizeHints` returns the durable committed block size when available, otherwise
307-
the advertised hint, otherwise `None`. Block sync uses those hints to pack contiguous
308-
`GetBlocks` ranges by estimated bytes and to set receive-path size-mismatch tolerance; the
309-
downloaded body still has to hash to the committed header, and the actual serialized size is
310-
settled when the body is received.
311293

312294
Wire and DoS bounds:
313295

314-
- The `body_sizes` count must exactly match the header count (`BodySizeCountMismatch`); there is
315-
no independent untrusted body-size length to preallocate from.
316296
- The byte budget that bounds a `Headers` message accounts for the per-header root
317297
(`HEADER_SYNC_BLOCK_COMMITMENT_ROOTS_BYTES = 4 + 32 + 32`), and the static
318298
range-fits-budget assertion includes it, so requesting roots reduces the per-message header

0 commit comments

Comments
 (0)