Use the TypeScript SDK

Use this page when you want Nullark inside your own TypeScript app. The SDK validates the runtime, recovery envelope, proof inputs, fee bounds, spent state, and calldata. Your app supplies local proving, current Merkle membership, chain reads, secure recovery storage, and wallet transport.

The npm release is pending. Install the SDK from the Nullark repository or from tarballs built from a reviewed checkout.

Install from source

cd /absolute/path/to/nullark
npm install
npm run build --workspace @nullark/sdk

mkdir package-out
npm pack --workspace @nullark/core --pack-destination package-out
npm pack --workspace @nullark/sdk --pack-destination package-out

npm install /absolute/path/to/nullark/package-out/nullark-core-0.0.0.tgz /absolute/path/to/nullark/package-out/nullark-sdk-0.0.0.tgz snarkjs viem

The SDK is ESM and includes its own TypeScript declarations. snarkjs ships without declarations, so strict TypeScript apps need a small local declaration:

snarkjs.d.ts

declare module "snarkjs" {
  export const groth16: {
    fullProve(
      witness: unknown,
      wasmPath: string,
      zkeyPath: string
    ): Promise<{ proof: unknown; publicSignals: string[] }>;
  };
}

Before you create the client

Have these pieces ready:

Your app provides	Used for
Authenticated WASM and zkey files	Deposit and withdrawal proofs
`resolveMembership`	The selected bundle’s depth-20 Merkle path and accepted root
`isNullifierSpent`	A current read of the pool’s `nullifiers` mapping
`runtimeFeeReadClient`	Block-consistent reads of the active pool fee
Recovery storage	The 32-byte key and encrypted envelope created before deposit submission
Wallet transport	Review, simulation, signing, and submission of the prepared transaction

Run proving where the user’s secrets stay under their control. A browser, desktop app, or local Node process can own the prover. A hosted prover callback receives the private witness. @nullark/sdk/node resolves and verifies local proving files. Keep that import in local Node or trusted build tooling. Browser apps use the main @nullark/sdk entry and an app-owned loader that checks downloaded artifact bytes against the runtime hashes before snarkjs receives them.

Create the client

This factory is the complete local-file setup. artifactDir is the directory containing the runtime’s /proving/... paths; in this repository that directory is apps/web/public.

import { groth16 } from "snarkjs";
import {
  Nullark,
  generateBundledChildDepositGroth16Proof,
  generateWithdrawalGroth16Proof,
  getRuntimeForNetwork,
  type ReadBundledChildNullifierStatus,
  type ResolveBundledChildMembership,
  type RuntimeFeeReadContractClient
} from "@nullark/sdk";
import {
  resolveProverArtifacts,
  verifyLocalProverArtifacts
} from "@nullark/sdk/node";

type CreateNullarkClientInput = {
  artifactDir: string;
  resolveMembership: ResolveBundledChildMembership;
  isNullifierSpent: ReadBundledChildNullifierStatus;
  runtimeFeeReadClient: RuntimeFeeReadContractClient;
};

export async function createNullarkClient(input: CreateNullarkClientInput) {
  const runtime = getRuntimeForNetwork("robinhood-testnet");
  const artifacts = resolveProverArtifacts(runtime, {
    mode: "local-artifact-dir",
    artifactDir: input.artifactDir
  });
  const artifactBinding = await verifyLocalProverArtifacts(runtime, artifacts);

  if (!artifactBinding.trusted) {
    throw new Error(`Proving files rejected: ${artifactBinding.reason}`);
  }

  const proverRunner = {
    fullProve: (witness: unknown, wasmPath: string, zkeyPath: string) =>
      groth16.fullProve(witness, wasmPath, zkeyPath)
  };

  return new Nullark({
    runtime,
    localDepositProver: ({ binding }) =>
      generateBundledChildDepositGroth16Proof({
        binding,
        artifacts,
        artifactBinding,
        proverRunner
      }),
    localWithdrawalProver: ({ witnessBundle }) =>
      generateWithdrawalGroth16Proof({
        witness: witnessBundle.witness,
        intent: witnessBundle.intent,
        artifacts,
        artifactBinding,
        proverRunner
      }),
    resolveMembership: input.resolveMembership,
    isNullifierSpent: input.isNullifierSpent,
    runtimeFeeReadClient: input.runtimeFeeReadClient
  });
}

`new Nullark(options)`

NullarkCurrentRuntime

