open-standards/wai/live-conformance/settlement

live-conformance/settlement — delivery settlement

The corpus of extensions/settlement.md §12: objects, a room with its grants, acknowledgements and declarations (WDA1, a node's declarations of its own instance among them, §4.4) with their item lists, the proof records (WRP1, live-rooms §10.5.1) their retrievals carried, per-hop records (WMH1, live-metering §3), and two kinds of vector: settlement statements (WSS1) and range proofs (WBR1), each with the outcome a verifier gives it.

It sits beside rooms/ and metering/ because its grants and proofs are live-rooms', read by that corpus's second implementation, live_rooms_verify.py, and its hop records are live-metering's, read by live_metering_verify.py.

Settlement equivalence. For each statement, a conforming verifier given the statement, the pool's records, item lists, proofs and hop records less those the vector withholds (by digest, §8.2) and with those it adds in extra, and the rooms it names, reaches the outcome the vector states (§8.3):

• refuse: the reason and where, at: ["statement"], ["room", id] or ["room", id, "grant", i], ["record", k] for the record k the statement names, ["record", k, "entry", j] for one of its entries, ["hop", k], or ["basis", k] for the basis of an attribution line;
• accept: the statement's digest, its currency (or null), the acknowledged objects and bytes by object class, each delivery line (class, payer, objects, bytes, amount, and whether it is free), each attribution line where it has any (attribution: payee, class, basis, objects, bytes, amount), the unacknowledged figures, the energy's coverage, unmetered and totals by class label, and the amount.

For each range proof, a conforming verifier given the proof, the content_hash it is checked against and the item of the audit it answers (or none, when null) reaches the outcome it states: refuse with its reason, or accept with the range, envelope_len, the covered chunks as offsets into X, and whether the length was established (§5.5). A verifier that reaches another outcome, reason, place or figure does not conform.

Provenance. Generated here: wai_settlement_vectors gen writes vectors.json from figures written in code, from fixed seeds: each key is SHA-256 of the corpus's fixed label and the principal's index, each object's bytes a SHA-256 stream of another fixed label and the object's name, each proof's challenge SHA-256 of a third label and an index, and every time is a constant (the room's t0 is 2026-10-16T00:00:00Z, and every statement settles its first minute); Ed25519 signing is deterministic (RFC 8032), so the file is the same bytes on every machine. The objects are opaque test bytes standing for envelopes, which nothing parses or decodes; those named s* stand for sealed objects, whose bytes are opaque as ciphertext is. The byte counts, prices and joule figures are synthetic constants chosen to exercise the rules, and were measured by nothing: the corpus states what the rules compute and claims nothing about what any delivery costs. The origins and URIs are .example names (RFC 2606). The generator asserts that each vector reaches the outcome it was written to have before it writes it.

Layout

One file, vectors.json:

• principals: the keys, by name (informative): a room authority and clock, an origin, a relay, an edge cache, four viewers, a viewer that forwards, and a stranger.
• objects: each object's content hash and length (informative).
• rooms: lesson, its descriptor (WRD1) and its grants (WRG1) in order: viewer A's with the seek power, viewer B's, C's and D's without it, and viewer A's second grant, which expires 15 s into the room; and lesson_forged, the same with a grant the stranger signed. grants names their digests.
• records: every acknowledgement and declaration a vector names, each with its items, one item list per entry, and its digest (informative; a verifier finds a record by the digest of its bytes).
• proofs: proof records by name, among them one by another key, one whose signature is not the key's, one naming another grant and one that does not read.
• hops: per-hop records of the relay (a counter reading, a model, an unmetered marker, one past the period and one whose class breaks live-metering §3.6) and one of the edge.
• statements: accepted, a relay paid by the edge and a viewer with two declarations and its energy in two classes; the edge paid for a granted fetch, a range of an object received in part, and a fetch served free; the origin paid for fills billed to the grant whose request they filled for, beside a fill no grant was presented for; a viewer paid for sealed objects it forwarded, under no tariff; and a relay with an unmetered hop record. Refused, each reason of §11 and the codes it reuses, each a control of one defect.
• ranges: accepted, a range across chunk boundaries, the head, the tail, a range within one chunk, whole objects of one and of several chunks, a range of a sealed object, an audit answered, and an interior range whose stated length is wrong and leaves the tree's shape unchanged; refused, a range past the end, an empty range, another object's bytes, a range past the true end under a longer length, chaining values dropped, added and changed, a proof checked against another content hash and one naming another, an audit the item does not cover, and records that do not read.

Regenerate and verify

cd wai/wai-rs
cargo run --no-default-features --features settlement --bin wai_settlement_vectors -- gen ../live-conformance/settlement
cargo run --no-default-features --features settlement --bin wai_settlement_vectors -- verify ../live-conformance/settlement
cargo test --no-default-features --features settlement --test settlement
python3 -I ../live-conformance/settlement_verify.py ../live-conformance/settlement