SDK

store

What geode.store does to a file step by step, what it returns and reports, what it costs, how a retry resumes, and the errors it raises.

TypeScript
store(file: GeodeFile, options?: StoreOptions): Promise<StoreResult>
store(files: readonly GeodeFile[], options?: StoreOptions): Promise<StoreResult[]>

store seals a file on the device, pays for it from the shielded balance with a proof, has the relayer write the ciphertext to Irys, and then stores the vault's encrypted manifest with the new entry. An array is stored one file at a time, in order, with the manifest stored after each file.

  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.

What it does

  1. Check the file

    A File object this client already stored returns its earlier result at once, with no request and no event. A file larger than maxFileBytes(name, type), the largest the 64 MiB bucket holds with this name and media type, raises PAYLOAD_TOO_LARGE, as does a name and media type over 16 KiB of JSON.

  2. Unlock the vault

    On the client's first vault call, the wallet signs the key message, and the client reads the manifest at the vault's locator (GET /manifest) and the note tree (GET /tree), decrypts the manifest with the view key and rebuilds the holder's notes. This is the same work as recover. A retry of a file with a term other than its first call's raises IDEMPOTENCY_CONFLICT here.

  3. Seal

    The file's bytes, name and media type are encrypted with XChaCha20-Poly1305 under a fresh random 32-byte file key, in 65,536-byte chunks, and padded to the smallest bucket that holds them. An unnamed Blob is sealed with the name file. The client then computes the receipt, which binds this ciphertext's root, its bucket and the term. See Sealing.

  4. Quote

    GET /quote with the bucket size and the term. The relayer prices the Irys data item that will carry the ciphertext: the bucket plus its signed header and tags. The client checks the quote before spending: its feeBps equals the feeBps in /config, its bucket and term match the request, totalLamports equals priceLamports + feeLamports + networkLamports, and feeLamports equals priceLamports * feeBps / 10000 rounded down. A quote that fails any check raises QUOTE_FAILED.

  5. Prove

    The client reads /tree again, takes the holder's two largest unspent notes, and spends the first one, or both, that cover totalLamports. Any excess goes to a new change note owned by the holder, with its memo encrypted under the view key. A Groth16 proof binds the spend to the receipt fields, the price, Geode's fee, the network refund (networkLamports), the relayer address in /config and the memos. See Binding hashes and Spending: two in, two out.

  6. Pay

    POST /pay with the proof, its public inputs, the receipt fields, the quote id, the price, Geode's fee, the network refund and the two output memos. The relayer submits the pay transaction and returns the receipt, which must equal the one the client computed.

  7. Store

    POST /upload with the receipt and the ciphertext as base64. The relayer writes it to Irys and returns the Irys id, the receipt, which must again equal the client's, and storedAt. The file entry (the result plus name, media type, size and storedAt) joins the vault's entries.

  8. Store the manifest

    The client reads the latest manifest again (GET /manifest, GET /tree and the gateway) and merges the files it stored into it. When the merged list equals the stored manifest, nothing more is paid. Otherwise the manifest, { version: 1, files } with every entry, is sealed under the view key as geode-manifest.json of media type application/vnd.geode.manifest+json, and goes through quote, prove, pay and store again with the term permanent. Its quote, payment and upload carry the vault's locator, so the price covers the Geode-Locator tag and GET /manifest finds this copy next (see The locator). Its progress events have kind: 'manifest'. See The manifest.

Arguments

store(file, options)
filerequired
GeodeFile | readonly GeodeFile[]
A File or Blob, or an array of them. The bytes never leave the device unencrypted.
options.term
'30d' | '1y' | 'permanent'
How long Irys keeps the file. permanent when omitted. It must be one of the relayer's /config.terms: permanent on the Irys network. The relayer answers any other term at the quote, after the file is sealed, with VALIDATION_ERROR naming the supported terms; that File object keeps its term, so store it again as a new File object with a supported term. The manifest is always stored permanent. See Terms the relayer accepts and Terms and quotes.
options.onProgress
(event: ProgressEvent) => void
Called at the start and end of every stage and after every sealed chunk, for the file and for its manifest.

Return value

store(file) resolves to one StoreResult; store(files) resolves to an array in the same order.

StoreResult
id
string
The Irys id of the ciphertext, 43 base64url characters.
key
string
The 32-byte file key, base64url (43 characters). It stays on the holder's device; the vault keeps it in the encrypted manifest.
receipt
string
The receipt the payment is bound to, a BN254 field element as 0x and 64 hex digits.
bucket
Bucket
The ciphertext size in bytes, one of the eleven buckets.
term
Term
The term the file was paid for.
link
string
The relative share link /s/<id>#<key>.

Progress events

Each event is a ProgressEvent: { stage, progress, name, index, kind }.