Runtime used for every check and prepared transaction. Robinhood integrations should pass the explicitly selected runtime instead of relying on a package default.

LocalBundledChildDepositProver

Required by deposits.prepare. It receives the private deposit witness and must return a 256-byte Groth16 proof plus the six matching public inputs.

LocalBundledChildWithdrawalProver

Required by withdrawals.prepare. It receives the private withdrawal witness and must return a 256-byte Groth16 proof plus the nine matching public inputs.

ResolveBundledChildMembership

Required by withdrawals.prepare. Return the selected bundle commitment, leaf index, 20 path elements, and an accepted root from the active pool.

ReadBundledChildNullifierStatus

Required by withdrawals.prepare. Return the current boolean value for the child nullifier from the runtime pool.

RuntimeFeeReadContractClient

Required by withdrawals.prepare. The interface matches getChainId, getBlock, and readContract reads used by a Viem public client.

(length: number) => Uint8Array

Test hook. Production integrations should use the default WebCrypto randomness.

Membership resolver contract

type ResolveBundledChildMembership = (input: {
  runtime: NullarkCurrentRuntime;
  bundle: V13BundledChildBundle;
  childIndex: number;
}) => Promise<{
  bundleCommitment: `0x${string}`;
  leafIndex: number;
  pathElements: readonly (bigint | `0x${string}`)[];
  root: `0x${string}`;
  depth?: number;
}>;

Build this from ordered CommitmentInserted history or a trusted indexer, then confirm the resulting root is accepted by the same pool.

Spent-state reader contract

type ReadBundledChildNullifierStatus = (input: {
  runtime: NullarkCurrentRuntime;
  nullifier: `0x${string}`;
}) => boolean | Promise<boolean>;

Read nullifiers(bytes32) at runtime.pool. The SDK checks it before and after withdrawal proving.

Fee reader contract

type RuntimeFeeReadContractClient = {
  getChainId(): Promise<number>;
  getBlock(input?: { blockNumber?: bigint }): Promise<{
    number?: bigint | null;
    hash: `0x${string}` | null;
  }>;
  readContract(input: {
    address: `0x${string}`;
    abi: readonly unknown[];
    functionName:
      | "feeController"
      | "feeBps"
      | "MAX_FEE_BPS"
      | "pendingFeeBps"
      | "pendingFeeActivationTime";
    blockNumber?: bigint;
  }): Promise<unknown>;
};

The SDK pins all fee reads to one block and verifies the chain, block hash, controller, and fee bounds.

Deposit and recovery

`deposits.prepare(input)`

Creates fresh bundle secrets, encrypts the recovery payload, runs the local deposit prover, validates its output, and returns one unsigned transaction.

string

required

A registered private-note template. one-as-two-halves deposits 1 ETH and creates two 0.5 ETH child notes.

Uint8Array

required

Exactly 32 random bytes. Keep the key with the matching envelope in encrypted user-controlled storage.

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

// Save recoveryKey and deposit.recovery.envelope before wallet submission.

DepositTransactionRequest

{ chainId, to, value, data } ready for wallet simulation and submission. value is the deposit amount.

NullarkRecoveryEnvelope

Encrypted recovery payload plus the runtime, pool, commitment, and payload bindings needed for restoration.

V13BundledChildBundle

The in-memory private bundle created for this deposit. Treat it as secret-bearing state.

HexString

Canonical 256-byte Groth16 proof accepted by the SDK.

readonly HexString[]

Six validated public inputs in the runtime’s deposit order.

object

Safe reconciliation fields: chain, pool, commitment, amount, and payload-presence flags. Private keys and note secrets are excluded.

Save the recovery key and envelope before opening the wallet. If the wallet result becomes uncertain, keep the same recovery material and reconcile the original commitment before preparing another deposit. The SDK accepts raw recovery-key bytes. The Transfer Console adds EIP-712 signer verification, wallet-bound key derivation, onchain event scanning, and bearer-note fallback around this primitive. Integrators need those boundaries before presenting wallet recovery.

`recovery.restore(input)`

Decrypts one saved envelope and returns the original private bundle after checking its runtime, pool, template set, payload hash, and bundle commitment.

NullarkRecoveryEnvelope

required

The exact envelope returned by deposits.prepare.

Uint8Array

required

The matching 32-byte key.

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

HexString

Commitment used to locate the bundle in pool history.

readonly V13BundledChildNote[]

Child amount, secret, commitment, owner commitment, and nullifier for each private note.

runtime identity

