Docs / Protocol reference

Offer, receipt and terms

Three structures carry the whole protocol: the terms a service registers, the offer it signs before payment and the receipt it signs after. All three are contract types; their canonical encoding is ScVal XDR, which is what gets hashed and signed.

JSON Schemas derived from the contract types: terms.json, offer.json, receipt.json. In JSON, 32-byte values are lowercase hex, i128 amounts are decimal strings, u64 times are Unix seconds, and addresses are strkeys.

Terms

A service’s registered warranty terms. Hashed (terms_hash) and versioned; every offer pins one version. min_stake is deliberately not part of the terms, so changing the stake requirement never invalidates offers or receipts a buyer holds.

OracleTerms

Validity rules

The registry rejects terms with InvalidTerms unless all of the following hold:

• predicates is non-empty, each ID is 1 to 6, and no ID repeats
• 1 ≤ claim_window ≤ max_claim_window (86,400 s on the first deployment)
• P3 listed ⇒ max_data_age > 0; P4 listed ⇒ allowed_status non-empty; P5 listed ⇒ max_response_bytes > 0
• P6 listed ⇒ claim_window ≤ max_oracle_claim_window (3,600 s) and oracle = Some(o) with o.max_oracle_age > 0

{
  "predicates": [3, 4, 6], "claim_window": 3600, "max_data_age": 30, "allowed_status": [200], "max_response_bytes": 4096,
  "oracle": { "oracle_contract": "C…", "oracle_asset": { "Other": "EUR" }, "max_deviation_bps": 50, "max_oracle_age": 600 }
}

Offer

The seller’s signed promise for one call, shown with the 402 response. It does not repeat the warranty conditions: those live on-chain as the registered terms, and terms_hash pins the exact version the buyer is paying under. The offer is the signed body; the signature travels beside it in SignedOffer { offer, signature }.

The middleware sets valid_until = now + offerValiditySeconds (default 120 s), max_claim from its configuration, price and asset from the matching x402 requirement, and key_version from the service’s current key.

Receipt

The seller’s signed statement of what it served and under which offer. Every field is a claim the seller can be held to. Signed body; the signature travels beside it in SignedReceipt { receipt, signature }.

OracleEvidence

The contract does not check that the payment happened. The seller’s signature over payment_reference and buyer is its admission that it did, and any payout comes from the seller’s own stake. The middleware takes buyer and payment_reference from the facilitator’s settlement result and only issues receipts for offers it signed itself.

Registry records

Service

SigningKey

ProtocolConfig, LaunchLimits, FeeConfig

Validator types