API reference

Every export of @hestia/sdk — the Hestia class, config, errors, association set, proof helpers, agent tools, and re-exports.

A complete reference of the @hestia/sdk public surface. Types are shown in their declared form.

Hestia

class Hestia {
  static create(cfg: HestiaConfig): Promise<Hestia>;

  readonly keys: Keys;

  get metaAddress(): string;          // hestia1… — share to receive
  exportViewingKey(): Hex;            // hex of vk — selective disclosure

  sync(): Promise<void>;              // pull events into the local index
  balance(token: Address): Promise<bigint>;

  shield(args: { token: Address; amount: bigint }): Promise<Hex>;
  send(args: { token: Address; amount: bigint; to: string; fee?: bigint }): Promise<Hex>;
  unshield(args: { token: Address; amount: bigint; to: Address; fee?: bigint }): Promise<Hex>;
}

All write methods resolve with the transaction hash after the receipt confirms.

HestiaConfig

interface HestiaConfig {
  chain: Chain;
  rpcUrl: string;
  pool: Address;
  registry: Address;
  usdc: Address;
  account: Account | Address;
  keys: Keys;
  association: AssociationProvider;
  artifacts: ArtifactsByArity;
  transport?: Transport;
  metaChain?: ChainName; // default "baseSepolia"
}

See The Hestia client for field-by-field notes.

InsufficientPrivateBalance

class InsufficientPrivateBalance extends Error {
  constructor(token: bigint, required: bigint);
}

Thrown by send / unshield when no single unspent note covers amount + fee. See coin selection.

AssociationSet & AssociationProvider

interface AssociationProvider {
  root(): bigint | Promise<bigint>;
  proof(label: bigint): MerkleProof | Promise<MerkleProof>;
}

class AssociationSet implements AssociationProvider {
  static create(depth?: number): Promise<AssociationSet>;
  add(label: bigint): number;        // approve a label, returns its index
  root(): bigint;
  proof(label: bigint): MerkleProof;
}

Proof helpers

For building or proving a transaction witness directly (advanced; the Hestia methods do this for you):

interface SpendInput {
  note: Note;
  leafIndex: number;
  merkleProof: MerkleProof;
}

interface TransactionWitness {
  sk: bigint;
  token: bigint;
  inputs: SpendInput[];
  outputs: Note[];
  withdrawAmount: bigint;
  feeAmount: bigint;
  recipient: bigint;
  relayer: bigint;
  associationRoot: bigint;
  associationProof: MerkleProof;
}

function buildCircuitInput(w: TransactionWitness): Record<string, unknown>;
function proveTransactionWitness(
  w: TransactionWitness,
  artifacts: ArtifactsByArity,
): Promise<ContractProof>;

Agent tools

interface AgentTool {
  name: string;
  description: string;
  parameters: Record<string, unknown>;
  execute: (args: Record<string, unknown>) => Promise<unknown>;
}

function createHestiaTools(hestia: Hestia): AgentTool[];
// → hestia_balance, hestia_shield, hestia_send, hestia_unshield

See agent tools.

Re-exports from @hestia/circuits

type Arity = "1x2" | "2x2";
interface CircuitArtifacts { wasm: string; zkey: string }
type ArtifactsByArity = Record<Arity, CircuitArtifacts>;
interface ContractProof {
  a: [bigint, bigint];
  b: [[bigint, bigint], [bigint, bigint]];
  c: [bigint, bigint];
  publicSignals: string[];
}

Re-exports from @hestia/common

interface Keys { sk: bigint; SK: bigint; vk: Uint8Array; VK: Uint8Array }

function deriveKeysFromSeed(seed: Uint8Array): Promise<Keys>;
function deriveKeysFromSignature(signature: Uint8Array): Promise<Keys>;

function encodeMetaAddress(m: MetaAddress): string;
function decodeMetaAddress(addr: string): MetaAddress;

const NATIVE_ETH: "0x0000000000000000000000000000000000000000";
const USDC_ADDRESS: { base: "0x8335…2913"; baseSepolia: "0x036C…CF7e" };

Versions

const SDK_VERSION: "0.1.0";
const PROTOCOL_VERSION: "0.1.0";

The note type referenced above (Note, MerkleProof, NotePlaintext) and the lower-level primitives (commitment, nullifier, labelFromLeafIndex, encryptNote, the IncrementalMerkleTree, Poseidon and field helpers) come from @hestia/common — documented under cryptographic primitives.