Identity checked again when the bundle is used for withdrawal.

Withdrawal

`withdrawals.prepare(input)`

Resolves membership, checks spent state and fee state, runs the local withdrawal prover, validates every public input, rechecks mutable chain state, and returns zero-value calldata.

V13BundledChildBundle

required

Bundle returned by recovery.restore or retained from the original deposit preparation.

number

required

Index of an available child note. The example template has child indices 0 and 1.

HexString

required

Nonzero EVM address that receives the public withdrawal.

string

Maximum accepted fee as decimal wei. The active fee becomes the exact bound when omitted.

string

Minimum amount the destination must receive as decimal wei. The current calculated net amount is used when omitted.

const withdrawal = await nullark.withdrawals.prepare({
  bundle,
  childIndex: 0,
  destination: "0x1111111111111111111111111111111111111111",
  maxFeeWei: "1650000000000000",
  minNetAmountWei: "498350000000000000"
});

{ chainId, to, value: 0n, data }

Unsigned withdrawal transaction. The pool call always carries zero ETH value.

string

Decimal wei values used by the proof and calldata.

HexString

Public withdrawal identity validated against the generated proof.

HexString fields

Canonical proof package already checked against the exact withdrawal intent.

Send the prepared transaction

Both methods return the same wallet-ready shape. Check the wallet chain, preserve to, value, and data, then wait for a receipt from the runtime RPC.

import {
  createPublicClient,
  createWalletClient,
  custom,
  http,
  type EIP1193Provider
} from "viem";
import {
  getRuntimeForNetwork,
  type PreparedBundledChildDeposit,
  type PreparedBundledChildWithdrawal
} from "@nullark/sdk";

type PreparedTransaction =
  | PreparedBundledChildDeposit["transaction"]
  | PreparedBundledChildWithdrawal["transaction"];

export async function sendPreparedTransaction(
  provider: EIP1193Provider,
  transaction: PreparedTransaction
) {
  const runtime = getRuntimeForNetwork("robinhood-testnet");
  const walletClient = createWalletClient({ transport: custom(provider) });
  const connectedChainId = await walletClient.getChainId();

  if (connectedChainId !== transaction.chainId) {
    throw new Error("Switch the wallet to the Nullark network before submitting.");
  }

  const [account] = await walletClient.getAddresses();
  if (!account) throw new Error("Connect a wallet before submitting.");

  const hash = await walletClient.sendTransaction({
    account,
    chain: null,
    to: transaction.to,
    value: transaction.value,
    data: transaction.data
  });
  const publicClient = createPublicClient({ transport: http(runtime.rpcUrl) });
  return publicClient.waitForTransactionReceipt({ hash });
}

Treat a rejected wallet request as cancelled. When a hash was returned or the transport timed out after signing, look up that hash and the prepared commitment or nullifier before offering a retry.

Common errors

Error includes	What to fix
`requires a trusted local deposit prover`	Add `localDepositProver` when creating the client.
`Proving files rejected`	Restore the runtime-pinned files; do not bypass the hash check.
`Recovery envelope does not match`	Use the runtime, envelope, and key saved for the same deposit.
`requires a Merkle membership resolver`	Supply a current depth-20 path for the bundle commitment.
`already spent`	Refresh the private balance and choose an available child.
`fee changed while proving`	Re-run `withdrawals.prepare` with fresh fee state.
`exceeds the user maximum`	Ask the user to review a new fee bound.
`does not match the intended withdrawal`	Discard the proof response and inspect the local prover boundary.

Use Deposit integration for receipt reconciliation, Withdrawal integration for preflight and settlement, and Proving files for artifact handling.

Workflows

Setup and recovery

Reference

Use the TypeScript SDK

Install from source

Before you create the client

Create the client

`new Nullark(options)`

Deposit and recovery

`deposits.prepare(input)`

`recovery.restore(input)`

Withdrawal

`withdrawals.prepare(input)`

Send the prepared transaction

Common errors

​Install from source

​Before you create the client

​Create the client

​new Nullark(options)

​Deposit and recovery

​deposits.prepare(input)

​recovery.restore(input)

​Withdrawal

​withdrawals.prepare(input)

​Send the prepared transaction

​Common errors

Install from source

Before you create the client

Create the client

`new Nullark(options)`

Deposit and recovery

`deposits.prepare(input)`

`recovery.restore(input)`

Withdrawal

`withdrawals.prepare(input)`

Send the prepared transaction

Common errors