@utxopia/sdk 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -1,170 +1,276 @@
-# UTXOpia SDK
+# @utxopia/sdk
 
-TypeScript client for [UTXOpia](https://utxopia.com) — a privacy-preserving Bitcoin-to-Solana
-bridge. Deposits arrive as commitments in a Merkle tree, transfers move between commitments with
-Groth16 JoinSplit proofs, and an amount only becomes public when someone withdraws.
+TypeScript SDK for interacting with the UTXOpia protocol - a privacy-preserving Bitcoin-to-Solana bridge using Zero-Knowledge Proofs.
 
-> **Alpha.** `0.1.0-alpha.1`. The protocol has not been deployed to mainnet — do not point this at
-> funds you cannot lose.
->
-> **The export surface is not a contract yet.** Roughly 430 things are exported; about a third are
-> exercised by the reference apps, and the rest is protocol surface nobody has needed yet or
-> helpers that were never deliberately made public. Being pre-1.0 is what makes that survivable:
-> the surface will be narrowed to the workflows below before 1.0, and anything outside them may
-> disappear in a minor release. Build against what `docs/API-MAP.md` marks as used; if you need
-> something else, open an issue so it gets kept on purpose rather than by accident.
-
-## Install
+## Installation
 
 ```bash
 bun add @utxopia/sdk
+# or
+npm install @utxopia/sdk
 ```
 
-Installing from git instead? Pin a commit, never a branch. A floating `#main` means two apps that
-installed a week apart disagree about the note format, and the failure surfaces as a proof that
-will not verify rather than as an install error:
+## Quick Start
+
+```typescript
+import {
+  deriveKeysFromWallet,
+  createStealthDeposit,
+  scanAnnouncements,
+  resolveSnsName,
+} from '@utxopia/sdk';
 
-```jsonc
-// package.json
-"@utxopia/sdk": "github:UTXOpia/utxopia-sdk#<full-commit-sha>"
+// 1. Derive keys from wallet
+const keys = await deriveKeysFromWallet(walletAdapter);
+
+// 2. Look up recipient by .utxopia.sol name
+const recipient = await resolveSnsName(connection, 'alice');
+
+// 3. Create stealth deposit
+const deposit = await createStealthDeposit(recipient, 100000n);
+
+// 4. Scan for incoming deposits
+const notes = await scanAnnouncements(keys, announcements);
 ```
 
-`snarkjs` and `react` are optional peers — install `snarkjs` only if you generate proofs, `react`
-only if you use the hooks.
+## Core Features
+
+### Key Derivation
+
+Derive spending and viewing keys from a Solana wallet signature (RAILGUN-style):
 
-## What the pieces are
+```typescript
+import { deriveKeysFromWallet, type UTXOpiaKeys } from '@utxopia/sdk';
+
+const keys: UTXOpiaKeys = await deriveKeysFromWallet(walletAdapter);
+// keys.spendingPubKey - for receiving funds
+// keys.viewingPubKey  - for scanning deposits
+// keys.spendingPrivKey - for claiming (keep secret!)
+// keys.viewingPrivKey  - for scanning (can delegate)
+```
 
-| Concept | What it means here |
-|---|---|
-| **Note** | A commitment `Poseidon(npk, token, amount)` in the tree. Owning one means knowing the key behind `npk`. |
-| **Nullifier** | `Poseidon(nullifyingKey, leafIndex)`. Published on spend so a note cannot be spent twice; it reveals nothing about which note it was. |
-| **Stealth address** | A recipient publishes a meta-address; each sender derives a fresh one-time `npk` from it, so payments to the same person are unlinkable on-chain. |
-| **JoinSplit(N,M)** | One proof spends N notes and creates M. Shapes with `N + M ≤ 10` are accepted on-chain, 45 in total. |
-| **Viewing key** | Decrypts incoming announcements. Separate from the spending key, so scanning can be delegated. |
+### Stealth Addresses (EIP-5564/DKSAP Pattern)
 
-## Quick start
+Create private deposits that only the recipient can detect and claim:
 
 ```typescript
 import {
-  deriveKeysFromWallet,
-  resolveSnsName,
   createStealthDeposit,
   scanAnnouncements,
-} from "@utxopia/sdk";
+  prepareClaimInputs,
+} from '@utxopia/sdk';
 
-// Keys come from a wallet signature over a fixed message — nothing to store.
-const keys = await deriveKeysFromWallet(walletAdapter);
+// Sender: Create stealth deposit
+const deposit = await createStealthDeposit(recipientMeta, amountSats);
+// deposit.ephemeralPub - publish on-chain
+// deposit.commitment   - add to Merkle tree
+// deposit.amountSats   - verified BTC amount
 
-// Recipients can be a .utxopia.sol name instead of a raw meta-address.
-const recipient = await resolveSnsName(connection, "alice");
+// Recipient: Scan for deposits
+const notes = await scanAnnouncements(keys, onChainAnnouncements);
 
-const deposit = await createStealthDeposit(recipient, 100_000n);
+// Recipient: Prepare claim inputs for ZK proof
+const claimInputs = await prepareClaimInputs(keys, note, merkleProof);
+```
 
-// Scanning is a local trial-decrypt of every announcement — there is no
-// "my transactions" endpoint to ask, by design.
-const notes = await scanAnnouncements(keys, announcements);
+### Note Generation
+
+Create and manage shielded notes:
+
+```typescript
+import {
+  generateNote,
+  deriveNote,
+  createClaimLink,
+  parseClaimLink,
+} from '@utxopia/sdk';
+
+// Generate random note
+const note = generateNote(100000n);
+
+// Derive deterministic note from seed
+const note = deriveNote('my-secret-phrase', 0, 100000n);
+
+// Create shareable claim link
+const link = createClaimLink(note);
+
+// Parse claim link
+const parsed = parseClaimLink(link);
 ```
 
-`docs/API-MAP.md` lists every export grouped by what you are building — config, keys, PDAs,
-notes, stealth, Bitcoin, proving, instructions, chain reads, disclosure — and marks which ones
-the reference apps actually use. `packages/sdk/README.md` covers each area in depth;
-`packages/sdk/docs/SDK.md` has the full type reference.
+### Taproot Address Derivation
 
-## Entry points
+Generate BTC deposit addresses:
 
 ```typescript
