SDK

Types

Every type and value @geode/sdk exports, with each field's type and meaning, the @geode/sdk/chain entry point, and the Term and Bucket values from @geode/contract.

@geode/sdk exports two functions, createGeode and maxFileBytes, one class, GeodeError, two constants, SIGNING_MESSAGE and MAX_FILE_BYTES, and the types below. Term and Bucket are defined in @geode/contract. The proof helpers are a second entry point, @geode/sdk/chain.

TypeScript
import { createGeode, maxFileBytes, GeodeError, SIGNING_MESSAGE, MAX_FILE_BYTES } from '@geode/sdk'
import type {
  Geode, GeodeWallet, GeodeOptions, GeodeFile, StoreStage, ProgressEvent, StoreOptions, StoreResult,
  FileEntry, OpenResult, Balance, RecoveryResult, TransactionResult, UnshieldResult, GeodeErrorCode,
} from '@geode/sdk'
import type { Term, Bucket } from '@geode/contract'

createGeode

TypeScript
function createGeode(options: GeodeOptions): Geode

Creates a client. Its keys and state live in memory for the lifetime of the returned object. See Install and createGeode.

Geode

TypeScript
interface Geode {
  store(file: GeodeFile, options?: StoreOptions): Promise<StoreResult>
  store(files: readonly GeodeFile[], options?: StoreOptions): Promise<StoreResult[]>
  open(id: string, key?: string): Promise<OpenResult>
  share(id: string): Promise<string>
  list(): Promise<FileEntry[]>
  balance(): Promise<Balance>
  shield(lamports: string | bigint): Promise<TransactionResult>
  unshield(input: { to: string; lamports: string | bigint }): Promise<UnshieldResult>
  recover(): Promise<RecoveryResult>
}
MethodPage
storestore
openopen
shareshare
listlist
balancebalance
shieldshield
unshieldunshield
recoverrecover

GeodeWallet

GeodeWallet
publicKeyrequired
string | Uint8Array | { toBase58(): string }
The wallet address: base58, 32 raw bytes, or an object with toBase58().
signMessagerequired
(message: Uint8Array) => Promise<Uint8Array | { signature: Uint8Array }>
Signs the key message; returns the 64-byte signature, bare or as { signature }.
signTransaction
(transaction: Uint8Array) => Promise<Uint8Array>
Signs a serialized transaction and returns the signed bytes. Preferred by shield.
signAndSendTransaction
(transaction: Uint8Array) => Promise<string | Uint8Array>
Signs and sends a serialized transaction; returns its signature, base58 or 64 bytes.

How a Wallet Standard wallet maps onto it is on Install and createGeode.

GeodeOptions

GeodeOptions
relayerUrlrequired
string
Base URL of the relayer API.
wallet
GeodeWallet
The holder's wallet. Unneeded for open with a key.
gatewayUrl
string
Ciphertext gateway; defaults to gatewayUrl from /config.
artifactsUrl
string
Base URL of geode.wasm and geode_final.zkey; defaults to artifactsUrl from /config.

GeodeFile

TypeScript
type GeodeFile = Blob & { readonly name?: string }

A browser or Node.js File, or any Blob. A Blob without a name is stored with the name file. Its type is sealed as the media type.

StoreStage

TypeScript
type StoreStage = 'sealing' | 'quoting' | 'proving' | 'paying' | 'storing' | 'stored'
ValueStage
sealingEncrypting and padding on the device
quotingGetting and checking the price
provingSelecting notes and making the Groth16 proof
payingThe relayer submitting pay
storingThe relayer writing the ciphertext to Irys
storedDone

ProgressEvent

ProgressEvent
stage
StoreStage
The stage the event reports.
progress
number
From 0 to 1. 0 at a stage's start, 1 at its end; sealing also reports each chunk.
name
string
The file's name, on the file's events and on its manifest's.
index
number
The file's position in the array passed to store; 0 for one file.
kind
'file' | 'manifest'
Whether the event is for the file or for the manifest stored after it.

StoreOptions

StoreOptions
term
Term
How long Irys keeps the file. 'permanent' when omitted. One of the relayer's /config.terms.
onProgress
(event: ProgressEvent) => void
Receives every progress event.

StoreResult

StoreResult
id
string
The Irys id of the ciphertext, 43 base64url characters.
key
string
The 32-byte file key, 43 base64url characters. It stays on the holder's device.
receipt
string
The receipt the payment is bound to, 0x and 64 lowercase hex digits.
bucket
Bucket
The ciphertext size in bytes.
term
Term
The term paid for.
link
string
The relative share link /s/<id>#<key>.

FileEntry

StoreResult and four fields kept only in the encrypted manifest.

