open-standards/wai/wai-ledger/README.md

wai-ledger

The WAI receipt ledger (extensions/receipt-ledger.md) as a service. A seller and a buyer both sign a tariff. The ledger verifies each record it is given by the extension that defines it: a room's session receipt, a delivering party's settlement statement with the acknowledgements its downstream parties signed, a package receipt with its indexes, an ad room's receipts with the players' presentation claims. For a period, it signs the invoice whose every line cites the records it came from, with the joules those records state per scope and per acquisition class, and two reports: the ad decisions against the presentation claims, and the delivery of each party with the bytes two parties were acknowledged for twice.

Every invoice is served with its verification document: the tariff, the invoice, the invoice before it in its chain, and the sources. Any verifier of the extension checks it without this service, the corpus's second implementation among them:

python3 -I ../live-conformance/receipt_ledger_verify.py --document document.json

Payments and tax are not here: an invoice is the figures a payment rests on.

Running it

cargo build --locked --release
WAI_LEDGER_DIR=/path/to/ledger WAI_LEDGER_KEY=/path/to/seller.key WAI_LEDGER_ADDR=127.0.0.1:8251 \
  ./target/release/wai-ledger serve

variable	meaning
WAI_LEDGER_DIR	the directory the service owns (required); created when absent
WAI_LEDGER_KEY	the seller key's file: 32 bytes, the Ed25519 seed; made with mode 0600 when absent
WAI_LEDGER_ADDR	the address it listens on (default 127.0.0.1:8251)

wai-ledger key prints the seller key of WAI_LEDGER_KEY, which a buyer's tariff names as its seller. wai-ledger verify FILE prints a verification document's outcome.

The directory:

LOCK                                  held exclusively while a process serves the directory
tariffs/<digest>/tariff.wlt           the tariff, both signatures
tariffs/<digest>/sources/<n>.json     the sources held, in the order they arrived
tariffs/<digest>/invoices/<n>.wli     the chain, in order
tariffs/<digest>/invoices/<n>.json    each invoice's verification document

Every file is written whole: to a temporary name, synced, renamed into place, and its directory synced. On start the service takes the lock (a second process on the same directory is refused), then reads every tariff, source and invoice back and verifies each again, and refuses to start on a chain that does not link.

Endpoints

GET /v1	the service, its seller key and its limits
GET /v1/health	ok
POST /v1/tariffs	{"tariff": <hex>}: a tariff whose seller is the service's key, both signatures verified; 201 and its digest
GET /v1/tariffs/{digest}	the tariff, its chain of invoices, and the sources held and not yet billed
POST /v1/sources	{"tariff": <digest>, "source": {...}}: the source verified by its extension, in the tariff's scope, under no other tariff, within the tariff's period, and checked against every source held (record_duplicate, record_overlap) and every record billed (record_rebilled); 201 and the records it holds
POST /v1/invoices	{"tariff": <digest>, "start": <µs>, "end": <µs>}: the invoice of the period over the sources held, not yet billed, that lie in it (a package always does), chained after the last, signed, verified and kept; 201, the invoice, its outcome with the reports, and its verification document
GET /v1/invoices/{digest}	the invoice, its outcome and its verification document
POST /v1/verify	a verification document: its outcome
GET /metrics	the service's counters in the text exposition format (../wai-metrics): requests by route, method and status (wai_ledger_requests_total), the tariffs, sources and invoices held, and the verifications running. No tariff, party, key or client is a label. It is the operator's, not an operation of the extension: a request that came through a front is answered 404, and a front that sets no forwarding field is configured not to pass the path on

A refusal is 422 with {"outcome": "refuse", "reason", "at"}, the extension's reason and place; a source refused by its own extension names that extension's reason and its place after "source". A body that is not what the endpoint takes is 400; an unknown tariff or invoice is 404. A request body is at most 64 MiB. Requests that change the ledger run one at a time; POST /v1/verify and GET /v1/invoices/{digest} verify at most two documents at a time.

The service has no accounts: a tariff binds a buyer by the buyer's own signature, and a source is accepted only when it verifies and the tariff's scope names its party, whoever submits it.

Checks

cargo test --locked --release          # the corpus's invoices issued byte for byte, the chain
                                       # recovered after a restart, each source billed once,
                                       # one process per directory
bash smoke.sh http://127.0.0.1:18251   # over HTTP, against an instance started with the corpus's
                                       # seller key (see .github/workflows/wai-ledger.yml)