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:

TermValue in the API and SDKKept 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:

FieldMeaning
bucketThe bucket bytes lands in.
priceLamportsThe 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.
feeLamportsGeode's fee: priceLamports × feeBps / 10,000, rounded down, so the holder keeps the rounding.
networkLamportsThe 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.
totalLamportspriceLamports + feeLamports + networkLamports, the amount the proof spends.
feeBpsGeode's fee rate in basis points.
expiresAtWhen 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:

  1. The file, at its bucket and the term chosen.
  2. 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.