-import { … } from "@utxopia/sdk";                 // everything below is re-exported here
-import { … } from "@utxopia/sdk/prover/web";      // browser proving (snarkjs + WebAssembly)
-import { … } from "@utxopia/sdk/prover/mobile";   // React Native proving
-import { … } from "@utxopia/sdk/bitcoin";         // taproot, Ika custody
-import { … } from "@utxopia/sdk/stealth";         // stealth addresses on their own
-import { … } from "@utxopia/sdk/btc-client";      // Esplora client, OP_RETURN encoding
+import { deriveTaprootAddress, verifyTaprootAddress } from '@utxopia/sdk';
+
+// Use the configured FROST/Ika custody public key; there is no safe default.
+const custodyInternalKey = getConfiguredCustodyInternalKey();
+const { address } = deriveTaprootAddress(
+  commitment,
+  'testnet',
+  custodyInternalKey,
+);
+
+// Verify address matches commitment
+const isValid = verifyTaprootAddress(address, commitment, custodyInternalKey);
 ```
 
-The root export is the whole surface. The subpaths exist so a bundle that only needs, say,
-Esplora does not pull in the prover.
+### Merkle Proofs
+
+Work with the on-chain commitment tree:
+
+```typescript
+import {
+  createMerkleProof,
+  proofToNoirFormat,
+  TREE_DEPTH,
+} from '@utxopia/sdk';
+
+const proof = createMerkleProof(leaves, leafIndex);
+const noirProof = proofToNoirFormat(proof);
+```
 
-## Naming
+## API Reference
 
-The prefix tells you what a call costs, so you can read an import list without opening anything:
+### Stealth Module
 
-| prefix | meaning |
-|---|---|
-| `derive*PDA` | pure address math, synchronous |
-| `fetch*` | hits the network — always async |
-| `get*` | reads local or already-fetched state — synchronous |
-| `parse*` | bytes in, typed object out; no IO |
-| `build*InstructionData` / `build*Instruction` | encode instruction data / assemble the full instruction |
-| `compute*Sync` | Poseidon hashes. Only the `Sync` form exists — poseidon-lite has nothing to await |
-| `encode`/`decode`, `pack`/`unpack`, `serialize`/`deserialize` | symmetric pairs, always both directions |
+| Function | Description |
+|----------|-------------|
+| `createStealthDeposit(recipient, amount)` | Create stealth deposit for recipient |
+| `scanAnnouncements(keys, announcements)` | Scan for deposits using viewing key |
+| `prepareClaimInputs(keys, note, proof)` | Prepare inputs for ZK claim proof |
+| `scanUnifiedNotes(keys, announcements)` | Scan announcement events for owned notes |
+| `resolveSnsName(conn, name)` | Look up .utxopia.sol name to stealth address |
 
-`PDA` is spelled in caps. Seven MagicBlock helpers used to say `Pda` and two RPC calls were named
-`get*`; they were renamed before the first publish, while doing so was still free.
+### Key Derivation Module
 
-## Proving
+| Function | Description |
+|----------|-------------|
+| `deriveKeysFromWallet(wallet)` | Derive keys from wallet signature |
+| `deriveKeysFromSignature(sig)` | Derive keys from raw signature |
+| `deriveKeysFromSeed(seed)` | Derive keys from seed bytes |
+| `createStealthMetaAddress(keys)` | Create stealth meta-address |
+| `createDelegatedViewKey(keys, perms, expiry)` | Create delegated view key |
 
-Proof generation needs circuit artifacts — a `.wasm` witness generator and a `.zkey` — which are
-too large to ship in the package. Point the prover at a host serving them:
+### Constants
 
 ```typescript
-import { setCircuitPath, generateJoinSplitProof } from "@utxopia/sdk/prover/web";
+// Program IDs
+UTXOPIA_PROGRAM_ID        // Main UTXOpia program (devnet)
+CHADBUFFER_PROGRAM_ID    // ChadBuffer for SPV proofs
+
+// Merkle Tree
+TREE_DEPTH              // 20
+MAX_LEAVES              // 2^20
+ZERO_VALUE              // Empty leaf value
 
-setCircuitPath("https://circuit.utxopia.com/circuits/v2/groth16");
-const proof = await generateJoinSplitProof(inputs);
 ```
 
-**Pin the artifacts you are willing to prove with.** The `.wasm` is the witness generator: it
-receives every private input a JoinSplit has — spending key, nullifying key, note randomness,
-amounts, the full Merkle path — in the clear. It arrives over plain `fetch`, where subresource
-integrity does not apply, and CDNs serve it `immutable, max-age=31536000`, so a substituted file
-survives in browser and edge caches long after the origin is cleaned. Proofs built from a poisoned
-generator still verify, so nothing fails and no user notices.
+## Types
 
-```typescript
-import { setCircuitArtifactDigests } from "@utxopia/sdk/prover/web";
-import digests from "./circuit-manifest.json"; // generated by your build, committed
+### UTXOpiaKeys
 
-setCircuitArtifactDigests(digests.artifacts);
+```typescript
+interface UTXOpiaKeys {
+  spendingPubKey: BabyJubPoint;
+  spendingPrivKey: bigint;
+  viewingPubKey: Uint8Array;
+  viewingPrivKey: Uint8Array;
+  nullifyingKey: bigint;
+}
 ```
 
-Keys are paths under the circuit base (`joinsplit_1x1/joinsplit_1x1_js/joinsplit_1x1.wasm`), so one
-manifest covers local dev and the CDN. Once set it fails closed: an artifact with no recorded
-digest is refused rather than trusted, so the manifest has to cover every shape your origin serves.
-The SDK cannot ship these — they change whenever circuits are rebuilt.
+### StealthDeposit
 
