Docs / Protocol reference

Claims

A claim is one transaction with one outcome. Anyone may submit it; the payout always goes to the buyer named in the receipt. Evidence or preconditions that fail return an error and record nothing. When the evidence is valid, the validator decides: a proven breach pays, an unproven one is recorded as rejected.

claim(predicate_id: u32, offer: SignedOffer, receipt: SignedReceipt, extra: ClaimExtra) -> Result<ClaimOutcome, ClaimError>
// ClaimOutcome: Paid(amount: i128) | Rejected(reason: u32)      reason 1 = NotProven, 2 = NotVerifiable

The pipeline

Checks, in order

1. Version. offer.version and receipt.version are both 1; else UnsupportedVersion.
2. Service. get_service(receipt.service_id) succeeds and the state is not Closed; else UnknownService.
3. Receipt signature. The key at receipt.key_version exists (else BadSignature); it was not retired before served_at (else KeyRetired); the Ed25519 signature over receipt_hash verifies (else the transaction traps).
4. Offer. offer.registry is this registry and offer.service_id == receipt.service_id and receipt.offer_hash == offer_hash(offer); else OfferMismatch. The key at offer.key_version exists (else BadSignature) and the offer signature verifies.
5. Claim window. get_terms(service_id, offer.terms_hash) succeeds (else OfferMismatch); served_at ≤ now and now ≤ served_at + claim_window; else WindowClosed.
6. Not paid before. No paid record exists for (service_id, payment_reference); else AlreadyClaimed.
7. Predicate and stake. predicate_id is in terms.predicates (else PredicateNotOffered); stake > 0 (else NoStake). For P1, the second receipt in extra passes the same signature and key-retirement checks.
8. Validator. A validator is set for the predicate (else ValidatorNotSet). Ok(()) is proven; Err(NotProven) is Rejected(1); any other failure is Rejected(2). Rejections emit ClaimRejected and return Ok(Rejected(reason)).
9. Payout. The claim record is written first, then slash(service_id, receipt.buyer, offer.max_claim) is called on the registry, which caps at the remaining stake (and at max_payout if set) and applies the slash rate limit. EpochCapReached from the registry returns SlashRateLimited, which rolls the record back so the claim can be retried; any other slash failure returns NoStake. On success the record is updated with the amount, ClaimPaid is emitted and Ok(Paid(amount)) returned.

Outcomes

Payout rule. payout = min(offer.max_claim, stake remaining), further capped by the launch limit max_payout when it is non-zero, and subject to the slash rate limit (at most 50% of epoch-start stake per epoch, first slash of an epoch always allowed). Recording the claim before slashing means a payout can never be made twice for one payment, even if the slash fails part-way.

Error codes

The TypeScript binding maps these codes to names (CLAIM_ERRORS), so a failed submission reads as WindowClosed (#4).

Claim records

Records are keyed by (service_id, payment_reference) in persistent storage; get_claim(service_id, payment_reference) returns one. Their lifetime is extended on every claim (threshold 30 days, extended to 60 days, counted in ledgers), far beyond the longest claim window.

Events

The registry additionally emits Slashed and, when the payout takes stake below the minimum, StateChanged to Suspended.

Functions

__constructor(admin, registry, change_delay)                        // change_delay > any unbonding delay (93,600 s on the first deployment)
claim(predicate_id, offer, receipt, extra) -> Result<ClaimOutcome, ClaimError>
get_claim(service_id, payment_reference) -> Option<ClaimRecord>
get_validator(predicate_id) -> Option<Address>
get_registry() -> Address
get_pending_validator(predicate_id) -> Option<PendingValidator { validator, eta }>
set_validator(predicate_id, validator) -> Result<u64, ClaimError>  // admin; first setting immediate (returns 0), replacement time-locked (returns eta)
apply_validator(predicate_id) -> Result<Address, ClaimError>       // anyone, after eta
cancel_validator_change(predicate_id) -> Result<(), ClaimError>    // admin
extend_instance_ttl()                                               // anyone; keeps instance storage alive