@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/pda.js

@@ -0,0 +1,384 @@
+/**
+ * PDA (Program Derived Address) Derivation Utilities
+ *
+ * Centralized module for all UTXOpia PDA derivations.
+ * Prevents code duplication across api.ts, pda.ts, etc.
+ *
+ * @module pda
+ */
+import { getAddressEncoder, getProgramDerivedAddress, } from "@solana/kit";
+import { UTXOPIA_PROGRAM_ID, UTXOPIA_POLICY_PROGRAM_ID, BTC_LIGHT_CLIENT_PROGRAM_ID, } from "./config";
+function seedBytes(value, label) {
+    const bytes = typeof value === "string"
+        ? new Uint8Array(getAddressEncoder().encode(value))
+        : value;
+    if (bytes.length !== 32)
+        throw new Error(`${label} must be 32 bytes`);
+    return bytes;
+}
+// =============================================================================
+// PDA Seeds
+// =============================================================================
+export const PDA_SEEDS = {
+    POOL_STATE: "pool_state",
+    COMMITMENT_TREE: "commitment_tree",
+    LIGHT_CLIENT: "btc_light_client",
+    BLOCK_HEADER: "block",
+    HEIGHT_INDEX: "height_index",
+    VERIFIED_TX: "verified_tx",
+    DEPOSIT: "deposit",
+    NULLIFIER: "nullifier",
+    POLICY_APPROVAL: "policy_approval",
+    EXIT_DESTINATION: "exit_destination",
+    VK_REGISTRY: "vk_registry",
+    TOKEN_CONFIG: "token_config",
+    POOL_CONFIG: "pool_config",
+};
+// =============================================================================
+// Seed builders — the single definition of every program-derived address
+//
+// These are the authority. Each mirrors the seed array the on-chain program
+// derives with, and every derivation in this file is built on them, so there is
+// one place to change when the program changes.
+//
+// They are exported and synchronous on purpose. `getProgramDerivedAddress` is
+// async, but consumers on @solana/web3.js need `findProgramAddressSync` and
+// `PublicKey`. Without a sync seam those consumers end up re-declaring the seeds
+// themselves — which is exactly how the web app's copy drifted out of sync with
+// the program twice (the nullifier and the redemption request both lost their
+// pool scope, and both failed only on chain, after a proof had been paid for).
+// Take the seeds from here and do your own address math with your own types.
+// =============================================================================
+const enc = (s) => new TextEncoder().encode(s);
+const u32le = (n, label) => {
+    if (!Number.isInteger(n) || n < 0 || n > 0xffffffff) {
+        throw new Error(`${label} must be a u32, got ${n}`);
+    }
+    const b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n, true);
+    return b;
+};
+const u64le = (n) => {
+    const b = new Uint8Array(8);
+    new DataView(b.buffer).setBigUint64(0, n, true);
+    return b;
+};
+/** `["pool_state", pool_id]` — pool_id is the pool's zkBTC mint. */
+export function poolStateSeeds(poolId) {
+    return [enc(PDA_SEEDS.POOL_STATE), seedBytes(poolId, "poolId")];
+}
+/** `["commitment_tree", pool_state, tree_index_le]`. */
+export function commitmentTreeSeeds(poolState, treeIndex = 0) {
+    return [
+        enc(PDA_SEEDS.COMMITMENT_TREE),
+        seedBytes(poolState, "poolState"),
+        u32le(treeIndex, "treeIndex"),
+    ];
+}
+/** `["token_config", pool_state, mint]`. */
+export function tokenConfigSeeds(poolState, mint) {
+    return [
+        enc(PDA_SEEDS.TOKEN_CONFIG),
+        seedBytes(poolState, "poolState"),
+        seedBytes(mint, "mint"),
+    ];
+}
+/** `["pool_config", pool_state]`. */
+export function poolConfigSeeds(poolState) {
+    return [enc(PDA_SEEDS.POOL_CONFIG), seedBytes(poolState, "poolState")];
+}
+/** `["nullifier", pool_state, nullifier]` on tree 0, and
+ *  `["nullifier", pool_state, tree_index_le, nullifier]` after a rotation.
+ *
+ *  A nullifier is Poseidon(nullifyingKey, leafIndex), so it names a note only
+ *  within one pool and one tree — leaf indices restart at 0 in each new tree.
+ *  Drop either scope and two distinct notes collapse onto one PDA, where
+ *  spending either strands the other. Tree 0 keeps the shorter seeds so records
+ *  already on chain stay reachable (`joinsplit_common.rs`). */
+export function nullifierRecordSeeds(nullifierHash, poolState, treeIndex = 0) {
+    const seeds = [
+        enc(PDA_SEEDS.NULLIFIER),
+        seedBytes(poolState, "poolState"),
+    ];
+    if (treeIndex !== 0)
+        seeds.push(u32le(treeIndex, "treeIndex"));
+    seeds.push(nullifierHash);
+    return seeds;
+}
+/** `["redemption", pool_state, user, nonce_le]` (`redeem.rs`). */
+export function redemptionRequestSeeds(poolState, userPubkey, nonce) {
+    return [
+        enc("redemption"),
+        seedBytes(poolState, "poolState"),
+        seedBytes(userPubkey, "userPubkey"),
+        u64le(nonce),
+    ];
+}
+/** `["vk_registry", [n_inputs], [n_outputs]]`. */
+export function vkRegistrySeeds(nInputs, nOutputs) {
+    return [enc(PDA_SEEDS.VK_REGISTRY), Uint8Array.of(nInputs), Uint8Array.of(nOutputs)];
+}
+/** `["deposit_receipt", txid]`, or `[..., vout_le]` for the OP_RETURN-free
+ *  `verify_deposit` flow. See deriveDepositReceiptPDA for which is which. */
+export function depositReceiptSeeds(depositTxid, depositVout) {
+    if (depositTxid.length !== 32) {
+        throw new Error(`depositTxid must be 32 bytes, got ${depositTxid.length}`);
+    }
+    const seeds = [enc("deposit_receipt"), depositTxid];
+    if (depositVout !== undefined)
+        seeds.push(u32le(depositVout, "depositVout"));
+    return seeds;
+}
+/** `["policy_approval", pool_state, request_hash, nonce]`. */
+export function policyApprovalSeeds(poolState, requestHash, nonce) {
+    if (requestHash.length !== 32 || nonce.length !== 32) {
+        throw new Error("requestHash and nonce must be 32 bytes");
+    }
+    return [
+        enc(PDA_SEEDS.POLICY_APPROVAL),
+        seedBytes(poolState, "poolState"),
+        requestHash,
+        nonce,
+    ];
+}
+/** `["exit_destination", pool_state, [kind], key]`. */
+export function exitDestinationSeeds(poolState, kind, key) {
+    if (key.length !== 32)
+        throw new Error("exit destination key must be 32 bytes");
+    if (kind !== EXIT_KIND_SOLANA_OWNER && kind !== EXIT_KIND_BTC_SCRIPT) {
+        throw new Error("unknown exit destination kind");
+    }
+    return [
+        enc(PDA_SEEDS.EXIT_DESTINATION),
+        seedBytes(poolState, "poolState"),
+        Uint8Array.of(kind),
+        key,
+    ];
+}
+/** `["btc_light_client"]`. */
+export function lightClientSeeds() {
+    return [enc(PDA_SEEDS.LIGHT_CLIENT)];
+}
+/** `["block", block_hash]`. */
+export function blockHeaderSeeds(blockHash) {
+    // A short hash still derives *an* address, just not the block's — the caller would then read
+    // or write the wrong account with no error anywhere. Every other 32-byte seed here is checked.
+    return [enc(PDA_SEEDS.BLOCK_HEADER), seedBytes(blockHash, "blockHash")];
+}
+/** `["height_index", height_le(8)]`. */
+export function heightIndexSeeds(height) {
+    return [enc(PDA_SEEDS.HEIGHT_INDEX), u64le(BigInt(height))];
+}
+/** `["verified_tx", block_hash, txid]`. */
+export function verifiedTransactionSeeds(blockHash, txid) {
+    return [enc(PDA_SEEDS.VERIFIED_TX), blockHash, txid];
+}
+// =============================================================================
+// Core UTXOpia PDAs
+// =============================================================================
+/**
+ * Derive Pool State PDA
+ */
+export async function derivePoolStatePDA(poolId, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: poolStateSeeds(poolId),
+    });
+    return [result[0], result[1]];
+}
+/**
+ * Derive Commitment Tree PDA
+ *
+ * @param treeIndex - Tree rotation index (default 0).
+ */
+export async function deriveCommitmentTreePDA(poolState, programId = UTXOPIA_PROGRAM_ID, treeIndex) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: commitmentTreeSeeds(poolState, treeIndex ?? 0),
+    });
+    return [result[0], result[1]];
+}
+/**
+ * Derive TokenConfig PDA for a specific mint
+ * Seeds: ["token_config", mint_pubkey_bytes]
+ */
+export async function deriveTokenConfigPDA(poolState, mintPubkey, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: tokenConfigSeeds(poolState, mintPubkey),
+    });
+    return [result[0], result[1]];
+}
+/** Derive ["pool_config", pool_state]. */
+export async function derivePoolConfigPDA(poolState, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: poolConfigSeeds(poolState),
+    });
+    return [result[0], result[1]];
+}
+/**
+ * Derive Nullifier Record PDA.
+ *
+ * Seeds are `["nullifier", pool_state, nullifier]` on tree 0, and
+ * `["nullifier", pool_state, tree_index_le, nullifier]` on any tree a rotation
+ * created. Both scopes exist because a nullifier is Poseidon(nullifyingKey,
+ * leafIndex) and so identifies a note only within one pool and one tree:
+ *
+ *  - Without the pool, the same seed spending into two vaults derives one PDA,
+ *    and spending in either strands the twin note in the other.
+ *  - Without the tree, the same happens across a rotation, because leaf indices
+ *    restart at 0 in every new tree.
+ *
+ * Tree 0 keeps the shorter seeds so the records already on chain stay reachable
+ * — re-deriving them would make every already-spent note spendable again.
+ */
+export async function deriveNullifierRecordPDA(nullifierHash, poolState, treeIndex = 0, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: nullifierRecordSeeds(nullifierHash, poolState, treeIndex),
+    });
+    return [result[0], result[1]];
+}
+/**
+ * Derive one-time PolicyApproval PDA.
+ * Seeds: ["policy_approval", pool_state, request_hash, nonce]
+ */
+export async function derivePolicyApprovalPDA(poolState, requestHash, nonce, programId = UTXOPIA_POLICY_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: policyApprovalSeeds(poolState, requestHash, nonce),
+    });
+    return [result[0], result[1]];
+}
+/** Destination kinds in the exit registry. Kind is a PDA seed, so a Solana
+ *  owner and a BTC script hash sharing the same 32 bytes stay distinct. */
+export const EXIT_KIND_SOLANA_OWNER = 0;
+export const EXIT_KIND_BTC_SCRIPT = 1;
+/**
+ * Derive an ExitDestination PDA — the append-only registry of destinations a
+ * permissioned pool's ragequit path may pay.
+ *
+ * Seeds: ["exit_destination", pool_state, [kind], key]
+ *
+ * `key` is the recipient token account's OWNER for `EXIT_KIND_SOLANA_OWNER`,
+ * or `sha256(btcScript)` for `EXIT_KIND_BTC_SCRIPT`.
+ */
+export async function deriveExitDestinationPDA(poolState, kind, key, programId) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: exitDestinationSeeds(poolState, kind, key),
+    });
+    return [result[0], result[1]];
+}
+// =============================================================================
+// BTC Light Client PDAs
+// =============================================================================
+/**
+ * Derive BTC Light Client PDA
+ */
+export async function deriveLightClientPDA(programId = BTC_LIGHT_CLIENT_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: lightClientSeeds(),
+    });
+    return [result[0], result[1]];
+}
+/**
+ * Derive Block Header PDA (hash-based)
+ * Seeds: ["block", blockHash(32)]
+ */
+export async function deriveBlockHeaderPDA(blockHash, programId = BTC_LIGHT_CLIENT_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: blockHeaderSeeds(blockHash),
+    });
+    return [result[0], result[1]];
+}
+/**
+ * Derive HeightIndex PDA
+ * Seeds: ["height_index", height_le_bytes(8)]
+ */
+export async function deriveHeightIndexPDA(height, programId = BTC_LIGHT_CLIENT_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: heightIndexSeeds(height),
+    });
+    return [result[0], result[1]];
+}
+/**
+ * Derive VerifiedTransaction PDA (btc-light-client)
+ *
+ * Seeds: ["verified_tx", blockHash(32), txid(32)]
+ */
+export async function deriveVerifiedTransactionPDA(blockHash, txid, programId = BTC_LIGHT_CLIENT_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: verifiedTransactionSeeds(blockHash, txid),
+    });
+    return [result[0], result[1]];
+}
+// =============================================================================
+// Redemption Request PDAs
+// =============================================================================
+/**
+ * Derive Redemption Request PDA
+ *
+ * Seeds: ["redemption", pool_state, user_pubkey(32), nonce_le(8)]
+ */
+export async function deriveRedemptionRequestPDA(poolState, userPubkey, nonce, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: redemptionRequestSeeds(poolState, userPubkey, nonce),
+    });
+    return [result[0], result[1]];
+}
+// =============================================================================
+// VK Registry PDAs
+// =============================================================================
+/**
+ * Derive VK Registry PDA for a JoinSplit variant
+ *
+ * Seeds: ["vk_registry", &[n_inputs], &[n_outputs]]
+ */
+export async function deriveVkRegistryPDA(nInputs, nOutputs, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: vkRegistrySeeds(nInputs, nOutputs),
+    });
+    return [result[0], result[1]];
+}
+// =============================================================================
+// Deposit Receipt PDAs
+// =============================================================================
+/**
+ * Derive Deposit Receipt PDA.
+ *
+ * Two on-chain schemes exist:
+ * - `complete_deposit` (disc 11, the active direct-vault flow): seeds ["deposit_receipt", txid] —
+ *   call WITHOUT `depositVout`.
+ * - `verify_deposit` (disc 25, OP_RETURN-free flow): seeds ["deposit_receipt", txid, vout(4 LE)] —
+ *   pass `depositVout` so a funding tx with multiple independent deposit outputs gets one receipt
+ *   per output (each creditable once) instead of the first output blocking the rest.
+ */
+export async function deriveDepositReceiptPDA(depositTxid, depositVout, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: depositReceiptSeeds(depositTxid, depositVout),
+    });
+    return [result[0], result[1]];
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Convert bigint commitment to bytes for PDA derivation
+ */
+export function commitmentToBytes(commitment) {
+    const hex = commitment.toString(16).padStart(64, "0");
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}

