open-standards/wai/extensions/rung-price.md

# WAI Extension: Rung Price

> Status: Draft. Registers the record `wai.delivery.rung_price`: a seller's signed list of what it
> charges to deliver a rung, and one rule for comparing delivery options with it. A **rung price
> list** (`wai-rung-prices`, §4) prices delivery per direction (`downlink` or `uplink`), bearer
> class ([bearer-receipts](bearer-receipts.md) §2), footprint of regions delivered to (ISO 3166
> codes in WAI's capitals, §2), ceiling of the rung's rate in bits per second, and unit; each unit
> is priced at the divisor of the ledger field that bills it, in [route-record](route-record.md)'s
> amounts, with the energy the seller states beside it. A seller's latest list stands alone, and
> one that lapses revives none (§5). A comparer's request removes the options its limits remove,
> and ranks the rest by a cost per receiver: a shared transmission's is held to its pass rate and
> divided by the audience the comparer states, or by one, never by an assumed one; the plan states
> the audience at which sharing is no dearer (§6). An energy figure ranks by its class only when
> the seller's own per-hop records, which the list names by digest, bear it out, are current, and
> come from a key the comparer confirmed for that class; any other figure ranks as an estimate, and
> one its own records contradict is set aside (§4.6, §6.4). A list is a quote: a buyer is billed
> only at a tariff it signed ([receipt-ledger](receipt-ledger.md) §4.2), and §7 says which tariff
> field bills each unit. The reference implementation is the `rung_price` module of `wai-rs`
> (feature `rung_price`), with the region code in `wai-rs`'s `region` module; the corpus is
> [`live-conformance/prices/`](../live-conformance/prices/), and its second implementation is
> `live-conformance/rung_price_verify.py`.
> Keywords **MUST**, **MUST NOT**, **SHOULD**, **MAY** are RFC 2119/8174.
>
> Texts read for this revision: RFC 8506, RFC 8006, RFC 9388, RFC 8216 and
> `draft-ietf-moq-msf-01`; 3GPP TS 32.291, TS 32.279 and TS 26.510 as a mirror of Release 19 gives
> them. ISO 3166 and ISO/IEC 23009-1 were not read: this text binds only the structure of a code
> (§2) and the name of an attribute.

## 1. Scope

In scope: the price list, its form, digest and signature, and the records its energy figures name
(§4); what a verifier derives from lists at an instant (§5); how delivery options are compared
under a request, with the records a comparer is given, and the neighbour order a comparison gives
an asker (§6); and which tariff field bills each unit of a list (§7).

Out of scope: a transport; how a seller sets its prices; what a delivery promises, which is a
deadline, an earliest useful time, a decay or a fallback rendition ([timeliness](timeliness.md)
§4), a schedule's availability and decoding bound ([carousel](carousel.md) §6.3), or service
counted against a region and a miss target, which no price states and
[cache-authority](cache-authority.md) §8 counts; payment; the records a line
bills from, which their own extensions define; and which sellers a comparer accepts.

Relationship to the core spec: `wai.delivery.rung_price` is a **record** ([SPEC](../SPEC.md) §5).
It names no payload format and is not dispatchable.

## 2. Terms

- **Seller**: an Ed25519 key that signs a list. **Comparer**: anyone who compares lists: a router,
  a buyer, or an asker of [holdings](holdings.md) §5.4.
- **Time**, **amount**, **document**, **canonical form**, **digest**, **unit**, **class**: as
  route-record §2. A time is in microseconds, and an amount in millionths of a minor unit
  (ISO 4217, by its alphabetic code).
- **Bearer class**: `bidirectional`, `multicast` or `unidirectional`, as bearer-receipts §2.
- **Direction**:
  - `downlink`: octets sent to the end user who receives the rung. This is RFC 8506 §8.25
    *CC-Output-Octets* ("sent to the end user") and 3GPP TS 32.291 §6.1.6.2.1.10
    `downlinkVolume`.
  - `uplink`: octets received from the end user who contributes it. This is RFC 8506 §8.24
    *CC-Input-Octets* ("received from the end user") and TS 32.291 `uplinkVolume`.

  A peer is not a direction. A peer that serves a neighbour serves it `downlink` on a
  `bidirectional` bearer, and is told apart by who signs. RFC 8506 §8.23 *CC-Total-Octets*
  ("regardless of the direction") states no direction, and is neither.
- **Region code**: either of these, written as WAI writes ISO 3166 codes elsewhere
  ([live-rooms](live-rooms.md) §3.7 `regions`, [channel-lineup](channel-lineup.md) §6.2
  `countries`, [forensic-watermark](forensic-watermark.md) §5.1 `region`):
  - an ISO 3166-1 alpha-2 code: two capitals `A`–`Z` (`XA`);
  - an ISO 3166-2 code: an alpha-2 code, `-`, then 1 to 3 capitals `A`–`Z` or digits `0`–`9`
    (`XA-1`).

  A code's **country** is its first two characters. Whether ISO assigns a code is not checked,
  and codes are compared byte for byte. CDNI writes the same codes in lowercase (RFC 8006 §4.3.8
  `countrycode`, RFC 9388 §2.1.1.1 `subdivisioncode`); a code maps to and from those by changing
  the case of its letters, exactly, and a CDNI footprint of both kinds is a `footprintunion` (RFC
  9388 §2.2).

  This is WAI's one definition of a region code, its country and *holds*: an extension that
  states a region cites this section rather than restating it.
- **Holds**: a list of region codes holds a code *r* when it lists *r*, or when *r* is an ISO
  3166-2 code and the list names *r*'s country. It never holds a country because it lists a
  subdivision of it.
- **Rung rate**: the bits per second a rendition delivered to each receiver takes, as its own
  description states it:
  - an HLS `BANDWIDTH` (RFC 8216 §4.3.4.2, "the peak segment bit rate");
  - an MSF `bitrate` (`draft-ietf-moq-msf-01` §5.2.22, the track's maximum bitrate in bits per
    second), a JSON number, taken **rounded up** to an integer;
  - a DASH Representation's `@bandwidth` (ISO/IEC 23009-1);
  - a packaging class's `max_kbps` × 1000 ([packaging](packaging.md) §3, its paragraph 3.3);
  - a room profile layer's `max_kbps` × 1000 (live-rooms §8.1);
  - a steering policy's tier bitrate ([energy-steering](energy-steering.md) §3.1 `tiers`);
  - a `wai:bitrate` ([capability-constraints](capability-constraints.md) §3.1).

  A packaging class with no `max_kbps` states no rate, and a request for it states `null`, never
  0 and never the lowest tier.
- **Pass rate**: the rate a transmission's passes take on their bearer (§7.2).
- **Per-hop record**: a hop's signed record of its part in one room session, `WMH1`
  ([live-metering](live-metering.md) §3). Its digest is SHA-256 over its bytes before `sig`
  (live-metering §3.5); its **room** is the room descriptor (live-rooms §3.1) whose digest is its
  `room`; and its **instant** is that room's `t0` + its `end` − 1, the last microsecond its span
  covers ([fleet](fleet.md) §4.5).
- ⌊x⌋ is x rounded down and ⌈x⌉ is x rounded up; products are computed in integers wide enough not
  to overflow.

## 3. Why a signed list beside the price book and the tariff

1. **A router and a buyer compare before any contract.** The price book is a router's own unsigned
   statement (route-record §11). A tariff names one buyer, and binds only once that buyer signs
   it (receipt-ledger §4.1, §4.2). Nothing signed lets a buyer hold a seller to a price before
   both exist. The list is the seller's word to every comparer, signed, with the window it holds
   for.
2. **Delivery is priced by what carries it, where, and in which direction**, not by an operation
   and an endpoint. A price book's `endpoint`, `provider`, `operation` and `capability` name a
   job's server and what it produces; a carrier produces nothing, and the catalogue has no
   delivery operation. Its `region` and `residency` are where an endpoint runs and where data
   rests, not where content is delivered to. Its `failures` are the router's own measurement,
   which a seller cannot sign. What delivery needs and the price book lacks is a direction, a
   bearer class, a footprint, a rate ceiling, and a signer with a validity window: those, and only
   those, are added (§4.2).
3. **A shared transmission and a per-receiver delivery are compared honestly.** On a `multicast`
   or `unidirectional` bearer one transmission serves every receiver, and their number is unknown
   ("the source learns nothing", [unidirectional-delivery](unidirectional-delivery.md) §2).
   Dividing by an assumed audience would read the unknown as the optimum. §6.3 divides by the
   audience a comparer states, and by 1 otherwise, and states the audience at which sharing stops
   costing more.
4. **It changes no byte of any record it prices.** Lines bill only quantities that signed records
   state (§7). A list is a quote, never a charge, as the price book's figures are (receipt-ledger
   §5.1, *Routing figures are never charges*).