StageEmitted with progressWhen
sealing0, then (chunk + 1) / chunks after each chunkEncryption
quoting0, 1Around GET /quote and its checks
proving0, 1Around note selection and the Groth16 proof
paying0, 1Around POST /pay
storing0, 1Around POST /upload
stored0, 1The ciphertext is on Irys
FieldValue
kind'file' for the file, 'manifest' for the manifest stored after it
nameThe file's name (file for an unnamed Blob), on both the file's and its manifest's events
indexThe file's position in the array, 0 for a single file

A retry emits only the stages it runs again.

What it costs

The holder's shielded balance pays two quoted totals per file. Each total is the Irys price of the signed data item (the bucket plus its header and tags), plus Geode's fee (priceLamports * feeBps / 10000 rounded down), plus the network refund (networkLamports), which repays the relayer the rent of the two nullifier accounts and the 5,000-lamport signature fee. The relayer reads the refund from the cluster's rent, and every quote states it.

PaymentPriced onPaid by
The fileIts bucket and the chosen term, plus Geode's fee and the network refundShielded balance, one proof
The manifestThe manifest's bucket and permanent, plus Geode's fee and the network refundShielded balance, one proof
pay transaction fee and nullifier rentThe relayer, repaid by the network refund

The wallet pays nothing and signs nothing. Each proof spends at most two notes, so each of the two payments must be covered by the holder's two largest notes at that moment; the change from the file's payment is one of the notes available to the manifest's. A balance that does not cover a payment this way raises INSUFFICIENT_BALANCE. See Notes and the pool.

Retry

The client keeps each File object's sealed bytes and progress until it is stored. Calling store again with the same object resumes where it stopped:

Stopped atThe retry
Before sealing finishedSeals again
Quote or proofQuotes and proves again with the same sealed bytes and receipt
pay with QUOTE_EXPIRED, UNKNOWN_ROOT or NULLIFIER_SPENTDrops the cached payment, then quotes and proves again with the same sealed bytes and receipt
pay, any other failureSends the same payment again
uploadUploads the same ciphertext under the paid receipt, with no new payment
The manifestSkips the file, reads the manifest again and resumes the manifest's payment the same way; when the merged entries changed since the failed attempt, it seals a new manifest

A retry of the same file with a different term raises IDEMPOTENCY_CONFLICT. An unfinished file never blocks a store of another file, unshield or recover. An array stops at the first file that fails; a retry of the same array returns the files already stored from memory and resumes the failed file.

TypeScript
import { GeodeError } from '@geode/sdk'

try {
  await geode.store(file)
} catch (error) {
  // The receipt is paid; the same File object uploads it again with no new payment.
  if (error instanceof GeodeError && error.code === 'IRYS_UNAVAILABLE') await geode.store(file)
  else throw error
}

Errors

Every failure is a GeodeError. Codes the relayer returns from /quote, /pay and /upload pass through unchanged and are listed at /docs/api#errors.

CodeRaised when
PAYLOAD_TOO_LARGEThe file is larger than maxFileBytes(name, type), or the name and media type exceed 16 KiB; on unlock, the manifest ciphertext is larger than 64 MiB
IDEMPOTENCY_CONFLICTThe same file is retried with a different term
WALLET_REJECTEDThe client has no wallet, or the wallet declines the key message or returns a signature that is not 64 bytes
VALIDATION_ERRORThe stored manifest has an unsupported format or an invalid entry, or a note memo that decrypts does not match its leaf
CONFIGURATION_REQUIRED/config has no relayer address, or no gateway URL is set when the manifest is read
QUOTE_FAILEDThe quote's fee, bucket, term or total does not match (see the Quote step in What it does)
INSUFFICIENT_BALANCEThe two largest notes do not cover the quoted total
UNKNOWN_ROOTThe tree leaves the relayer returned do not hash to its root
PROOF_FAILEDNo artifacts URL is configured, the artifacts cannot be downloaded, or the prover fails or yields other public signals
RELAYER_FAILED/pay or /upload returns a receipt other than the client's, or a relayer reply does not match the contract
NOT_FOUND, IRYS_UNAVAILABLE, WRONG_KEYThe vault's manifest cannot be fetched or decrypted when it is read
UPSTREAM_UNAVAILABLEA network failure or any other unrecognised error

Samples

TypeScript
const { id, key, link } = await geode.store(file)
TypeScript
const result = await geode.store(file, {
  term: 'permanent',
  onProgress({ stage, progress, kind }) {
    console.log(kind, stage, Math.round(progress * 100) + '%')
  },
})
TypeScript
const results = await geode.store(files, {
  onProgress: event => console.log(event.index, event.name, event.kind, event.stage),
})
const links = results.map(result => result.link)