package/packages/sdk/dist/pool-state.d.ts

@@ -0,0 +1,100 @@
+/**
+ * PoolState account layout and fee arithmetic.
+ *
+ * Both mirror the program (`state/pool.rs`, `utils/fees.rs`), so both belong
+ * here rather than in an app: a consumer that re-derives either gets it right
+ * until the struct grows a field, and then reads the wrong bytes with no error.
+ * TokenConfig and CommitmentTree are already decoded in this package; this
+ * closes the gap for the third account.
+ *
+ * @module pool-state
+ */
+export declare const POOL_STATE_DISCRIMINATOR = 1;
+/** `core::mem::size_of::<PoolState>()`. Fields are appended into `_reserved`,
+ *  so the length is stable across the additions made so far. */
+export declare const POOL_STATE_LEN = 332;
+/** Byte offsets of every field, in declaration order (`#[repr(C)]`). */
+export declare const POOL_STATE_OFFSETS: {
+    readonly discriminator: 0;
+    readonly bump: 1;
+    readonly flags: 2;
+    readonly authority: 4;
+    readonly zkbtcMint: 36;
+    readonly poolVault: 68;
+    readonly depositVault: 100;
+    readonly depositCount: 132;
+    readonly totalMinted: 140;
+    readonly totalBurned: 148;
+    readonly pendingRedemptions: 156;
+    readonly lastUpdate: 164;
+    readonly minDeposit: 172;
+    readonly maxDeposit: 180;
+    readonly totalShielded: 188;
+    readonly serviceFeeBase: 196;
+    readonly feePool: 204;
+    readonly pendingMinDeposit: 212;
+    readonly pendingMaxDeposit: 220;
+    readonly pendingServiceFee: 228;
+    readonly pendingExecuteAfter: 236;
+    readonly depositFeeBps: 244;
+    readonly withdrawalFeeBps: 246;
+    readonly totalBtcHeld: 248;
+    readonly utxoCount: 256;
+    readonly activeTreeIndex: 258;
+    readonly utxoCountHi: 262;
+    readonly auditor: 264;
+    readonly auditorViewingPubkey: 296;
+    readonly nullifierCount: 328;
+};
+/** `flags` bits, from `state/pool.rs`. */
+export declare const POOL_FLAG: {
+    readonly PAUSED: number;
+    readonly PERMISSIONED: number;
+    readonly AUDITOR_FROZEN: number;
+    readonly VK_REGISTRY_FROZEN: number;
+};
+export interface PoolFees {
+    depositFeeBps: number;
+    withdrawalFeeBps: number;
+}
+export interface PoolState extends PoolFees {
+    bump: number;
+    paused: boolean;
+    permissioned: boolean;
+    auditorFrozen: boolean;
+    vkRegistryFrozen: boolean;
+    zkbtcMint: Uint8Array;
+    poolVault: Uint8Array;
+    depositCount: bigint;
+    totalMinted: bigint;
+    totalBurned: bigint;
+    pendingRedemptions: bigint;
+    minDeposit: bigint;
+    maxDeposit: bigint;
+    totalShielded: bigint;
+    serviceFeeBase: bigint;
+    feePool: bigint;
+    totalBtcHeld: bigint;
+    activeTreeIndex: number;
+    auditor: Uint8Array;
+    auditorViewingPubkey: Uint8Array;
+    /** Counts only records created since the counter was added; older pools
+     *  start from zero, so treat it as a floor rather than a total. */
+    nullifierCount: number;
+    /** `utxo_count` widened by `utxo_count_hi`, which was carved out later. */
+    utxoCount: number;
+}
+/** Fees only — the common case, and readable from a truncated account. */
+export declare function parsePoolFees(data: Uint8Array): PoolFees | null;
+/** Full decode. Returns null rather than throwing: callers poll this against
+ *  whatever the RPC hands back, including a pool from an older deployment. */
+export declare function parsePoolState(data: Uint8Array): PoolState | null;
+export declare const BPS_DENOMINATOR = 10000n;
+/**
+ * Compute an on-chain basis-point fee. Unshield withdrawals enforce a one-unit
+ * minimum; deposits use plain floor division. Quoting a fee any other way shows
+ * the user a number the program will not charge.
+ */
+export declare function computeBpsFee(amount: bigint, bps: number, minimumOne?: boolean): bigint;
+/** What share of `gross` a fee represents, in basis points. */
+export declare function feeShareBps(fee: bigint, gross: bigint): number;

