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.
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.
- Seal
- Quote
- Prove
- Pay
- Store
- Open
What it does
Check the file
A
Fileobject this client already stored returns its earlier result at once, with no request and no event. A file larger thanmaxFileBytes(name, type), the largest the 64 MiB bucket holds with this name and media type, raisesPAYLOAD_TOO_LARGE, as does a name and media type over 16 KiB of JSON.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 asrecover. A retry of a file with atermother than its first call's raisesIDEMPOTENCY_CONFLICThere.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
Blobis sealed with the namefile. The client then computes the receipt, which binds this ciphertext's root, its bucket and the term. See Sealing.Quote
GET /quotewith 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: itsfeeBpsequals thefeeBpsin/config, its bucket and term match the request,totalLamportsequalspriceLamports + feeLamports + networkLamports, andfeeLamportsequalspriceLamports * feeBps / 10000rounded down. A quote that fails any check raisesQUOTE_FAILED.Prove
The client reads
/treeagain, takes the holder's two largest unspent notes, and spends the first one, or both, that covertotalLamports. 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/configand the memos. See Binding hashes and Spending: two in, two out.Pay
POST /paywith 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 thepaytransaction and returns the receipt, which must equal the one the client computed.Store
POST /uploadwith 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, andstoredAt. The file entry (the result plus name, media type, size andstoredAt) joins the vault's entries.Store the manifest
The client reads the latest manifest again (
GET /manifest,GET /treeand 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 asgeode-manifest.jsonof media typeapplication/vnd.geode.manifest+json, and goes through quote, prove, pay and store again with the termpermanent. Its quote, payment and upload carry the vault's locator, so the price covers theGeode-Locatortag andGET /manifestfinds this copy next (see The locator). Its progress events havekind: 'manifest'. See The manifest.
Arguments
filerequiredGeodeFile | readonly GeodeFile[]File or Blob, or an array of them. The bytes never leave the device unencrypted.options.term'30d' | '1y' | 'permanent'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) => voidReturn value
store(file) resolves to one StoreResult; store(files) resolves to an array in the same order.
idstringkeystringreceiptstring0x and 64 hex digits.bucketBuckettermTermlinkstring/s/<id>#<key>.Progress events
Each event is a ProgressEvent: { stage, progress, name, index, kind }.
| Stage | Emitted with progress | When |
|---|---|---|
sealing | 0, then (chunk + 1) / chunks after each chunk | Encryption |
quoting | 0, 1 | Around GET /quote and its checks |
proving | 0, 1 | Around note selection and the Groth16 proof |
paying | 0, 1 | Around POST /pay |
storing | 0, 1 | Around POST /upload |
stored | 0, 1 | The ciphertext is on Irys |
| Field | Value |
|---|---|
kind | 'file' for the file, 'manifest' for the manifest stored after it |
name | The file's name (file for an unnamed Blob), on both the file's and its manifest's events |
index | The 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.
| Payment | Priced on | Paid by |
|---|---|---|
| The file | Its bucket and the chosen term, plus Geode's fee and the network refund | Shielded balance, one proof |
| The manifest | The manifest's bucket and permanent, plus Geode's fee and the network refund | Shielded balance, one proof |
pay transaction fee and nullifier rent | The 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 at | The retry |
|---|---|
| Before sealing finished | Seals again |
| Quote or proof | Quotes and proves again with the same sealed bytes and receipt |
pay with QUOTE_EXPIRED, UNKNOWN_ROOT or NULLIFIER_SPENT | Drops the cached payment, then quotes and proves again with the same sealed bytes and receipt |
pay, any other failure | Sends the same payment again |
upload | Uploads the same ciphertext under the paid receipt, with no new payment |
| The manifest | Skips 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.
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.
| Code | Raised when |
|---|---|
PAYLOAD_TOO_LARGE | The 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_CONFLICT | The same file is retried with a different term |
WALLET_REJECTED | The client has no wallet, or the wallet declines the key message or returns a signature that is not 64 bytes |
VALIDATION_ERROR | The 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_FAILED | The quote's fee, bucket, term or total does not match (see the Quote step in What it does) |
INSUFFICIENT_BALANCE | The two largest notes do not cover the quoted total |
UNKNOWN_ROOT | The tree leaves the relayer returned do not hash to its root |
PROOF_FAILED | No 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_KEY | The vault's manifest cannot be fetched or decrypted when it is read |
UPSTREAM_UNAVAILABLE | A network failure or any other unrecognised error |
Samples
const { id, key, link } = await geode.store(file)const result = await geode.store(file, {
term: 'permanent',
onProgress({ stage, progress, kind }) {
console.log(kind, stage, Math.round(progress * 100) + '%')
},
})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)