FileEntry
...StoreResult
StoreResult
id, key, receipt, bucket, term, link.
name
string
The file name.
type
string
The media type.
size
number
The plaintext size in bytes.
storedAt
string
ISO 8601 UTC time the relayer stored the file, from POST /upload.

OpenResult

OpenResult
bytes
Uint8Array<ArrayBuffer>
The plaintext. new Blob([bytes], { type }) makes a file of it.
name
string
The sealed name.
type
string
The sealed media type.

Balance

Balance
lamports
string
Unspent notes summed, decimal lamports.
notes
number
The number of unspent notes.

RecoveryResult

RecoveryResult
found
boolean
Whether a manifest exists under the vault's locator.
files
number
File entries in the manifest.
notes
number
Unspent notes rebuilt.
lamports
string
Their sum, decimal lamports.

TransactionResult

The result of shield.

TransactionResult
signature
string
The base58 transaction signature.
slot
number
The slot of confirmation.

UnshieldResult

The result of unshield: TransactionResult and the withdrawal's debit.

UnshieldResult
...TransactionResult
TransactionResult
signature, slot.
networkLamports
string
The network refund paid to the relayer, decimal lamports: the rent of the two nullifier accounts and the 5,000-lamport signature fee.
totalLamports
string
The whole shielded debit, the amount plus networkLamports, decimal lamports.

GeodeError

TypeScript
class GeodeError extends Error {
  readonly code: GeodeErrorCode
  constructor(code: GeodeErrorCode, message: string, options?: ErrorOptions)
}

name is 'GeodeError'; cause holds the original failure. See Errors.

GeodeErrorCode

TypeScript
type GeodeErrorCode = ErrorCode | 'WALLET_REJECTED' | 'WRONG_KEY' | 'PROOF_FAILED'

ErrorCode is every relayer API code, listed at /docs/api#errors. The three device codes are on Errors.

SIGNING_MESSAGE

The message the wallet signs once per client to derive the vault keys, two lines joined by \n:

Text
Geode key derivation v1
Sign to unlock your encrypted vault. This does not send a transaction.

The relayer's /config returns the same string as signingMessage. See Keys.

MAX_FILE_BYTES

TypeScript
const MAX_FILE_BYTES: number
function maxFileBytes(name: string, type: string): number

MAX_FILE_BYTES is the largest file, in bytes, whose sealed form fits the 64 MiB bucket with an empty name and media type: 67092415. maxFileBytes(name, type) is the exact limit for one name and media type, smaller by the extra length of their UTF-8 JSON; a name and media type over 16 KiB of JSON raise PAYLOAD_TOO_LARGE. store checks each file against maxFileBytes and refuses a larger one with PAYLOAD_TOO_LARGE. Sealing shows how each bucket's capacity is reached.

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

declare const file: File
const fits = file.size <= maxFileBytes(file.name, file.type)

@geode/sdk/chain

TypeScript
import { receiptHash, merkleRoot, buildWitness, prove } from '@geode/sdk/chain'

The second entry point carries the pure helpers a client proves with: the encodings, hashes, tree and witness that the program and the circuit share, and the browser prover. createGeode uses them for every proof; an application needs them only to build or check proofs itself. See The proof that pays.

ModuleExports
EncodingFIELD_MODULUS, BASE_FIELD_MODULUS, U64_MAX, FieldValue, integer, field, u64, bytesToBigInt, bigIntToBytes, fieldBytes, fieldHex, fromHex, bytes32, limbs128, toBase64, fromBase64, publicAmountForDeposit, publicAmountForWithdrawal
HashingTREE_DEPTH, MAX_MEMO_BYTES, TERM_CODES, StorageTerm, Memos, AddressValue, Note, InputNote, ReceiptFields, addressBytes, ownerHash, commitmentHash, createNote, nullifierHash, nodeHash, memoHash, receiptHash, shieldBindingHash, payBindingHash, unshieldBindingHash
Merkle treeMerklePath, zeroNodes, merklePath, merkleRoot
WitnessPublicInputs, Witness, WitnessInput, buildWitness, publicSignals
ProverProof, ProofBytes, ProverArtifacts, ProveOptions, Proved, proofToSolana, proofBytes, signalsToPublicInputs, prove, verifyProof

Term

From @geode/contract: '30d' | '1y' | 'permanent'.

ValueKept for
30d30 days
1y1 year
permanentPermanently, the default

A relayer accepts the subset its storage network takes, listed in /config.terms. See Terms and quotes.

Bucket

From @geode/contract: the eleven ciphertext sizes in bytes, each a power of two from 64 KiB to 64 MiB. A sealed file takes the smallest bucket that holds its bytes, name, type and framing.

BucketBytes
64 KiB65536
128 KiB131072
256 KiB262144
512 KiB524288
1 MiB1048576
2 MiB2097152
4 MiB4194304
8 MiB8388608
16 MiB16777216
32 MiB33554432
64 MiB67108864