package/packages/sdk/dist/pool-state.js

@@ -0,0 +1,126 @@
+/**
+ * PoolState account layout and fee arithmetic.
+ *
+ * Both mirror the program (`state/pool.rs`, `utils/fees.rs`), so both belong
+ * here rather than in an app: a consumer that re-derives either gets it right
+ * until the struct grows a field, and then reads the wrong bytes with no error.
+ * TokenConfig and CommitmentTree are already decoded in this package; this
+ * closes the gap for the third account.
+ *
+ * @module pool-state
+ */
+export const POOL_STATE_DISCRIMINATOR = 0x01;
+/** `core::mem::size_of::<PoolState>()`. Fields are appended into `_reserved`,
+ *  so the length is stable across the additions made so far. */
+export const POOL_STATE_LEN = 332;
+/** Byte offsets of every field, in declaration order (`#[repr(C)]`). */
+export const POOL_STATE_OFFSETS = {
+    discriminator: 0,
+    bump: 1,
+    flags: 2,
+    authority: 4,
+    zkbtcMint: 36,
+    poolVault: 68,
+    depositVault: 100,
+    depositCount: 132,
+    totalMinted: 140,
+    totalBurned: 148,
+    pendingRedemptions: 156,
+    lastUpdate: 164,
+    minDeposit: 172,
+    maxDeposit: 180,
+    totalShielded: 188,
+    serviceFeeBase: 196,
+    feePool: 204,
+    pendingMinDeposit: 212,
+    pendingMaxDeposit: 220,
+    pendingServiceFee: 228,
+    pendingExecuteAfter: 236,
+    depositFeeBps: 244,
+    withdrawalFeeBps: 246,
+    totalBtcHeld: 248,
+    utxoCount: 256,
+    activeTreeIndex: 258,
+    utxoCountHi: 262,
+    auditor: 264,
+    auditorViewingPubkey: 296,
+    nullifierCount: 328,
+};
+/** `flags` bits, from `state/pool.rs`. */
+export const POOL_FLAG = {
+    PAUSED: 1 << 0,
+    PERMISSIONED: 1 << 1,
+    AUDITOR_FROZEN: 1 << 2,
+    VK_REGISTRY_FROZEN: 1 << 3,
+};
+const view = (data) => new DataView(data.buffer, data.byteOffset, data.byteLength);
+/** Fees only — the common case, and readable from a truncated account. */
+export function parsePoolFees(data) {
+    if (data.length < POOL_STATE_OFFSETS.withdrawalFeeBps + 2 ||
+        data[0] !== POOL_STATE_DISCRIMINATOR) {
+        return null;
+    }
+    const v = view(data);
+    return {
+        depositFeeBps: v.getUint16(POOL_STATE_OFFSETS.depositFeeBps, true),
+        withdrawalFeeBps: v.getUint16(POOL_STATE_OFFSETS.withdrawalFeeBps, true),
+    };
+}
+/** Full decode. Returns null rather than throwing: callers poll this against
+ *  whatever the RPC hands back, including a pool from an older deployment. */
+export function parsePoolState(data) {
+    if (data.length < POOL_STATE_LEN || data[0] !== POOL_STATE_DISCRIMINATOR) {
+        return null;
+    }
+    const v = view(data);
+    const o = POOL_STATE_OFFSETS;
+    const flags = data[o.flags];
+    const bytes = (at, len = 32) => data.subarray(at, at + len);
+    return {
+        bump: data[o.bump],
+        paused: (flags & POOL_FLAG.PAUSED) !== 0,
+        permissioned: (flags & POOL_FLAG.PERMISSIONED) !== 0,
+        auditorFrozen: (flags & POOL_FLAG.AUDITOR_FROZEN) !== 0,
+        vkRegistryFrozen: (flags & POOL_FLAG.VK_REGISTRY_FROZEN) !== 0,
+        zkbtcMint: bytes(o.zkbtcMint),
+        poolVault: bytes(o.poolVault),
+        depositCount: v.getBigUint64(o.depositCount, true),
+        totalMinted: v.getBigUint64(o.totalMinted, true),
+        totalBurned: v.getBigUint64(o.totalBurned, true),
+        pendingRedemptions: v.getBigUint64(o.pendingRedemptions, true),
+        minDeposit: v.getBigUint64(o.minDeposit, true),
+        maxDeposit: v.getBigUint64(o.maxDeposit, true),
+        totalShielded: v.getBigUint64(o.totalShielded, true),
+        serviceFeeBase: v.getBigUint64(o.serviceFeeBase, true),
+        feePool: v.getBigUint64(o.feePool, true),
+        depositFeeBps: v.getUint16(o.depositFeeBps, true),
+        withdrawalFeeBps: v.getUint16(o.withdrawalFeeBps, true),
+        totalBtcHeld: v.getBigUint64(o.totalBtcHeld, true),
+        activeTreeIndex: v.getUint32(o.activeTreeIndex, true),
+        utxoCount: v.getUint16(o.utxoCount, true) + (v.getUint16(o.utxoCountHi, true) << 16),
+        auditor: bytes(o.auditor),
+        auditorViewingPubkey: bytes(o.auditorViewingPubkey),
+        nullifierCount: v.getUint32(o.nullifierCount, true),
+    };
+}
+// =============================================================================
+// Fee arithmetic
+// =============================================================================
+export const BPS_DENOMINATOR = 10000n;
+/**
+ * Compute an on-chain basis-point fee. Unshield withdrawals enforce a one-unit
+ * minimum; deposits use plain floor division. Quoting a fee any other way shows
+ * the user a number the program will not charge.
+ */
+export function computeBpsFee(amount, bps, minimumOne = true) {
+    if (amount <= 0n || bps <= 0)
+        return 0n;
+    const fee = (amount * BigInt(bps)) / BPS_DENOMINATOR;
+    return fee > 0n || !minimumOne ? fee : 1n;
+}
+/** What share of `gross` a fee represents, in basis points. */
+export function feeShareBps(fee, gross) {
+    if (fee <= 0n || gross <= 0n)
+        return 0;
+    return Number((fee * BPS_DENOMINATOR) / gross);
+}