## 4. The list

### 4.1 Members

A list is a document (route-record §2) of exactly these members:

| member | form |
|---|---|
| `kind` | `"wai-rung-prices"` |
| `version` | `1` |
| `seller` | a key: 64 lowercase hexadecimal digits |
| `currency` | three capitals `A`–`Z` (ISO 4217) |
| `issued` | a time: from when the list states its prices |
| `expires` | a time: from when it states nothing |
| `entries` | 1 to 1,024 entries (§4.2), in §4.5 rule 4's order |
| `sig` | 128 lowercase hexadecimal digits (§4.4) |

### 4.2 An entry

| member | form | meaning |
|---|---|---|
| `direction` | `"downlink"` or `"uplink"` | §2 |
| `bearer` | `"bidirectional"`, `"multicast"` or `"unidirectional"` | bearer-receipts §2 |
| `footprint` | 1 to 8,192 region codes (§2), strictly ascending by their bytes | the regions it delivers to |
| `max_bps` | an integer from 1 to 2⁵³ − 1 | the tier's ceiling: it prices a rung whose rate (or pass rate, for a transmission unit) is at most this, unless a lower ceiling of the same list, direction, bearer and unit, holding the region, also covers it (§6.2 `tier`) |
| `unit` | a unit (route-record §2): one of §4.3's (rule 5) | what is priced |
| `divisor` | an integer at least 1: the unit's divisor (rule 5) | as route-record §3.2 |
| `price` | an integer, at most the unit's bound (rule 5) | an amount per `divisor` units |
| `energy_uj` | an integer of at least 1, or `null` | the microjoules the seller states per `divisor` units, as route-record §3.2; `null` when it states none, and never 0, as bearer-receipts §4.2 refuses a zero figure |
| `energy_class` | a class (route-record §2), or `null` exactly when `energy_uj` is `null` | the class of that figure |
| `energy_ppm` | an integer from 1 to 2³² − 1 when `energy_class` is `CalibratedInstrument` or `OnChipCounter`, and `null` otherwise | the figure's declared uncertainty, in parts per million of it ([energy-measurement](energy-measurement.md) §2.3): the largest its records declare (§4.6 rule 4) |
| `energy_evidence` | 1 to 64 digests, each 64 lowercase hexadecimal digits, in strictly ascending order of their bytes, when `energy_class` is `CalibratedInstrument`, `OnChipCounter` or `ModelBased`; `null` otherwise | the per-hop records (§2) whose rate the figure is (§4.6) |

- A ceiling of 2⁵³ − 1 is how a seller prices any rung. It is not a sentinel: no document states a
  greater rate.
- 8,192 codes exceed the codes ISO 3166-1 and ISO 3166-2 assign together, and rule 6 forbids a
  code twice in one tier, so one entry never needs more.
- **An entry is a whole price.** It is the price of what it carries, counted in its unit alone. A
  seller that would also bill another unit for the same delivery has stated a price it does not
  hold to. Two entries of a seller are alternatives, and a comparer ranks them as such.
- **A class above `Estimator` names its records.** A class says how a figure was obtained
  (energy-measurement §2), and a list is no reading (§10). An entry whose class is above
  `Estimator` names the per-hop records whose rate its figure is, and one of a hardware class
  states the declared uncertainty energy-measurement §2.3 requires of that class. An entry that
  names none states an estimate, and its class says so. 64 records bound what one entry costs a
  comparer to read.

### 4.3 Units, by bearer class and direction

