wai.delivery.settlement (E6): a hop is paid only for bytes the next hop signed for #404

Merged

dcharlot merged 6 commits from wai/settlement into main 2026-10-21 19:12:00 -04:00

Conversation 0 Commits 6 Files changed 19 +6166 -17

dcharlot commented 2026-10-21 13:36:23 -04:00

Owner

Copy link

wai.delivery.settlement (E6): a hop is paid only for bytes the next hop signed for

Delivery settled on what the party that received it signed, not on the sender's own logs.

What is in it

• wai/extensions/settlement.md, which registers the record wai.delivery.settlement:

  • Acknowledgement WDA1 (§3). The downstream party (a next hop or a sink) signs what it received in a window. Each entry covers one object class (live, fetch, fill, ancillary) under one grant and one proof. It states the objects as the tree root of jwp-receipts §2.2 (unlabelled leaves, so a whole group in order gives the publisher's root), and gives a count, a byte count and the SHA-256 of the item list. The item list travels beside the record: content hash, start, end. Records of one (mode, upstream, downstream) form a chain: windows do not overlap, and prev names the record before. A relay acknowledges upstream and is acknowledged downstream over the same content hashes. A hop's billable bytes are exactly the bytes its downstream parties signed for. An acknowledgement whose downstream is its own upstream is refused (self_acknowledged).

  • Unacknowledged delivery (§4). A hop whose downstream will not or cannot sign uses a declaration: the same layout with mode 2, signed by the hop. It is counted in its own class, unacknowledged: never zero, never billed, and never covering a byte the same party acknowledged in an overlapping window (declared_and_acknowledged). Bearers: "a unidirectional bearer settles under unidirectional-delivery §4", with no duplication of T2's work.

  • Range proof WBR1 (§5). It carries the covered chunks of a range plus the chaining value of every subtree of BLAKE3's chunk tree that lies outside them, and it verifies to the content hash. It generalises http-delivery §6's head proof, whose ranges start at 0. A proof establishes the object's length only when it reaches the last chunk (a tail proof), and the verifier reports whether it did. §5.6 defines audits: an auditor names an acknowledged item and asks for a proof of a range within it.

  • Paid retrieval (§6). A fetch below the live edge, a recording fetch, or a fill past a cache is billed only to a room grant whose WRP1 proof the request carried. Each entry is checked against live-rooms §10.5.4 steps 2–5, the grant's window and the seek power, and one proof pays for one record (pop_replayed). A retrieval made without a grant is free, and a statement that bills it is refused (paid_without_grant).

  • Statement WSS1 (§7). One per party per period. It holds:

    • lines by object class and payer (the downstream key for delivery classes, the grant for retrieval classes);
    • the acknowledged bytes by class, and the declared bytes;
    • joules by acquisition class from the party's WMH1 records, never summed across classes (classes_summed);
    • the amount under a declared tariff, in millionths of a minor unit per 10^9 bytes, rounded down once per line.

    The verifier recomputes every figure. A line that bills bytes no acknowledgement covers is bytes_not_acknowledged; any other difference is statement_mismatch. Line kind 2 is reserved for a payee that is not a hop (the CO6 slot), with payee and payer already in the line layout. This revision refuses it.

  • Logs (§9). Each acknowledged item maps onto an RFC 7937 cdni_http_request_v1 record (cdni_http_request_v2 under RFC 9246), with the acknowledgement's digest in a remark directive. §9.2 states what a log cannot carry: a counter-signature. Each log record is the writer's own word, and SHA256-hash is the writer's own integrity hash. A log therefore maps onto declarations, never onto acknowledgements. §9.3 covers SVTA2050, SVTA2007 and SVTA2006, cited by identifier only. Only their published summaries could be read, and the text says so.

  • Viewers as relays over ciphertext (§10, built). An acknowledgement binds the content hash of the sealed bytes, so a forwarder that cannot open what it forwards earns acknowledged bytes and can prove ranges of them. The corpus has one such statement and one sealed range proof.

  • §11 is the reasons table (19 codes). §13 states what an acknowledgement reveals and to whom, with no gate of its own (per the owner rule). A regime that asks the operator for a lawful basis is pointed at the lawful-basis declaration (jwp-receipts §2.4.6).

• wai-rs module settlement (feature settlement = ["live_metering", "jwp_hash"], no new dependency). It has the records, the range proof via blake3's hazmat API (as the head proof uses it), grant and proof checks via live_room, WMH1 via live_metering, verify, and unit tests. It also has the generator wai_settlement_vectors and tests/settlement.rs.
• Corpus wai/live-conformance/settlement/, written from fixed seeds:

  • 48 statements. Five are accepted:

    • a relay paid by an edge and a viewer, with two declarations and two energy classes;
    • an edge with a granted DVR fetch, a partial object and a free fetch;
    • an origin's fills billed to the viewer's grant, beside an ungranted free fill;
    • a viewer forwarding sealed objects;
    • an unmetered hop.

    The rest are refused, each a control of one defect. They include every negative the brief named: billing bytes no acknowledgement covers, an acknowledgement signed by the hop itself, a paid fetch without a grant, joules summed across classes, a statement that does not recompute, and an acknowledgement replayed from another period.

  • 24 range proofs. Accepted cases include an interior range, the head, the tail (length established), one chunk, whole objects, a sealed object, an answered audit, and an interior range under a wrong length that leaves the tree's shape unchanged (accepted, length not established). Refused cases include a range past the end, an empty range, bytes of another object, a range past the true end under a longer length, a chaining value dropped, added or changed, another content hash, an audit outside its item, and records that do not read.

• Independent verifier live-conformance/settlement_verify.py, run as python3 -I. It shares no code with wai-rs. It reuses BLAKE3 from claim-conformance/_blake3.py by import (the pattern exists: its subtree_cv and parent_cv are the head proof's tree), strict Ed25519 from _ed25519.py, and live_rooms_verify.py / live_metering_verify.py for rooms, grants, proofs and WMH1. It requires every mutated copy of the corpus to fail, and drops each of its own 29 checks in turn, requiring the corpus to catch each one.
• Wiring.
  • a CI step in wai-conformance.yml, with the extension added to paths:;
  • the REGISTRY.md record list, SPEC.md §5 (record list and paragraph) and the CHANGELOG.md entry;
  • codecs/registry.rs (CAP_DELIVERY_SETTLEMENT, and the wire identifiers WDA1 §3.1, WBR1 §5.2, WSS1 §7.1), with the registry export regenerated;
  • the int_kernels_vectors.rs exclusion reason for live-conformance extended to settlement;
  • the corpus README with a **Provenance.** line, and live-conformance/README.md.

Design decisions and why

• Time is Unix microseconds, not a room clock. A statement settles a party across rooms and outside rooms. WMH1 spans are placed with their room's t0, read from the descriptor the verifier is given.
• The verifier finds a record by the digest of the bytes it is given, never by a stated key. So a truncated record can never be found under its name, and bad bytes cannot pose as a record.
• Item lists are signed by digest, and their content hashes also by the §2.2 root. The root keeps one-object inclusion proofs and publisher-root equality. The digest binds the byte ranges.
• One proof pays for one record. A statement verifier cannot check the serving hop's challenge or context (live-rooms §10.5.4 steps 6–7), so it checks the possession steps, the grant window and the seek power, and refuses reuse across records.
• Unacknowledged bytes have their own figures and never appear in a line. A CDNI log is mapped onto declarations for the same reason.

Checks (all cargo work ran on the build host via rb)

check	command	result
corpus regenerates and verifies	cargo run --no-default-features --features settlement --bin wai_settlement_vectors -- gen/verify ../live-conformance/settlement	PASS, PASS
module tests	cargo test --no-default-features --features settlement --lib settlement::	5 passed
corpus test	cargo test --no-default-features --features settlement --test settlement	4 passed
clippy	cargo clippy --no-default-features --features settlement --all-targets	no notes in settlement files (pre-existing notes elsewhere, e.g. unpinned_read dead code, which also appears with --features live_metering alone)
second implementation	python3 -I live-conformance/settlement_verify.py live-conformance/settlement	exit 0: 48 statements, 24 ranges, 18 mutated copies fail, 29 weakened verifiers fail
neighbouring verifiers	live_events, live_rooms, live_metering, energy_steering, ai_usage, live_moderation _verify.py, and http_verify.py	all exit 0
registry	cargo run --no-default-features --bin wai -- registry export then --check; cargo test --lib codecs::registry	up to date; 14 passed
provenance	cargo test --no-default-features --test corpus_provenance --test cli_registry; --test int_kernels_vectors every_decoded_output_states_a_sha256 (CI feature set)	pass
repo checks	check-tests-in-ci.py, check-workflow-concurrency.sh, check-spec-refs.py, check-wai-section-refs.py, check-no-vanity-metrics.sh, test-public-text-checks.sh, check-comparative-prose.sh, check-orphan-sources.py	all clean

Not run: check-public-names.sh, which needs the private WAI_NAME_DENYLIST. CI runs it.

Falsifications (committed first, then broken on the host and restored)

broken rule	result
the self_acknowledged check	cargo test --test settlement exit 101
exact consumption of chaining values	exit 101
the bytes_not_acknowledged check	exit 101
a row dropped from §11	the_extension_lists_the_reasons fails, and settlement_verify.py exits 1 ("18 reasons")

After restoring, exit 0. The Python verifier's own drop-each-check loop first found two checks the corpus did not exercise: item-list overlap, and a proof whose content_hash field names another object. Two vectors were added for them (items_share_a_byte, names_another_content_hash).

Not done

• Real money, payment rails and any outward contact (out of scope).
• Line kind 2 is reserved and refused, for CO6.
• SVTA2050's added fields are not mapped, because its body is not public.
• A conservation check, matching what a relay bills against what it acknowledged upstream across one period, is described in §3.7 but is not a refusal.

🤖 Generated with Claude Code

## `wai.delivery.settlement` (E6): a hop is paid only for bytes the next hop signed for Delivery settled on what the party that received it signed, not on the sender's own logs. ### What is in it - **`wai/extensions/settlement.md`**, which registers the record `wai.delivery.settlement`: - **Acknowledgement `WDA1` (§3).** The downstream party (a next hop or a sink) signs what it received in a window. Each entry covers one object class (`live`, `fetch`, `fill`, `ancillary`) under one grant and one proof. It states the objects as the tree root of jwp-receipts §2.2 (unlabelled leaves, so a whole group in order gives the publisher's root), and gives a count, a byte count and the SHA-256 of the item list. The item list travels beside the record: content hash, start, end. Records of one (mode, upstream, downstream) form a **chain**: windows do not overlap, and `prev` names the record before. A relay acknowledges upstream and is acknowledged downstream over the same content hashes. A hop's billable bytes are exactly the bytes its downstream parties signed for. An acknowledgement whose downstream is its own upstream is refused (`self_acknowledged`). - **Unacknowledged delivery (§4).** A hop whose downstream will not or cannot sign uses a **declaration**: the same layout with mode 2, signed by the hop. It is counted in its own class, `unacknowledged`: never zero, never billed, and never covering a byte the same party acknowledged in an overlapping window (`declared_and_acknowledged`). Bearers: "a unidirectional bearer settles under unidirectional-delivery §4", with no duplication of T2's work. - **Range proof `WBR1` (§5).** It carries the covered chunks of a range plus the chaining value of every subtree of BLAKE3's chunk tree that lies outside them, and it verifies to the content hash. It generalises http-delivery §6's head proof, whose ranges start at 0. A proof establishes the object's length only when it reaches the last chunk (a tail proof), and the verifier reports whether it did. §5.6 defines audits: an auditor names an acknowledged item and asks for a proof of a range within it. - **Paid retrieval (§6).** A fetch below the live edge, a recording fetch, or a fill past a cache is billed only to a room grant whose `WRP1` proof the request carried. Each entry is checked against live-rooms §10.5.4 steps 2–5, the grant's window and the seek power, and one proof pays for one record (`pop_replayed`). A retrieval made without a grant is free, and a statement that bills it is refused (`paid_without_grant`). - **Statement `WSS1` (§7).** One per party per period. It holds: - lines by object class and payer (the downstream key for delivery classes, the grant for retrieval classes); - the acknowledged bytes by class, and the declared bytes; - joules by acquisition class from the party's `WMH1` records, never summed across classes (`classes_summed`); - the amount under a declared tariff, in millionths of a minor unit per 10^9 bytes, rounded down once per line. The verifier recomputes every figure. A line that bills bytes no acknowledgement covers is `bytes_not_acknowledged`; any other difference is `statement_mismatch`. **Line kind 2 is reserved** for a payee that is not a hop (the CO6 slot), with `payee` and `payer` already in the line layout. This revision refuses it. - **Logs (§9).** Each acknowledged item maps onto an RFC 7937 `cdni_http_request_v1` record (`cdni_http_request_v2` under RFC 9246), with the acknowledgement's digest in a `remark` directive. §9.2 states what a log cannot carry: a counter-signature. Each log record is the writer's own word, and `SHA256-hash` is the writer's own integrity hash. A log therefore maps onto declarations, never onto acknowledgements. §9.3 covers SVTA2050, SVTA2007 and SVTA2006, cited by identifier only. Only their published summaries could be read, and the text says so. - **Viewers as relays over ciphertext (§10, built).** An acknowledgement binds the content hash of the sealed bytes, so a forwarder that cannot open what it forwards earns acknowledged bytes and can prove ranges of them. The corpus has one such statement and one sealed range proof. - §11 is the reasons table (19 codes). §13 states what an acknowledgement reveals and to whom, with no gate of its own (per the owner rule). A regime that asks the operator for a lawful basis is pointed at the `lawful-basis` declaration (jwp-receipts §2.4.6). - **`wai-rs` module `settlement`** (feature `settlement = ["live_metering", "jwp_hash"]`, no new dependency). It has the records, the range proof via blake3's `hazmat` API (as the head proof uses it), grant and proof checks via `live_room`, `WMH1` via `live_metering`, `verify`, and unit tests. It also has the generator `wai_settlement_vectors` and `tests/settlement.rs`. - **Corpus `wai/live-conformance/settlement/`**, written from fixed seeds: - **48 statements.** Five are accepted: - a relay paid by an edge and a viewer, with two declarations and two energy classes; - an edge with a granted DVR fetch, a partial object and a free fetch; - an origin's fills billed to the viewer's grant, beside an ungranted free fill; - a viewer forwarding sealed objects; - an unmetered hop. The rest are refused, each a control of one defect. They include every negative the brief named: billing bytes no acknowledgement covers, an acknowledgement signed by the hop itself, a paid fetch without a grant, joules summed across classes, a statement that does not recompute, and an acknowledgement replayed from another period. - **24 range proofs.** Accepted cases include an interior range, the head, the tail (length established), one chunk, whole objects, a sealed object, an answered audit, and an interior range under a wrong length that leaves the tree's shape unchanged (accepted, length **not** established). Refused cases include a range past the end, an empty range, bytes of another object, a range past the true end under a longer length, a chaining value dropped, added or changed, another content hash, an audit outside its item, and records that do not read. - **Independent verifier `live-conformance/settlement_verify.py`**, run as `python3 -I`. It shares no code with wai-rs. It reuses BLAKE3 from `claim-conformance/_blake3.py` by import (the pattern exists: its `subtree_cv` and `parent_cv` are the head proof's tree), strict Ed25519 from `_ed25519.py`, and `live_rooms_verify.py` / `live_metering_verify.py` for rooms, grants, proofs and `WMH1`. It requires every mutated copy of the corpus to fail, and drops each of its own 29 checks in turn, requiring the corpus to catch each one. - **Wiring.** - a CI step in `wai-conformance.yml`, with the extension added to `paths:`; - the `REGISTRY.md` record list, `SPEC.md` §5 (record list and paragraph) and the `CHANGELOG.md` entry; - `codecs/registry.rs` (`CAP_DELIVERY_SETTLEMENT`, and the wire identifiers `WDA1` §3.1, `WBR1` §5.2, `WSS1` §7.1), with the registry export regenerated; - the `int_kernels_vectors.rs` exclusion reason for `live-conformance` extended to settlement; - the corpus README with a `**Provenance.**` line, and `live-conformance/README.md`. ### Design decisions and why - **Time is Unix microseconds, not a room clock.** A statement settles a party across rooms and outside rooms. `WMH1` spans are placed with their room's `t0`, read from the descriptor the verifier is given. - **The verifier finds a record by the digest of the bytes it is given**, never by a stated key. So a truncated record can never be found under its name, and bad bytes cannot pose as a record. - **Item lists are signed by digest, and their content hashes also by the §2.2 root.** The root keeps one-object inclusion proofs and publisher-root equality. The digest binds the byte ranges. - **One proof pays for one record.** A statement verifier cannot check the serving hop's challenge or context (live-rooms §10.5.4 steps 6–7), so it checks the possession steps, the grant window and the seek power, and refuses reuse across records. - **Unacknowledged bytes have their own figures and never appear in a line.** A CDNI log is mapped onto declarations for the same reason. ### Checks (all cargo work ran on the build host via `rb`) | check | command | result | |---|---|---| | corpus regenerates and verifies | `cargo run --no-default-features --features settlement --bin wai_settlement_vectors -- gen/verify ../live-conformance/settlement` | PASS, PASS | | module tests | `cargo test --no-default-features --features settlement --lib settlement::` | 5 passed | | corpus test | `cargo test --no-default-features --features settlement --test settlement` | 4 passed | | clippy | `cargo clippy --no-default-features --features settlement --all-targets` | no notes in settlement files (pre-existing notes elsewhere, e.g. `unpinned_read` dead code, which also appears with `--features live_metering` alone) | | second implementation | `python3 -I live-conformance/settlement_verify.py live-conformance/settlement` | exit 0: 48 statements, 24 ranges, 18 mutated copies fail, 29 weakened verifiers fail | | neighbouring verifiers | `live_events`, `live_rooms`, `live_metering`, `energy_steering`, `ai_usage`, `live_moderation` `_verify.py`, and `http_verify.py` | all exit 0 | | registry | `cargo run --no-default-features --bin wai -- registry export` then `--check`; `cargo test --lib codecs::registry` | up to date; 14 passed | | provenance | `cargo test --no-default-features --test corpus_provenance --test cli_registry`; `--test int_kernels_vectors every_decoded_output_states_a_sha256` (CI feature set) | pass | | repo checks | `check-tests-in-ci.py`, `check-workflow-concurrency.sh`, `check-spec-refs.py`, `check-wai-section-refs.py`, `check-no-vanity-metrics.sh`, `test-public-text-checks.sh`, `check-comparative-prose.sh`, `check-orphan-sources.py` | all clean | Not run: `check-public-names.sh`, which needs the private `WAI_NAME_DENYLIST`. CI runs it. ### Falsifications (committed first, then broken on the host and restored) | broken rule | result | |---|---| | the `self_acknowledged` check | `cargo test --test settlement` exit 101 | | exact consumption of chaining values | exit 101 | | the `bytes_not_acknowledged` check | exit 101 | | a row dropped from §11 | `the_extension_lists_the_reasons` fails, and `settlement_verify.py` exits 1 ("18 reasons") | After restoring, exit 0. The Python verifier's own drop-each-check loop first found two checks the corpus did not exercise: item-list overlap, and a proof whose `content_hash` field names another object. Two vectors were added for them (`items_share_a_byte`, `names_another_content_hash`). ### Not done - Real money, payment rails and any outward contact (out of scope). - Line kind 2 is reserved and refused, for CO6. - SVTA2050's added fields are not mapped, because its body is not public. - A conservation check, matching what a relay bills against what it acknowledged upstream across one period, is described in §3.7 but is not a refusal. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 5 commits 2026-10-21 13:36:24 -04:00

wai: delivery settlement — acknowledgements, range proofs, paid retrieval and statements (spec text and reference module, in progress) ... 6eef9a3b8a

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai: settlement corpus, its README, and the independent Python verifier ... 46508a0fdb

The corpus holds 48 statements and 24 range proofs written from fixed
seeds; wai-rs and settlement_verify.py agree on every outcome, every
mutated copy fails, and every check the Python verifier drops is caught.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai: register wai.delivery.settlement — registry, wire identifiers, SPEC §5, CHANGELOG and the CI step ... 436ca07b8d

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai: settlement — clippy's let chains and as_chunks ... 2e46cfa72c

Co-Authored-By: Claude Opus 5.5 <[email protected]>

wai: settlement §13 — what an acknowledgement reveals and to whom; a regime's lawful basis is a lawful-basis declaration ... 63cfd68220

The acknowledgement and its settlement are the delivery service's own
mechanics, with no gate of their own: the text states what each party
learns, and points a regime that asks the operator for a lawful basis
to jwp-receipts §2.4.6.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot added 1 commit 2026-10-21 19:11:44 -04:00

Merge origin/main into wai/settlement (contribution records) ... 869d5d4694

Co-Authored-By: Claude Opus 5.5 <[email protected]>

dcharlot merged commit 22c8427255 into main 2026-10-21 19:12:00 -04:00

dcharlot referenced this pull request from a commit 2026-10-21 19:12:02 -04:00

Merge pull request 'wai.delivery.settlement (E6): a hop is paid only for bytes the next hop signed for' (#404) from wai/settlement into main

dcharlot referenced this pull request 2026-10-21 20:06:59 -04:00

wai.media.takedown: takedown across every rendition and cache, against the regime's clock (TKD) #420

dcharlot referenced this pull request 2026-10-22 03:14:15 -04:00

wai.media.upscale: super-resolution as an exact derivation, residuals against it, per-title priors, and an account of sink-made pictures (C3) #408

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!404

No description provided.