@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/note.js

@@ -0,0 +1,483 @@
+/**
+ * Note (shielded commitment) utilities for UTXOpia
+ *
+ * A Note represents a shielded deposit with:
+ * - nullifier: Random secret for spending
+ * - secret: Additional entropy
+ * - amount: Value in satoshis
+ *
+ * Hash values (commitment, nullifierHash) are computed by circom circuits
+ * using Poseidon. This SDK stores the raw secrets and optionally
+ * accepts pre-computed hash values.
+ */
+import { randomFieldElement, bigintToBytes, sha256Hash, bytesToBigint, BN254_FIELD_PRIME, babyJubMul, BABYJUB_BASE8 } from "./crypto";
+import { computeUnifiedCommitmentSync, computeNullifierSync, hashNullifierSync, computeJoinSplitCommitmentSync, computeNPKSync, computeJoinSplitNullifierSync } from "./poseidon";
+/**
+ * Generate a new note with random nullifier and secret
+ *
+ * Note: Hash values are NOT computed here. They will be computed
+ * by the circom circuits during proof generation.
+ *
+ * @param amountSats - Amount in satoshis
+ * @returns Note with secrets (hashes are 0n until circuit execution)
+ */
+export function generateNote(amountSats) {
+    const nullifier = randomFieldElement();
+    const secret = randomFieldElement();
+    return createNoteFromSecrets(nullifier, secret, amountSats);
+}
+/**
+ * Create a note from known secrets
+ *
+ * @param nullifier - Nullifier field element
+ * @param secret - Secret field element
+ * @param amountSats - Amount in satoshis
+ * @param commitment - Optional pre-computed commitment (from circuit)
+ * @param nullifierHash - Optional pre-computed nullifier hash (from circuit)
+ * @returns Note structure
+ */
+export function createNoteFromSecrets(nullifier, secret, amountSats, commitment, nullifierHash) {
+    // Computed values are 0n until provided from circuit outputs
+    const comm = commitment ?? 0n;
+    const nullHash = nullifierHash ?? 0n;
+    const noteHash = 0n; // Intermediate hash not typically exposed
+    return {
+        amount: amountSats,
+        nullifier,
+        secret,
+        note: noteHash,
+        commitment: comm,
+        nullifierHash: nullHash,
+        nullifierBytes: bigintToBytes(nullifier),
+        secretBytes: bigintToBytes(secret),
+        commitmentBytes: bigintToBytes(comm),
+        nullifierHashBytes: bigintToBytes(nullHash),
+    };
+}
+/**
+ * Update note with computed hash values from circom circuit execution
+ *
+ * @param note - Note to update
+ * @param commitment - Commitment from circuit output
+ * @param nullifierHash - Nullifier hash from circuit output
+ * @returns Updated note
+ */
+export function updateNoteWithHashes(note, commitment, nullifierHash) {
+    return {
+        ...note,
+        commitment,
+        nullifierHash,
+        commitmentBytes: bigintToBytes(commitment),
+        nullifierHashBytes: bigintToBytes(nullifierHash),
+    };
+}
+/**
+ * Serialize a note for storage or transmission
+ *
+ * Only stores the essential data (amount, nullifier, secret).
+ * Optionally includes pre-computed hash values.
+ */
+export function serializeNote(note) {
+    const serialized = {
+        amount: note.amount.toString(),
+        nullifier: note.nullifier.toString(),
+        secret: note.secret.toString(),
+    };
+    // Include computed values if available
+    if (note.commitment !== 0n) {
+        serialized.commitment = note.commitment.toString();
+    }
+    if (note.nullifierHash !== 0n) {
+        serialized.nullifierHash = note.nullifierHash.toString();
+    }
+    return serialized;
+}
+/**
+ * Deserialize and restore a note from stored data
+ */
+export function deserializeNote(data) {
+    const amount = BigInt(data.amount);
+    const nullifier = BigInt(data.nullifier);
+    const secret = BigInt(data.secret);
+    const commitment = data.commitment ? BigInt(data.commitment) : undefined;
+    const nullifierHash = data.nullifierHash
+        ? BigInt(data.nullifierHash)
+        : undefined;
+    return createNoteFromSecrets(nullifier, secret, amount, commitment, nullifierHash);
+}
+/**
+ * Format satoshis as BTC string
+ */
+export function formatBtc(sats) {
+    const btc = Number(sats) / 100000000;
+    return btc.toFixed(8) + " BTC";
+}
+/**
+ * Parse BTC string to satoshis
+ */
+export function parseBtc(btcString) {
+    const btc = parseFloat(btcString.replace(" BTC", ""));
+    return BigInt(Math.round(btc * 100000000));
+}
+/**
+ * Check if a note has computed hash values
+ */
+export function noteHasComputedHashes(note) {
+    return note.commitment !== 0n && note.nullifierHash !== 0n;
+}
+// ============================================================================
+// Note Commitment/Nullifier Helpers
+// ============================================================================
+/**
+ * Get the public key X coordinate from a note's nullifier (used as private key)
+ *
+ * In the unified model: pubKey = nullifier * BASE8 (on Baby Jubjub curve)
+ * Returns pubKey.x for commitment computation
+ */
+export function getNotePublicKeyX(note) {
+    const pubKey = babyJubMul(note.nullifier, BABYJUB_BASE8);
+    return pubKey.x;
+}
+/**
+ * Compute the commitment for a note
+ *
+ * commitment = Poseidon(pubKeyX, amount)
+ * where pubKeyX = (nullifier * G).x
+ *
+ * Returns the note with commitment fields populated
+ */
+export function computeNoteCommitment(note) {
+    const pubKeyX = getNotePublicKeyX(note);
+    const commitment = computeUnifiedCommitmentSync(pubKeyX, note.amount);
+    const commitmentBytes = bigintToBytes(commitment);
+    return {
+        ...note,
+        commitment,
+        commitmentBytes,
+    };
+}
+/**
+ * Compute the nullifier and nullifier hash for a note at a given leaf index
+ *
+ * nullifier = Poseidon(privKey, leafIndex)
+ * nullifierHash = Poseidon(nullifier)
+ *
+ * @returns Object with computed nullifier values
+ */
+export function computeNoteNullifier(note, leafIndex) {
+    const nullifier = computeNullifierSync(note.nullifier, leafIndex);
+    const nullifierHash = hashNullifierSync(nullifier);
+    const nullifierHashBytes = bigintToBytes(nullifierHash);
+    return {
+        nullifier,
+        nullifierHash,
+        nullifierHashBytes,
+    };
+}
+// ============================================================================
+// Deterministic Note Derivation (HD-style)
+// ============================================================================
+/**
+ * Derive a note deterministically from a seed phrase/name and index.
+ *
+ * This allows recovery of all notes from just the seed + index.
+ * Similar to HD wallets in Bitcoin.
+ *
+ * The seed is first hashed to create a 32-byte master key, then
+ * nullifier and secret are derived from that master key.
+ *
+ * @param seed - Seed phrase, name, or password (any string)
+ * @param index - Note index (0, 1, 2, ...)
+ * @param amountSats - Amount in satoshis
+ * @returns Note with deterministically derived secrets
+ *
+ * @example
+ * ```typescript
+ * // Derive notes from a name
+ * const note0 = deriveNote("albertgogogo", 0, 100_000n);
+ * const note1 = deriveNote("albertgogogo", 1, 50_000n);
+ *
+ * // Later: recover the same notes
+ * const recovered = deriveNote("albertgogogo", 0, 100_000n);
+ * // recovered.nullifier === note0.nullifier ✓
+ * ```
+ */
+export function deriveNote(seed, index, amountSats) {
+    // Step 1: Hash seed to get 32-byte master key (normalizes any input)
+    const master = deriveMasterKey(seed);
+    // Step 2: Derive nullifier and secret from master + index
+    const nullifier = deriveFromMaster(master, index, 0); // 0 = nullifier domain
+    const secret = deriveFromMaster(master, index, 1); // 1 = secret domain
+    return createNoteFromSecrets(nullifier, secret, amountSats);
+}
+/**
+ * Derive master key from seed (32 bytes)
+ *
+ * master = SHA256(seed)
+ *
+ * You can cache this and use deriveNoteFromMaster() for efficiency.
+ */
+export function deriveMasterKey(seed) {
+    const encoder = new TextEncoder();
+    const seedBytes = encoder.encode(seed);
+    return sha256Hash(seedBytes);
+}
+/**
+ * Derive a note from a pre-computed master key
+ *
+ * More efficient if deriving many notes from the same seed.
+ *
+ * @example
+ * ```typescript
+ * const master = deriveMasterKey("albertgogogo");
+ * const note0 = deriveNoteFromMaster(master, 0, 100_000n);
+ * const note1 = deriveNoteFromMaster(master, 1, 50_000n);
+ * ```
+ */
+export function deriveNoteFromMaster(master, index, amountSats) {
+    const nullifier = deriveFromMaster(master, index, 0);
+    const secret = deriveFromMaster(master, index, 1);
+    return createNoteFromSecrets(nullifier, secret, amountSats);
+}
+/**
+ * Derive field element from master key + index + domain
+ *
+ * result = SHA256(master || index || domain) mod BN254_PRIME
+ *
+ * @param master - 32-byte master key
+ * @param index - Note index
+ * @param domain - 0 for nullifier, 1 for secret
+ */
+function deriveFromMaster(master, index, domain) {
+    // Build input: master (32) || index (4) || domain (1) = 37 bytes
+    const input = new Uint8Array(37);
+    input.set(master, 0);
+    // Index as 4 bytes little-endian
+    const view = new DataView(input.buffer);
+    view.setUint32(32, index, true);
+    // Domain as 1 byte
+    input[36] = domain;
+    // Hash and reduce to field
+    const hash = sha256Hash(input);
+    return bytesToBigint(hash) % BN254_FIELD_PRIME;
+}
+/**
+ * Derive multiple notes at once from a seed
+ *
+ * More efficient than calling deriveNote() multiple times
+ * because master key is computed only once.
+ *
+ * @param seed - Seed phrase
+ * @param amounts - Array of amounts for each note
+ * @param startIndex - Starting index (default 0)
+ * @returns Array of derived notes
+ *
+ * @example
+ * ```typescript
+ * // Create a wallet with 3 notes
+ * const notes = deriveNotes("albertgogogo", [100_000n, 50_000n, 25_000n]);
+ * ```
+ */
+export function deriveNotes(seed, amounts, startIndex = 0) {
+    // Compute master once, derive all notes from it
+    const master = deriveMasterKey(seed);
+    return amounts.map((amount, i) => deriveNoteFromMaster(master, startIndex + i, amount));
+}
+/**
+ * Check the strength of a seed phrase
+ *
+ * Returns estimated bits of entropy.
+ * Recommended: >= 80 bits for moderate security, >= 128 bits for high security
+ */
+export function estimateSeedStrength(seed) {
+    // Very rough entropy estimation
+    const length = seed.length;
+    const hasLower = /[a-z]/.test(seed);
+    const hasUpper = /[A-Z]/.test(seed);
+    const hasDigit = /[0-9]/.test(seed);
+    const hasSpecial = /[^a-zA-Z0-9]/.test(seed);
+    let charsetSize = 0;
+    if (hasLower)
+        charsetSize += 26;
+    if (hasUpper)
+        charsetSize += 26;
+    if (hasDigit)
+        charsetSize += 10;
+    if (hasSpecial)
+        charsetSize += 32;
+    // Entropy = length * log2(charsetSize)
+    const bits = Math.floor(length * Math.log2(charsetSize || 1));
+    let strength;
+    let warning;
+    if (bits < 40) {
+        strength = "weak";
+        warning = "DANGER: This seed can be easily brute-forced. Use a longer passphrase!";
+    }
+    else if (bits < 80) {
+        strength = "moderate";
+        warning = "Consider using a longer passphrase for better security.";
+    }
+    else if (bits < 128) {
+        strength = "strong";
+    }
+    else {
+        strength = "very_strong";
+    }
+    return { bits, strength, warning };
+}
+// Poseidon initialization state (for API compatibility)
+/**
+ * Create a simple note (alias for generateNote but returns NoteData)
+ *
+ * Use this to generate note data for circom circuit inputs.
+ *
+ * @param amount - Amount in satoshis
+ * @returns NoteData with nullifier, secret, and amount
+ */
+export function createNote(amount) {
+    const note = generateNote(amount);
+    return {
+        nullifier: note.nullifier,
+        secret: note.secret,
+        amount: note.amount,
+    };
+}
+// initPoseidon/isPoseidonReady used to live here as well, over a flag local to this module. The
+// barrel exported initPoseidon from poseidon.ts and isPoseidonReady from here, so they read
+// different state: `await initPoseidon(); isPoseidonReady()` returned false forever. Both now
+// belong to poseidon.ts, which owns the actual hasher.
+/**
+ * Prepare withdrawal - creates change note for remaining balance
+ *
+ * PRIVACY: All withdrawals are indistinguishable on-chain.
+ * Change amount can be >= 0, and the commitment always looks random.
+ *
+ * @param inputNote - Note being spent
+ * @param withdrawAmount - Amount to withdraw
+ * @returns Change note with remaining balance (can be 0)
+ */
+export function prepareWithdrawal(inputNote, withdrawAmount) {
+    if (withdrawAmount <= 0n) {
+        throw new Error("Withdraw amount must be positive");
+    }
+    if (withdrawAmount > inputNote.amount) {
+        throw new Error("Withdraw amount exceeds note balance");
+    }
+    const changeAmount = inputNote.amount - withdrawAmount;
+    const changeNote = createNote(changeAmount);
+    return { changeNote, changeAmount };
+}
+/**
+ * Create a stealth note from scanned announcement data
+ *
+ * @param amount - Decrypted amount
+ * @param random - Decrypted random value
+ * @param ephemeralSpendPub - Sender's ephemeral pubkey
+ * @param leafIndex - Merkle tree leaf index
+ * @returns StealthNote structure
+ */
+export function createStealthNote(amount, random, ephemeralSpendPub, leafIndex) {
+    return {
+        amount,
+        random,
+        ephemeralSpendPubX: ephemeralSpendPub.x,
+        ephemeralSpendPubY: ephemeralSpendPub.y,
+        leafIndex,
+        notePubKey: 0n, // Computed in circuit
+        commitment: 0n, // Computed in circuit
+        randomBytes: bigintToBytes(random),
+        commitmentBytes: new Uint8Array(32),
+    };
+}
+/**
+ * Update stealth note with computed values from circuit
+ */
+export function updateStealthNoteWithHashes(note, notePubKey, commitment) {
+    return {
+        ...note,
+        notePubKey,
+        commitment,
+        commitmentBytes: bigintToBytes(commitment),
+    };
+}
+/**
+ * Serialize stealth note for storage
+ */
+export function serializeStealthNote(note) {
+    const serialized = {
+        amount: note.amount.toString(),
+        random: note.random.toString(),
+        ephemeralSpendPubX: note.ephemeralSpendPubX.toString(),
+        ephemeralSpendPubY: note.ephemeralSpendPubY.toString(),
+        leafIndex: note.leafIndex,
+    };
+    if (note.notePubKey !== 0n) {
+        serialized.notePubKey = note.notePubKey.toString();
+    }
+    if (note.commitment !== 0n) {
+        serialized.commitment = note.commitment.toString();
+    }
+    return serialized;
+}
+/**
+ * Deserialize stealth note from storage
+ */
+export function deserializeStealthNote(data) {
+    const note = createStealthNote(BigInt(data.amount), BigInt(data.random), {
+        x: BigInt(data.ephemeralSpendPubX),
+        y: BigInt(data.ephemeralSpendPubY),
+    }, data.leafIndex);
+    if (data.notePubKey && data.commitment) {
+        return updateStealthNoteWithHashes(note, BigInt(data.notePubKey), BigInt(data.commitment));
+    }
+    return note;
+}
+/**
+ * Check if stealth note has computed hashes
+ */
+export function stealthNoteHasComputedHashes(note) {
+    return note.notePubKey !== 0n && note.commitment !== 0n;
+}
+/**
+ * Create a JoinSplit note from key components
+ *
+ * @param tokenId - Token identifier from computeTokenId(mintBytes)
+ */
+export function createJoinSplitNote(mpk, random, amount, tokenId, leafIndex = -1) {
+    const npk = computeNPKSync(mpk, random);
+    const commitment = computeJoinSplitCommitmentSync(npk, tokenId, amount);
+    return {
+        npk,
+        token: tokenId,
+        amount,
+        random,
+        leafIndex,
+        commitment,
+    };
+}
+/**
+ * Compute nullifier for a JoinSplit note
+ */
+export function computeJoinSplitNoteNullifier(nullifyingKey, leafIndex) {
+    return computeJoinSplitNullifierSync(nullifyingKey, BigInt(leafIndex));
+}
+export function serializeJoinSplitNote(note) {
+    return {
+        npk: note.npk.toString(),
+        token: note.token.toString(),
+        amount: note.amount.toString(),
+        random: note.random.toString(),
+        leafIndex: note.leafIndex,
+        commitment: note.commitment.toString(),
+    };
+}
+export function deserializeJoinSplitNote(data) {
+    return {
+        npk: BigInt(data.npk),
+        token: BigInt(data.token),
+        amount: BigInt(data.amount),
+        random: BigInt(data.random),
+        leafIndex: data.leafIndex,
+        commitment: BigInt(data.commitment),
+    };
+}

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