| unit | bearer | direction | basis | divisor | price at most | counts |
|---|---|---|---|---|---|---|
| `bytes` | `bidirectional` | `downlink` | receiver | 10⁹ | 2⁵³ − 1 | bytes one receiver is delivered |
| `subscriber_us` | `bidirectional` | `downlink` | receiver | 10⁶ | 2³² − 1 | microseconds one receiver is subscribed at the rung ([live-metering](live-metering.md) §3.3) |
| `publisher_us` | `bidirectional` | `uplink` | receiver | 10⁶ | 2³² − 1 | microseconds one contributor publishes (live-metering §4.4) |
| `bytes_sent` | `multicast`, `unidirectional` | either | transmission | 10⁹ | 2⁵³ − 1 | octets transmitted: carousel §5.4's `bytes_sent` |
| `pass_us` | `multicast`, `unidirectional` | either | transmission | 10⁶ | 2⁵³ − 1 | microseconds of passes: Σ `count` × `duration_ms` × 1000 over a schedule's entries (carousel §2, §4.1) |

**The basis follows from the bearer class.** A `bidirectional` bearer reaches each receiver over
its own path; the other two classes reach every receiver with one transmission (bearer-receipts
§2).

**A per-receiver unit on a shared bearer is refused**, because no sender can count it: the source
learns nothing (unidirectional-delivery §2), and receiver time on an ATSC 3.0 broadcast or a 5G
media streaming service comes only as unsigned reports (bearer-receipts §9.5; 3GPP TS 26.510 §9.6.3.2
reports consumption under a second as 0).

**Each divisor and bound is the ledger field's** that bills the unit (receipt-ledger §4.1 and
§6.3; §7 here): room prices are u32, per second, and delivery prices u64, per 10⁹ bytes. So every
price transcribes into its tariff field exactly, and since a unit has one divisor, a price has one
encoding.

**Units no record can bill are absent.** No record counts an object delivered (settlement §3.4
acknowledges byte ranges), so there is no `objects` unit; no ledger source counts uplink bytes, so
`bytes` is downlink only. A unit is added with the record and the ledger field that bill it.

**Two units take records.** A relay's per-hop record states its energy beside the media bytes it
sent and the subscriber time it served (live-metering §3.2, §3.3), so a `bytes` or `subscriber_us`
entry may name records (§4.6). No record a seller signs states `publisher_us` beside its energy: a
room's publisher time is its room-session receipt's, signed by the room's authority or a metering
key (live-metering §4.3, §4.4). Nor does one state a transmission's: its energy is its publisher's
declaration (bearer-receipts §4.1, §4.3), and its octets and pass time are its schedule's (carousel
§5.4). An entry of those units states an estimate or no figure. A unit takes records when a record
its seller signs states its energy beside a quantity of the unit.

### 4.4 Digest and signature

The **digest** of a list is SHA-256 over the canonical form of the list without `sig`, written as
64 lowercase hexadecimal digits. The **signature** is Ed25519 by `seller` over `wai:rung-prices`
(ASCII) and 0x01, followed by that same canonical form: route-record §5.3's construction under its
own domain. It is verified strictly, as SPEC §7 *Signatures* verifies every signature: a key that
is not the canonical encoding of a point of large order fails, as does a signature whose scalar is
not below the group order.

The digest leaves `sig` out, as [holdings](holdings.md) §4.3 digests a record's bytes without its
signature. Ed25519 admits many valid signatures of one body, one for each nonce, and strict
verification removes only S-malleability; a digest over `sig` would read one seller's two signings
of one body as two lists, and two such lists at one `issued` as a contradiction. The digest names
what the seller said; the signature is checked on its own.

### 4.5 Reading and rules

A reader is given a text. It refuses it `rung_prices_malformed` when the text holds more than
1,048,576 bytes, is not a document, or breaks one of rules 1 to 4. A list that reads is then
refused for rule 5 or rule 6, with that rule's own reason, and then for its signature
(`rung_prices_signature_invalid`, §4.4). The rules, in order:

1. Its members are exactly §4.1's, and each entry's exactly §4.2's, each of its form. `version` is
   1.
2. `issued` is below `expires`.
3. Each `footprint` is strictly ascending by bytes, and lists no subdivision code whose country it
   also lists: that would be a second encoding of the same footprint.
4. The entries are in strictly ascending order of (`direction`, `bearer`, `unit`, `max_bps`, the
   first code of `footprint`): strings by their bytes, integers by value. No two entries of one
   (`direction`, `bearer`, `unit`, `max_bps`) have the same `price`, `energy_uj`, `energy_class`,
   `energy_ppm` and `energy_evidence`: such entries are one entry over the union of their
   footprints.
5. Each entry's `unit` is one §4.3 lists, on its `bearer` and in its `direction`; its `divisor` is
   that unit's; its `price` is at most that unit's bound; and it names records only when its unit
   is `bytes` or `subscriber_us` (`rung_prices_unit_invalid`).
6. Within one (`direction`, `bearer`, `unit`, `max_bps`), no region code is listed by two entries,
   and no entry lists a subdivision code whose country another entry lists
   (`rung_prices_ambiguous`). Either would give one region two prices at one tier.

So a list reads the same whatever the order of its members, since the canonical form is what is
signed; each region, tier and unit has at most one price in a list; and two lists that state the
same prices are the same body, with the same digest.

### 4.6 Energy evidence

An entry's `energy_evidence` names the per-hop records whose rate its figure is. The list signs
their digests, so the records a seller names are fixed with its prices, and a comparer that is
given them checks the figure against them (§6.4).

A text a comparer is given (§6) **names** a digest when it holds 64 to 1,048,576 bytes: SHA-256
over all its bytes but the last 64, as live-metering §5.1 finds a per-hop record and fleet §4.4 a
room descriptor. A named record is **given** when a text naming its digest reads and verifies as a
per-hop record of the room its own `room` names (live-metering §3.5, §3.6), live-metering §3.7's
bound not applied, as fleet §4.3 does not apply it. Its room is given when a text naming the
record's `room` reads and verifies as fleet §4.4 reads a room descriptor. Texts naming one digest
differ at most in their last 64 bytes, the signature, so every text that reads and verifies gives
the same record. A text that does not gives nothing: a damaged copy refutes nothing, and only what
a seller named and its hop signed can refute the seller's figure.

