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.
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
function createGeode(options: GeodeOptions): GeodeCreates a client. Its keys and state live in memory for the lifetime of the returned object. See Install and createGeode.
Geode
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>
}| Method | Page |
|---|---|
store | store |
open | open |
share | share |
list | list |
balance | balance |
shield | shield |
unshield | unshield |
recover | recover |
GeodeWallet
publicKeyrequiredstring | Uint8Array | { toBase58(): string }toBase58().signMessagerequired(message: Uint8Array) => Promise<Uint8Array | { signature: Uint8Array }>{ signature }.signTransaction(transaction: Uint8Array) => Promise<Uint8Array>shield.signAndSendTransaction(transaction: Uint8Array) => Promise<string | Uint8Array>How a Wallet Standard wallet maps onto it is on Install and createGeode.
GeodeOptions
relayerUrlrequiredstringwalletGeodeWalletopen with a key.gatewayUrlstringgatewayUrl from /config.artifactsUrlstringgeode.wasm and geode_final.zkey; defaults to artifactsUrl from /config.GeodeFile
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
type StoreStage = 'sealing' | 'quoting' | 'proving' | 'paying' | 'storing' | 'stored'| Value | Stage |
|---|---|
sealing | Encrypting and padding on the device |
quoting | Getting and checking the price |
proving | Selecting notes and making the Groth16 proof |
paying | The relayer submitting pay |
storing | The relayer writing the ciphertext to Irys |
stored | Done |
ProgressEvent
stageStoreStageprogressnumber0 to 1. 0 at a stage's start, 1 at its end; sealing also reports each chunk.namestringindexnumberstore; 0 for one file.kind'file' | 'manifest'StoreOptions
onProgress(event: ProgressEvent) => voidStoreResult
idstringkeystringreceiptstring0x and 64 lowercase hex digits.bucketBuckettermTermlinkstring/s/<id>#<key>.FileEntry
StoreResult and four fields kept only in the encrypted manifest.
...StoreResultStoreResultid, key, receipt, bucket, term, link.namestringtypestringsizenumberstoredAtstringPOST /upload.OpenResult
bytesUint8Array<ArrayBuffer>new Blob([bytes], { type }) makes a file of it.namestringtypestringBalance
lamportsstringnotesnumberRecoveryResult
foundbooleanfilesnumbernotesnumberlamportsstringTransactionResult
The result of shield.
signaturestringslotnumberUnshieldResult
The result of unshield: TransactionResult and the withdrawal's debit.
...TransactionResultTransactionResultsignature, slot.networkLamportsstringtotalLamportsstringnetworkLamports, decimal lamports.GeodeError
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
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:
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
const MAX_FILE_BYTES: number
function maxFileBytes(name: string, type: string): numberMAX_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.
import { maxFileBytes } from '@geode/sdk'
declare const file: File
const fits = file.size <= maxFileBytes(file.name, file.type)@geode/sdk/chain
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.
| Module | Exports |
|---|---|
| Encoding | FIELD_MODULUS, BASE_FIELD_MODULUS, U64_MAX, FieldValue, integer, field, u64, bytesToBigInt, bigIntToBytes, fieldBytes, fieldHex, fromHex, bytes32, limbs128, toBase64, fromBase64, publicAmountForDeposit, publicAmountForWithdrawal |
| Hashing | TREE_DEPTH, MAX_MEMO_BYTES, TERM_CODES, StorageTerm, Memos, AddressValue, Note, InputNote, ReceiptFields, addressBytes, ownerHash, commitmentHash, createNote, nullifierHash, nodeHash, memoHash, receiptHash, shieldBindingHash, payBindingHash, unshieldBindingHash |
| Merkle tree | MerklePath, zeroNodes, merklePath, merkleRoot |
| Witness | PublicInputs, Witness, WitnessInput, buildWitness, publicSignals |
| Prover | Proof, ProofBytes, ProverArtifacts, ProveOptions, Proved, proofToSolana, proofBytes, signalsToPublicInputs, prove, verifyProof |
Term
From @geode/contract: '30d' | '1y' | 'permanent'.
| Value | Kept for |
|---|---|
30d | 30 days |
1y | 1 year |
permanent | Permanently, 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.
| Bucket | Bytes |
|---|---|
| 64 KiB | 65536 |
| 128 KiB | 131072 |
| 256 KiB | 262144 |
| 512 KiB | 524288 |
| 1 MiB | 1048576 |
| 2 MiB | 2097152 |
| 4 MiB | 4194304 |
| 8 MiB | 8388608 |
| 16 MiB | 16777216 |
| 32 MiB | 33554432 |
| 64 MiB | 67108864 |