docs(dig-node): correct inbound-demand proximity + gap_fill anchor contract wording - #171
Merged
Merged
Conversation
Co-Authored-By: Claude <noreply@anthropic.com>
…ntract wording (#2050) Make the normative SPEC + doc-comments state ONLY the security properties the code actually enforces. No behaviour change (docs-only). Item 1: soften the INBOUND_DEMAND_MIN_PROXIMITY / SPEC §7.10d claim that naming a near key costs an on-chain mint. The gate binds WHERE a peer can steer caching (near this node's peer_id, unmovable) — not the cost of triggering network work: a near key naming no real store just finds no DHT providers and fails cheaply. The mint + merkle cost binds a later step — becoming a cached HOLDER (serve-time root-pin + merkle bind the anchor). Item 2: reconcile the gap_fill_generation contract with its inbound-demand caller. Document the sanctioned caller-chosen-root exception: inbound-demand passes a peer-supplied root on purpose (demand-caching warms the requested capsule); it is safe because merkle + the serve-time pin bind the anchor regardless of who chose the root, so the worst case is caching REAL near-neighbourhood content of a possibly-old generation (#1623), never junk. Version 0.93.2 -> 0.93.3 (patch, docs only). Co-Authored-By: Claude <noreply@anthropic.com>
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
2 participants
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.
Closes dig_ecosystem#2050 (items 1 + 2). Doc/contract-accuracy follow-up from #2014 — flagged by that PR's adversarial gate + loop-security. No behaviour change.
Why
The inbound-demand proximity docs claimed a stronger security property than the code enforces: that grinding a store key toward this node's
peer_id(to steer caching) costs real on-chain mints. An overstated invariant in a normative SPEC is a latent hazard — future work must not rely on it.What the code actually enforces (traced):
note_inbound_demand→inbound_demand_pull_admitted(XOR-proximity gate vsnode_peer_id) →spawn_capsule_backfill→gap_fill_generation(store, peer-supplied root)→cache_fetch_and_cache→sync_module_from(lands at the served root; does NOT resolve a chain-anchored root itself). The anchor binds downstream: merkle verification againstroot+ the serve-time read-path pin (§14.4) — content is never served as current unless its root equals the chain-anchored tip. The proximity gate imposes no per-key mint cost; a near key naming no real store simply finds no DHT providers and fails cheaply.What changed (docs/prose only)
crates/dig-node-core/src/relevance.rs(INBOUND_DEMAND_MIN_PROXIMITYdoc) — now states what the gate binds (confines where a peer can steer caching, near the unmovablepeer_id) and what it does NOT (impose a naming/mint cost on triggering the cheap DHT lookup).crates/dig-node-core/src/lib.rs(inbound_demand_pull_admitteddoc) — dropped the mint-cost clause.SPEC.md§7.10d — same correction in normative prose.gap_fill_generationdoc-contract (crates/dig-node-core/src/seams/capsule/capsule_store.rs): it asserted itsrootis "never a caller-chosen root", but inbound-demand legitimately passes a peer-supplied root. Documented the sanctioned exception (inbound-demand passes a peer-supplied root on purpose; must NOT be re-routed through the anchored-root resolver — that would defeat demand-caching's purpose) with the safety rationale (merkle + serve-time pin bind the anchor → worst case is caching REAL near-neighbourhood content of a possibly-old generation, per #1623, never junk/out-of-neighbourhood/fabricated). Softened the contract's opening "verify against the chain-anchored root" → "merkle-verify againstroot".Item 3 deferred (proximity tightening toward k-closest for the
DIG_NODE_INBOUND_DEMAND_CACHEdefault-ON flip) — needs a live network-size signal + a fresh security review; stays open on #2050.How verified
cargo build -p dig-node-coreclean;cargo test -p dig-node-core --lib→ 653 passed, 0 failed (doctests unaffected);cargo fmt --allclean.git diff --stat= exactly the intended files; no stray edits. Confirmed the specific overstatement did not propagate elsewhere (the other "grind" mentions in the SPEC are distinct, accurate claims about the 256-bit-preimage XOR signal, not the mint-cost claim).Version
root
[workspace.package].version0.93.2 → 0.93.3 (patch, docs);Cargo.lockregenerated.Generated by Claude Code