Each given record is held to these, in order, and the first that fails **refutes** the entry's
figure, with its reason:

1. Its `role` is 1 (`rung_prices_evidence_role`): a downlink price is a relay's, and a compositor
   or an ingest gateway serves no subscriber.
2. Its `hop` is the list's `seller` (`rung_prices_evidence_signer`). A figure is the rate of its
   seller's own readings, never of another key's that it chose to name.
3. Its figure is not the unmetered marker, and its class's tag is the one energy-measurement §2.7
   gives the entry's `energy_class`: 5 for `CalibratedInstrument`, 4 for `OnChipCounter`, 2 for
   `ModelBased` (`rung_prices_evidence_class`). Figures of two classes are never summed
   (live-metering §4.5).

When every named record and the room of each is given, the records together are held to these, in
order:

4. For `CalibratedInstrument` and `OnChipCounter`, `energy_ppm` is the largest `relative_ppm` among
   them (`rung_prices_evidence_class`). When each record's error is within its declared relative
   uncertainty, their sum's is within the largest (receipt-ledger §6.6), and so is any rate of it.
5. With *J* the sum of their `joules` and *D* the sum of their quantities in the entry's unit, *D*
   is at least 1 and `energy_uj` is ⌈*J* × `divisor` / *D*⌉ (`rung_prices_evidence_figure`): the
   records' rate per `divisor` units, rounded up so that it never states less than they do. For at
   most 64 records *J* × `divisor` is below 2¹⁰⁰. A record's quantity is:
   - in `bytes`, the `bytes` of its track entries of kind 1 (a media track) and `dir` 2 (out), as
     energy-steering §5.3 counts delivery on its basis 1;
   - in `subscriber_us`, its `subscriber_us` of layer classes 0 to 7, as energy-steering §5.3
     counts delivery on its basis 2 at floor tier 0.

   Either charges every joule of the hop's span to its media delivery, so the figure is never less
   than any division of those joules among what the hop carried would give.

Records that pass all five **bear out** the figure. What they bind is a rate the seller's own relay
spent and signed, not the delivery a comparer buys: which region, rung or receivers a record's
session served, it does not say (§10). Whether a comparer relies on them, at its instant and for
its seller's key, is §6.4's.

## 5. What a verifier derives

### 5.1 At an instant

A list that reads and verifies is refused `rung_prices_not_yet` when the verifier's instant
`at_us` is below its `issued`. A verifier does not stretch the window. One whose clock it does not
trust **SHOULD** say which instant it used (holdings §5.1); a plan always states it (§6.6).

### 5.2 One seller's lists

Of a seller's lists that are not refused, the one with the greatest `issued` is the seller's
**latest**, and every other is `superseded`.

- Two latest lists with different digests are each set aside, `rung_prices_contradicted`.
- Two latest lists with the same digest are one list, whatever their signatures (§4.4).
- A latest list whose `expires` is at or before `at_us` is refused `rung_prices_expired`. The
  seller then has **no standing list**, and an earlier list stays superseded.
- Otherwise the latest list **stands**.

This differs from holdings §5.3 on purpose. A seller that repriced has withdrawn its earlier
prices. Reviving them when the later list lapses would read a withdrawn, possibly lower, price as
current: the buyer's best case, taken from a statement its seller replaced.

A list's verdict is written as holdings writes a record's: `stands`, `superseded`,
`set-aside reason=rung_prices_contradicted`, or `reject reason=` and the reason.

## 6. Comparing delivery options

A comparer computes the following from the lists it is given, the texts it is given as evidence
(§4.6), an instant and a request, and a verifier computes the same. Nothing depends on the order
the lists or the texts are given in, beyond the positions of the lists' verdicts in the plan, on a
text being given twice, on the order of a document's members, or on anything else.

### 6.1 The request

A request is a document of at most 65,536 bytes, of exactly these members, each of its form.
Otherwise it is refused `rung_request_invalid`, and nothing is derived.

| member | form |
|---|---|
| `kind` | `"wai-rung-request"` |
| `direction` | `"downlink"` or `"uplink"` |
| `to` | a region code (§2): the region delivered to |
| `rate_bps` | `null`, or an integer from 1 to 2⁵³ − 1: the rung's rate (§2), held against receiver-basis entries; `null` when the comparer does not know it |
| `pass_rate_bps` | `null`, or an integer from 1 to 2⁵³ − 1: the pass rate (§7.2) of the passes the comparer plans, held against transmission-basis entries; `null` when it does not know it |
| `bearers` | `null`, or 1 to 3 bearer classes in strictly ascending order of their bytes: the classes it will consider |
| `currency` | three capitals `A`–`Z` |
| `quantities` | as route-record §3.1: 1 to 16 objects of exactly `unit` and `quantity` (an integer at least 1), in strictly ascending order of `unit`. A receiver unit's quantity is per receiver, and a transmission unit's per transmission. |
| `max_price` | as route-record §3.1's `max_price`: 0 to 16 objects of exactly `unit`, `price` and `divisor` (an integer at least 1), in strictly ascending order of `unit` |
| `audience` | `null`, or an integer at least 1: the receivers the comparer states a shared transmission reaches |
| `sort` | `"price"` or `"energy"`: the first ranking key |
| `confirmed` | 0 to 256 objects of exactly `key` (a key: 64 lowercase hexadecimal digits) and `class` (`CalibratedInstrument`, `OnChipCounter` or `ModelBased`), in strictly ascending order of `key` and, for one key, of `class`, by their bytes: the keys the comparer has confirmed for a class |
| `evidence_age_us` | an integer from 1 to 2⁵³ − 1: the most a record's instant (§2) may be before the instant used |

`to` is required: a delivery that names no region cannot be held to any footprint. `bearers`
`null` is the comparer's statement that it considers every class; it limits nothing, as
route-record §3.1's `regions` `null` limits nothing.

