Concepts
Receipts and disclosure
Every settled payment is a receipt. The owner or the payee can disclose one payment to one person, who checks it against the chain.
A receipt is the record of one payment: who was paid, how much, for which request, what was returned and when. The chain already holds all of it, encrypted. The owner and the payee read it with their own keys, and either of them can disclose that one payment to someone else without showing anything more.
What a receipt binds
Two transactions make a receipt. pay creates the hold, which carries the payee, the owner, the amount, the mint, the request hash and the deadline. settle spends the hold and carries the response hash.
| Field | Type | Meaning |
|---|---|---|
paySignature | signature | The pay transaction. It identifies the payment. |
payee | Address | Who was paid. |
owner | Address | The owner of the remit that paid. |
amount | u64 string | The price, in base units of mint. |
mint | Address | The mint it was paid in. |
requestHash | 32 bytes, hex | The hash of the request the payment was made for. |
status | held, settled or refunded | Where the payment stands. |
paidAt | unix seconds | When the hold was created. |
settleSignature | signature | The settle transaction. Present once settled. |
responseHash | 32 bytes, hex | The hash of the response the payee returned. Present once settled. |
settledAt | unix seconds | When it settled. Present once settled. |
The agent fixes the request hash when it pays. It is part of the hold's commitment, so nobody can change it afterwards. The payee fixes the response hash when it settles. Together they say: this payee was paid this amount for this request and answered with this response.
A payment that was refunded has a receipt too. It shows the hold and that it returned to the owner, with no response hash.
Disclosing one payment
A disclosed receipt is one string. It holds the pay signature and the hold's opening: the values behind the hold's commitment, which are the payee, the owner, the amount, the mint, the request hash, the deadline and the hold's blinding value.
The owner discloses from the remit's statement and the payee from the Earn screen. Each payment has a Disclose button that copies a link to Verify with the receipt in it. The receipt can be sent as the link or as the bare string.
What the person who receives it can read:
- that payment's fields, as in the table above
What they cannot read from it:
- the remit it came from: its balance, its caps, its payee list, its expiry
- any other payment by the same agent or to the same payee
- anything else in the owner's or the payee's private balance
A receipt carries no key. It cannot spend anything and it does not decrypt any other transaction.
How a receipt is verified
Verification trusts nothing in the receipt. It checks each value against the chain:
- It recomputes the hold's commitment from the opening in the receipt.
- It fetches the
paytransaction by its signature and checks that this commitment is among its outputs. A receipt with a changed amount, payee or request hash produces a different commitment and does not match. - It derives the hold's nullifier and looks for the transaction that spent the hold.
- If that transaction is a
settle, the status issettledand the response hash is read from its instruction data. If it is arefund, the status isrefunded. If the hold is unspent, the status isheld.
Verify does this for a pasted receipt and needs no wallet. The same check is one API call:
POST /v1/engine/receipts/verify
Content-Type: application/json
{ "receipt": "<the disclosed string>" }It answers with the fields above, or with one of two errors:
| Code | Status | Meaning |
|---|---|---|
RECEIPT_NOT_FOUND | 404 | The string is not a receipt, or no pay transaction with that signature exists. |
RECEIPT_MISMATCH | 422 | The transaction exists and the receipt's values do not match its output. |
Checking the request and the response
A receipt proves which hashes were paid for and settled. Someone who also has the request and the response themselves can hash them and compare: The HTTP payment scheme defines both hashes.