package/packages/sdk/dist/poseidon.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Poseidon Hash - BN254 compatible with circom circuits and Solana's sol_poseidon
+ *
+ * Uses poseidon-lite: pure JavaScript, zero dependencies, works in
+ * Browser, Node.js, and React Native (no WASM required).
+ *
+ * UNIFIED MODEL:
+ * - Commitment = Poseidon(pub_key_x, amount)
+ * - Nullifier = Poseidon(priv_key, leaf_index)
+ * - Nullifier Hash = Poseidon(nullifier)
+ */
+/**
+ * Initialize poseidon (no-op — poseidon-lite needs no initialization)
+ * Kept for backward API compatibility.
+ */
+export declare function initPoseidon(): Promise<void>;
+/**
+ * Whether Poseidon can hash right now.
+ *
+ * Always true: poseidon-lite is pure synchronous JS with nothing to load, so `initPoseidon()`
+ * exists only so callers written against a WASM-backed hasher keep working. Kept honest rather
+ * than tracking a flag — the previous version lived in note.ts over its own state and reported
+ * false no matter what you called.
+ */
+export declare function isPoseidonReady(): boolean;
+/**
+ * Synchronous Poseidon hash (no initialization required with poseidon-lite)
+ */
+export declare function poseidonHashSync(inputs: bigint[]): bigint;
+export declare const BN254_SCALAR_FIELD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+export declare function computeUnifiedCommitmentSync(pubKeyX: bigint, amount: bigint): bigint;
+export declare function computeNullifierSync(privKey: bigint, leafIndex: bigint): bigint;
+export declare function hashNullifierSync(nullifier: bigint): bigint;
+export declare function computeMPKSync(pkX: bigint, pkY: bigint, nullifyingKey: bigint): bigint;
+export declare function computeNPKSync(mpk: bigint, random: bigint): bigint;
+export declare function computeJoinSplitCommitmentSync(npk: bigint, token: bigint, amount: bigint): bigint;
+export declare function computeJoinSplitNullifierSync(nullifyingKey: bigint, leafIndex: bigint): bigint;
+/**
+ * Reduce a 32-byte big-endian value to BN254 scalar field (mod p).
+ * Must match on-chain reduce_to_field_exact in crypto.rs.
+ */
+export declare function reduceToField(bytes: Uint8Array): bigint;
+/**
+ * Compute token_id from mint address: Poseidon(reduce_to_field(mint), 0)
+ *
+ * Must match on-chain compute_token_id in crypto.rs which uses
+ * poseidon2_hash(reduce_to_field_exact(mint), [0u8; 32]).
+ */
+export declare function computeTokenId(mintBytes: Uint8Array): bigint;
+/**
+ * Convenience: compute token_id from a Solana address string
+ */
+export declare function computeTokenIdFromAddress(mintAddress: string): bigint;