@@ -0,0 +1,160 @@
+/**
+ * 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 { type Address } from "@solana/kit";
+export declare const PDA_SEEDS: {
+    readonly POOL_STATE: "pool_state";
+    readonly COMMITMENT_TREE: "commitment_tree";
+    readonly LIGHT_CLIENT: "btc_light_client";
+    readonly BLOCK_HEADER: "block";
+    readonly HEIGHT_INDEX: "height_index";
+    readonly VERIFIED_TX: "verified_tx";
+    readonly DEPOSIT: "deposit";
+    readonly NULLIFIER: "nullifier";
+    readonly POLICY_APPROVAL: "policy_approval";
+    readonly EXIT_DESTINATION: "exit_destination";
+    readonly VK_REGISTRY: "vk_registry";
+    readonly TOKEN_CONFIG: "token_config";
+    readonly POOL_CONFIG: "pool_config";
+};
+/** `["pool_state", pool_id]` — pool_id is the pool's zkBTC mint. */
+export declare function poolStateSeeds(poolId: Address | Uint8Array): Uint8Array[];
+/** `["commitment_tree", pool_state, tree_index_le]`. */
+export declare function commitmentTreeSeeds(poolState: Address | Uint8Array, treeIndex?: number): Uint8Array[];
+/** `["token_config", pool_state, mint]`. */
+export declare function tokenConfigSeeds(poolState: Address | Uint8Array, mint: Address | Uint8Array): Uint8Array[];
+/** `["pool_config", pool_state]`. */
+export declare function poolConfigSeeds(poolState: Address | Uint8Array): Uint8Array[];
+/** `["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 declare function nullifierRecordSeeds(nullifierHash: Uint8Array, poolState: Address | Uint8Array, treeIndex?: number): Uint8Array[];
+/** `["redemption", pool_state, user, nonce_le]` (`redeem.rs`). */
+export declare function redemptionRequestSeeds(poolState: Address | Uint8Array, userPubkey: Address | Uint8Array, nonce: bigint): Uint8Array[];
+/** `["vk_registry", [n_inputs], [n_outputs]]`. */
+export declare function vkRegistrySeeds(nInputs: number, nOutputs: number): Uint8Array[];
+/** `["deposit_receipt", txid]`, or `[..., vout_le]` for the OP_RETURN-free
+ *  `verify_deposit` flow. See deriveDepositReceiptPDA for which is which. */
+export declare function depositReceiptSeeds(depositTxid: Uint8Array, depositVout?: number): Uint8Array[];
+/** `["policy_approval", pool_state, request_hash, nonce]`. */
+export declare function policyApprovalSeeds(poolState: Address | Uint8Array, requestHash: Uint8Array, nonce: Uint8Array): Uint8Array[];
+/** `["exit_destination", pool_state, [kind], key]`. */
+export declare function exitDestinationSeeds(poolState: Address | Uint8Array, kind: number, key: Uint8Array): Uint8Array[];
+/** `["btc_light_client"]`. */
+export declare function lightClientSeeds(): Uint8Array[];
+/** `["block", block_hash]`. */
+export declare function blockHeaderSeeds(blockHash: Uint8Array): Uint8Array[];
+/** `["height_index", height_le(8)]`. */
+export declare function heightIndexSeeds(height: number | bigint): Uint8Array[];
+/** `["verified_tx", block_hash, txid]`. */
+export declare function verifiedTransactionSeeds(blockHash: Uint8Array, txid: Uint8Array): Uint8Array[];
+/**
+ * Derive Pool State PDA
+ */
+export declare function derivePoolStatePDA(poolId: Address | Uint8Array, programId?: Address): Promise<[Address, number]>;
+/**
+ * Derive Commitment Tree PDA
+ *
+ * @param treeIndex - Tree rotation index (default 0).
+ */
+export declare function deriveCommitmentTreePDA(poolState: Address | Uint8Array, programId?: Address, treeIndex?: number): Promise<[Address, number]>;
+/**
+ * Derive TokenConfig PDA for a specific mint
+ * Seeds: ["token_config", mint_pubkey_bytes]
+ */
+export declare function deriveTokenConfigPDA(poolState: Address | Uint8Array, mintPubkey: Uint8Array, programId?: Address): Promise<[Address, number]>;
+/** Derive ["pool_config", pool_state]. */
+export declare function derivePoolConfigPDA(poolState: Address | Uint8Array, programId?: Address): Promise<[Address, number]>;
+/**
+ * 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 declare function deriveNullifierRecordPDA(nullifierHash: Uint8Array, poolState: Address | Uint8Array, treeIndex?: number, programId?: Address): Promise<[Address, number]>;
+/**
+ * Derive one-time PolicyApproval PDA.
+ * Seeds: ["policy_approval", pool_state, request_hash, nonce]
+ */
+export declare function derivePolicyApprovalPDA(poolState: Address | Uint8Array, requestHash: Uint8Array, nonce: Uint8Array, programId?: Address): Promise<[Address, number]>;
+/** 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 declare const EXIT_KIND_SOLANA_OWNER = 0;
+export declare 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 declare function deriveExitDestinationPDA(poolState: Address | Uint8Array, kind: number, key: Uint8Array, programId: Address): Promise<[Address, number]>;
+/**
+ * Derive BTC Light Client PDA
+ */
+export declare function deriveLightClientPDA(programId?: Address): Promise<[Address, number]>;
+/**
+ * Derive Block Header PDA (hash-based)
+ * Seeds: ["block", blockHash(32)]
+ */
+export declare function deriveBlockHeaderPDA(blockHash: Uint8Array, programId?: Address): Promise<[Address, number]>;
+/**
+ * Derive HeightIndex PDA
+ * Seeds: ["height_index", height_le_bytes(8)]
+ */
+export declare function deriveHeightIndexPDA(height: number | bigint, programId?: Address): Promise<[Address, number]>;
+/**
+ * Derive VerifiedTransaction PDA (btc-light-client)
+ *
+ * Seeds: ["verified_tx", blockHash(32), txid(32)]
+ */
+export declare function deriveVerifiedTransactionPDA(blockHash: Uint8Array, txid: Uint8Array, programId?: Address): Promise<[Address, number]>;
+/**
+ * Derive Redemption Request PDA
+ *
+ * Seeds: ["redemption", pool_state, user_pubkey(32), nonce_le(8)]
+ */
+export declare function deriveRedemptionRequestPDA(poolState: Address | Uint8Array, userPubkey: Uint8Array, nonce: bigint, programId?: Address): Promise<[Address, number]>;
+/**
+ * Derive VK Registry PDA for a JoinSplit variant
+ *
+ * Seeds: ["vk_registry", &[n_inputs], &[n_outputs]]
+ */
+export declare function deriveVkRegistryPDA(nInputs: number, nOutputs: number, programId?: Address): Promise<[Address, number]>;
+/**
+ * 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 declare function deriveDepositReceiptPDA(depositTxid: Uint8Array, depositVout?: number, programId?: Address): Promise<[Address, number]>;
+/**
+ * Convert bigint commitment to bytes for PDA derivation
+ */
+export declare function commitmentToBytes(commitment: bigint): Uint8Array;