WAI Extension: Play Royalties
Mirrored from the canonical text at commit 498e6b88 ().
Status: Draft. Registers the record
wai.delivery.play_royalties: what a service’s plays of recordings give each holder of a share in the works recorded, as a statement anyone holding the signed records recomputes. A listener’s device signs a play receipt (wai-play) for each play, under a key made for one subscriber and one period and bound to the subscriber’s entitlement of key-release by the entitlement’s holder key: it names the recording by a works document of music-rights and its position, the milliseconds played, a region aggregated as WAI aggregates one, and the delivered objects it presented, by the content hashes jwp-receipts names them by. The service signs a pool (wai-royalty-pool): its period, currency and amount, the invoices of receipt-ledger the amount is computed from where it names them, the model (pro_rataoruser_centric), every threshold a play and a recording meet to count, the multipliers, and the listeners it excludes, each with its reason. A ledger signs a statement (wai-royalty-statement): one counted-plays table, the pool divided over it in integers with the largest-remainder rule revenue-share divides by, each recording’s part divided among its works, and each work’s part among the holders of right-shares’ view of its key, where a view in conflict goes to a suspense line, never paid and never resolved, and money no stated share reaches goes to an unallocated line that says why. A verifier given the receipts recomputes every figure and refuses a statement that does not recompute; one given no receipts checks the statement against its own aggregates and says so. No new transport, no payment and no legal rule: a statement is the figures a payment rests on, and how they are checked. The reference implementation is theplay_royaltiesmodule ofwai-rs(featureplay_royalties); the corpus islive-conformance/play-royalties/, and its second implementation islive-conformance/play_royalties_verify.py. Keywords MUST, MUST NOT, SHOULD, MAY are RFC 2119/8174.Texts read for this revision: the WAI texts this one cites, as merged on 14 November 2026; RFC 8032; RFC 8259; RFC 8785; FIPS 180-4. Decision D139 records the choices this text makes and why.
1. Scope
In scope: the play receipt, its binding to an entitlement and its digest and signature (§3); the pool, its thresholds, multipliers, exclusions and funding (§4); which plays count and the counted-plays table (§5); dividing the pool over the table under each model, a recording’s part among its works and a work’s part among its holders, with the suspense and unallocated lines (§6); the statement (§7); its verification from the receipts or from its aggregates (§8); and what a statement does not show (§9).
Out of scope: paying anyone, an account a payment reaches, and converting a currency; what a subscriber pays and how a service sets a pool’s amount or rate, which a pool states and this text does not choose; whether a holder is entitled to what a share statement states, which right-shares §1 leaves out too; resolving a conflict between share statements; shares of a recording’s own rights (its sound recording, as distinct from the works it is a performance of), which no WAI record states in this revision; how a device decides that a person listened; and every legal effect of a pool or a statement. WAI texts set no legal rules: this extension states what a statement carries and how it is checked, not what anyone is owed under any law or contract.
Relationship to the core spec: wai.delivery.play_royalties is a record (SPEC
§5): signed records a WAI tool emits and verifies. It names no payload format and is not
dispatchable.
Relationship to the texts it reads: a play receipt names a works document by its digest (music-rights §5.2), an entitlement by its digest (key-release §5.2) and objects by their content hashes (jwp-receipts §2.1); a pool names invoices by their digests (receipt-ledger §6.7); a statement reads views of right-shares §5.2. It changes none of their records, rules, corpora or reasons.
2. Terms
- Document, canonical form, digest, key, signature, time, amount and
content hash: as route-record §2. Every integer of a document is
therefore at most 2⁵³ − 1. A period is a span of time from its
start(included) to itsend(excluded). - Works document, text and package: as music-rights §5.1, §2. A recording is named
by a works document’s digest and its position from 0 in the document’s
recordings; its length is itsto_ms−from_ms; its works are the work statements itsworksmember names, in that member’s order. A work is named by a works document’s digest and its position from 0 in the document’sworks. - Share type, right type, view, agreed party and a view’s status: as right-shares §3 and §5.2. A key of a view is a work, a share type and a right type.
- Region code and holds: as rung-price §2.
- Entitlement, holder key and entitlement authority: as key-release §2 and §5.1; an entitlement holds as key-release §5.2 says, and its digest is that section’s.
- Group receipt and object receipt: jwp-receipts §2.4.1 and §2.4.2, in their JSON form.
- Invoice: receipt-ledger §6.1’s
WLI1, its digest as receipt-ledger §6.7 computes it. - Service: the key that signs a pool. Ledger: the key that signs a statement; it may be the service’s or another party’s.
- Listener: a key a device holds for one subscriber and one period, which signs that subscriber’s play receipts of the period (§3). A listener is one subscriber’s within its period: two listeners are two subscribers, and a subscriber’s plays in another period are signed under another key.
- ppm: an integer share in millionths, of 10⁶.
- ⌊x⌋ is x rounded down; products are computed in integers wide enough not to overflow.
3. The play receipt
3.1 The receipt
A play receipt states one play of one recording. It is a document of exactly these members:
| member | form |
|---|---|
kind | "wai-play" |
version | 1 |
listener | a key: the listener, which signs the receipt |
start, end | times, start below end: the period the listener is for |
entitlement | 64 lowercase hexadecimal digits: the digest of the subscriber’s entitlement |
binding | a signature: by the entitlement’s holder key (§3.2) |
works | 64 lowercase hexadecimal digits: the digest of a works document |
recording | an integer: the position from 0 of the recording in that document’s recordings |
at | a time, from start (included) to end (excluded): when the play began |
played_ms | an integer from 1: the milliseconds of the recording presented |
region | a region code, or null where the device does not state one |
context | "chosen" where the listener chose the recording, "programmed" where the service chose it, or null where the device does not state which |
objects | an array of 1 to 512 content hashes, in strictly ascending order: the delivered objects the play presented |
sig | a signature by listener (§3.3) |
region is the code the device aggregates its own location to before anything leaves it, as
audience-decision §4.3 aggregates a session’s: a receipt carries the code
and no more. A receipt states a play of the subscriber its entitlement names, and a device signs
one receipt for each play; two plays that began at one instant are two receipts only where some
member differs.
3.2 The binding
The binding ties a listener to one entitlement for its period. It is Ed25519 by the
entitlement’s holder key over wai:play-listener (ASCII) and 0x01, followed by the canonical form
of the document of exactly the receipt’s entitlement, listener, start and end, verified
strictly as SPEC §7 Signatures verifies every signature. Every receipt of one
listener in its period carries the same binding. The device that holds the holder key makes a
listener when a period begins and signs its one binding for that period.
3.3 Digest and signature
The digest of a receipt is SHA-256 over the canonical form of the receipt without sig,
written as 64 lowercase hexadecimal digits. Its signature is Ed25519 by listener over
wai:play (ASCII) and 0x01, followed by that same canonical form, verified strictly as SPEC §7
Signatures has it. A receipt is named by its digest.
4. The pool
4.1 The pool
A pool states the money a service divides by plays in one period, and every rule it divides by. It is a document of exactly these members:
| member | form |
|---|---|
kind | "wai-royalty-pool" |
version | 1 |
service | a key: the service, which signs the pool |
start, end | times, start below end: the period |
currency | three capitals A–Z: an alphabetic currency code of ISO 4217 |
amount | an amount from 1: what the pool divides |
funding | null, or an object of exactly invoices and rate_ppm (§4.4) |
model | "pro_rata" or "user_centric" (§6.2, §6.3) |
contributions | null under pro_rata; under user_centric, an array of 1 to 65 536 objects of exactly listener (a key) and amount (an amount from 1), in strictly ascending order of listener (§6.3) |
share_type | a share type (right-shares §3): the share of a work the pool pays |
right | a right type (right-shares §3): the right the plays use |
authorities | an array of 1 to 64 keys, in strictly ascending order: the entitlement authorities whose entitlements a receipt may cite |
publishers | an array of 1 to 64 keys, in strictly ascending order: the keys whose group receipts may deliver a play’s objects |
regions | null, or an array of 1 to 8 192 region codes in strictly ascending order of their bytes: the regions whose plays the pool counts |
qualifying_ms | an integer from 1: the least played_ms that counts a play |
min_plays | an integer from 1: the least counted plays a recording needs |
min_listeners | an integer from 1: the least distinct listeners a recording’s counted plays need |
listener_cap | null, or an integer from 1: the most plays of one listener the period counts |
multipliers | an array of 0 to 2 objects of exactly context ("chosen" or "programmed") and weight (an integer from 2 to 1 000), in the order chosen, programmed, each context at most once |
below | "redistribute" or "unallocated": where the part of a recording below a threshold goes (§6.1) |
excluded | an array of 0 to 65 536 objects of exactly listener (a key) and reason, in strictly ascending order of listener |
sig | a signature by service (§4.5) |
A pool divides money for one share type and one right: a service that pays two rights divides two pools.
4.2 Thresholds and multipliers
Every threshold is a member of the pool, and the service signs it: qualifying_ms for a play,
min_plays and min_listeners for a recording, listener_cap for a listener, and regions for
where a play was. A threshold of 1, and null for listener_cap and regions, leave nothing out.
A play’s weight is the weight of the multiplier whose context is the receipt’s, and 1 where
the pool lists none for it, or where the receipt’s context is null. A weight multiplies a play
in the table (§5.2); it never makes a play count that does not.
4.3 Exclusions
The pool lists each listener whose plays it does not count, with the service’s reason:
"artificial" (plays the service found not made by a person listening), "test" (a key of the
service’s own testing), "refunded" (a subscription whose fee was returned) or "other". An
exclusion is the service’s statement, signed; a verifier checks that it was applied as listed and
that its money is on a line of its own (§6.3), not why it was made.
4.4 Funding
funding null states that amount is the service’s figure, which no record the pool names
computes. Otherwise invoices is an array of 1 to 256 digests of invoices, in strictly ascending
order, and rate_ppm an integer from 1 to 10⁶; then amount is ⌊S × rate_ppm / 10⁶⌋, where
S is the sum of the invoices’ amount, and each invoice is one the service sold, in the pool’s
currency, for a period within the pool’s (§8.2 step 3). A verifier holding the invoices recomputes
the amount from them.
Under user_centric, the contributions sum to exactly amount: they are how the service divides
the pool among its subscribers, one contribution for each listener, and a subscriber that knows
its own listener checks its own line. A pool may list a contribution of a listener no receipt
names (§6.3).
4.5 Digest and signature
The digest of a pool is SHA-256 over the canonical form of the pool without sig, and its
signature is Ed25519 by service over wai:royalty-pool (ASCII) and 0x01, followed by that
canonical form, verified strictly (SPEC §7 Signatures).
5. Counting
5.1 Which plays count
The receipts of a pool are taken in ascending order of (at, digest). Each is, at the first of
these that applies:
- excluded: its
listeneris listed in the pool’sexcluded; - short: its
played_msis belowqualifying_ms; - region_unknown: the pool’s
regionsis notnulland the receipt’sregionisnull; region_outside: the pool’sregionsis notnulland does not hold the receipt’sregion; - capped:
listener_capis notnullandlistener_capreceipts of its listener, earlier in this order, are counted; - otherwise counted, with its weight (§4.2).
A receipt that is not counted is still a receipt the statement rests on: the statement states how
many of each class there are (§7.1, uncounted). A cap is applied in the order of the plays, so
the plays past it are a listener’s latest.
5.2 The counted-plays table
The table has one row for each recording with at least one counted play, in ascending
order of (works by its bytes, recording). A row states:
plays: its counted plays;weighted: the sum of their weights;listeners: the number of distinct listeners among them;status:"counted"whenplaysis at leastmin_playsandlistenersat leastmin_listeners; otherwise"below_plays"whenplaysis belowmin_plays, and"below_listeners"when it is not.
Under user_centric the table also has its listening: for each listener with at least one
counted play, in ascending order of the listener, that listener’s rows, each a recording with its
plays and weighted of that listener alone, in the table’s order. A row’s plays and
weighted are the sums of the listening’s, and its listeners the number of listeners whose
listening names it.
The table is one table for both models: the thresholds read it, every division reads it, and a verifier given no receipts reads the statement’s copy of it (§8.3).
6. Dividing the pool
6.1 The division
A division of an amount A among parts with integer weights w₁ … wₙ, each at least 1, in their order, gives each part an integer, and the integers sum to A exactly. With W the sum of the weights:
- each part’s quota is A × wᵢ, its base ⌊quota / W⌋, and its remainder quota − base × W;
- the leftover is A less the sum of the bases, which is less than n;
- the parts with the largest remainders, as many as the leftover, each receive one more than their base; between equal remainders, the earlier part receives it first.
This is revenue-share §7.3’s largest-remainder rule with weights that need not sum to 10⁶. Each division rounds once: its parts are floors, and the residue goes by the remainders. No play is ever valued alone, so rounding does not accumulate over plays.
The division set is the rows a model divides over: under below "redistribute", the rows
whose status is counted, so a recording below a threshold takes no part and the others share
what its plays would have taken; under "unallocated", every row, and the part of a row below a
threshold goes to its below_threshold line (§6.6), so the counted recordings take only what
their own plays give them.
6.2 Pro rata
The pool’s amount is divided among the rows of the division set, each weighted by its
weighted, in the table’s order. A pool whose division set has no row gives its whole amount to
the no_plays line.
6.3 User-centric
Each contribution, in the pool’s order, is divided by itself:
- a contribution of an excluded listener goes to the
excludedline; - a contribution of a listener whose listening names no row of the division set goes to the
no_playsline; - otherwise the contribution is divided among the rows of the division set its listener’s
listening names, each weighted by that listener’s
weighted, in the table’s order.
A row’s part is the sum of the parts every contribution gives it. A listener with a counted play has a contribution (§8.2 step 8): the model divides each subscriber’s money by its own plays, and a play no contribution pays for is a play of nobody the pool funds.
6.4 A recording among its works
A row whose status is counted gives its part to its recording’s works: divided among them in
equal weights, in the order the recording’s works names them; a recording whose works document
names no work for it gives its part to its no_work line. A works document states no share of a
recording among its works, so equal weights are this revision’s rule. A work’s part is the sum
of the parts its recordings give it.
6.5 A work among its holders
The holders of a work are those of the view of the key (the work, the pool’s share_type, the
pool’s right) that combining the share statements given for its works document gives
(right-shares §5.2). For each work with a part, in ascending order of (works by its bytes,
work):
- No statement. No statement given for its works document states the key: its part goes to
its
no_statementline. - Suspense. The view’s status is
conflict: its part goes to itssuspenseline. A suspense line pays no claimant and resolves nothing: the claims stay as right-shares §5.3 leaves them. The statement states the money held for the work; who claims it is the view’s, from the share statements given. - Holders. Otherwise the part is divided among the view’s agreed parties whose share is not
null, in the view’s order, weighted by their shares, and then, where the view’s remainder is above 0, the remainder, weighted by it. Each party’s part is itspaymentsline; the remainder’s part is the work’sremainderline: the share of agreed parties whose share is not known, and of the right no party claims.
A share not known is never paid as 0 and never shared out among the shares that are known: its
money is on the remainder line, as right-shares §4.1 keeps it in the remainder.
6.6 The lines
Every unit of the pool’s amount is on exactly one line:
- a payment of a work:
works,work, the party’snameandisnias the view names it, itsshareand itsamount; - a suspense line of a work:
works,workandamount; - an unallocated line, which states its
reason, and where it names a recordingworksandrecording, or a workworksandwork, then itsamount:
| reason | names | what it holds |
|---|---|---|
no_plays | nothing | a pro rata pool whose division set has no row; under user_centric, the contributions of listeners whose listening reaches no row of it |
excluded | nothing | under user_centric, the contributions of excluded listeners |
below_threshold | a recording | under below "unallocated", the part of a row below a threshold |
no_work | a recording | the part of a counted recording whose works document names no work for it |
no_statement | a work | the part of a work no share statement given states the key of |
remainder | a work | the part of a view’s remainder |
A line stands wherever what it holds stands, whatever its amount: a remainder line for every
work with a part whose view has a remainder above 0, a payment for every agreed party with a share,
and an unallocated line of each kind the division gives part of the pool to, so that a reader sees
every holder and every share not known even where a part rounds to 0. Payments are in ascending
order of (works, work) and then the view’s order; suspense lines in ascending order of
(works, work); unallocated lines in the order of the table above, and within a reason in
ascending order of (works, recording) or (works, work).
7. The statement
7.1 The statement
A statement states the division of one pool. It is a document of exactly these members:
| member | form |
|---|---|
kind | "wai-royalty-statement" |
version | 1 |
ledger | a key: the ledger, which signs the statement |
pool | 64 lowercase hexadecimal digits: the pool’s digest |
works | an array of 0 to 1 024 digests, in strictly ascending order: the works documents the table’s rows name |
receipts | an object of exactly count (an integer) and digest (64 lowercase hexadecimal digits): the receipts the statement rests on (below) |
uncounted | an object of exactly excluded, short, region_unknown, region_outside and capped, each an integer: the receipts not counted, by class (§5.1) |
recordings | an array of 0 to 65 536 rows, each an object of exactly works, recording, plays, weighted, listeners (each of plays, weighted and listeners an integer from 1), status and amount (an amount) |
listening | null under pro_rata; under user_centric, an array of 0 to 65 536 objects of exactly listener (a key) and rows (an array of 1 to 65 536 rows), each row an object of exactly works, recording, plays and weighted (each of plays and weighted an integer from 1) |
payments | an array of payments (§6.6), each an object of exactly works, work, name (a text), isni (a string or null), share (ppm from 1 to 10⁶) and amount |
suspense | an array of suspense lines, each an object of exactly works, work and amount |
unallocated | an array of unallocated lines, each an object of exactly reason and amount, with works and recording or works and work where §6.6’s table names them |
sums | an object of exactly payments, suspense and unallocated: each kind’s lines summed |
sig | a signature by ledger (§7.2) |
A row’s amount is its part of the division under §6.2 or §6.3 where its status is counted, and
0 where it is not: a row below a threshold takes no part, and its plays’ money is either shared by
the counted rows or on its below_threshold line, as the pool’s below says. The three sums
add to the pool’s amount.
receipts commits to every receipt the table was counted from, counted or not: count is their
number, and digest SHA-256 over wai:royalty-receipts (ASCII) and 0x01, followed by each
receipt’s digest (32 bytes) in strictly ascending order. A ledger that later discloses the receipts
discloses exactly these; one that drops a receipt changes the digest.
7.2 Digest and signature
The digest of a statement is SHA-256 over the canonical form of the statement without sig,
and its signature is Ed25519 by ledger over wai:royalty-statement (ASCII) and 0x01, followed by
that canonical form, verified strictly (SPEC §7 Signatures).
8. Verification
8.1 Inputs
A verifier is given one verification document, a JSON object of exactly these members:
| member | value |
|---|---|
pool | the pool’s text |
statement | the statement’s text |
invoices | an array of invoices, each its bytes in lowercase hexadecimal |
works | an array of objects of exactly text (a works document’s text) and package (exactly pack_digest and components: the package it names, music-rights §5.3) |
shares | an array of objects of exactly works (a works document’s digest) and statements (an array of share statements’ texts, in order) |
receipts | null where the receipts are not disclosed; otherwise an object of exactly plays (an array of play receipts’ texts), entitlements (an array of entitlements, each its bytes in lowercase hexadecimal), groups (an array of group receipts) and objects (an array of object receipts) |
8.2 Steps
It refuses at the first that applies, with the reason and where (at, the path of the input):
royalty_document_malformed, atdocument: the document is not of §8.1’s form.- The pool, at
pool:pool_malformedwhen its text holds more than 4 194 304 bytes, is not a document, or its members are not exactly §4.1’s, each of its form,contributionsnullexactly underpro_rata;pool_signature_invalidwhen its signature does not verify;pool_contributions_mismatchwhen, underuser_centric, the contributions do not sum toamount. - The funding, where it is not
null, each invoice in the orderinvoicesnames them, atpool,fundingand its position:pool_invoice_missingwhen no invoice given has that digest (SHA-256 over its bytes before its last 64);pool_invoice_invalidwhen it does not read by receipt-ledger §6.8, its signature among its rules;pool_invoice_foreignwhen itsselleris not the pool’sservice, itscurrencynot the pool’s, or its period not within the pool’s. Then, atpool,pool_amount_mismatchwhenamountis not §4.4’s. - The statement, at
statement:statement_malformedwhen its text holds more than 16 777 216 bytes, is not a document, or its members are not exactly §7.1’s, each of its form;statement_signature_invalidwhen its signature does not verify;statement_pool_mismatchwhenpoolis not the pool’s digest. - The works documents, each in order, at
worksand its position: verified against its package by music-rights §5.3, that text’s reason;royalty_document_malformedwhen its digest is an earlier one’s. Then, atstatement,statement_works_missingwhen the statement’sworksnames a digest no works document given has. - The share statements, each group in order, at
sharesand its position:shares_works_unknownwhen itsworksis not the digest of a works document given, androyalty_document_malformedwhen it is an earlier group’s; then its statements combined over that works document and its package by right-shares §5.2, a refusal being that text’s reason with the position of the statement afterstatements. - The receipts, where they are given:
- each entitlement, at
receipts,entitlementsand its position:entitlement_invalidwhen it does not hold (key-release §5.2);entitlement_foreignwhen its authority is not one of the pool’sauthorities; - each group receipt, at
receipts,groupsand its position:delivery_invalidwhen it does not read or its signature does not verify (jwp-receipts §3, steps 1 and 2);delivery_foreignwhen itssigner_pubkeyis not one of the pool’spublishers; - each object receipt, at
receipts,objectsand its position:delivery_invalidwhen it does not read, or no group receipt given of itstrack_aliasandgroup_idholds it by its proof (jwp-receipts §3, steps 4 and 5); - each play receipt, in order, at
receipts,playsand its position:play_malformed: its text holds more than 65 536 bytes, is not a document, or its members are not exactly §3.1’s, each of its form;play_signature_invalid: its signature does not verify by itslistener;play_duplicate: its digest is an earlier receipt’s;play_period_mismatch: itsstartandendare not the pool’s;play_entitlement_missing: no entitlement given has itsentitlementas digest;play_binding_invalid: itsbindingdoes not verify by the entitlement’s holder key;play_not_entitled: ⌊at/ 10⁶⌋ is before the entitlement’snot_beforeor after itsnot_after;play_listener_conflict: an earlier receipt binds itslistenerto another entitlement, or itsentitlementto another listener;play_recording_unknown: itsworksis not the digest of a works document given, or itsrecordingnot the position of one of that document’s recordings;play_longer_than_recording: itsplayed_msis above the recording’s length;play_not_delivered: one of itsobjectsis not thecontent_hashof an object receipt given.
- each entitlement, at
- The figures, at
statement. The table is counted from the receipts (§5) where they are given, and is the statement’srecordingsandlisteningwhere they are not.contribution_missing, atpool: underuser_centric, a listener of the table’s listening has no contribution.- With the receipts:
statement_receipts_mismatchwhenreceiptsis not their count and digest (§7.1); thenstatement_table_mismatchwhenworks,uncounted, the rows but theiramount, orlisteningare not those counted. Without them:statement_table_mismatchwhen the statement’s table does not hold together: the rows are not in §5.2’s order, each recording once, or a row’sworksandrecordingare not a recording of a works document given, itsstatusis not the one §5.2 gives itsplaysandlisteners, itsweightedis below itsplaysor above itsplaystimes the pool’s largest weight, itslistenersabove itsplays,worksis not the rows’ works documents, orlisteningis notnullexactly underpro_rataand, underuser_centric, is not in §5.2’s orders or does not sum to the rows as §5.2 says. statement_lines_mismatchwhen a row’samount, a line, the order of the lines orsumsis not what §6 gives over the table.
8.3 Outcome
- refuse: the reason and
at. - accept: the statement’s digest and the pool’s; the model; the basis,
receiptswhere the table was counted from the receipts andaggregateswhere it was read from the statement; the funding,invoiceswhere the amount was recomputed from invoices andstatedwhere the pool’sfundingisnull; the currency and the amount; the number of receipts,nullon the basisaggregates; the counted plays, the rows and the rows below a threshold; and the sums of the payments, the suspense lines and the unallocated lines.
On the basis aggregates, a verifier has checked the division, the thresholds against the rows,
the works and the holders’ shares, and that every unit of the pool is on a line: it has not checked
that the rows are what any receipt states, and it says so. A ledger that cannot disclose the
receipts to a reader discloses the statement, whose receipts commits to them, so that a later
check against them is of the same receipts.
9. What a statement does not show
- That anyone listened. A receipt is its device’s statement, under a key the subscriber’s
entitlement holder bound for the period. The binding shows that the entitlement’s holder made
the listener and that the entitlement authority is one the pool names; the objects show that
what the play presented was delivered under a publisher the pool names. Neither shows a person
listening, which the service’s exclusions speak to and the pool’s
qualifying_msbounds. - That the objects are the recording’s. A receipt names the recording it played and the delivered objects it presented, and no record of this revision ties an object’s content hash to a recording of a works document: a verifier checks that each object was delivered under a publisher the pool names, not that it carries the recording the receipt names.
- That the pool is all the money. A pool with
fundingstates the invoices it was computed from, and a verifier recomputes the amount from them; one without it states a figure. Revenue the service did not invoice, or invoiced outside the pool’s invoices, is in no statement. - That a share is owed. Payments follow the shares that share statements state and combine to, and a statement shows what each view gives; whether a signer holds what it states is right-shares §10’s question, not this text’s.
- The receipts, without them. On the basis
aggregates, the rows are the ledger’s. Thereceiptscommitment fixes which receipts a later disclosure must be.
10. Reasons
| reason | raised at |
|---|---|
royalty_document_malformed | §8.2 steps 1, 5 and 6 |
pool_malformed | §8.2 step 2 |
pool_signature_invalid | §8.2 step 2 |
pool_contributions_mismatch | §4.4, §8.2 step 2 |
pool_invoice_missing | §8.2 step 3 |
pool_invoice_invalid | §8.2 step 3 |
pool_invoice_foreign | §4.4, §8.2 step 3 |
pool_amount_mismatch | §4.4, §8.2 step 3 |
statement_malformed | §8.2 step 4 |
statement_signature_invalid | §8.2 step 4 |
statement_pool_mismatch | §8.2 step 4 |
statement_works_missing | §8.2 step 5 |
shares_works_unknown | §8.2 step 6 |
entitlement_invalid | §8.2 step 7 |
entitlement_foreign | §8.2 step 7 |
delivery_invalid | §8.2 step 7 |
delivery_foreign | §8.2 step 7 |
play_malformed | §8.2 step 7 |
play_signature_invalid | §8.2 step 7 |
play_duplicate | §8.2 step 7 |
play_period_mismatch | §8.2 step 7 |
play_entitlement_missing | §8.2 step 7 |
play_binding_invalid | §3.2, §8.2 step 7 |
play_not_entitled | §8.2 step 7 |
play_listener_conflict | §8.2 step 7 |
play_recording_unknown | §8.2 step 7 |
play_longer_than_recording | §8.2 step 7 |
play_not_delivered | §8.2 step 7 |
contribution_missing | §6.3, §8.2 step 8 |
statement_receipts_mismatch | §7.1, §8.2 step 8 |
statement_table_mismatch | §5.2, §8.2 step 8 |
statement_lines_mismatch | §6, §8.2 step 8 |
A verifier also gives music-rights’ reasons for a works document it refuses (§8.2 step 5) and right-shares’ reasons, with music-rights’ for an ISNI, for a share statement it refuses (§8.2 step 6).
11. Conformance
live-conformance/play-royalties/ holds the corpus, in one file, vectors.json, written from fixed
seeds by wai_play_royalties_vectors gen. It holds each record once, by name: two works documents
with their packages and a third no play names; the share statements over the first two, the
second’s two statements in conflict over one work; four subscribers’ entitlements and a fifth’s;
the group and object receipts of each of six recordings’ three objects; fifteen play receipts of
one month by four listeners; two invoices of the service in one chain; nine pools and their
statements; and the altered copies the refused cases need. Each case names the records of one
verification document (§8.1), and the member it drops where it drops one, with its outcome (§8.3)
and its class:
accepted for a statement recomputed from the receipts with an amount recomputed from invoices,
gap for one checked against its aggregates or with an amount the service states, and refused.
Every figure of a statement, every row, part, line and sum, is declared by hand in the generator and
never copied from the reference, which must then accept it and state it itself, byte for byte, from
the same receipts.
- Accepted: a pro rata pool funded by two invoices, redistributing what recordings below a threshold would take, whose lines hold payments, a remainder, a suspense line for a work whose share statements conflict, a recording of no work and a work no statement states; the same receipts with the part below a threshold unallocated; with chosen plays weighing 3; with one play a listener; with plays in two countries, so that a play elsewhere and one with no region are not counted; and user-centric pools, with a subscriber who played nothing and a listener excluded, under both rules for recordings below a threshold.
- Gaps: a pool whose amount is stated; one whose recordings all fall below its threshold, so
that its whole amount is on
no_plays; and a pro rata and a user-centric statement checked against their aggregates, with no receipts given. - Refused: every reason of §10 at least once, each case a control of one defect against an accepted document, among them a receipt held back from a statement that names it, a share rounded up, a recording below a threshold paid, a suspense line paid to one of its claimants, a share not known paid as if the known shares were the whole, a contribution missing, and a status misstated and a share not known paid against aggregates; and a works document and a share statement each refused by its own text, with that text’s reason. Each condition of §8.2 that shares its reason with others has a case of its own: an invoice of the service in another currency, one ending after the pool’s period and one beginning before it; an object receipt that does not read; a play before its entitlement holds; a listener bound a second time, by another subscriber’s entitlement; a play of a works document not given; with the receipts, a statement whose uncounted classes, listening or works documents are not those counted; and against its aggregates, rows out of order, a row of no recording, a weighted figure past its bound, more listeners than plays, works documents that are not the rows’ and a listening that does not sum to its rows.
wai_play_royalties_vectors verify and the test tests/play_royalties.rs check that the file
regenerates byte for byte, that wai-rs gives every case its outcome and class, that every reason
of §10 is some case’s, and that §10 lists exactly the reference’s reasons; the module’s own tests
require the reference to state each accepted statement the corpus declares. live-conformance/play_royalties_verify.py
is the second implementation, written from this text and sharing no code with wai-rs: it takes
documents from route_record_verify.py, works documents from music_rights_verify.py, views from
right_shares_verify.py, entitlements from key_release_verify.py, group and object receipts from
jwp_verify.py and invoices from receipt_ledger_verify.py, and writes everything this text adds
itself: the receipt, the pool, the statement, counting, every division and every line. It gives
every case its outcome, requires every mutated copy of the corpus to fail, and drops each of its own
checks in turn and requires the corpus to catch the weakened verifier. Each condition of §8.2 is a
check of its own, and a check no case makes refuse is named and must be caught by the checks no
vector carries.
12. Security and privacy considerations
- Who signs what. The device signs each play under its listener; the entitlement’s holder binds the listener; the entitlement authority signs the entitlement; the publisher signs the objects delivered; the service signs the pool and every rule in it; the signers of share statements sign the shares; the ledger signs the statement. A ledger cannot move a play to another recording, count a short play, drop a threshold, round a part against a holder or pay a work in conflict: a verifier with the receipts recomputes every figure from records the ledger did not sign alone.
- What the service still controls. The pool’s amount where it is stated, its thresholds and
exclusions, its multipliers and which receipts it gives the ledger. Each is signed and shown: a
threshold is a member, an exclusion a listed key with a reason, and a statement states every
receipt it rests on by
receiptsand every receipt it did not count by class. A holder that suspects receipts were withheld asks for the receipts the commitment names. - Unknown is not zero. A share not known is on a
remainderline, a work no statement states on ano_statementline, a recording of no work on ano_workline: never a payment of 0 to a party and never a part of another party’s share. A verifier refuses a statement that pays any of them to a holder (statement_lines_mismatch). - Conflicts are held, not resolved. A work whose view is in conflict is paid to no claimant: its money is on a suspense line, and the statement names no winner (right-shares §5.3).
- What a statement reveals. Rows name recordings and their counted plays; under
user_centricthe listening names each listener’s plays of each recording, by a key that lasts one period and that only the subscriber’s holder key can be shown to have bound. A receipt states a region aggregated on the device and no location. A verification document with receipts also holds the entitlements, whose holder keys and sessions name a subscription to whoever holds the entitlement authority’s records: it travels between the service, the ledger and an auditor they choose, and a statement on the basisaggregatesreveals no receipt and no entitlement. - The listener lasts one period. A new listener each period keeps one period’s plays from being linked to another’s by the key; the entitlement digest a receipt cites does link them for whoever holds receipts of both periods, and a service that discloses receipts of several periods discloses that link.