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.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
Request
POST /upload with Content-Type: application/json.
receiptrequiredFieldPOST /pay.ciphertextrequiredBase6489478488 characters (64 MiB of bytes). Its decoded length must equal the receipt's bucket and its SHA-256 must equal the receipt's ciphertextRoot.locatorHash32GET /manifest can find it; omitted when the payment carried none. See The locator and The manifest.Response
idrequiredIrysIdreceiptrequiredFieldgatewayUrlrequiredstringconfig.gatewayUrl), / and id. See Gateway.storedAtrequiredTimestampBehaviour
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:
- The relayer is ready (
PROGRAM_UNAVAILABLE). - The body: content type, JSON, then the schema. The whole request also falls under the body limit.
receiptnames a paid receipt (RECEIPT_NOT_PAID).- The decoded ciphertext is exactly
bucketbytes and hashes tociphertextRoot(VALIDATION_ERROR, stageupload). locatorequals the locator the receipt was paid with, both absent included (IDEMPOTENCY_CONFLICT, stageupload, "The manifest metadata does not match the paid quote.").- A receipt already stored: its
idis 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.
| Code | Raised when | Next |
|---|---|---|
PROGRAM_UNAVAILABLE | The relayer is not ready. Retryable. | Retry later with the same body. |
UNSUPPORTED_MEDIA_TYPE | The body is not sent as application/json. | Set the content type. |
PAYLOAD_TOO_LARGE | The request body exceeds 90 MiB. | Ciphertext above the 64 MiB bucket cannot be stored. |
VALIDATION_ERROR | The 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_PAID | No paid receipt has this id ("The receipt has no indexed payment."). | Pay first with POST /pay, then upload with the receipt it returns. |
IDEMPOTENCY_CONFLICT | The 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_BALANCE | The relayer could not fund the Irys storage this upload needs. Not retryable. | Send the same request again later. |
STORAGE_PAYEE_KEY_REQUIRED | The relayer is not set up to fund the Irys storage this upload needs. Not retryable. | Send the same request again later. |
IRYS_UNAVAILABLE | The Irys upload failed. Retryable. | Send the same request again. |
Example
import { toBase64 } from '@geode/contract'
const stored = await client.upload({
receipt: paid.receipt,
ciphertext: toBase64(padded),
})
// stored.id is the Irys idPOST /upload
Content-Type: application/json
{
"receipt": "0x<receipt id from /pay>",
"ciphertext": "<base64 of the padded ciphertext>",
"locator": "0x<locator, for a manifest upload>"
}