Nullark SDK API reference

Reference for integration path proven by current @nullark/sdk source and package-pinned starter. Start with complete SDK integration when you want runnable order.

`Nullark`

Create one client with one runtime and one matching set of adapters.

import { Nullark } from "@nullark/sdk";

const nullark = new Nullark({
  runtime,
  localDepositProver,
  localWithdrawalProver,
  readDeposits,
  resolveMembership,
  isNullifierSpent,
  runtimeFeeReadClient
});

Client exposes runtime as nullark.runtime and five public operations:

Operation	Purpose
`nullark.recovery.createKey()`	Create recovery key
`nullark.deposits.prepare(input)`	Prepare recoverable deposit and unsigned request
`nullark.recovery.restore(input)`	Restore private bundle from key and envelope
`nullark.balances.get(input)`	Recover matching deposits and total available notes
`nullark.withdrawals.prepare(input)`	Prepare bounded withdrawal and unsigned request

Constructor options

Option	Used by	Value expected
`runtime`	All operations	Runtime object; defaults to `getCurrentRuntime()`
`localDepositProver`	`deposits.prepare`	Callback returning `proof` and `publicInputs`
`localWithdrawalProver`	`withdrawals.prepare`	Callback returning `proof` and `publicInputs`
`readDeposits`	`balances.get`	Deposit events plus reader source identity
`resolveMembership`	`withdrawals.prepare`	Bundle commitment, leaf index, path elements, and root
`isNullifierSpent`	Balance and withdrawal	Reader source identity plus boolean `spent`
`runtimeFeeReadClient`	`withdrawals.prepare`	Chain ID, block snapshot, and pool fee reads
`randomBytes`	Recovery, deposit, withdrawal	Optional byte source; SDK uses WebCrypto when omitted

Missing operation-specific adapter rejects that operation before transaction preparation finishes.

`recovery.createKey`

const recoveryKey = nullark.recovery.createKey();

No input. Returns new Uint8Array containing exactly 32 bytes. When randomBytes is set, callback must return requested byte count. Keep returned bytes with recovery envelope created by deposits.prepare.

`deposits.prepare`

const deposit = await nullark.deposits.prepare({
  templateId: "one-as-two-halves",
  recoveryKey
});

Input

Field	Type	Required	Meaning
`templateId`	`string`	Yes	Template registered by active runtime
`recoveryKey`	`Uint8Array`	Yes	Recovery key containing 32 bytes

Method creates private bundle, encrypts recovery envelope, builds proof binding, calls localDepositProver, validates returned proof data, then builds unsigned transaction.

Result

Field	Meaning
`transaction.chainId`	Runtime chain ID
`transaction.to`	Runtime pool address
`transaction.value`	Deposit amount as `bigint`
`transaction.data`	Encoded deposit call
`proof`	Proof bytes returned by local prover after SDK checks
`publicInputs`	Public inputs checked against deposit binding
`binding`	Commitment, amount, encrypted payload, hashes, inputs, and prover witness
`recovery.bundle`	Private bundle used by withdrawal preparation
`recovery.envelope`	Encrypted recovery data stored with recovery key
`publicEvidence`	Chain, pool, commitment, amount, and flags showing private keys and note secrets are absent

Keep binding, recovery.bundle, key, and witness data inside trusted client. Wallet receives transaction after recovery backup passes restore roundtrip. Preparation rejects missing prover, unknown template, invalid recovery key, malformed prover result, or proof data that fails binding checks.

`recovery.restore`

const bundle = await nullark.recovery.restore({
  recoveryKey,
  envelope
});

Input

Field	Type	Required	Meaning
`recoveryKey`	`Uint8Array`	Yes	Same 32 bytes saved for deposit
`envelope`	`NullarkRecoveryEnvelope`	Yes	Encrypted envelope returned by deposit preparation

Method checks envelope against active runtime, opens it with recovery key, verifies recovered bundle commitment, then returns bundle accepted by withdrawals.prepare. Wrong key, changed envelope, or runtime mismatch rejects restore.

`balances.get`

const balance = await nullark.balances.get({ recoveryKey });

Input

Field	Type	Required	Meaning
`recoveryKey`	`Uint8Array`	Yes	Key used by deposits you want to find

Method calls readDeposits, tries matching encrypted events locally, calls isNullifierSpent for each recovered note, and sums notes still available.

Result

Field	Type	Meaning
`availableBalanceWei`	`string`	Sum of available recovered notes in decimal wei
`deposits`	`array`	Deposits opened by recovery key
`deposits[].event`	`object`	Commitment, amount, and encrypted payload supplied by reader
`deposits[].bundle`	`object`	Restored bundle accepted by withdrawal preparation
`deposits[].notes`	`array`	Nonzero child notes found in bundle
`deposits[].notes[].childIndex`	`number`	Index passed to withdrawal preparation
`deposits[].notes[].amountWei`	`string`	Note amount in decimal wei
`deposits[].notes[].commitment`	hex string	Child commitment
`deposits[].notes[].nullifier`	hex string	Value used by spent-state reader
`deposits[].notes[].status`	`"available" \| "spent"`	Current reader result

Spent notes stay in notes with status "spent"; available balance excludes their amounts. Unrelated encrypted events stay out of deposits. Call requires both readDeposits and isNullifierSpent. Malformed events, duplicate commitments, malformed status, or reader-source mismatch reject whole read.

