Protocol

The relayer

What the Geode relayer does for a holder, what it is bound to, and how a store recovers when a step fails.

The relayer is the Geode service that submits the holder's payment and stores the holder's file, so the wallet stays out of every payment. It prices uploads, submits pay and unshield as their only signer and fee payer, writes ciphertext to Irys, and serves the tree and the manifest lookup. It never holds a key of the holder's and never sees a file in the clear.

What it does

StepEndpointWhat the relayer does
PriceGET /quoteReturns the Irys price for a bucket and term, Geode's fee, the network refund and their total.
PayPOST /payBuilds the pay transaction around the holder's proof, signs it as sole signer and fee payer, and sends it.
StorePOST /uploadUploads the ciphertext of a paid receipt to Irys with the tag Geode-Receipt, and Geode-Locator for a manifest.
UnshieldPOST /unshieldSubmits unshield the same way as pay.
ShieldPOST /shield/buildBuilds the shield transaction for the holder's wallet to sign.
ReadGET /tree, GET /manifest, GET /see/:refServes the pool's leaves and nullifiers, a locator's latest manifest, and an upload's public record.

The relayer signs and pays for pay and unshield: the signature fee and the rent of their two nullifier accounts. Each spend repays exactly that from the pool, in the same transaction, as the network refund (networkLamports). GET /unshield/quote prices an unshield's network refund the way GET /quote prices a store's.

What it is bound to

  • Who may relay. The program's config lists up to eight relayer addresses. pay and unshield from any other signer fail with UnauthorizedRelayer.
  • The proof names the relayer. The relayer's address is inside the pay and unshield binding hashes. A proof made for one relayer verifies only when that relayer signs, so a proof cannot be taken and submitted by anyone else. See The proof that pays.
  • The money has fixed destinations. On pay, the price goes to the storage vault and the fee to the fee vault; on unshield, the amount goes to the recipient in the proof. The relayer receives only the network refund, an amount the program computes from the cluster's rent, and chooses none of these destinations.
  • Exact bytes. An upload is accepted only for a receipt already paid, with ciphertext exactly as long as the receipt's bucket and hashing to its ciphertext root.

When a step fails

The receipt is fixed by the sealed bytes, so every step can be retried against it.

  • Pay failed before landing. Nothing moved. The SDK takes a new quote and a new proof for the same receipt on QUOTE_EXPIRED, UNKNOWN_ROOT and NULLIFIER_SPENT.
  • Paid, upload failed. The payment stands. POST /upload with the same receipt and bytes stores it; nothing is paid twice.
  • Retried after success. POST /pay with a receipt already paid returns that payment, and POST /upload with a receipt already stored returns its Irys id. Both are idempotent.

In the SDK, retrying store with the same File does all of this. See store.