A key is **confirmed** for a class when the comparer holds, under an anchor it relies on, a head of
a key log ([jwp-receipts](jwp-receipts.md) §7.4) with an entry for the key whose `may_sign` holds
`live/relay` and `energy/` followed by the class, and that is not revoked, as live-metering §5.2
places a hop's key; for a hardware class, only under a pinned anchor (jwp-receipts §7.5,
*Pinned-only authorities*). `confirmed` and `evidence_age_us` are the comparer's own statements, as
its `audience` is (§6.3), and the plan restates them in the request's digest. A comparison reads no
key log: it takes the keys a relying party has confirmed, as bearer-receipts §6.1 takes them.

### 6.2 Candidates and removals

The **candidates** are the entries of the lists that stand (§5) whose `direction` is the
request's, in ascending order of their sellers' keys, by bytes, and within each list in entry
order. A candidate's `entry` is its position in its list's `entries`, from 0.

A candidate's **rate** is the request's `rate_bps` when its basis is receiver, and its
`pass_rate_bps` when its basis is transmission (§4.3). A `null` rate stands for 2⁵³ − 1, which only
the unbounded ceiling covers.

Each candidate is held to every limit below, in this order, and its **removals** list each limit
that holds, in this order, with the value the limit read, as route-record §4.3 lists removals:

| limit | removes a candidate when | value |
|---|---|---|
| `currency` | its list's `currency` is not the request's | its list's `currency` |
| `bearer` | `bearers` is not `null`, and does not list its `bearer` | its `bearer` |
| `unit` | the request states no quantity in its `unit`. Units are never converted (route-record §4.2): a `bytes` quantity never prices `bytes_sent`. | its `unit` |
| `footprint` | its `footprint` does not hold `to` (§2) | its `footprint` |
| `rate` | its `max_bps` is below its rate | its `max_bps` |
| `tier` | another entry of its list, of the same `direction`, `bearer` and `unit`, holds `to` and has a `max_bps` at least the candidate's rate and below the candidate's own: a rung is priced at the least ceiling that covers it | the least such `max_bps` |
| `unit_price` | `max_price` has an entry for its `unit`, and its `price` × that entry's `divisor` exceeds that entry's `price` × its own `divisor` (route-record §4.3) | its `price` |

A candidate with no removal is a **survivor**. Rules 4 and 6 and the `tier` limit leave each seller
at most one survivor of each bearer class and unit. The least ceiling that covers a rate, for each
(`direction`, `bearer`, `unit`) of a list, is found in one pass over its entries.

### 6.3 Cost and energy per receiver

For a candidate whose unit the request states a quantity *q* for:

- its **list cost** is *T* = ⌊*q* × `price` / `divisor`⌋;
- its **list energy** is *E* = ⌊*q* × `energy_uj` / `divisor`⌋, when `energy_uj` is stated
  (route-record §4.2).

Each is `null` past 2⁵³ − 1, and *E* is `null` when `energy_uj` is. *T* is exactly what a ledger
bills for *q* at that price, rounded once (receipt-ledger §3 rule 2). A candidate's `cost` and
`energy` are then:

- **receiver basis** (`bidirectional`): *T* and *E*;
- **transmission basis** (`multicast`, `unidirectional`): ⌈*T* / *n*⌉ and ⌈*E* / *n*⌉, where *n*
  is the request's `audience`, or **1** when it is `null`.

A candidate the request states no quantity for has a `null` cost and energy, and one whose evidence
is refuted (§6.4) a `null` energy.

**Why 1.** This is bearer-receipts §7's form, ⌈ · / max(1, *n*)⌉, for its reason: unknown is not
zero, and no figure divided by an assumed audience is anyone's share. With no stated audience, one
receiver bears the whole transmission: the worst case for the only option whose per-receiver
figure depends on *n*, since a receiver-basis cost does not change with *n*. Rounding up keeps each
receiver's share of *T* an upper bound in integers.

**A stated audience is the comparer's own statement**, as a relying party's loss bound is its own
(carousel §12), and the plan restates it.

- It **SHOULD** be at most the number of keys counted for an earlier transmission of the same
  service under bearer-receipts §6.2 step 6, counting only keys the comparer confirmed under the
  `reconciliation` authority from an origin that gives that authority to one key per receiver
  (bearer-receipts §7 *Keys are not receivers*, jwp-receipts §7.4), or the `hits` of a tally of an
  earlier transmission (cache-authority §8.4), which counts only a stated population's keys.
  Unconfirmed keys can over-count receivers, and dividing by an over-count reads a shared option
  as cheaper than it is.
- It **MUST NOT** be a count of aggregated reports: such reports are not authenticated, and their
  floor "is a floor of reports, not of people" ([telemetry-aggregation](telemetry-aggregation.md)
  §13).

`energy` here is an **allocation over the stated audience**. It **MUST NOT** be reported as
bearer-receipts §7's bound, which counts reconciliation keys, nor as any receiver's reading.

A candidate's `energy` is never a reading of the delivery it prices. A checked figure (§6.4) is the
rate its seller's own records state, applied to the request's quantity: its class and its energy
rank say what backs that rate, not how the delivery's energy will be read.

### 6.4 Ranking

Survivors are ordered by this list of keys: the request's `sort`; the other of `price` and
`energy`; `seller`; and `entry`. Two survivors compare by the first key on which they differ:

- **`price`**: the smaller `cost` first. A `null` comes after every stated cost, and two `null`s
  do not differ (route-record §4.4).
- **`energy`**: evidence first, as energy-steering §6.2 ranks pathways, where the evidence is what
  the comparer checked and never the class a list names. A survivor's **energy rank** is 4 whenever
  its `energy` is `null`, a figure past 2⁵³ − 1 and a refuted one among them; otherwise 0 for a
  `CalibratedInstrument` figure, 1 for `OnChipCounter` and 2 for `ModelBased` when its evidence is
  `checked`, and 3 for every other figure. The smaller rank first. Within rank 0 or 1, the smaller
  `energy` × (10⁶ + `energy_ppm`) first; within rank 2 or 3, the smaller `energy` first; two
  survivors of rank 4 do not differ.
- **`seller`**: the smaller key, by its bytes, first.
- **`entry`**: the smaller position first.

Survivors differ in seller or entry, so the order is total. The **order** is the survivors in it,
each as its `seller` and `entry`, and each survivor's **rank** is its position there, from 1.