-## Layout
+```typescript
+interface StealthDeposit {
+  ephemeralPub: Uint8Array;  // 32 bytes (Ed25519)
+  amountSats: bigint;
+  commitment: Uint8Array;    // 32 bytes
+  createdAt: number;
+}
+```
 
+### ScannedNote
+
+```typescript
+interface ScannedNote {
+  amount: bigint;
+  ephemeralPub: Uint8Array;
+  stealthPub: BabyJubPoint;
+  leafIndex: number;
+  commitment: Uint8Array;
+}
 ```
-packages/sdk/          the SDK — keys, notes, stealth, proving, Solana instructions
-packages/btc-client/   standalone Esplora client and deposit OP_RETURN encoding
+
+### ConnectionAdapter
+
+```typescript
+interface ConnectionAdapter {
+  getAccountInfo: (
+    pubkey: { toBytes(): Uint8Array }
+  ) => Promise<{ data: Uint8Array } | null>;
+}
 ```
 
+## Security Considerations
+
+1. **Never expose spending private key** - Only needed for claiming
+2. **Viewing key can be delegated** - For balance monitoring without spend capability
+3. **Nullifiers prevent double-spending** - Derived from spending key + leaf index
+4. **Commitments hide amounts** - Poseidon hash of NPK, token, and amount
+
 ## Development
 
 ```bash
+# Install dependencies
 bun install
-bun run test     # 782 tests
-bun run build    # tsc
+
+# Build
+bun run build
+
+# Run tests
+bun test
+```
+
+## Verify it yourself: rebuild the tree from chain
+
+Spending a note needs a Merkle proof, and a Merkle proof needs the whole leaf
+set — which normally comes from our indexer. If the leaves weren't recoverable
+from the chain itself, "you can exit without the operator" would be a promise
+rather than a property.
+
+This script rebuilds a pool's entire leaf set from Solana transaction logs and
+checks the result against the root the program is verifying against. It talks to
+a public RPC endpoint and nothing else — no backend, no indexer, no API key:
+
+```bash
+TREE=<commitment-tree-pda> bun run scripts/rebuild-tree-from-chain.ts
 ```
 
-Tests are pure unit tests — no network, no validator, no proving. They run in about eight seconds,
-so there is no reason to skip them.
+```
+on-chain: 123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
+  134/134 scanned, 123 leaves
+recovered 123/123 leaves from logs
+rebuilt:  123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
 
-## Security
+MATCH — the leaf set is recoverable from chain alone
+```
 
-Two things worth knowing before you build on this:
+It exits non-zero on a mismatch or on missing leaves, so it works as a check in
+CI as well as by hand.
 
-- **`createDelegatedViewKey` currently hands over the `nullifyingKey`.** Because
-  `nullifier = Poseidon(nullifyingKey, leafIndex)` does not depend on note contents and leaf
-  indices are small public integers, anyone holding it can compute every nullifier that key will
-  ever produce and link the owner's entire spend history, retroactively and permanently. The
-  `fromSlot`/`toSlot` and FULL/SCAN/INCOMING_ONLY fields on a delegated key are metadata, not
-  enforcement. Treat a delegated viewing key as handing over the whole account, not a slice of it.
-  `extractViewOnlyBundle` correctly omits the key and is the safer thing to reach for.
-- Keys derive from a wallet signature, so **any party who can make that wallet sign the derivation
-  message can reconstruct the shielded identity.** A hardware wallet does not change this.
+| Env | Default | |
+|---|---|---|
+| `RPC` | devnet | Any Solana RPC endpoint |
+| `TREE` | `DEVNET_CONFIG.commitmentTreePda` | Commitment tree PDA to rebuild |
+| `EPOCH_SIG` | — | Tree's `INITIALIZE` signature. Optional; set it to skip a dead epoch if the PDA was closed and recreated |
+| `PACE_MS` | `120` | Delay between requests. Raise it if your endpoint throttles you |
 
-Report anything else privately rather than in a public issue.
+Public endpoints rate-limit this scan aggressively — the script paces itself and
+backs off, so expect it to take a minute or two rather than to fail.
 
 ## License
 

package/{packages/sdk/dist → dist}/client.d.ts

@@ -18,7 +18,7 @@
  */
 import { type NetworkConfig, type NetworkId } from "./config";
 import { type AuthSignatureKeyDerivationOptions, type UTXOpiaKeys, type StealthMetaAddress, type WalletSignerAdapter, type KeySetupResult } from "./keys";
