Relayer API

POST /upload

How to hand the relayer a sealed ciphertext against a paid receipt and get back its Irys id.

POST /upload stores one ciphertext. The relayer checks it against a receipt paid with POST /pay and writes it to Irys tagged with that receipt, so the holder never holds an Irys balance or signs an upload. It is called right after pay, once for each file and once for each new version of the holder's manifest.

  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 /upload with Content-Type: application/json.

UploadRequest
receiptrequired
Field
The receipt id returned by POST /pay.
ciphertextrequired
Base64
The padded ciphertext, standard base64, at most 89478488 characters (64 MiB of bytes). Its decoded length must equal the receipt's bucket and its SHA-256 must equal the receipt's ciphertextRoot.
locator
Hash32
The holder's locator, the same one the receipt was quoted and paid with. Sent only when the ciphertext is a manifest, so GET /manifest can find it; omitted when the payment carried none. See The locator and The manifest.

Response

UploadResponse
idrequired
IrysId
The ciphertext's Irys id, 43 characters of base64url. A share link and the manifest name the file by it.
receiptrequired
Field
The receipt the ciphertext was stored against.
gatewayUrlrequired
string
The URL the ciphertext can be fetched from as raw bytes: the Irys gateway (config.gatewayUrl), / and id. See Gateway.
storedAtrequired
Timestamp
When the relayer recorded the ciphertext as stored.

Behaviour

An upload is idempotent per receipt, and uploads for one receipt are handled one at a time. Once a receipt has a stored ciphertext, the same receipt, ciphertext and locator return the same id and store nothing again; a retry after a lost response, or after IRYS_UNAVAILABLE, is safe with the same paid receipt.

The checks run in this order:

  1. The relayer is ready (PROGRAM_UNAVAILABLE).
  2. The body: content type, JSON, then the schema. The whole request also falls under the body limit.
  3. receipt names a paid receipt (RECEIPT_NOT_PAID).
  4. The decoded ciphertext is exactly bucket bytes and hashes to ciphertextRoot (VALIDATION_ERROR, stage upload).
  5. locator equals the locator the receipt was paid with, both absent included (IDEMPOTENCY_CONFLICT, stage upload, "The manifest metadata does not match the paid quote.").
  6. A receipt already stored: its id is returned.

The relayer then writes the ciphertext to Irys as the data item the quote priced (see What is priced), with the tags Geode-Receipt (the receipt id), Geode-Locator (the locator, when paid with one) and Geode-Term (the receipt's term). Before it writes, it looks Irys up for an item already tagged with this receipt and returns that item's id when its tags and bytes match. When Irys holds different tags or bytes for the receipt, the answer is IDEMPOTENCY_CONFLICT (stage upload, not retryable); when Irys fails, IRYS_UNAVAILABLE.

On success the receipt moves from paid to stored with its irysId and storedAt set; its tags stay the ones POST /pay recorded, Geode-Receipt and, for a manifest, Geode-Locator. A sent locator now resolves to this id in GET /manifest.

Errors

Codes are explained in full under Errors.

CodeRaised whenNext
PROGRAM_UNAVAILABLEThe relayer is not ready. Retryable.Retry later with the same body.
UNSUPPORTED_MEDIA_TYPEThe body is not sent as application/json.Set the content type.
PAYLOAD_TOO_LARGEThe request body exceeds 90 MiB.Ciphertext above the 64 MiB bucket cannot be stored.
VALIDATION_ERRORThe JSON is malformed or fails the schema (fieldErrors names the fields); or the ciphertext's length or hash differs from the receipt (stage upload, "The ciphertext length or root does not match the paid receipt.").Send the exact padded bytes the receipt was paid for.
RECEIPT_NOT_PAIDNo paid receipt has this id ("The receipt has no indexed payment.").Pay first with POST /pay, then upload with the receipt it returns.
IDEMPOTENCY_CONFLICTThe locator differs from the one the receipt was paid with ("The manifest metadata does not match the paid quote."), or Irys holds different bytes or tags for this receipt.Send the locator and bytes the receipt was paid for, or pay a new receipt.
INSUFFICIENT_BALANCEThe relayer could not fund the Irys storage this upload needs. Not retryable.Send the same request again later.
STORAGE_PAYEE_KEY_REQUIREDThe relayer is not set up to fund the Irys storage this upload needs. Not retryable.Send the same request again later.
IRYS_UNAVAILABLEThe Irys upload failed. Retryable.Send the same request again.

Example

TypeScript
import { toBase64 } from '@geode/contract'

const stored = await client.upload({
  receipt: paid.receipt,
  ciphertext: toBase64(padded),
})
// stored.id is the Irys id