Protocol
Terms and quotes
The storage terms, which ones a relayer offers, how a store is priced, and what the shielded balance pays for one file.
Every upload is stored for a term. The term is part of the file's receipt, so it is paid for and fixed before the bytes are sent. The protocol defines three:
| Term | Value in the API and SDK | Kept for |
|---|---|---|
| 30 days | '30d' | 30 days from upload |
| 1 year | '1y' | One year from upload |
| Permanent | 'permanent' | Permanently, on Irys's permanent storage |
The list is exported as TERMS from @geode/contract, and the receipt carries the term as a code (0, 1, 2).
Which terms a relayer offers
A relayer offers the terms its storage network takes and lists them in GET /config as terms. A relayer that writes to the Irys network offers permanent. A quote for a term outside the list answers VALIDATION_ERROR naming the terms on offer. permanent is the default in GET /quote and in store.
How a store is priced
GET /quote?bytes=<ciphertext bytes>&term=<term> prices one upload:
| Field | Meaning |
|---|---|
bucket | The bucket bytes lands in. |
priceLamports | The Irys storage price for the exact data item: the bucket's bytes plus the signed header and tags Irys stores with them, at that term. |
feeLamports | Geode's fee: priceLamports × feeBps / 10,000, rounded down, so the holder keeps the rounding. |
networkLamports | The network refund: the rent-exempt minimum of the two nullifier accounts pay creates, plus the 5,000-lamport signature fee, repaid to the relayer. It follows the cluster's rent. |
totalLamports | priceLamports + feeLamports + networkLamports, the amount the proof spends. |
feeBps | Geode's fee rate in basis points. |
expiresAt | When the quote stops being accepted by POST /pay. |
The price follows the bucket, not the file's size: every file in a bucket at a term costs the same. Current prices for every bucket are on Pricing.
What one store costs
Storing a file pays for two uploads out of the shielded balance:
- The file, at its bucket and the term chosen.
- The manifest, at its own bucket and always
permanent. See The manifest.
Each of the two pays priceLamports + feeLamports + networkLamports. The relayer signs and pays pay up front and the network refund repays it in the same transaction. The holder's wallet pays nothing after shield.
Where the money goes
The storage price funds the upload on Irys. The network refund goes to the relayer that submitted the payment. Geode's fee goes to the fee vault, which buys $GEODE and burns it; Pricing tells it in full.