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.

  1. Seal
  2. Quote
  3. Prove
  4. Pay
  5. Store
  6. Open
Every file, from your device to Irys. Dashed: what the chain sees. Solid: what stays with you.

Request

POST /pay with Content-Type: application/json.

PayRequest
proofrequired
Proof
The Groth16 proof: a (64 bytes), b (128 bytes) and c (64 bytes), each base64 in groth16-solana order. See How values travel.
publicInputsrequired
PublicInputs
The proof's public inputs, below.
receiptrequired
ReceiptFields
What is being paid for, below.
quoteIdrequired
string
The quoteId from GET /quote, 1 to 512 characters.
priceLamportsrequired
U64
The quote's priceLamports, unchanged.
feeLamportsrequired
U64
The quote's feeLamports, unchanged.
networkLamportsrequired
U64
The quote's networkLamports, unchanged: the network refund pay moves from the pool vault to the relayer.
locator
Hash32
The quote's locator, unchanged: sent when the quote was requested with one (a manifest), omitted when it was not. See The locator.
memosrequired
[Memo, Memo]
One encrypted note memo per output commitment, in the same order. Each is base64 of at most 108 characters, decoding to at most 80 bytes.
publicInputs
rootrequired
Field
The tree root the proof was built against, from GET /tree.
nullifiersrequired
[Field, Field]
The nullifiers of the two input notes, one of which may be a zero-amount dummy.
outputCommitmentsrequired
[Field, Field]
The two new notes: the change and a zero-valued second output.
publicAmountrequired
Field
The proof's public amount for priceLamports plus feeLamports plus networkLamports, the quote's totalLamports. See Spending: two in, two out.
bindingHashrequired
Field
The payment binding for receipt, priceLamports, feeLamports, networkLamports, the relayer and memos.
receipt
ciphertextRootrequired
Hash32
SHA-256 of the padded ciphertext, exactly as it will be uploaded.
bucketrequired
Bucket
The quote's bucket. The padded ciphertext is exactly this many bytes.
termrequired
Term
The quote's term.

The 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

PayResponse
receiptrequired
Field
The receipt id. Pass it to POST /upload and GET /receipt/:id.
signaturerequired
Signature
The pay transaction's signature.
slotrequired
integer
The slot it landed in.

The 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:

  1. The relayer is ready (PROGRAM_UNAVAILABLE).
  2. The body: content type, JSON, then the schema.
  3. A receipt already paid under the receipt id: its payment is returned.
  4. 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.
  5. Unless this exact request was already signed and has not expired: quoteId is a quote this relayer signed that has not passed expiresAt (QUOTE_EXPIRED); networkLamports equals the current network refund (QUOTE_EXPIRED, "The network refund changed. Request a fresh quote."); and receipt.bucket, receipt.term, priceLamports, feeLamports, networkLamports and locator (both absent included) equal the quote's (VALIDATION_ERROR, "The receipt does not match the signed quote.").
  6. publicInputs.publicAmount is the public amount for price plus fee plus networkLamports, and publicInputs.bindingHash is the payment binding for this request and relayer (PROOF_INVALID, stage simulation).
  7. The program config exists (PROGRAM_UNAVAILABLE), its fee equals the relayer's fee rate and it lists this relayer (CONFIGURATION_REQUIRED).
  8. Unless this exact request was already signed and has not expired: neither nullifier account exists (NULLIFIER_SPENT, stage build).
  9. 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_INVALID or NULLIFIER_SPENT (never retryable) or INSUFFICIENT_BALANCE, and any other failure SIMULATION_FAILED or CHAIN_REFUSED.
  10. 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.

CodeRaised whenNext
PROGRAM_UNAVAILABLEThe relayer is not ready, or the program config account does not exist yet. Retryable.Retry later with the same body.
UNSUPPORTED_MEDIA_TYPEThe body is not sent as application/json.Set the content type.
VALIDATION_ERRORThe 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_EXPIREDThe 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_EXPIREDAn earlier signed payment for this receipt expired without landing. Retryable.Quote again, prove for the new total, pay.
PROOF_INVALIDpublicAmount 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_REQUIREDThe relayer's fee rate differs from the program config's, or the program config does not list this relayer.Try again later.
NULLIFIER_SPENTA nullifier account already exists, or the program refused a nullifier.Read GET /tree, drop spent notes, prove with unspent ones.
UNKNOWN_ROOTThe program does not accept the proof's root.Read GET /tree, prove against its root, pay.
INSUFFICIENT_BALANCEThe pool vault cannot cover the transfer.Retry later.
SIMULATION_FAILEDThe transaction failed simulation for another reason.See message and programError.
CHAIN_REFUSEDThe chain refused the transaction for another reason.See message and programError.
RELAYER_FAILEDThe signed payment is still pending. Retryable.Send the same request again.

Example

TypeScript
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:

HTTP
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>"]
}