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.

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

const geode = createGeode({ wallet, relayerUrl: 'https://api.geode.directory' })
const { id, key, link } = await geode.store(file)

Install

Shell
npm i @geode/sdk
PropertyValue
Package@geode/sdk
Version0.1.7
Module formatESM only ("type": "module"), with two entry points: @geode/sdk and @geode/sdk/chain
RuntimesNode.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

TypeScript
function createGeode(options: GeodeOptions): Geode

createGeode returns a Geode client. It makes no request and asks the wallet for nothing until a method needs it.

GeodeOptions
relayerUrlrequired
string
The address of the Geode relayer, https://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.
wallet
GeodeWallet
The holder's wallet. Every method needs it except open called with a key. A method that needs it while it is absent raises WALLET_REJECTED ("Connect a wallet to unlock this vault.").
gatewayUrl
string
Where ciphertext is fetched from, as <gatewayUrl>/<id>. When omitted, the gatewayUrl from the relayer's /config is used. The client reads /config either way.
artifactsUrl
string
Where the proving artifacts are fetched from, as <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:

TypeScript
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.

GeodeWallet
publicKeyrequired
string | Uint8Array | { toBase58(): string }
The wallet address. A string is read as base58, a Uint8Array as the 32 key bytes, an object through toBase58(). It must decode to 32 bytes.
signMessagerequired
(message: Uint8Array) => Promise<Uint8Array | { signature: Uint8Array }>
Signs the key message. The result is the 64-byte Ed25519 signature, bare or as { signature }. Any other length raises WALLET_REJECTED.
signTransaction
(transaction: Uint8Array) => Promise<Uint8Array>
Signs the serialized shield transaction and returns the signed bytes; the relayer submits them. Used when present.
signAndSendTransaction
(transaction: Uint8Array) => Promise<string | Uint8Array>
Signs and sends the 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 StandardGeodeWallet
account.address (or account.publicKey)publicKey
solana:signMessage, output signaturesignMessage
solana:signTransaction, output signedTransactionsignTransaction
solana:signAndSendTransaction, output signaturesignAndSendTransaction
TypeScript
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

RequestWhenPer
signMessage(SIGNING_MESSAGE)The first time a method needs the vault keys: every method except open with a keyClient. A declined request is asked again on the next call.
signTransaction or signAndSendTransactionEach shield callCall

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 /config response, 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 store and recover, with the files this client stored merged in.
  • The holder's unspent notes, rebuilt from /tree on every balance, recover and manifest read, and before every proof.
  • For each File object passed to store: its sealed bytes, receipt and paid state until it is stored, then its result.
  • For each unshield whose submission failed: its proved request, under its to and lamports, 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

MethodReturnsDoes
store(file, options?)StoreResult (or StoreResult[] for an array)Seals, pays for and stores files, then stores the updated manifest
open(id, key?)OpenResultFetches and decrypts a stored file
share(id)stringReturns the /s/<id>#<key> link of a vault file
list()FileEntry[]Lists the files in the vault's manifest
balance()BalanceSums the holder's unspent notes
shield(lamports)TransactionResultDeposits SOL from the wallet into the pool
unshield({ to, lamports })UnshieldResultWithdraws shielded SOL to an address
recover()RecoveryResultReloads the manifest and notes

Failures are GeodeError values with a stable code.