SDK
Install and createGeode
How to install @geode/sdk, every option createGeode takes, when the wallet is asked to sign, and the methods a client has.
@geode/sdk seals, pays for, stores and opens files from the holder's device. A client is one call to createGeode, and storing a file is one more.
import { createGeode } from '@geode/sdk'
const geode = createGeode({ wallet, relayerUrl: 'https://api.geode.directory' })
const { id, key, link } = await geode.store(file)Install
npm i @geode/sdk| Property | Value |
|---|---|
| Package | @geode/sdk |
| Version | 0.1.7 |
| Module format | ESM only ("type": "module"), with two entry points: @geode/sdk and @geode/sdk/chain |
| Runtimes | Node.js >=22 and browsers |
| Contract | @geode/contract 0.1.7, the schemas the relayer validates with |
| Cryptography | @noble/ciphers, @noble/hashes, poseidon-lite, snarkjs |
The package uses fetch, TextEncoder, TextDecoder, atob and btoa from the runtime. snarkjs reads Buffer in its browser build, so importing @geode/sdk sets globalThis.Buffer to the buffer package when the runtime has none.
createGeode
function createGeode(options: GeodeOptions): GeodecreateGeode returns a Geode client. It makes no request and asks the wallet for nothing until a method needs it.
relayerUrlrequiredstringhttps://api.geode.directory, the base URL of its API. Trailing slashes are removed. Every JSON request (/config, /quote, /pay, /upload, /unshield/quote, /unshield, /tree, /manifest, /shield/build, /shield/confirm) goes here.walletGeodeWalletopen called with a key. A method that needs it while it is absent raises WALLET_REJECTED ("Connect a wallet to unlock this vault.").gatewayUrlstring<gatewayUrl>/<id>. When omitted, the gatewayUrl from the relayer's /config is used. The client reads /config either way.artifactsUrlstring<artifactsUrl>/geode.wasm and <artifactsUrl>/geode_final.zkey. When omitted, the artifactsUrl from /config is used. A Node.js caller can pass an absolute path to the directory holding both files.A client that only opens shared files needs no wallet:
import { readFile } from 'node:fs/promises'
import { createGeode } from '@geode/sdk'
const reader = createGeode({ relayerUrl: 'https://api.geode.directory' })
// In Node.js, a File made from disk bytes is a valid input to store().
const bytes = await readFile('./report.pdf')
const report = new File([bytes], 'report.pdf', { type: 'application/pdf' })The wallet
GeodeWallet is a Wallet Standard adapter reduced to raw bytes: messages and transactions go in as Uint8Array.
publicKeyrequiredstring | Uint8Array | { toBase58(): string }Uint8Array as the 32 key bytes, an object through toBase58(). It must decode to 32 bytes.signMessagerequired(message: Uint8Array) => Promise<Uint8Array | { signature: Uint8Array }>{ signature }. Any other length raises WALLET_REJECTED.signTransaction(transaction: Uint8Array) => Promise<Uint8Array>shield transaction and returns the signed bytes; the relayer submits them. Used when present.signAndSendTransaction(transaction: Uint8Array) => Promise<string | Uint8Array>shield transaction and returns its signature, as base58 or as 64 bytes. Used when signTransaction is absent.shield needs one of the two transaction methods; a wallet with neither raises WALLET_REJECTED.
Mapping a Wallet Standard wallet
| Wallet Standard | GeodeWallet |
|---|---|
account.address (or account.publicKey) | publicKey |
solana:signMessage, output signature | signMessage |
solana:signTransaction, output signedTransaction | signTransaction |
solana:signAndSendTransaction, output signature | signAndSendTransaction |
import type { GeodeWallet } from '@geode/sdk'
// The connected account and the wallet's features, as Wallet Standard defines them.
type SolanaAccount = { address: string; publicKey: Uint8Array }
declare const account: SolanaAccount
declare const features: {
'solana:signMessage': {
signMessage(...inputs: { account: SolanaAccount; message: Uint8Array }[]): Promise<readonly { signedMessage: Uint8Array; signature: Uint8Array }[]>
}
'solana:signTransaction': {
signTransaction(...inputs: { account: SolanaAccount; transaction: Uint8Array }[]): Promise<readonly { signedTransaction: Uint8Array }[]>
}
}
const wallet: GeodeWallet = {
publicKey: account.address,
async signMessage(message) {
const [output] = await features['solana:signMessage'].signMessage({ account, message })
return output.signature
},
async signTransaction(transaction) {
const [output] = await features['solana:signTransaction'].signTransaction({ account, transaction })
return output.signedTransaction
},
}When the wallet is asked to sign
| Request | When | Per |
|---|---|---|
signMessage(SIGNING_MESSAGE) | The first time a method needs the vault keys: every method except open with a key | Client. A declined request is asked again on the next call. |
signTransaction or signAndSendTransaction | Each shield call | Call |
The wallet signs nothing else. store and unshield pay with a proof the relayer submits, so no payment after shield reaches the wallet.
The key message is SIGNING_MESSAGE. Its signature is the seed of the vault: HKDF-SHA256 derives the spending key, the view key, and the locator (the SHA-256 of the view key) under which the manifest is found. The same wallet yields the same vault on any device. See Keys.
What the client keeps in memory
Everything a client holds lives in the object createGeode returned and nothing is written to storage:
- The spending key, view key and locator, once the key message is signed.
- The relayer's
/configresponse, fetched once and fetched again only after a failed read. - The vault's file entries, read from the manifest on first use and read again by each
storeandrecover, with the files this client stored merged in. - The holder's unspent notes, rebuilt from
/treeon everybalance,recoverand manifest read, and before every proof. - For each
Fileobject passed tostore: its sealed bytes, receipt and paid state until it is stored, then its result. - For each
unshieldwhose submission failed: its proved request, under itstoandlamports, until a retry settles it.
A new client created with createGeode starts from the wallet alone and reads the rest back from the relayer and Irys.
Calls run one at a time
store, shield, unshield and recover change the vault or the balance. A client runs them one at a time, in the order they were called: each starts when the previous one has settled, whether it resolved or rejected. open, share, list and balance read and run at once.
A store that fails keeps its file's sealed bytes and receipt on the client. Other calls go on as usual, and a later store of the same File resumes it. See retrying a store.
Methods
| Method | Returns | Does |
|---|---|---|
store(file, options?) | StoreResult (or StoreResult[] for an array) | Seals, pays for and stores files, then stores the updated manifest |
open(id, key?) | OpenResult | Fetches and decrypts a stored file |
share(id) | string | Returns the /s/<id>#<key> link of a vault file |
list() | FileEntry[] | Lists the files in the vault's manifest |
balance() | Balance | Sums the holder's unspent notes |
shield(lamports) | TransactionResult | Deposits SOL from the wallet into the pool |
unshield({ to, lamports }) | UnshieldResult | Withdraws shielded SOL to an address |
recover() | RecoveryResult | Reloads the manifest and notes |
Failures are GeodeError values with a stable code.