`withdrawals.prepare`

const withdrawal = await nullark.withdrawals.prepare({
  bundle,
  childIndex,
  destination,
  maxFeeWei,
  minNetAmountWei
});

Input

Field	Type	Required	Meaning
`bundle`	restored bundle	Yes	Bundle returned by recovery or balance read
`childIndex`	`number`	Yes	Available nonzero note selected by user
`destination`	`HexString`	Yes	Nonzero recipient address
`maxFeeWei`	decimal `string`	No	Highest fee accepted by user
`minNetAmountWei`	decimal `string`	No	Lowest recipient amount accepted by user

When fee bounds are omitted, method uses fee and net amount read during preparation as exact bounds. Preparation checks bundle/runtime match, resolves membership, checks selected note, reads fee, checks user bounds, calls local prover, validates proof intent, reads fee again, checks selected note again, then builds unsigned transaction.

Result

Field	Meaning
`transaction`	Unsigned `{ chainId, to, value, data }`; `value` is `0n`
`proof`	Checked withdrawal proof bytes
`publicInputs`	Checked withdrawal inputs
`encryptedPayload`	Cover payload included with call
`nullifier`	Selected note identifier used for spent check
`root`	Membership root used by proof
`destination`	Normalized recipient address
`grossAmountWei`	Selected note amount
`feeWei`	Fee used by proof
`netAmountWei`	Recipient amount
`maxFeeWei`	Applied fee ceiling
`minNetAmountWei`	Applied recipient floor

Preparation rejects spent note, missing adapter, invalid destination, invalid decimal bound, fee above ceiling, net amount below floor, fee change during proving, or prover result that fails proof checks.

Adapter contracts

All chain readers stay tied to nullark.runtime.

Reader source

readDeposits and isNullifierSpent return same source fields with their data:

type NullarkReaderSource = {
  chainId: number;
  pool: HexString;
  runtimeId: string;
  runtimeIdHash: HexString;
  templateSetHash: HexString;
};

SDK checks every field against active runtime.

Adapter shapes

Adapter	Receives	Returns
`readDeposits`	`{ runtime }`	`{ source, events }`, each event containing `commitment`, `amountWei`, `encryptedPayload`
`resolveMembership`	`{ runtime, bundle, childIndex }`	`{ bundleCommitment, leafIndex, pathElements, root }`
`isNullifierSpent`	`{ runtime, nullifier }`	`{ source, spent }`
`runtimeFeeReadClient.getChainId`	No input	Chain ID
`runtimeFeeReadClient.getBlock`	Optional block number	Block number and hash
`runtimeFeeReadClient.readContract`	Address, ABI, function name, optional block	Pool fee value
`localDepositProver`	`{ runtime, bundle, recoverableDeposit, binding }`	`{ proof, publicInputs }`
`localWithdrawalProver`	`{ runtime, witnessBundle }`	`{ proof, publicInputs }`

Starter setup helpers

These exports wire proving path used by starter:

Import	Export	Use
`@nullark/sdk`	`getCurrentRuntime`	Read bundled runtime object
`@nullark/sdk`	`generateBundledChildDepositGroth16Proof`	Run deposit proof through supplied prover runner
`@nullark/sdk`	`generateWithdrawalGroth16Proof`	Run withdrawal proof through supplied prover runner
`@nullark/sdk/node`	`resolveProverArtifacts`	Resolve runtime file paths into local paths or HTTPS URLs
`@nullark/sdk/node`	`verifyLocalProverArtifacts`	Check local file hashes and record bindings

@nullark/sdk/node reads local files with Node APIs. Keep that entry in Node code. Main @nullark/sdk entry carries client, methods, types, proof helpers, and runtime helpers.

Common stops

Stop	Check
Deposit prover missing	Pass `localDepositProver` when creating client
Balance reader missing	Pass both `readDeposits` and `isNullifierSpent`
Withdrawal adapter missing	Pass membership, spent-state, fee, and withdrawal-prover adapters
Reader source mismatch	Point every reader at same runtime and pool
Recovery restore failed	Use untouched envelope with matching 32-byte key
Note already spent	Refresh `balances.get` and choose available note
Fee changed during proof	Run `withdrawals.prepare` again with user-approved bounds

Submission status stays app-owned. Use starter-backed errors and status flow before any retry.

Workflows

Setup and recovery

Reference

Nullark SDK API reference

`Nullark`

Constructor options

`recovery.createKey`

`deposits.prepare`

Input

Result

`recovery.restore`

Input

`balances.get`

Input

Result

`withdrawals.prepare`

Input

Result

Adapter contracts

Reader source

Adapter shapes

Starter setup helpers

Common stops

​Nullark

​Constructor options

​recovery.createKey

​deposits.prepare

​Input

​Result

​recovery.restore

​Input

​balances.get

​Input

​Result

​withdrawals.prepare

​Input

​Result

​Adapter contracts

​Reader source

​Adapter shapes

​Starter setup helpers

​Common stops

`Nullark`

Constructor options

`recovery.createKey`

`deposits.prepare`

Input

Result

`recovery.restore`

Input

`balances.get`

Input

Result

`withdrawals.prepare`

Input

Result

Adapter contracts

Reader source

Adapter shapes

Starter setup helpers

Common stops