A candidate's **evidence** is `null` when its entry names no records. Otherwise it is the first of
these that holds:

1. `refuted reason=` and the reason of the first of §4.6 rules 1 to 3 that a given record breaks,
   its records taken in the order of `energy_evidence`;
2. `absent`: a record it names, or the room of one, is not given (§4.6);
3. `refuted reason=` and the reason of §4.6 rule 4 or rule 5, the first that fails;
4. `outside-window`: a record's instant (§2) is below `at_us` − `evidence_age_us`, or at or after
   `at_us`;
5. `unconfirmed`: `confirmed` does not hold its seller with its `energy_class`;
6. `checked`.

A refuted figure is contradicted by records its own seller named and its own hop signed, as two
latest lists of one seller that differ contradict each other (§5.2): it is set aside, and its
`energy` is `null` (§6.3). An `absent`, `outside-window` or `unconfirmed` figure is its seller's
word, which the comparer cannot check: it ranks as an estimate, whatever class it names, at most
[oer-receipts](oer-receipts.md) §2's `projected` (§10). So a class decides nothing unless the
seller's own records, current and given, bear its figure out under a key the comparer confirmed for
it.

**Uncertainty.** Within a hardware rank each figure is taken one declared standard uncertainty
above itself (energy-measurement §2.3), so a precise figure ranks before a slightly smaller one its
seller read less precisely. For 500,000,000 `bytes`, a `CalibratedInstrument` figure of 900,000,000
per 10⁹ declared to 20,000 ppm is an `energy` of 450,000,000 µJ, compared as 450,000,000 ×
1,020,000 = 459,000,000,000,000; one of 910,000,000 declared to 5,000 ppm is 455,000,000 µJ,
compared as 455,000,000 × 1,005,000 = 457,275,000,000,000, and ranks first. The product is a
comparison, not a limit: a standard uncertainty bounds nothing (energy-measurement §2.1), and a
plan states no product. It is below 2⁸⁶. `ModelBased` and `Estimator` figures carry no declared
uncertainty (energy-measurement §2.1), and rank by their figure.

Figures of two ranks are never compared, so an unknown, unchecked or weaker figure never outranks a
checked one, however much smaller; every figure of rank 3 is read as an estimate and compared as
one. Route-record §4.4 compares figures whatever their class; this text follows energy-steering
§6.2, the stricter rule, with which bearer-receipts §7 and receipt-ledger §6.6 agree.

### 6.5 The decision and the break-even audience

`decided_by` is `none` when there is no survivor, `only_survivor` when there is one, and otherwise
the first key on which the first two survivors of the order differ: `price`, `energy`, `seller` or
`entry`. `runner_up` is the second survivor, as its `seller` and `entry`, or `null` when there are
fewer than two.

Let *c*\* be the least stated `cost` among the receiver-basis survivors. Each transmission-basis
survivor's **break-even audience**, `break_even`, is the least audience at which its cost per
receiver is no more than *c*\*:

- `null` when *T* is `null`, or when there is no such *c*\*;
- when *c*\* is 0: 1 when *T* is 0, and `null` otherwise;
- otherwise max(1, ⌈*T* / *c*\*⌉).

This holds because ⌈*T* / *n*⌉ ≤ *c* exactly when *n* ≥ *T* / *c*, for an integer *c*. The figure
needs no audience and assumes none: it tells a comparer how many receivers make sharing no dearer,
and the comparer judges whether it has them.

### 6.6 Outcome

The outcome is either a refusal, `rung_request_invalid`, or a **plan** of these members:

- `request`: the request's digest;
- `at_us`: the instant used;
- `lists`: for each list given, in the order given, its `verdict` (§5.2) and its `digest`, or
  `null` for a list refused at reading (§4.5);
- `evidence`: the digests of the records and rooms the texts given as evidence give (§4.6), in
  ascending order of their bytes, each once;
- `audience`: the *n* used;
- `candidates`: each candidate in §6.2's order, as `seller`, `entry`, `bearer`, `unit`, `max_bps`,
  `basis` (`receiver` or `transmission`), `removed` (each removal as `limit` and `value`), `cost`,
  `energy`, `energy_class`, `energy_ppm`, `evidence`, `energy_rank`, `transmission_cost`,
  `break_even` and `rank`. `energy_ppm` is its entry's; `evidence` and `energy_rank` are §6.4's,
  for every candidate; `transmission_cost` is *T* and `break_even` §6.5's figure for a
  transmission-basis survivor, and both are `null` for every other candidate; `rank` is `null` for
  a removed one;
- `order`: the survivors, in order;
- `decision`: `decided_by` and `runner_up`.

**A neighbour order.** An asker of holdings §5.4 gives its neighbours' records "in the order it
prefers them", an order it judges itself, and a timeliness plan takes its holder sources in the
asker's order and chooses the first that is on time (timeliness §7.1, §7.3). An asker that orders
its neighbours by price takes the order from a plan over their lists. A neighbour's list is one
whose `seller` is the `holder` of its holdings record (holdings §4.1), the two keys compared byte
for byte. The asker's **neighbour order** is then:

1. the sellers of the plan's `order`, each at its first position there;
2. then every other neighbour, in ascending order of its key, by bytes: those with no standing
   list (§5.2), and those whose list has no survivor.

A neighbour with no price for the delivery comes after every priced one, never before, as a `null`
cost ranks last (§6.4). Holdings §5.4 then keeps, in this order, the neighbours whose record stands and
holds the object. A holder that signs its records with a fresh key (holdings §9) has no list under
that key, and is ordered among the unpriced: unlinking its records is its choice, and this is its
cost.

## 7. What bills each unit

### 7.1 The table

A list is a quote. A buyer is billed only at the tariff it signed (receipt-ledger §4.2). Each list
unit is billed by the tariff field that prices the record stating its quantity, and no line is
added where a field already prices that record: a second price would bill one quantity twice.

