Reference
SDK
Every export of @pook/sdk: the client and its methods, the standalone functions, the types they take and return, the errors they throw, and the lower-level helpers. Call a hook from your app is the guided version.
npm i @pook/sdk @pook/circuitsloadCircuits() from @pook/circuits returns the circuits for the runtime it is called in, the browser or Node. Pass what it resolves to as wasm.
The package is an ES module, typed, and runs in the browser and in Node. Amounts are in an asset's smallest unit, as a decimal string or a bigint. Addresses and mints are base58 strings. SOL is named by the wrapped SOL mint.
createPook
function createPook(config: PookConfig): PookMakes a client. One client holds one signer, that signer's keys while unlocked, and a cache of the last scan of notes.
| PookConfig | Type | Meaning |
|---|---|---|
apiUrl | string | The Pook API. |
wasm | PookWasmModule | The circuits, from loadCircuits() of @pook/circuits. Required by run, leave, openSeat and closeSeat. |
relayerUrl | string | A relayer to submit through, in place of the one the API uses. |
proverTee | ProverTee | How Rings spend proofs are requested. By default on mainnet, each request is encrypted to the attested Rings prover enclave. See Notes and the private balance. |
signer | WalletSigner | The wallet. Can be set later with setSigner. |
keys | HolderKeys | Keys from an earlier unlock, to start unlocked. |
proverUrl | string | A prover service to read circuit files from. Defaults to the API. |
photonUrl | string | A Rings indexer to scan notes from. Defaults to the API. |
rpcUrl | string | A Solana RPC. Defaults to the API’s pass-through. |
fetch | typeof fetch | A fetch to use in place of the global one. |
headers | Record<string, string> | Headers sent with every request. |
credentials | RequestCredentials | The credentials mode of every request. |
keyDerivation | KeyDerivationSeam | Replaces how keys are derived from the signer. |
noteScanner | NoteScannerSeam | Replaces how notes are fetched and decrypted. |
prover | ProverSeam | Replaces how a proof request is answered. |
configurePook
function configurePook(config: PookConfig): PookMakes a client and keeps it as the default for the standalone functions below.
The session
| Method | Type | Meaning |
|---|---|---|
pook.setSigner(signer) | void | Sets or clears the wallet. A different wallet locks the client. |
pook.unlock(signer?) | Promise<HolderKeys> | Asks the wallet to sign the message POOK/derive/v1 and derives the holder’s keys from the signature. |
pook.lock() | void | Drops the keys and the cached notes. |
pook.isUnlocked() | boolean | Whether keys are held. |
pook.client | PookApiClient | The typed API client the SDK calls through, one method for each route. |
run
pook.run(hookId: string, params: RunParams): Promise<RunResult>Runs a published hook against the private balance: quote, prove, relay, follow. On a seat hook with no seat, it opens a seat first.
| RunParams | Type | Meaning |
|---|---|---|
amount | string | bigint | The amount in. For a hook with no asset in, the amount asked of the protocol. |
in | string | Mint of the asset in. Alias: mintIn. |
out | string | Mint of the asset out. Alias: mintOut. |
slippageBps | number | Slippage in basis points. Default 50. |
minimumOut | string | bigint | The least accepted back, in the out asset’s smallest unit. Required for a hook with an asset out that is not one of the launch hooks. |
seat | string | The seat’s address, for a seat hook. |
args | Record<string, string> | Values for the hook’s own inputs, by name. |
onStage | (stage: RunStage, detail?) => void | Called at each stage. |
signal | AbortSignal | Cancels the call. |
RunStage is 'quoting' | 'opening_seat' | 'proving' | 'relayed' | 'confirmed'.
| RunResult | Type | Meaning |
|---|---|---|
quote | QuoteResponse | The quote the run was proved against. |
relay | RelaySubmissionResponse | The relayer’s record of the submission. |
signature | string | null | The run’s transaction. |
seat | string | null | The seat used or opened. |
openSeatSignature | string | null | The transaction that opened the seat, when this run opened one. |
Throws ApiClientError with INSUFFICIENT_BALANCE when no one or two notes cover the amount, NOT_FOUND when a seat hook is given a seat the holder has no note for, and whatever the quote or the relayer answers. A hook outside the launch set that has an asset out answers VALIDATION_ERROR naming minimumOut when it is left out, and its quote carries minimumOutFromCaller: true. A transaction that fails on chain does not throw: relay.status is failed or expired, and relay.error says why.
enter
pook.enter(params: EnterParams): Promise<EnterResult>Moves an asset from the signer's wallet into the private balance. The wallet signs one transaction.
| EnterParams | Type | Meaning |
|---|---|---|
mint | string | The asset. |
amount | string | bigint | How much. |
source | 'wallet' | 'rings' | Where it comes from. Default wallet. |
signer | WalletSigner | A signer for this call, in place of the client’s. |
onStage | (stage: EnterStage, detail?) => void | Called at each stage. |
signal | AbortSignal | Cancels the call. |
EnterStage is 'building' | 'proving' | 'signing' | 'submitted' | 'confirmed'. proving is reported when the source is a Rings private balance, which spends up to two Rings notes in one enter. EnterResult holds build (the TxBuildResponse), tx (the TxStatusResponse) and signature.
Throws ApiClientError with UNAUTHORIZED when no signer is set and WALLET_REJECTED when the wallet declines.
leave
pook.leave(params: LeaveParams): Promise<LeaveResult>Moves an asset out of the private balance to a public address or a Rings private balance. A relayer submits it.
| LeaveParams | Type | Meaning |
|---|---|---|
mint | string | The asset. |
amount | string | bigint | How much leaves the balance. The relayer’s fee comes off it. |
destination | string | A Solana address. For a Rings destination, the wallet address the recipient registered with Rings: the SDK looks up their Rings address from it. |
destinationType | 'wallet' | 'rings' | Default wallet. |
destinationViewTag | string | For a caller that already holds the recipient’s Rings owner hash: pass the hash in hex as destination and the 32-byte view tag here, base58. |
onStage | (stage: LeaveStage, detail?) => void | Called at each stage. |
signal | AbortSignal | Cancels the call. |
LeaveStage is 'quoting' | 'proving' | 'relayed' | 'confirmed'. LeaveResult holds relay and signature.
Throws ApiClientError with NOT_FOUND when a Rings destination is a wallet address with no record in the Rings user registry.
openSeat and closeSeat
pook.openSeat(options?: OpenSeatOptions): Promise<SeatActionResult>
pook.closeSeat(seatAddress: string, options?: { openerRelayer?: string; signal?: AbortSignal }): Promise<SeatActionResult>openSeat opens a seat and creates its seat note. run calls it for you on a first seat run. OpenSeatOptions takes protocol ('kamino', the default, which also creates the seat's Kamino accounts, or 'none'), lendingMarket (a Kamino market, default the main market), seatIndex and signal.
closeSeat closes a seat that holds and owes nothing and returns its rent to the relayer that opened it. It throws NOT_FOUND when the holder has no note for that seat, and SEAT_NOT_EMPTY while the seat still holds collateral or owes debt.
SeatActionResult holds relay, seatAddress, seatCommitmentHex and signature.
balance, seats and activity
pook.balance(options?): Promise<BalanceResult>
pook.seats(options?): Promise<SeatPosition[]>
pook.activity(options?): Promise<ActivityItem[]>All three scan the holder's notes on the device first. options takes signer and signal.
| Returns | Type | Meaning |
|---|---|---|
BalanceResult | object | assets: one AssetBalance for each asset held (mint, symbol, decimals, amount, noteCount). notes: every DecryptedNote. asOf: when it was read. |
SeatPosition | object | seatAddress, protocol, protocolName, obligationAddress, status (open, empty or closed), collateral and debt (each mint, symbol, decimals, amount, usdValue), healthFactor, actions, openerRelayer, updatedAt. |
ActivityItem | object | id, kind (enter, run or leave), hookId, mint, symbol, decimals, amount, signature, slot, timestamp. Newest first. |
pook.publicBalance(mint?: string, options?): Promise<PublicBalanceResponse>Reads the public balance of the connected wallet, or of options.wallet, for one mint. Default SOL.
defineHook, simulateHook and publishHook
defineHook(input: DefineHookInput): HookDefinition
pook.simulateHook(params: SimulateHookParams): Promise<SimulateHookResponse>
pook.publishHook(params: PublishHookParams): Promise<EnterResult>defineHook checks a hook definition against the hook schema and returns it frozen. It throws a ZodError naming each field that is wrong. It talks to nothing.
simulateHook runs the hook's instruction against chain state with the stage in place. SimulateHookParams takes hook, sampleAmountIn, and optionally sampleMintIn, sampleMintOut and sampleArgs. The response holds passed, computeUnits, logs, estimatedTxBytes, accountCount and error when it failed.
publishHook builds the publish_hook transaction, has the wallet sign it and submits it. PublishHookParams takes hook, and optionally signer, onStage and signal. The signer becomes the hook's author. It answers HOOK_ALREADY_EXISTS when the name is taken.
claimAuthorFees
pook.claimAuthorFees(params: ClaimAuthorFeesParams): Promise<EnterResult>
pook.authorFees(wallet: string): Promise<AuthorFeesResponse>authorFees lists what an author's hooks have earned and what is claimable, for each hook and asset. claimAuthorFees takes hookIds, optionally mint to claim one asset, signer, onStage and signal. The wallet signs one transaction, and the claimable amount is paid to it.
Reading the registry
No wallet is needed for these. Each returns the API's response as typed.
| Method | Type | Meaning |
|---|---|---|
pook.hooks(query?) | Promise<HooksPage> | The registry. Filters: protocol, kind, q. Paged. |
pook.hook(id) | Promise<HookDetailResponse> | One hook in full, with its recent runs. |
pook.quote(hookId, body) | Promise<QuoteResponse> | A quote without a run. |
pook.runs(query?) | Promise<RunsPage> | The public feed of runs. Filters: hookId, protocol. |
pook.runsStreamUrl(query?) | string | The address of the live feed, for an EventSource. |
pook.stats() | Promise<StatsResponse> | Counts of hooks, runs and open seats, and volume by asset. |
pook.config() | Promise<ConfigResponse> | The program and its addresses, the fee rates and the supported assets. |
pook.health() | Promise<HealthResponse> | Whether the API is ready. |
pook.parseIdl(body) | Promise<ParsedIdlResponse> | A program’s instructions, from its ID or its IDL as JSON. |
Standalone functions
After configurePook, the methods are also plain functions. Each takes a client as an optional last argument.
import { configurePook, run, enter, leave, balance, seats, activity } from '@pook/sdk'
import { loadCircuits } from '@pook/circuits'
configurePook({ apiUrl: 'https://api.pook.codes', wasm: await loadCircuits(), signer })
await run('jupiter.swap', { in, out, amount })The functions are run, enter, leave, openSeat, closeSeat, balance, publicBalance, seats, activity, publishHook, simulateHook, claimAuthorFees and defineHook. Calling one before configurePook throws an Error.
Types
| Type | Type | Meaning |
|---|---|---|
WalletSigner | object | publicKey: string. signMessage(message: Uint8Array): Promise<Uint8Array>. signTransaction?(transactionBase64: string): Promise<{ signedTransactionBase64?: string; signature?: string }>. |
HolderKeys | object | What unlock derives: wallet, authorityPda, ownerHash, viewingPkBase64, and the secrets seed, viewingSecret and nullifierSecretHex. Keep it on the device. |
DecryptedNote | object | One note: commitment, kind (balance or seat), action (enter, run or leave), mint, symbol, decimals, amount, spent, nullifier, signature, slot, timestamp, and for a seat note seatAddress. |
Pook | object | The client createPook returns. |
PookConfig | object | The options of createPook. |
HookDefinition, DefineHookInput | object | A hook definition, after and before defineHook. |
PookWasmModule | interface | The shape of the circuits module. |
KeyDerivationSeam, NoteScannerSeam, ProverSeam | object | The three replaceable parts of a client. |
The request and response types of the API are exported under the names the API reference uses: QuoteRequest, QuoteResponse, RelaySubmissionResponse, TxBuildResponse, TxStatusResponse, HookSummary, HookDetail, HookDetailResponse, HookDraft, HooksPage, RunsPage, PublicRun, SeatPosition, SimulateHookResponse, ParsedIdlResponse, AuthorFeesResponse, AuthorHookFee, ConfigResponse, HealthResponse, StatsResponse, AssetInfo, PublicBalanceResponse, ProverCircuitsResponse, MintConstraint, OnChainDataSlot, OnChainAccountSlot, OnChainCompanion, WirePublishHookArgs, PookApiClient.
Errors
Every failure the SDK reports is an ApiClientError, apart from a ZodError from defineHook and an Error from a standalone function called before configurePook.
| ApiClientError | Type | Meaning |
|---|---|---|
code | ErrorCode | A stable code to branch on. |
message | string | A sentence fit to show. |
status | number | The HTTP status. |
stage | ErrorStage | Where it failed: validation, build, wallet, wallet_rejected, simulation, proving, relay, send, confirmation or expired, among others. |
retryable | boolean | Whether the same call can succeed later. |
programError | ProgramError | When a program refused: programId, name and number. |
fieldErrors | Record<string, string[]> | For VALIDATION_ERROR, the messages for each field. |
body | ApiErrorBody | The whole error as the API sent it. |
The SDK raises three codes itself: UNAUTHORIZED when a signer is needed and none is set, WALLET_REJECTED when the wallet declines to sign, and INSUFFICIENT_BALANCE when the notes do not cover an amount. Every other code comes from the API, and the API reference lists them all. Program errors by name and number are in the program reference, and POOK_ERROR_NAMES maps number to name.
Constants and pure helpers
| Export | Type | Meaning |
|---|---|---|
POOK_ERROR_NAMES | Record<number, string> | The program’s errors, number to name. |
POOK_TAGS | object | The program’s instruction tags, by name. |
errors | object | The API’s error table: errors.status maps each code to its HTTP status, errors.knownCodes lists them. |
CONTRACT_VERSION | string | The version of the API contract the SDK was built against. |
WSOL_MINT, SYSTEM_PROGRAM_ID | string | The wrapped SOL mint and the System program. |
RINGS_DERIVE_MESSAGE | string | The message unlock signs. |
computeFeeSplit(out, runFeeBps, authorShareBps) | object | The run fee and its two parts for a result, rounded as the program rounds: runFee, protocolFee, authorFee. |
computeCallHash(targetProgram, hasMintOut, mintOut, data, accounts) | Uint8Array | The hash of a resolved call, as the program computes it and the proof fixes it. |
resolveCpiData(dataTemplateHex, dataSlots, amountIn, minOut, callerData) | Uint8Array | A hook’s instruction data with its slots filled. |
hookIdHash(hookId) | Uint8Array | The 32 bytes a hook’s address is derived from. |
hookDraftToOnChain(draft) | WirePublishHookArgs | A hook definition as publish_hook stores it. |
shortAddress(address, n?) | string | An address shortened for display. |
createClient(baseUrl, options?) | PookApiClient | The typed API client on its own, without keys or proving. |
Keys and addresses
These derive what the client derives. They are exported for tools that work below run.
| Export | Type | Meaning |
|---|---|---|
deriveAuthorityPda(programId) | Promise<[string, number]> | The authority and its bump. |
deriveStagePda(programId) | Promise<[string, number]> | The stage and its bump. |
deriveConfigPda(programId) | Promise<[string, number]> | The config account and its bump. |
deriveSeatPda(programId, commitment) | Promise<[string, number]> | A seat’s address from its commitment. |
deriveSeatStatePda(programId, commitment) | Promise<[string, number]> | A seat’s state account. |
deriveAuthorFeesPda(programId, author, mintBytes) | Promise<[string, number]> | An author’s fee account for one asset. |
deriveAtaAddress(owner, mint, tokenProgram?) | Promise<string> | An associated token account. |
derivePookPda(programId, seeds) | Promise<[string, number]> | Any address derived from the program. |
deriveSppSplInterfaceWithBump(ringsProgramId, mint) | Promise<[string, number]> | The Solana Privacy Program’s account for a token. |
deriveNullifierSecretBytes(seed, index) | Uint8Array | The one-time secret for note number index. |
deriveSeatSecretBytes(seed, seatIndex) | Uint8Array | The secret of seat number seatIndex. |
deriveSeatCommitmentBytes(seed, seatIndex) | Uint8Array | That seat’s commitment. |
deriveOneTimePdaKeys(keys, index) | Promise<object> | Everything for one note number: owner hash, nullifier key, Rings address. |
deriveProgramOwnerZeroAddress(keys) | Promise<Uint8Array> | The Rings address a seat’s commitment is reserved under. |
authorityIdentityFieldDec(authorityPda) | string | The authority as the circuits take it. |
buildKaminoOpenSeatSetup(seatPda, lendingMarket?) | Promise<object> | The setup calls that create a seat’s Kamino accounts when it opens. |
deriveRingsWalletKeys(signer, spr) | Promise<LocalKeys> | The holder’s own Rings keys, from one wallet signature. Used to enter from a Rings private balance. |
buildRingsEnterTransact(params) | Promise<object> | The Rings transfer that moves a holder’s Rings notes into a Pook note, proved and ready for enter. |
resolveRingsRecipientAddress(spr, walletAddress, signal?) | Promise<{ ownerHash, viewTag }> | A recipient’s Rings owner hash and view tag, looked up from the wallet address they registered with Rings. |
clearScanState(keys) | void | Drops the key material a client cached while scanning notes for these keys. |
defaultKeyDerivation, defaultNoteScanner, defaultProver | seam | The parts a client uses unless createPook is given others. |
loadCircuitArtifacts, proveProgramAndSpp, createMultiKeyProofAuthority | function | The proving steps run uses: fetch a circuit’s files, prove the Pook circuit and the Rings spend together, and sign for several one-time keys. |
The package also passes through the pieces of the Rings client it builds on: createSprClient, syncWallet, buildDepositTransaction, buildRegistrationTransaction, the types LocalKeys and ShieldedAddress, Wallet, AssetRegistry, ProofInputUtxo, toProgramWalletUtxo, initializePoseidon, poseidon, hashBytes, solanaOwnerIdentity, kitAddress, addressEncoder, and the constants DEFAULT_TREE_ID, NATIVE_SOL_MINT, SHIELDED_POOL_PROGRAM_ID, SOL_INTERFACE and SPL_TOKEN_PROGRAM_ID.