-import { type ViewOnlyKeys, type StealthOutputWithKeys, type NonInteractiveDepositResult } from "./stealth";
+import { type ViewOnlyKeys, type StealthOutputWithKeys, type NonInteractiveDepositResult, type TweakDepositResult } from "./stealth";
 import { type UtxoDescriptor } from "./psbt";
 import { type DepositOpReturnContext } from "./taproot";
 export interface UTXOpiaClientConfig {
@@ -137,6 +137,30 @@ export declare class UTXOpiaClient {
     computeNullifier(note: {
         leafIndex: number;
     }): Uint8Array;
+    /**
+     * Prepare an OP_RETURN-free BTC deposit address (`verify_deposit`, disc 25).
+     *
+     * The ephemeral key is derived from this wallet's own viewing node and
+     * `depositIndex`, never randomly. A deposit address commits to the ephemeral
+     * key through its tapleaf and its key path is a NUMS point, so an address whose
+     * ephemeral key is lost is one nobody can ever spend. Indexing it makes the
+     * viewing key a complete backup: walk `depositIndex` upward and every address
+     * comes back.
+     *
+     * Self-deposit only. The address is recovered by whoever holds the viewing key
+     * it was derived from, so generating one *for someone else* would hand them a
+     * note they own but coins they could never recover. Pay a third party with a
+     * shielded transfer instead.
+     *
+     * `depositIndex` must be persisted and monotonic. Reusing one re-derives the
+     * same address, which is safe on chain but links the two deposits.
+     */
+    prepareTweakDeposit(opts: {
+        depositIndex: number;
+        ikaXOnlyPubkey: Uint8Array;
+        recipient?: StealthMetaAddress;
+        network?: "mainnet" | "testnet" | "regtest";
+    }): Promise<TweakDepositResult>;
     /**
      * Prepare a BTC deposit: generate stealth deposit address + OP_RETURN.
      * Returns the deposit result (btcAddress, opReturnPayload) ready for PSBT building.

package/{packages/sdk/dist → dist}/client.js

@@ -22,7 +22,7 @@ import { initConfig, getConfig } from "./config";
 import { parseMerkleProofResponse } from "./merkle";
 import { eddsaPoseidonSign } from "./keys";
 import { setupKeysFromWallet, setupKeysFromSeed, setupKeysFromAuthSignature, recreateStealthAddress, serializeKeysForStorage, deserializeKeysFromStorage, clearUTXOpiaKeys, } from "./keys";
-import { scanUnifiedNotesMulti, scanAnnouncementsViewOnlyMulti, computeNullifierHashForNote, computeNullifierBytes, isDepositForViewerHex, createDepositFromConfig, createStealthOutputWithKeys, } from "./stealth";
+import { scanUnifiedNotesMulti, scanAnnouncementsViewOnlyMulti, computeNullifierHashForNote, computeNullifierBytes, isDepositForViewerHex, createDepositFromConfig, createTweakDeposit, depositViewingNode, createStealthOutputWithKeys, } from "./stealth";
 import { selectUtxos } from "./psbt";
 import { hexToBytes } from "./crypto";
 import { EventClient } from "./event-client";
@@ -308,6 +308,41 @@ export class UTXOpiaClient {
         throw new Error("Not authenticated");
     }
     // ─── Phase 2: Deposit + Shield ─────────────────────────────────
+    /**
+     * Prepare an OP_RETURN-free BTC deposit address (`verify_deposit`, disc 25).
+     *
+     * The ephemeral key is derived from this wallet's own viewing node and
+     * `depositIndex`, never randomly. A deposit address commits to the ephemeral
+     * key through its tapleaf and its key path is a NUMS point, so an address whose
+     * ephemeral key is lost is one nobody can ever spend. Indexing it makes the
+     * viewing key a complete backup: walk `depositIndex` upward and every address
+     * comes back.
+     *
+     * Self-deposit only. The address is recovered by whoever holds the viewing key
+     * it was derived from, so generating one *for someone else* would hand them a
+     * note they own but coins they could never recover. Pay a third party with a
+     * shielded transfer instead.
+     *
+     * `depositIndex` must be persisted and monotonic. Reusing one re-derives the
+     * same address, which is safe on chain but links the two deposits.
+     */
+    async prepareTweakDeposit(opts) {
+        if (!this._keys) {
+            throw new Error("No keys (login first)");
+        }
+        const meta = opts.recipient ?? this._stealthAddress;
+        if (!meta)
+            throw new Error("No recipient stealth address (login first or provide recipient)");
+        if (opts.recipient && this._stealthAddress && opts.recipient !== this._stealthAddress) {
+            throw new Error("prepareTweakDeposit is self-deposit only: the recipient must be able to derive the " +
+                "ephemeral key to recover the coins, and only this wallet's viewing key can");
+        }
+        const network = opts.network ?? sdkBitcoinNetworkToAddressNetwork(this.config.bitcoinNetwork);
+        return createTweakDeposit(meta, opts.ikaXOnlyPubkey, {
+            viewingNode: depositViewingNode(this._keys.viewingPrivKey),
+            depositIndex: opts.depositIndex,
+        }, network);
+    }
     /**
      * Prepare a BTC deposit: generate stealth deposit address + OP_RETURN.
      * Returns the deposit result (btcAddress, opReturnPayload) ready for PSBT building.

package/{packages/sdk/dist → dist}/crypto-ed25519.d.ts

@@ -20,6 +20,20 @@ export declare function ed25519GenerateKeyPair(): {
     privKey: Uint8Array;
     pubKey: Uint8Array;
 };
+/**
+ * Derive an Ed25519 keypair deterministically from secret material.
+ *
+ * Used for deposit ephemeral keys, where a random keypair is a liability: the
+ * deposit address commits to the ephemeral pubkey, so losing it makes the coins
+ * unspendable by anyone, forever. Deriving it from the owner's seed means the
+ * seed alone can rebuild every address they were ever handed.
+ *
+ * @param material - secret bytes; hashed, so it need not be uniform
+ */
+export declare function ed25519KeyPairFromMaterial(material: Uint8Array): {
+    privKey: Uint8Array;
+    pubKey: Uint8Array;
+};
 /**
  * Derive an Ed25519 public key from a private key
  *

package/{packages/sdk/dist → dist}/crypto-ed25519.js

@@ -27,6 +27,20 @@ export function ed25519GenerateKeyPair() {
     const pubKey = ed25519.getPublicKey(privKey);
     return { privKey, pubKey };
 }
+/**
+ * Derive an Ed25519 keypair deterministically from secret material.
+ *
+ * Used for deposit ephemeral keys, where a random keypair is a liability: the
+ * deposit address commits to the ephemeral pubkey, so losing it makes the coins
+ * unspendable by anyone, forever. Deriving it from the owner's seed means the
+ * seed alone can rebuild every address they were ever handed.
+ *
+ * @param material - secret bytes; hashed, so it need not be uniform
+ */
+export function ed25519KeyPairFromMaterial(material) {
+    const privKey = sha256(material);
+    return { privKey, pubKey: ed25519.getPublicKey(privKey) };
+}
 /**
  * Derive an Ed25519 public key from a private key
  *

package/{packages/sdk/dist → dist}/index.d.ts

@@ -34,7 +34,7 @@ export { fetchTokenConfig, getTokenId, fetchSupportedTokens, fetchEnabledTokens,
 export { MAGICBLOCK_DELEGATION_PROGRAM_ID, MAGICBLOCK_DEVNET_ROUTER_URL, MAGICBLOCK_DEVNET_ROUTER_WS_URL, MAGICBLOCK_EPHEMERAL_VAULT_ID, MAGICBLOCK_MAGIC_CONTEXT_ID, MAGICBLOCK_MAGIC_PROGRAM_ID, MAGICBLOCK_MAX_PER_MEMBERS, MAGICBLOCK_PERMISSION_PROGRAM_ID, MAGICBLOCK_PER_MEMBER_FLAGS, MAGICBLOCK_VALIDATOR_IDENTITIES, buildDefaultPrivacyDomain, buildMagicBlockPerMemberFlags, deriveMagicBlockCommitRecordPDA, deriveMagicBlockCommitStatePDA, deriveMagicBlockDelegateBufferPDA, deriveMagicBlockDelegationMetadataPDA, deriveMagicBlockDelegationRecordPDA, deriveMagicBlockPermissionPDA, deriveMagicBlockUndelegateBufferPDA, requiresMagicBlockEndpoint, getMagicBlockEndpoint, getMagicBlockValidatorIdentity, createMagicBlockRouterConnection, type BuildPrivacyDomainOptions, type MagicBlockEndpointConfig, type MagicBlockExecutionMode, type MagicBlockPolicyMode, type MagicBlockPerMemberFlagName, type MagicBlockValidatorRegion, type PrivacyDomainConfig, type PrivacyDomainKind, } from "./magicblock";
 export { generateNote, createNoteFromSecrets, serializeNote, deserializeNote, noteHasComputedHashes, getNotePublicKeyX, computeNoteCommitment, computeNoteNullifier, formatBtc, parseBtc, deriveNote, deriveNotes, deriveMasterKey, deriveNoteFromMaster, estimateSeedStrength, createNote, prepareWithdrawal, createStealthNote, serializeStealthNote, deserializeStealthNote, type Note, type SerializedNote, type NoteData, type StealthNote, type SerializedStealthNote, createJoinSplitNote, computeJoinSplitNoteNullifier, serializeJoinSplitNote, deserializeJoinSplitNote, type JoinSplitNote, type SerializedJoinSplitNote, } from "./note";
 export { createMerkleProof, createMerkleProofFromBigints, proofToCircomFormat, proofToOnChainFormat, createEmptyMerkleProof, leafIndexToPathIndices, pathIndicesToLeafIndex, validateMerkleProofStructure, parseMerkleProofResponse, TREE_DEPTH, ROOT_HISTORY_SIZE, MAX_LEAVES, ZERO_VALUE, type MerkleProof, } from "./merkle";
-export { deriveTaprootAddress, deriveTaprootAddressWithRefund, depositTweakCommitment, buildRefundScript, computeTapLeafHash, verifyTaprootAddress, createP2TRScriptPubkey, parseP2TRScriptPubkey, isValidBitcoinAddress, getInternalKey, createCustomInternalKey, createOpReturnScriptFromPayload, buildDepositOpReturn, parseDepositOpReturn, encodeDepositOpReturnHeader, decodeDepositOpReturnHeader, validateDepositOpReturnContext, computeDepositPoolTag, DEPOSIT_DESTINATION_CHAIN, DEPOSIT_BITCOIN_NETWORK, DEPOSIT_OP_RETURN_VERSION, DEPOSIT_POOL_TAG_SIZE, DEPOSIT_OP_RETURN_SIZE, type DepositDestinationChain, type DepositBitcoinNetwork, type DepositOpReturnContext, type ParsedDepositOpReturn, } from "./taproot";
+export { deriveTaprootAddress, deriveTaprootAddressWithRefund, depositTweakCommitment, deriveDepositAddress, depositLeafScript, DEPOSIT_NUMS_INTERNAL_KEY, buildRefundScript, computeTapLeafHash, verifyTaprootAddress, createP2TRScriptPubkey, parseP2TRScriptPubkey, isValidBitcoinAddress, getInternalKey, createCustomInternalKey, createOpReturnScriptFromPayload, buildDepositOpReturn, parseDepositOpReturn, encodeDepositOpReturnHeader, decodeDepositOpReturnHeader, validateDepositOpReturnContext, computeDepositPoolTag, DEPOSIT_DESTINATION_CHAIN, DEPOSIT_BITCOIN_NETWORK, DEPOSIT_OP_RETURN_VERSION, DEPOSIT_POOL_TAG_SIZE, DEPOSIT_OP_RETURN_SIZE, type DepositDestinationChain, type DepositBitcoinNetwork, type DepositOpReturnContext, type ParsedDepositOpReturn, } from "./taproot";
 export { encodeClaimLink, decodeClaimLink, parseClaimUrl, } from "./claim-link";
 export type { ProofData, MerkleProofInput, CircuitType, JoinSplitProofInputs, } from "./prover/web";
 export { uploadTransactionToBuffer, uploadProofToBuffer, closeBuffer, readBufferData, fetchRawTransaction, fetchMerkleProof, prepareVerifyDeposit, buildMerkleProof, needsBuffer as bufferNeedsBuffer, getProofSource, calculateUploadTransactions, CHADBUFFER_PROGRAM_ID, AUTHORITY_SIZE, MAX_DATA_PER_WRITE, SOLANA_TX_SIZE_LIMIT, type ProofUploadResult, } from "./chadbuffer";
@@ -44,7 +44,7 @@ export { getConfig, setConfig, createConfig, initConfig, DEVNET_CONFIG, DEVNET_R
 export { POOL_STATE_DISCRIMINATOR, POOL_STATE_LEN, POOL_STATE_OFFSETS, POOL_FLAG, parsePoolState, parsePoolFees, BPS_DENOMINATOR, computeBpsFee, feeShareBps, } from "./pool-state";
 export type { PoolState, PoolFees } from "./pool-state";
 export { PDA_SEEDS, poolStateSeeds, commitmentTreeSeeds, tokenConfigSeeds, poolConfigSeeds, nullifierRecordSeeds, redemptionRequestSeeds, vkRegistrySeeds, depositReceiptSeeds, policyApprovalSeeds, exitDestinationSeeds, lightClientSeeds, blockHeaderSeeds, heightIndexSeeds, verifiedTransactionSeeds, derivePoolStatePDA, deriveCommitmentTreePDA, deriveNullifierRecordPDA, derivePolicyApprovalPDA, deriveExitDestinationPDA, EXIT_KIND_SOLANA_OWNER, EXIT_KIND_BTC_SCRIPT, deriveLightClientPDA, deriveBlockHeaderPDA, deriveHeightIndexPDA, deriveVkRegistryPDA, deriveRedemptionRequestPDA, deriveTokenConfigPDA, derivePoolConfigPDA, deriveDepositReceiptPDA, commitmentToBytes, } from "./pda";
-export { createStealthDeposit, createStealthDepositWithKeys, createStealthOutput, createStealthOutputWithKeys, createStealthOutputForCommitment, packStealthOutputForCircuit, scanAnnouncements, scanAnnouncementsViewOnly, scanAnnouncementsViewOnlyMulti, exportViewOnlyKeys, encodeViewOnlyKeys, decodeViewOnlyKeys, prepareClaimInputs, scanUnifiedNotes, scanUnifiedNotesMulti, encryptAmount, decryptAmount, computeNullifierHashForNote, computeNullifierBytes, parseAnnouncementsFromHex, createDepositFromConfig, createDirectVaultDeposit, createTweakDeposit, isDepositForViewer, isDepositForViewerHex, ANNOUNCEMENT_TYPE_DEPOSIT, ANNOUNCEMENT_TYPE_TRANSFER, type StealthDeposit, type StealthOutputData, type StealthOutputWithKeys, type CircuitStealthOutput, type ScannedNote, type ClaimInputs as StealthClaimInputs, type OnChainStealthAnnouncement, type ConnectionAdapter, type ViewOnlyKeys, type ViewOnlyScannedNote, createNonInteractiveDeposit, pickIkaCustodyKey, type NonInteractiveDepositResult, type TweakDepositResult, type NonInteractiveDepositWithRefundResult, } from "./stealth";
+export { createStealthDeposit, createStealthDepositWithKeys, createStealthOutput, createStealthOutputWithKeys, createStealthOutputForCommitment, packStealthOutputForCircuit, scanAnnouncements, scanAnnouncementsViewOnly, scanAnnouncementsViewOnlyMulti, exportViewOnlyKeys, encodeViewOnlyKeys, decodeViewOnlyKeys, prepareClaimInputs, scanUnifiedNotes, scanUnifiedNotesMulti, encryptAmount, decryptAmount, computeNullifierHashForNote, computeNullifierBytes, parseAnnouncementsFromHex, createDepositFromConfig, createDirectVaultDeposit, createTweakDeposit, depositEphemeralKeyPair, depositViewingNode, outgoingViewingNode, outgoingEphemeralKeyPair, findNextSendIndex, isDepositForViewer, isDepositForViewerHex, ANNOUNCEMENT_TYPE_DEPOSIT, ANNOUNCEMENT_TYPE_TRANSFER, type StealthDeposit, type StealthOutputData, type StealthOutputWithKeys, type CircuitStealthOutput, type ScannedNote, type ClaimInputs as StealthClaimInputs, type OnChainStealthAnnouncement, type ConnectionAdapter, type ViewOnlyKeys, type ViewOnlyScannedNote, createNonInteractiveDeposit, pickIkaCustodyKey, type NonInteractiveDepositResult, type TweakDepositResult, type DepositRecoveryMaterial, type OutgoingRecoveryMaterial, type NonInteractiveDepositWithRefundResult, } from "./stealth";
 export { buildDepositPsbt, estimateDepositFee, fetchUtxos, selectUtxos, type BuildDepositPsbtParams, type BuildDepositPsbtResult, type UtxoDescriptor, } from "./psbt";
 export { EsploraClient, esploraTestnet, esploraMainnet, type EsploraTransaction, type EsploraVin, type EsploraVout, type EsploraStatus, type EsploraAddressInfo, type EsploraUtxo, type EsploraMerkleProof, type EsploraNetwork, } from "./core/esplora";
 export { MempoolClient, mempoolTestnet, mempoolMainnet, reverseBytes, type BlockHeader, type TransactionInfo, type SPVProofData, } from "./core/mempool";
@@ -53,7 +53,7 @@ export { setDebug } from "./logger";
 export { createFetchConnectionAdapter, createConnectionAdapterFromWeb3, createConnectionAdapterFromKit, getConnectionAdapter, clearConnectionAdapterCache, type RpcConfig, type Web3Connection, type KitRpc, } from "./solana/connection";
 export { resolveSnsName, resolveStealthName, parseSnsStealthData, isSnsStealthAddress, isAuditorDisclosable, SnsComplianceFlags, SNS_COMPLIANCE_AUDITOR_OFFSET, SNS_COMPLIANCE_AUDITOR_BYTES, deriveParentDomainKey, SNS_STEALTH_DATA_SIZE, type SnsStealthAddress, } from "./sns-resolver";
 export { COMMITMENT_TREE_DISCRIMINATOR, parseCommitmentTreeData, isValidRoot, fetchCommitmentTree, getCommitmentIndex, saveCommitmentIndex, CommitmentTreeIndex, buildCommitmentTreeFromChain, fetchLeafIndexForCommitment, fetchMerkleProofForCommitment, getMerkleProofFromTree, type CommitmentTreeState, type RpcClient, type OnChainMerkleProof, } from "./commitment-tree";
-export { INSTRUCTION_DISCRIMINATORS, buildShieldInstructionData, buildShieldInstruction, type ShieldInstructionOptions, buildApproveRedemptionSigningInstructionData, buildApproveRedemptionSigningInstruction, buildCancelRedemptionInstructionData, buildCancelRedemptionInstruction, type CancelRedemptionInstructionOptions, bigintTo32Bytes, bytes32ToBigint, buildTransactInstructionData, buildTransactInstruction, buildRedeemInstructionData, buildUnshieldInstructionData, buildUnshieldInstruction, buildProposePoolUpdateInstructionData, buildProposePoolUpdateInstruction, buildExecutePoolUpdateInstructionData, buildExecutePoolUpdateInstruction, buildCancelPoolUpdateInstructionData, buildCancelPoolUpdateInstruction, buildRotateTreeInstructionData, buildRotateTreeInstruction, type RotateTreeOptions, buildMagicBlockDelegateInstructionData, buildMagicBlockDelegateInstruction, buildMagicBlockCommitInstructionData, buildMagicBlockCommitInstruction, buildMagicBlockPerPermissionInstructionData, buildMagicBlockPerPermissionInstruction, buildPolicyRequestHash, buildPolicyIntentParts, buildRegisterExitDestinationInstruction, buildRegisterExitDestinationInstructionData, MAX_POLICY_INTENT_PARTS, buildInitializePolicyApprovalInstructionData, buildInitializePolicyApprovalInstruction, buildPolicyApprovalDecisionInstruction, buildPolicyApprovalCommitInstruction, buildCompleteDepositPermissionedInstructionData, buildCompleteDepositPermissionedInstruction, buildShieldPermissionedInstructionData, buildShieldPermissionedInstruction, buildRotateAuditorInstructionData, buildRotateAuditorInstruction, type MagicBlockDelegateTarget, type MagicBlockDelegateInstructionOptions, type MagicBlockCommitInstructionOptions, type MagicBlockPerPermissionOperation, type MagicBlockPerPermissionMember, type MagicBlockPerPermissionInstructionOptions, type PolicyApprovalDecision, type InitializePolicyApprovalOptions, type CompleteDepositPermissionedOptions, type ShieldPermissionedInstructionOptions, type RotateAuditorOptions, buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, buildSetPoolConfigInstructionData, parsePoolConfig, type ParsedPoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, type Instruction, type ApproveRedemptionSigningInstructionOptions, type TransactInstructionOptions, type UnshieldInstructionOptions, type ProposePoolUpdateOptions, type ExecutePoolUpdateOptions, type CancelPoolUpdateOptions, } from "./instructions";
+export { INSTRUCTION_DISCRIMINATORS, buildShieldInstructionData, buildShieldInstruction, type ShieldInstructionOptions, buildApproveRedemptionSigningInstructionData, buildApproveRedemptionSigningInstruction, buildCancelRedemptionInstructionData, buildCancelRedemptionInstruction, type CancelRedemptionInstructionOptions, bigintTo32Bytes, bytes32ToBigint, buildTransactInstructionData, buildTransactInstruction, buildRedeemInstructionData, buildUnshieldInstructionData, buildUnshieldInstruction, buildProposePoolUpdateInstructionData, buildProposePoolUpdateInstruction, buildExecutePoolUpdateInstructionData, buildExecutePoolUpdateInstruction, buildCancelPoolUpdateInstructionData, buildCancelPoolUpdateInstruction, buildRotateTreeInstructionData, buildRotateTreeInstruction, type RotateTreeOptions, buildMagicBlockDelegateInstructionData, buildMagicBlockDelegateInstruction, buildMagicBlockCommitInstructionData, buildMagicBlockCommitInstruction, buildMagicBlockPerPermissionInstructionData, buildMagicBlockPerPermissionInstruction, buildPolicyRequestHash, buildPolicyIntentParts, buildRegisterExitDestinationInstruction, buildRegisterExitDestinationInstructionData, MAX_POLICY_INTENT_PARTS, buildInitializePolicyApprovalInstructionData, buildInitializePolicyApprovalInstruction, buildPolicyApprovalDecisionInstruction, buildPolicyApprovalCommitInstruction, buildCompleteDepositPermissionedInstructionData, buildCompleteDepositPermissionedInstruction, buildShieldPermissionedInstructionData, buildShieldPermissionedInstruction, buildRotateAuditorInstructionData, buildRotateAuditorInstruction, type MagicBlockDelegateTarget, type MagicBlockDelegateInstructionOptions, type MagicBlockCommitInstructionOptions, type MagicBlockPerPermissionOperation, type MagicBlockPerPermissionMember, type MagicBlockPerPermissionInstructionOptions, type PolicyApprovalDecision, type InitializePolicyApprovalOptions, type CompleteDepositPermissionedOptions, type ShieldPermissionedInstructionOptions, type RotateAuditorOptions, buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, buildVerifyDepositPermissionedInstructionData, buildSetPoolConfigInstructionData, parsePoolConfig, type ParsedPoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, type Instruction, type ApproveRedemptionSigningInstructionOptions, type TransactInstructionOptions, type UnshieldInstructionOptions, type ProposePoolUpdateOptions, type ExecutePoolUpdateOptions, type CancelPoolUpdateOptions, } from "./instructions";
 export { VK_REGISTRY_DISCRIMINATOR, VK_REGISTRY_LEN, MAX_IC_POINTS, MAX_SAFE_JOINSPLIT_SIZE, INIT_VK_REGISTRY_DISCRIMINATOR, UPDATE_VK_REGISTRY_DISCRIMINATOR, joinSplitNumPublicInputs, computeVkHash, vkeyJsonToVkMaterial, buildVkRegistryData, parseVkRegistry, assertVkRegistryForShape, isVkRegistryReady, type JoinSplitVkMaterial, type SnarkjsVkeyJson, type ParsedVkRegistry, } from "./vk-registry";
 export { fetchExplorerDeposits, fetchExplorerTransfers, fetchExplorerRedemptions, parseNullifierRecord, parseRedemptionRequest, NULLIFIER_RECORD_SIZE, REDEMPTION_REQUEST_SIZE, NULLIFIER_RECORD_DISCRIMINATOR, REDEMPTION_REQUEST_DISCRIMINATOR, OPERATION_TYPE_LABELS, type ExplorerDeposit, type ExplorerTransferEvent, type ExplorerRedemption, type IndexerLeaf, } from "./explorer";
 export { parseProgramEvents, parseNullifierSpentEvent, parseStealthAnnouncementEvent, parseSenderMemoEvent, parseBtcOriginAttestationEvent, parseAuditorCiphertextEvent, EVENT_NULLIFIER_SPENT, EVENT_STEALTH_ANNOUNCEMENT, EVENT_NULLIFIERS_BATCH, EVENT_ANNOUNCEMENTS_BATCH, EVENT_SENDER_MEMO, EVENT_BTC_ORIGIN_ATTESTATION, EVENT_AUDITOR_CIPHERTEXT, type NullifierSpentEvent, type StealthAnnouncementEvent, type SenderMemoEvent, type BtcOriginAttestationEvent, type AuditorCiphertextEvent, type ProgramEvent, } from "./events";

package/{packages/sdk/dist → dist}/index.js

@@ -94,7 +94,7 @@ export { createMerkleProof, createMerkleProofFromBigints, proofToCircomFormat, p
 // ==========================================================================
 // Taproot address utilities
 // ==========================================================================
-export { deriveTaprootAddress, deriveTaprootAddressWithRefund, depositTweakCommitment, buildRefundScript, computeTapLeafHash, verifyTaprootAddress, createP2TRScriptPubkey, parseP2TRScriptPubkey, isValidBitcoinAddress, getInternalKey, createCustomInternalKey, createOpReturnScriptFromPayload, buildDepositOpReturn, parseDepositOpReturn, encodeDepositOpReturnHeader, decodeDepositOpReturnHeader, validateDepositOpReturnContext, computeDepositPoolTag, DEPOSIT_DESTINATION_CHAIN, DEPOSIT_BITCOIN_NETWORK, DEPOSIT_OP_RETURN_VERSION, DEPOSIT_POOL_TAG_SIZE, DEPOSIT_OP_RETURN_SIZE, } from "./taproot";
+export { deriveTaprootAddress, deriveTaprootAddressWithRefund, depositTweakCommitment, deriveDepositAddress, depositLeafScript, DEPOSIT_NUMS_INTERNAL_KEY, buildRefundScript, computeTapLeafHash, verifyTaprootAddress, createP2TRScriptPubkey, parseP2TRScriptPubkey, isValidBitcoinAddress, getInternalKey, createCustomInternalKey, createOpReturnScriptFromPayload, buildDepositOpReturn, parseDepositOpReturn, encodeDepositOpReturnHeader, decodeDepositOpReturnHeader, validateDepositOpReturnContext, computeDepositPoolTag, DEPOSIT_DESTINATION_CHAIN, DEPOSIT_BITCOIN_NETWORK, DEPOSIT_OP_RETURN_VERSION, DEPOSIT_POOL_TAG_SIZE, DEPOSIT_OP_RETURN_SIZE, } from "./taproot";
 // ==========================================================================
 // Claim link utilities
 // ==========================================================================
@@ -127,7 +127,7 @@ poolStateSeeds, commitmentTreeSeeds, tokenConfigSeeds, poolConfigSeeds, nullifie
 // ==========================================================================
 // Stealth address utilities
 // ==========================================================================
-export { createStealthDeposit, createStealthDepositWithKeys, createStealthOutput, createStealthOutputWithKeys, createStealthOutputForCommitment, packStealthOutputForCircuit, scanAnnouncements, scanAnnouncementsViewOnly, scanAnnouncementsViewOnlyMulti, exportViewOnlyKeys, encodeViewOnlyKeys, decodeViewOnlyKeys, prepareClaimInputs, scanUnifiedNotes, scanUnifiedNotesMulti, encryptAmount, decryptAmount, computeNullifierHashForNote, computeNullifierBytes, parseAnnouncementsFromHex, createDepositFromConfig, createDirectVaultDeposit, createTweakDeposit, isDepositForViewer, isDepositForViewerHex, ANNOUNCEMENT_TYPE_DEPOSIT, ANNOUNCEMENT_TYPE_TRANSFER, createNonInteractiveDeposit, pickIkaCustodyKey, } from "./stealth";
+export { createStealthDeposit, createStealthDepositWithKeys, createStealthOutput, createStealthOutputWithKeys, createStealthOutputForCommitment, packStealthOutputForCircuit, scanAnnouncements, scanAnnouncementsViewOnly, scanAnnouncementsViewOnlyMulti, exportViewOnlyKeys, encodeViewOnlyKeys, decodeViewOnlyKeys, prepareClaimInputs, scanUnifiedNotes, scanUnifiedNotesMulti, encryptAmount, decryptAmount, computeNullifierHashForNote, computeNullifierBytes, parseAnnouncementsFromHex, createDepositFromConfig, createDirectVaultDeposit, createTweakDeposit, depositEphemeralKeyPair, depositViewingNode, outgoingViewingNode, outgoingEphemeralKeyPair, findNextSendIndex, isDepositForViewer, isDepositForViewerHex, ANNOUNCEMENT_TYPE_DEPOSIT, ANNOUNCEMENT_TYPE_TRANSFER, createNonInteractiveDeposit, pickIkaCustodyKey, } from "./stealth";
 // ==========================================================================
 // PSBT builder for wallet-integrated deposits
 // ==========================================================================
@@ -181,7 +181,7 @@ buildRotateTreeInstructionData, buildRotateTreeInstruction,
 // MagicBlock lifecycle
 buildMagicBlockDelegateInstructionData, buildMagicBlockDelegateInstruction, buildMagicBlockCommitInstructionData, buildMagicBlockCommitInstruction, buildMagicBlockPerPermissionInstructionData, buildMagicBlockPerPermissionInstruction, buildPolicyRequestHash, buildPolicyIntentParts, buildRegisterExitDestinationInstruction, buildRegisterExitDestinationInstructionData, MAX_POLICY_INTENT_PARTS, buildInitializePolicyApprovalInstructionData, buildInitializePolicyApprovalInstruction, buildPolicyApprovalDecisionInstruction, buildPolicyApprovalCommitInstruction, buildCompleteDepositPermissionedInstructionData, buildCompleteDepositPermissionedInstruction, buildShieldPermissionedInstructionData, buildShieldPermissionedInstruction, buildRotateAuditorInstructionData, buildRotateAuditorInstruction, 
 // Verify instruction data builders
-buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, 
+buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, buildVerifyDepositPermissionedInstructionData, 
 // Pool config (disc 2) builder + parser
 buildSetPoolConfigInstructionData, parsePoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, } from "./instructions";
 // ==========================================================================