| list unit | billed by | from | rung in the line |
|---|---|---|---|
| `subscriber_us` | `room` prices 1 to 9, u32 per second (receipt-ledger §4.1; §6.3 units 2 to 10) | a room-session receipt's `subscriber_us` per layer class | the layer class is the rung (live-metering §3.3): a buyer prices layer class *i* from the tier that covers that layer's rate (live-rooms §8.1, energy-steering §3.1) |
| `publisher_us` | `room` price 0, u32 per second (§6.3 unit 1) | its `publisher_us` | none |
| `bytes` (`downlink`) | `delivery` prices, u64 per 10⁹, per object class (receipt-ledger §4.1; settlement §7.1), or the `room` price of `bytes_out`, u32 per 10⁹ (receipt-ledger §4.7 item 1; §6.3 unit 14) | acknowledged bytes (settlement §3.2), or a room-session receipt's `bytes_out` | none: no acknowledgement and no room receipt names a rung, so one price bills every rung. A `bytes` price above 2³² − 1 transcribes into `delivery` only. |
| `bytes_sent`, `pass_us` | `transmission` prices of a tariff of version 7, u64 per 10⁹ octets or per 10⁶ microseconds, one for each bearer class, unit and ceiling (receipt-ledger §4.1, §4.10; receipt-ledger §6.3 source kind 6) | the `bytes_sent` or `pass_us` (carousel §5.4) of each entry receipt-ledger §4.10 bills: of a standing schedule on a `multicast` or `unidirectional` instance its publisher declared, or on a node's own instance (receipt-ledger §5.1 `group` and `cache`) | the tier: in each unit an entry is billed at the price of its instance's declared class whose ceiling is the least at or above its pass rate (§7.2), and the line's `unit` is that price's index from 1 (receipt-ledger §6.3) |

A buyer that signs a tariff from a list copies the entry it accepts for each tier and unit into the
corresponding field, and every list price fits its field exactly (§4.3). The copy is the buyer's
own transcription, and no verifier checks it: the tariff holds its own prices (receipt-ledger §3).

**A transmission is billed at its tier.** A tariff of version 7 prices a transmission in §4.3's two
transmission units, with their divisors and bounds (receipt-ledger §4.10). An entry of a
transmission unit transcribes into one transmission price: its `bearer` as 2 `multicast` or 3
`unidirectional`, its `unit` as 1 `bytes_sent` or 2 `pass_us`, its `max_bps` as the ceiling, and
its `price`. A transmission price states no direction and no footprint: for each class, unit and
ceiling, the buyer copies the entry it accepts for the direction and the region it buys. A schedule
entry is billed at the least ceiling of its class that covers its pass rate, as §6.2's `tier` limit
prices a rung at the least ceiling that covers it. An entry whose pass rate is above every ceiling
of its class and a unit is billed nothing in that unit, and the ledger's transmissions report names
it (receipt-ledger §8.3). A tariff of versions 1 to 6 holds no transmission price and bills no
transmission.

### 7.2 The pass rate

For an entry of a carousel schedule, *P* = `bytes_sent` / `count` is the octets one pass sends: Σ
*m* · T over its source blocks for `raptorq` and `raptor`, and L for `no-code` (carousel §5.4). The division is
exact. The entry's **pass rate** is ⌈8000 × *P* / `duration_ms`⌉ bits per second, computed in 128
bits.

It is a pure function of the signed schedule. It is the carriage rate the passes take on the
bearer, repair symbols included, which is what a seller of broadcast capacity prices by tier. A
pass rate above every ceiling has no price.

### 7.3 Never delivery

A transmission price prices what a publisher's declaration attests, that it transmitted
(bearer-receipts §4), in the octets and pass time its own schedule planned (carousel §5.4). It
**MUST NOT** be presented as delivery to anyone (bearer-receipts §6.3; settlement §4.2). 3GPP TS
32.279 §5.1.2 charges a 5G multicast-broadcast session the same way: it requires the session's
duration, allows its transmitted volume, keeps quota per rating group per session, and names no
quantity per receiving device.

## 8. Reasons

The codes this extension adds, each with where it is raised:

| reason | raised at |
|---|---|
| `rung_prices_malformed` | §4.5, rules 1 to 4 |
| `rung_prices_unit_invalid` | §4.5 rule 5 |
| `rung_prices_ambiguous` | §4.5 rule 6 |
| `rung_prices_signature_invalid` | §4.4, §4.5 |
| `rung_prices_evidence_role` | §4.6 rule 1; §6.4 |
| `rung_prices_evidence_signer` | §4.6 rule 2; §6.4 |
| `rung_prices_evidence_class` | §4.6 rules 3 and 4; §6.4 |
| `rung_prices_evidence_figure` | §4.6 rule 5; §6.4 |
| `rung_prices_not_yet` | §5.1 |
| `rung_prices_expired` | §5.2 |
| `rung_prices_contradicted` | §5.2 |
| `rung_request_invalid` | §6.1 |

## 9. Conformance

[`live-conformance/prices/`](../live-conformance/prices/) holds the corpus, written from fixed
seeds by `wai_rung_price_vectors gen` as `vectors.json`. Its regions are ISO 3166-1 user-assigned
codes and subdivisions of them, and name no place. It has:

- **Lists**: lists that read, among them every unit of §4.3 and both shared bearer classes, a
  country beside another country's subdivision, the bounds of a ceiling, a footprint, a room price
  and a window, an entry of each class that names records, an uncertainty of 2³² − 1, 64 records
  named, two entries that differ only in their records and two that differ only in their
  uncertainty, a list with its members in another order, and one body under a second valid
  signature; and a negative control for each rule of §4.5, for each unit on a bearer or in a
  direction where §4.3 does not admit it, for a class above `Estimator` that names no records, an
  estimate that names some, records with no figure, an uncertainty on a class that declares none or
  missing from one that does, an uncertainty of 0 or 2³², records named as an empty list, out of
  order, twice, past 64, in capitals or in a unit that takes none, two entries that are one but for
  their footprints, records included, and signatures that do not verify, a key of small order and a
  scalar not below the group order among them.
- **Verdicts**: a list at each edge of its window; a later list superseding an earlier one, a later
  one not yet issued, and a lapsed latest list reviving nothing; one list given twice, one body
  signed twice, and two lists of one instant that differ.
