Relayer API
POST /pay
How to submit the proof that pays for one ciphertext's storage, and what the relayer checks before it settles.
POST /pay submits a storage payment. The browser sends a Groth16 proof that spends the holder's notes for a quote's total, returns the change as a new note and binds the payment to one storage receipt; the relayer submits pay with itself as fee payer. It is called after GET /quote and before POST /upload. The holder's wallet signs nothing and appears in no part of the request.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
Request
POST /pay with Content-Type: application/json.
proofrequiredProofa (64 bytes), b (128 bytes) and c (64 bytes), each base64 in groth16-solana order. See How values travel.publicInputsrequiredPublicInputsreceiptrequiredReceiptFieldsquoteIdrequiredstringquoteId from GET /quote, 1 to 512 characters.priceLamportsrequiredU64priceLamports, unchanged.feeLamportsrequiredU64feeLamports, unchanged.networkLamportsrequiredU64networkLamports, unchanged: the network refund pay moves from the pool vault to the relayer.locatorHash32locator, unchanged: sent when the quote was requested with one (a manifest), omitted when it was not. See The locator.memosrequired[Memo, Memo]nullifiersrequired[Field, Field]outputCommitmentsrequired[Field, Field]publicAmountrequiredFieldpriceLamports plus feeLamports plus networkLamports, the quote's totalLamports. See Spending: two in, two out.bindingHashrequiredFieldreceipt, priceLamports, feeLamports, networkLamports, the relayer and memos.ciphertextRootrequiredHash32bucketrequiredBuckettermrequiredTermThe binding hash
The receipt id is the hash of the three receipt fields alone; it names no relayer, and it is the receipt's id from then on. See The receipt. The payment binding, publicInputs.bindingHash, ties the proof to that receipt, the price, the fee, the network refund, the change memos and the relayer named by relayer in GET /config. See Binding hashes.
Response
receiptrequiredFieldPOST /upload and GET /receipt/:id.signaturerequiredSignaturepay transaction's signature.slotrequiredintegerThe response arrives once the transaction is confirmed and indexed, so the next GET /tree already holds the change note.
Behaviour
A receipt is paid once. Requests for one receipt are handled one at a time, and a request whose receipt is already paid returns that payment's receipt, signature and slot and settles nothing new, whatever its quote and nullifiers. A retry after a lost response is therefore safe.
The checks run in this order, and the first that fails answers:
- The relayer is ready (
PROGRAM_UNAVAILABLE). - The body: content type, JSON, then the schema.
- A receipt already paid under the receipt id: its payment is returned.
- An earlier signed payment for this receipt that has not settled: the relayer follows it. Confirmed, its payment is returned; expired,
TRANSACTION_EXPIRED; still pending,RELAYER_FAILED. - Unless this exact request was already signed and has not expired:
quoteIdis a quote this relayer signed that has not passedexpiresAt(QUOTE_EXPIRED);networkLamportsequals the current network refund (QUOTE_EXPIRED, "The network refund changed. Request a fresh quote."); andreceipt.bucket,receipt.term,priceLamports,feeLamports,networkLamportsandlocator(both absent included) equal the quote's (VALIDATION_ERROR, "The receipt does not match the signed quote."). publicInputs.publicAmountis the public amount for price plus fee plusnetworkLamports, andpublicInputs.bindingHashis the payment binding for this request and relayer (PROOF_INVALID, stagesimulation).- The program config exists (
PROGRAM_UNAVAILABLE), its fee equals the relayer's fee rate and it lists this relayer (CONFIGURATION_REQUIRED). - Unless this exact request was already signed and has not expired: neither nullifier account exists (
NULLIFIER_SPENT, stagebuild). - The transaction is built, simulated, signed by the relayer and sent. The program checks the root, the proof and the nullifiers; its refusals answer
UNKNOWN_ROOT,PROOF_INVALIDorNULLIFIER_SPENT(never retryable) orINSUFFICIENT_BALANCE, and any other failureSIMULATION_FAILEDorCHAIN_REFUSED. - The transaction confirms. Still pending, it answers
RELAYER_FAILED: send the same request again.
"This exact request" is the same receipt with the same publicInputs and locator; the relayer journals each signed transaction under them, so a retry follows the transaction already signed instead of signing a second one.
On success the nullifiers are recorded as spent, both output commitments are appended to the tree with their memos, and the receipt is recorded as paid with its tags: Geode-Receipt and, when sent, Geode-Locator. POST /upload checks its locator against that tag. The price goes to the storage vault, the fee to the fee vault and the network refund to the relayer; see Instructions.
Errors
Codes are explained in full under Errors.
| Code | Raised when | Next |
|---|---|---|
PROGRAM_UNAVAILABLE | The relayer is not ready, or the program config account does not exist yet. Retryable. | Retry later with the same body. |
UNSUPPORTED_MEDIA_TYPE | The body is not sent as application/json. | Set the content type. |
VALIDATION_ERROR | The JSON is malformed or fails the schema (fieldErrors names the fields); or the receipt's bucket, term, price, fee, networkLamports or locator differ from the quote. | Fix the body; send the quote's values unchanged. |
QUOTE_EXPIRED | The quoteId is malformed, not signed by this relayer, or expired; or the network refund changed since the quote. Retryable. | Quote again, prove for the new total, pay. |
TRANSACTION_EXPIRED | An earlier signed payment for this receipt expired without landing. Retryable. | Quote again, prove for the new total, pay. |
PROOF_INVALID | publicAmount or bindingHash does not match this request ("The proof public amount or binding does not match this instruction."), or the program refused the proof. | Rebuild the proof from the quote and the receipt fields sent. |
CONFIGURATION_REQUIRED | The relayer's fee rate differs from the program config's, or the program config does not list this relayer. | Try again later. |
NULLIFIER_SPENT | A nullifier account already exists, or the program refused a nullifier. | Read GET /tree, drop spent notes, prove with unspent ones. |
UNKNOWN_ROOT | The program does not accept the proof's root. | Read GET /tree, prove against its root, pay. |
INSUFFICIENT_BALANCE | The pool vault cannot cover the transfer. | Retry later. |
SIMULATION_FAILED | The transaction failed simulation for another reason. | See message and programError. |
CHAIN_REFUSED | The chain refused the transaction for another reason. | See message and programError. |
RELAYER_FAILED | The signed payment is still pending. Retryable. | Send the same request again. |
Example
const quote = await client.quote({ bytes: ciphertext.length, term: 'permanent' })
const paid = await client.pay({
proof, // { a, b, c } from the prover
publicInputs, // root, nullifiers, outputCommitments, publicAmount, bindingHash
receipt: { ciphertextRoot, bucket: quote.bucket, term: quote.term },
quoteId: quote.quoteId,
priceLamports: quote.priceLamports,
feeLamports: quote.feeLamports,
networkLamports: quote.networkLamports,
memos, // the two encrypted output memos
})The same request on the wire, with placeholder values in the required shapes:
POST /pay
Content-Type: application/json
{
"proof": {
"a": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
"b": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
"c": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=="
},
"publicInputs": {
"root": "0x1111111111111111111111111111111111111111111111111111111111111111",
"nullifiers": [
"0x1212121212121212121212121212121212121212121212121212121212121212",
"0x1414141414141414141414141414141414141414141414141414141414141414"
],
"outputCommitments": [
"0x1313131313131313131313131313131313131313131313131313131313131313",
"0x1515151515151515151515151515151515151515151515151515151515151515"
],
"publicAmount": "0x<public amount>",
"bindingHash": "0x<payment binding>"
},
"receipt": {
"ciphertextRoot": "0x<sha-256 of the padded ciphertext>",
"bucket": 4194304,
"term": "permanent"
},
"quoteId": "<quoteId>",
"priceLamports": "<priceLamports>",
"feeLamports": "<feeLamports>",
"networkLamports": "<networkLamports>",
"locator": "0x<the quote's locator, for a manifest payment>",
"memos": ["<base64 change memo>", "<base64 zero-value memo>"]
}