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
| Step | Endpoint | What the relayer does |
|---|---|---|
| Price | GET /quote | Returns the Irys price for a bucket and term, Geode's fee, the network refund and their total. |
| Pay | POST /pay | Builds the pay transaction around the holder's proof, signs it as sole signer and fee payer, and sends it. |
| Store | POST /upload | Uploads the ciphertext of a paid receipt to Irys with the tag Geode-Receipt, and Geode-Locator for a manifest. |
| Unshield | POST /unshield | Submits unshield the same way as pay. |
| Shield | POST /shield/build | Builds the shield transaction for the holder's wallet to sign. |
| Read | GET /tree, GET /manifest, GET /see/:ref | Serves 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.
payandunshieldfrom any other signer fail withUnauthorizedRelayer. - The proof names the relayer. The relayer's address is inside the
payandunshieldbinding 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; onunshield, 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_ROOTandNULLIFIER_SPENT. - Paid, upload failed. The payment stands.
POST /uploadwith the same receipt and bytes stores it; nothing is paid twice. - Retried after success.
POST /paywith a receipt already paid returns that payment, andPOST /uploadwith 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.