- **Evidence**: per-hop records of two rooms, one a month older than the other, and their
  descriptors, and comparisons that give each verdict of §6.4 and each reason of §4.6: a figure
  checked at each class; records summed under the largest uncertainty; a figure rounded up, and one
  stated a microjoule below it or above it; subscriber time without layer class 8; media bytes
  without an events track's or the bytes a relay received; a record whose only copy's signature
  fails, and one that also has a copy that verifies; a room not given, and one whose signature
  fails; a named digest whose text is not a per-hop record; the window at both edges, and one
  record of several outside it, named first or last; each verdict of §6.4 where the next that can
  hold with it holds too; a record that breaks rules 1, 2 and 3, one that breaks rules 2 and 3, two
  records of which the first breaks rule 3 and the second rule 1, and records that fail rules 4
  and 5; and a removed candidate's evidence and energy rank. Against an honest model-based figure,
  a seller that states a calibrated figure with no records named, which does not read; with
  records it does not give; with its own records under a key nobody confirmed for that class, or
  confirmed only for another class; with another seller's records; over its counter's records;
  with a smaller figure or uncertainty than its records state, or a larger uncertainty; with a
  smaller uncertainty than the record it names first; over records of no delivery, of a compositor
  or of an ingest gateway; or over a record not given, named first, and one of another class; and
  a model-based figure over unmetered records. Two calibrated figures ordered by their
  uncertainty, and a precise figure a hundred times larger after an imprecise one; two counter
  figures ordered by theirs; and a calibrated figure before a counter's.
- **Comparisons**: the cost per receiver of a shared transmission with no audience, below, at and
  above its break-even; each tier rule, for the rung's rate and the pass rate apart; a region held
  by its own code or its country's and never upward; every limit, several of them on one candidate;
  the energy order by checked evidence first, an unknown figure and a figure past the bound last;
  every decision; holders' prices beside one holder whose list lapsed and one that prices another
  region, the plan §6.6's neighbour order is taken from; a request that confirms 256 keys; and a
  refusal for each rule of §6.1.

A conforming verifier gives every case the outcome the corpus states, member for member.
`wai_rung_price_vectors verify` and the test `tests/rung_price.rs` check that the file regenerates
byte for byte, that `wai-rs` gives every case its outcome, that every reason of §8 appears and that
§8 lists exactly the reference's codes, and that every limit of §6.2, every decision of §6.5, every
evidence of §6.4 and every energy rank occurs. `live-conformance/rung_price_verify.py` is the
second implementation, written from this text: it shares no code with `wai-rs`; it reads documents
with route-record's second implementation, per-hop records with live-metering's
(`live_metering_verify.py`), room descriptors with fleet's (`fleet_verify.py`) and signatures with
the claim corpus's strict Ed25519 check, writes §2's region code, §4, §5 and §6 itself, mutates
copies of the corpus and requires every copy to fail, and drops each of its own checks in turn and
requires the corpus to catch the weakened verifier. The bounds no vector carries, a text of
1,048,577 bytes, a list of 1,025 entries, a request of 65,537 bytes and an evidence text of
1,048,577 bytes, both implementations check themselves.

## 10. Security and privacy considerations

- **A list is its seller's word.** It binds the seller to its prices for its window; nothing in it
  is a measurement. Its energy figure is what the seller expects to spend, and no reading of any
  delivery: at most [oer-receipts](oer-receipts.md) §2's `projected` grade. A figure whose evidence
  is `checked` (§6.4) is, besides, the rate its seller's own signed readings state, by stated
  arithmetic (§4.6), and ranks at their class; any other figure ranks as an estimate.
- **A label is not evidence.** A seller can sign any class, and can sign records of any class with
  its own key: a signature settles who said a number, not how it was read (energy-measurement
  §2.2). So a class counts only under a key the comparer confirmed for it from an origin it relies
  on, pinned for a hardware class (§6.1), and only for a figure the seller's own current records
  bear out (§4.6). A seller that names records it does not give, or that nobody confirmed, ranks as
  an estimate; one whose own records contradict it ranks with the unknown. Among estimates the
  smallest figure ranks first, and no rule here tells an honest one from a low one: that is which
  sellers a comparer accepts.
- **Chosen records.** A seller names the records it chooses. A checked figure is the rate of those
  records' spans, not of all its delivery: a seller that names its most efficient spans states
  their rate, and `evidence_age_us` bounds only how old their rooms say they are: a room
  descriptor's `t0` is its authority's word, which nothing here confirms, and a seller may sign its
  own room.
- **Which sellers.** `compare` ranks every list it is given, and a key nobody vouches for, signing
  a price of 0, ranks first. A comparer gives only lists of sellers it accepts, as an asker orders
  only its own neighbours (holdings §5.4). A comparer **MAY** accept a seller whose key it places
  with a serving role ([cache-authority](cache-authority.md) §4.4).
- **Ties.** Exact ties of price and energy are broken by key bytes, which a seller can choose.
  That buys only a tie.
- **Unknown is restrictive** (route-record §11): an unstated footprint, rate, pass rate or quantity
  removes the entry or holds it to the unbounded tier; a `null` cost or energy ranks last; an
  unknown audience is one receiver; a lapsed list revives no earlier one; and a figure whose
  records are not given, not current or not confirmed ranks as an estimate, and one its own records
  refute as unknown.
- **Repricing.** The latest list stands alone, and two of one instant that differ offer nothing.
- **A stated audience is the comparer's.** A plan with an audience above 1 rests on that
  statement, and restates it. The break-even audience lets a comparer decide without stating one.
- **What a list reveals.** It reveals the seller's prices, tiers and footprint to everyone it
  reaches. A peer that signs its list with the key of its holdings record links its prices to its
  holdings (holdings §9); a peer that wants its records unlinked signs with a separate key, and the
  two are then not joined. A list names its records only by digest; a seller that gives a comparer
  its per-hop records reveals their rooms, spans, sessions, subscriber time and bytes to that
  comparer.
- **Bounded work.** A list is at most 1,048,576 bytes and a request at most 65,536, each read once.
  A comparison is one pass over each standing list's entries, and each footprint test is a search
  in sorted codes. Each text given as evidence is hashed once and read once as a per-hop record and
  once as a room descriptor, and an entry names at most 64 records.