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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utxopia/sdk",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "UTXOpia public SDK workspace",
   "license": "MIT",
   "repository": {

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

@@ -20,7 +20,7 @@ import { type Address } from "@solana/kit";
  */
 export declare function address(input: string): Address;
 export type NetworkType = "devnet" | "mainnet" | "localnet";
-export type AppNetworkId = NetworkType | "devnet-regtest";
+export type AppNetworkId = NetworkType | "devnet-regtest" | "devnet-testnet4";
 export interface NetworkConfig {
     /** Network identifier */
     network: NetworkType;
@@ -99,10 +99,41 @@ export declare const CHADBUFFER_PROGRAM_ID: Address;
 /** ChadBuffer Program ID for localnet testing */
 export declare const LOCALNET_CHADBUFFER_PROGRAM_ID: Address;
 /**
- * Fresh multi-pool devnet deployment (2026-07-26).
- * The default domain is public; institution pools are selected explicitly.
+ * Greenfield devnet + Bitcoin testnet4 deployment (2026-08-26).
+ *
+ * The previous deployment's programs were closed on chain, so this is not a redeploy and none
+ * of the old addresses resolve any more — anything still pinned to CvfSyACR… is talking to a
+ * program that no longer exists.
+ *
+ * Two pools were deployed, each with its own Ika DKG and therefore its own dWallet. The default
+ * below is the OPEN pool. Select the verified pool by overriding `zkbtcMint` and
+ * `ikaDwalletXOnlyPubkey` — `getConfig` re-derives poolStatePda, commitmentTreePda and poolVault
+ * from the mint, so those two values are all a caller needs:
+ *
+ *   verified  mint  G78CTddWGDaNaSKQayAt7m3pzcMyaUNxgR8y3R34YvEv
+ *             state Eqn9SmFYtacrdfPE9Shbi8bDXLjCNNz3WhHfqtJnwbKY
+ *             xonly 16c563baa11bfc8fe93acafe8fe169b954b3ead3ecda7754c615dec9e840b5a5
+ *
+ * Read off chain, not from the deploy notes: Eqn9SmFY… is the pool whose PoolState flags carry
+ * the permissioned bit (0b10 at offset 2). The deployment also contains a THIRD pool —
+ * 3chHiDqM… / 7wDtDd1u… — which the deploy notes name as the verified one but which is not
+ * permissioned and whose mint has zero supply. Treat it as abandoned; do not wire it up.
  */
 export declare const DEVNET_CONFIG: NetworkConfig;
+/**
+ * Solana devnet + Bitcoin **regtest** deployment — the environment app.utxopia.com serves.
+ *
+ * This is a different deployment from DEVNET_CONFIG above, not a Bitcoin-side variation of it:
+ * a different program (CvfSyACR…), a different pool, a different Ika dWallet. It used to share
+ * DEVNET_CONFIG and differ only by bitcoinNetwork, which worked while one program hosted both.
+ * It no longer does — after 2026-08-26 there are two programs — so `devnet-regtest` resolving
+ * to DEVNET_CONFIG would silently point this environment at testnet4's program and pool.
+ *
+ * Pool addresses derived from the mint with the same seeds getConfig uses, then confirmed on
+ * devnet: pool_state and commitment_tree owned by CvfSyACR… at 332 and 8816 bytes, the vault by
+ * Token-2022 at 170.
+ */
+export declare const DEVNET_REGTEST_CONFIG: NetworkConfig;
 /**
  * Mainnet Configuration (placeholder - not yet deployed)
  */

package/packages/sdk/dist/config.js

@@ -44,21 +44,42 @@ export const LOCALNET_CHADBUFFER_PROGRAM_ID = address("EgWyMVFZewHmjJ9GGvVBTyaC3
 // Network Configurations
 // =============================================================================
 /**
- * Fresh multi-pool devnet deployment (2026-07-26).
- * The default domain is public; institution pools are selected explicitly.
+ * Greenfield devnet + Bitcoin testnet4 deployment (2026-08-26).
+ *
+ * The previous deployment's programs were closed on chain, so this is not a redeploy and none
+ * of the old addresses resolve any more — anything still pinned to CvfSyACR… is talking to a
+ * program that no longer exists.
+ *
+ * Two pools were deployed, each with its own Ika DKG and therefore its own dWallet. The default
+ * below is the OPEN pool. Select the verified pool by overriding `zkbtcMint` and
+ * `ikaDwalletXOnlyPubkey` — `getConfig` re-derives poolStatePda, commitmentTreePda and poolVault
+ * from the mint, so those two values are all a caller needs:
+ *
+ *   verified  mint  G78CTddWGDaNaSKQayAt7m3pzcMyaUNxgR8y3R34YvEv
+ *             state Eqn9SmFYtacrdfPE9Shbi8bDXLjCNNz3WhHfqtJnwbKY
+ *             xonly 16c563baa11bfc8fe93acafe8fe169b954b3ead3ecda7754c615dec9e840b5a5
+ *
+ * Read off chain, not from the deploy notes: Eqn9SmFY… is the pool whose PoolState flags carry
+ * the permissioned bit (0b10 at offset 2). The deployment also contains a THIRD pool —
+ * 3chHiDqM… / 7wDtDd1u… — which the deploy notes name as the verified one but which is not
+ * permissioned and whose mint has zero supply. Treat it as abandoned; do not wire it up.
  */
 export const DEVNET_CONFIG = {
     network: "devnet",
-    utxopiaProgramId: address("CvfSyACR8xemPdeJsB3D8Xh15rKUQ3b5c1PvnmABCBJp"),
+    utxopiaProgramId: address("28z2AtKA6aFGrGCh4ns1rmp7vGpWuh6x3H7gXKBcfxur"),
     policyProgramId: address("9asWYKVriWGpExW5xM44ChHjZtispkLCiWKkM8SQi8Rs"),
-    btcLightClientProgramId: address("859B7kw1xDyY8rzSXY6pAPNxaAsPWrsaAPJk3iivd43g"),
+    // testnet4 light client, deployed 2026-08-26. Must match the `devnet` arm of
+    // BTC_LIGHT_CLIENT_PROGRAM_ID in programs/utxopia/src/constants.rs.
+    btcLightClientProgramId: address("4LZbktiNsiVAe2bwPCTPNgqiWWgZNUj4T3bDx8GZmehv"),
     chadbufferProgramId: CHADBUFFER_PROGRAM_ID,
     token2022ProgramId: TOKEN_2022_PROGRAM_ID,
     ataProgramId: ATA_PROGRAM_ID,
-    poolStatePda: address("9xeWc39r3Z176MUpMpaqCGJGneHMj4pfMRv9u6dp2Qgd"),
-    commitmentTreePda: address("4FvM9dCzDvr39Xu5xRUQc6EEm3UjSikyWUY5Hzpc5C4A"),
-    zkbtcMint: address("GuruxfN5irYcCyDiKFMeDRTNbP2WeHF1oWjQ8q8Esc16"),
-    poolVault: address("3GffHxesFsGj4QmgQ8ozs17dZFNTv4AAhdwyR2XZPzkm"),
+    // Open pool. Derived and then confirmed on chain: pool_state and commitment_tree are owned by
+    // the program (332 / 8816 bytes), the vault by Token-2022 (170 bytes).
+    poolStatePda: address("FezM7ksBwftqrd4TtabMa9uXt51eCT5M946YnpSEQZHm"),
+    commitmentTreePda: address("CHwJZqNAUag6ARDfmntvmbS4WeAsGX67f2vALxXbB6PP"),
+    zkbtcMint: address("87zWstDnNgMig2vk8q8jTrK6YTcyugeRTanfT3LfyU3T"),
+    poolVault: address("8VMfH4mDizU6nHybQumxeauyiEL2QTqrGQLXmAr9wpC3"),
     // RPC Endpoints
     solanaRpcUrl: "https://api.devnet.solana.com",
     solanaWsUrl: "wss://api.devnet.solana.com",
@@ -67,8 +88,11 @@ export const DEVNET_CONFIG = {
     esploraUrl: "https://mempool.space/testnet4/api",
     // Circuit CDN (Groth16 artifacts: .wasm, .zkey files)
     circuitCdnUrl: "https://circuit.utxopia.com/circuits/v2/groth16",
-    // Groth16 Verifier: verification is inline in the UTXOpia program (no separate verifier program)
-    groth16VerifierProgramId: address("AjbX243s2JMFG2uhfTjKkadjPvQEPgcuyV3vfLJv36MT"), // inline in utxopia program
+    // Groth16 verification is inline in the UTXOpia program, so this is the same address.
+    // It used to hold a stale third id, which `getConfig` silently overwrote with the program id
+    // whenever a programId override was supplied — meaning the constant was only ever read on the
+    // no-override path, where it was wrong.
+    groth16VerifierProgramId: address("28z2AtKA6aFGrGCh4ns1rmp7vGpWuh6x3H7gXKBcfxur"),
     // VK Hashes (SHA256 of serialized VK bytes, generated from circom trusted setup)
     vkHashes: {
         claim: "7af0e702e7b595fbdb62fd268e6c529481003e07957e0f60e4fb23cd9fe6a77f",
@@ -88,8 +112,12 @@ export const DEVNET_CONFIG = {
         "1x4": "01728b82e810a8ba604cc66aa6a563444d18f4598c402d11767d0a7e5049a9be",
         "4x1": "0362b306b17dae916d836d9448a26c97e51b1b0a1a0ed052ebfbd4800e5000cf",
     },
-    // Ika dWallet x-only pubkey — populated by ./scripts/sync-env.sh from devnet-state.json.
-    ikaDwalletXOnlyPubkey: "0000000000000000000000000000000000000000000000000000000000000000",
+    // Ika dWallet x-only pubkey for the OPEN pool, read from its PoolConfig PDA
+    // (GQ5ZfD4tJmgcquHLAHSbmAm72Foi9hf3VduPrroysM1b, offset 68..100) on 2026-08-26.
+    // All-zero here used to mean "deposit addresses cannot be derived until sync-env.sh runs";
+    // the two pools have distinct dWallets, so a single synced value could only ever be right
+    // for one of them. See the verified pool's key in the header comment above.
+    ikaDwalletXOnlyPubkey: "3a6ab80ba14bc050f048ee3e0b77d8935adf4fc5e2f5947311f26cc2cb5bd194",
     // SNS Subdomain Resolution (devnet)
     snsNameServiceProgramId: "namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX", // SPL Name Service (devnet)
     snsRegistrarProgramId: "snshBoEQ9jx4QoHBpZDQPYdNCtw7RMxJvYrKFEhwaPJ", // SNS Registrar (devnet)
@@ -99,6 +127,32 @@ export const DEVNET_CONFIG = {
     snsReverseLookupClass: "7NbD1vprif6apthEZAqhRfYuhrqnuderB8qpnfXGCc8H", // Reverse lookup class (devnet)
     snsStealthDataVersion: 1,
 };
+/**
+ * Solana devnet + Bitcoin **regtest** deployment — the environment app.utxopia.com serves.
+ *
+ * This is a different deployment from DEVNET_CONFIG above, not a Bitcoin-side variation of it:
+ * a different program (CvfSyACR…), a different pool, a different Ika dWallet. It used to share
+ * DEVNET_CONFIG and differ only by bitcoinNetwork, which worked while one program hosted both.
+ * It no longer does — after 2026-08-26 there are two programs — so `devnet-regtest` resolving
+ * to DEVNET_CONFIG would silently point this environment at testnet4's program and pool.
+ *
+ * Pool addresses derived from the mint with the same seeds getConfig uses, then confirmed on
+ * devnet: pool_state and commitment_tree owned by CvfSyACR… at 332 and 8816 bytes, the vault by
+ * Token-2022 at 170.
+ */
+export const DEVNET_REGTEST_CONFIG = {
+    ...DEVNET_CONFIG,
+    utxopiaProgramId: address("CvfSyACR8xemPdeJsB3D8Xh15rKUQ3b5c1PvnmABCBJp"),
+    groth16VerifierProgramId: address("CvfSyACR8xemPdeJsB3D8Xh15rKUQ3b5c1PvnmABCBJp"),
+    btcLightClientProgramId: address("8hCSNKf8ByqZdet2D4SDiZHDrB1u9ohkhqKKzr9i7vfQ"),
+    poolStatePda: address("CeEEmE9MvFPZtqcgv1rsXmzNmfvchbs8VEZJGFKZ2Cyj"),
+    commitmentTreePda: address("45bCw97GssorJM9b1ZWZLMGy1NJUczcaNVaKASmCRohL"),
+    zkbtcMint: address("BJ5SXA33qK8r8BxJD4nQPf72ae9bactiA2Zqo33EcvPu"),
+    poolVault: address("JsZ1ipHZWiZYE8kRDXmEkKuiK6KKVxCVJKv1tGnCkM6"),
+    ikaDwalletXOnlyPubkey: "243a6c47504f82d168754da9392a9dbcbab9b9f9c515a609227fac4642b2a26f",
+    bitcoinNetwork: "regtest",
+    esploraUrl: "http://localhost:2140",
+};
 /**
  * Mainnet Configuration (placeholder - not yet deployed)
  */
@@ -221,6 +275,24 @@ function esploraUrlForNetwork(net) {
         default: return `https://mempool.space/${net}/api`;
     }
 }
+/**
+ * Base config for an app network id. Two devnet deployments now exist, so this cannot be
+ * derived from NetworkType alone — that is what normalizeAppNetwork collapses away.
+ */
+function baseConfigForAppNetwork(network) {
+    switch (network) {
+        case "localnet":
+            return LOCALNET_CONFIG;
+        case "mainnet":
+            return MAINNET_CONFIG;
+        case "devnet-regtest":
+            return DEVNET_REGTEST_CONFIG;
+        case "devnet-testnet4":
+        case "devnet":
+        default:
+            return DEVNET_CONFIG;
+    }
+}
 function normalizeAppNetwork(network) {
     switch (network) {
         case "mainnet":
@@ -229,6 +301,7 @@ function normalizeAppNetwork(network) {
             return "localnet";
         case "devnet":
         case "devnet-regtest":
+        case "devnet-testnet4":
         default:
             return "devnet";
     }
@@ -239,6 +312,7 @@ function bitcoinNetworkForAppNetwork(network) {
         case "devnet-regtest":
             return "regtest";
         case "devnet":
+        case "devnet-testnet4":
             return "testnet4";
         case "mainnet":
             return "mainnet";
@@ -273,7 +347,7 @@ export function setConfig(network) {
         const baseNetwork = normalizeAppNetwork(network);
         switch (baseNetwork) {
             case "devnet":
-                currentConfig = DEVNET_CONFIG;
+                currentConfig = baseConfigForAppNetwork(network);
                 break;
             case "mainnet":
                 throw new Error("Mainnet is not yet deployed. " +
@@ -318,11 +392,7 @@ export async function initConfig(overrides) {
         (typeof process !== "undefined" && (process.env?.NEXT_PUBLIC_NETWORK || process.env?.UTXOPIA_NETWORK)) ||
         "devnet";
     const networkId = normalizeAppNetwork(appNetworkId);
-    const baseConfig = networkId === "localnet"
-        ? LOCALNET_CONFIG
-        : networkId === "mainnet"
-            ? MAINNET_CONFIG
-            : DEVNET_CONFIG;
+    const baseConfig = baseConfigForAppNetwork(appNetworkId);
     const config = { ...baseConfig };
     const appBitcoinNetwork = bitcoinNetworkForAppNetwork(appNetworkId);
     const btcNetOverride = typeof process !== "undefined" && process.env?.NEXT_PUBLIC_BTC_NETWORK;

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

@@ -34,16 +34,17 @@ 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, 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, 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";
 export { computeBoundParamsHash, computeSolanaDomainBoundParamsHash, computeSolanaDomainSeparator, computeStealthDataHash, createTransferBoundParams, createUnshieldBoundParams, createRedeemBoundParams, SOLANA_BOUND_CHAIN_ID, SOLANA_DEVNET_BOUND_CHAIN_ID, SOLANA_MAINNET_BOUND_CHAIN_ID, DEFAULT_BOUND_PARAMS, type BoundParams, type BoundParamsMode, type SolanaPrivacyDomainContext, type SolanaPrivacyDomainKind, } from "./bound-params";
-export { getConfig, setConfig, createConfig, initConfig, DEVNET_CONFIG, MAINNET_CONFIG, LOCALNET_CONFIG, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ATA_PROGRAM_ID, UTXOPIA_POLICY_PROGRAM_ID, SDK_VERSION, DEPLOYMENT_INFO, JOINSPLIT_TREE_DEPTH, type NetworkConfig, type NetworkType, } from "./config";
+export { formatSpendDoc, renderSpendDoc, SpendDocMismatch, type SpendDoc, type SpendSignals, } from "./spend-doc";
+export { getConfig, setConfig, createConfig, initConfig, DEVNET_CONFIG, DEVNET_REGTEST_CONFIG, MAINNET_CONFIG, LOCALNET_CONFIG, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ATA_PROGRAM_ID, UTXOPIA_POLICY_PROGRAM_ID, SDK_VERSION, DEPLOYMENT_INFO, JOINSPLIT_TREE_DEPTH, type NetworkConfig, type NetworkType, } from "./config";
 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, 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 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, 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 { 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";
@@ -52,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, 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, 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/index.js

@@ -94,7 +94,7 @@ export { createMerkleProof, createMerkleProofFromBigints, proofToCircomFormat, p
 // ==========================================================================
 // Taproot address utilities
 // ==========================================================================
-export { deriveTaprootAddress, deriveTaprootAddressWithRefund, 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, 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
 // ==========================================================================
@@ -107,10 +107,11 @@ export { uploadTransactionToBuffer, uploadProofToBuffer, closeBuffer, readBuffer
 // Bound Parameters (JoinSplit transaction binding)
 // ==========================================================================
 export { computeBoundParamsHash, computeSolanaDomainBoundParamsHash, computeSolanaDomainSeparator, computeStealthDataHash, createTransferBoundParams, createUnshieldBoundParams, createRedeemBoundParams, SOLANA_BOUND_CHAIN_ID, SOLANA_DEVNET_BOUND_CHAIN_ID, SOLANA_MAINNET_BOUND_CHAIN_ID, DEFAULT_BOUND_PARAMS, } from "./bound-params";
+export { formatSpendDoc, renderSpendDoc, SpendDocMismatch, } from "./spend-doc";
 // ==========================================================================
 // Configuration
 // ==========================================================================
-export { getConfig, setConfig, createConfig, initConfig, DEVNET_CONFIG, MAINNET_CONFIG, LOCALNET_CONFIG, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ATA_PROGRAM_ID, UTXOPIA_POLICY_PROGRAM_ID, SDK_VERSION, DEPLOYMENT_INFO, JOINSPLIT_TREE_DEPTH, } from "./config";
+export { getConfig, setConfig, createConfig, initConfig, DEVNET_CONFIG, DEVNET_REGTEST_CONFIG, MAINNET_CONFIG, LOCALNET_CONFIG, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ATA_PROGRAM_ID, UTXOPIA_POLICY_PROGRAM_ID, SDK_VERSION, DEPLOYMENT_INFO, JOINSPLIT_TREE_DEPTH, } from "./config";
 // ==========================================================================
 // PoolState account layout + fee arithmetic
 // ==========================================================================
@@ -126,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, 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, isDepositForViewer, isDepositForViewerHex, ANNOUNCEMENT_TYPE_DEPOSIT, ANNOUNCEMENT_TYPE_TRANSFER, createNonInteractiveDeposit, pickIkaCustodyKey, } from "./stealth";
 // ==========================================================================
 // PSBT builder for wallet-integrated deposits
 // ==========================================================================
@@ -180,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, 
+buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, 
 // Pool config (disc 2) builder + parser
 buildSetPoolConfigInstructionData, parsePoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, } from "./instructions";
 // ==========================================================================

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

@@ -32,10 +32,13 @@ export declare const INSTRUCTION_DISCRIMINATORS: {
     readonly CLAIM_FEES: 10;
     readonly COMPLETE_DEPOSIT: 11;
     readonly SHIELD: 12;
+    /** OP_RETURN-free deposit: note keys ride in instruction data, proven by the
+     *  deposit address's Taproot tweak. */
+    readonly VERIFY_DEPOSIT: 25;
     readonly TRANSACT: 13;
     readonly UNSHIELD: 14;
     readonly REDEEM: 15;
-    readonly RESERVED_REQUEST_REDEMPTION: 16;
+    readonly FREEZE_VK_REGISTRY: 16;
     readonly COMPLETE_REDEMPTION: 17;
     readonly MARK_PROCESSING: 18;
     readonly CANCEL_REDEMPTION: 19;
@@ -113,6 +116,17 @@ export interface CompleteRedemptionInstructionOptions {
         poolVault: Address;
         completionReceipt: Address;
         poolConfig: Address;
+        /** HeightIndex PDA for the VerifiedTransaction's block —
+         *  `deriveHeightIndexPDA(blockHeight, config.btcLightClientProgramId)`.
+         *
+         *  REQUIRED. The program re-checks that the proof's block is still the canonical one at
+         *  that height before it settles (audit_1 F-BTC-04): a VerifiedTransaction records a merkle
+         *  proof that was valid once and is never invalidated, and the confirmation count is taken
+         *  against a tip that only grows, so neither notices a reorg. Omitting this fails with
+         *  InvalidSpvProof — the program locates the account by address, so its position in the
+         *  list does not matter, but its absence is an error rather than a skipped check.
+         */
+        heightIndex: Address;
         /** Change UTXO PDA. Required when poolScript is non-empty. */
         changeUtxo?: Address;
         /** zkBTC TokenConfig PDA (credits protocol revenue) */
@@ -135,6 +149,17 @@ export interface ApproveRedemptionSigningInstructionOptions {
         redemptionRequest: Address;
         authority: Address;
         poolConfig: Address;
+        /** HeightIndex PDA for the VerifiedTransaction's block —
+         *  `deriveHeightIndexPDA(blockHeight, config.btcLightClientProgramId)`.
+         *
+         *  REQUIRED. The program re-checks that the proof's block is still the canonical one at
+         *  that height before it settles (audit_1 F-BTC-04): a VerifiedTransaction records a merkle
+         *  proof that was valid once and is never invalidated, and the confirmation count is taken
+         *  against a tip that only grows, so neither notices a reorg. Omitting this fails with
+         *  InvalidSpvProof — the program locates the account by address, so its position in the
+         *  list does not matter, but its absence is an error rather than a skipped check.
+         */
+        heightIndex: Address;
         ikaProgram: Address;
         ikaCoordinator: Address;
         ikaMessageApproval: Address;
@@ -732,6 +757,38 @@ export declare function buildCompleteDepositInstructionData(params: {
     depositTxSize: number;
     depositTxid: Uint8Array;
 }): Uint8Array;
+/**
+ * Build utxopia verify_deposit instruction data (disc=25).
+ *
+ * The OP_RETURN-free deposit path. `notePublicKey` + `ephemeralPubkey` travel in
+ * instruction data instead of in the Bitcoin transaction, and the program proves
+ * them against the deposit output's Taproot tweak — a different key pair derives
+ * a different address, which the funding transaction did not pay. Nothing marks
+ * the deposit as a UTXOpia transaction on chain, so any wallet or exchange that
+ * can send to a P2TR address can fund it.
+ *
+ * The address must be derived from `depositTweakCommitment(npk, eph)`, NOT from
+ * the note key alone — the program hashes both, so that a caller cannot swap in
+ * an ephemeral key that leaves the note undiscoverable.
+ *
+ * Sweep mode only: `depositTxSize` must be non-zero. The receipt PDA is seeded
+ * `["deposit_receipt", txid, vout]`, so pass `depositVout` to
+ * `deriveDepositReceiptPDA` for this flow.
+ *
+ * Layout: disc(1) + sweep_txid(32) + block_height(u64 LE) + sweep_tx_size(u32 LE)
+ *         + deposit_tx_size(u32 LE) + deposit_txid(32) + ephemeral_pubkey(32)
+ *         + note_public_key(32) + deposit_vout(u32 LE) = 149 bytes
+ */
+export declare function buildVerifyDepositInstructionData(params: {
+    sweepTxid: Uint8Array;
+    blockHeight: number;
+    sweepTxSize: number;
+    depositTxSize: number;
+    depositTxid: Uint8Array;
+    ephemeralPubkey: Uint8Array;
+    notePublicKey: Uint8Array;
+    depositVout: number;
+}): Uint8Array;
 /** PoolConfig account discriminator (0x0a) */
 export declare const POOL_CONFIG_DISCRIMINATOR = 10;
 /** Serialized PoolConfig account length (bytes) */
@@ -901,6 +958,17 @@ export interface CompleteDepositPermissionedOptions {
         tokenConfig: Address;
         /** 14. pool_config PDA (readonly) */
         poolConfig: Address;
+        /** HeightIndex PDA for the VerifiedTransaction's block —
+         *  `deriveHeightIndexPDA(blockHeight, config.btcLightClientProgramId)`.
+         *
+         *  REQUIRED. The program re-checks that the proof's block is still the canonical one at
+         *  that height before it settles (audit_1 F-BTC-04): a VerifiedTransaction records a merkle
+         *  proof that was valid once and is never invalidated, and the confirmation count is taken
+         *  against a tip that only grows, so neither notices a reorg. Omitting this fails with
+         *  InvalidSpvProof — the program locates the account by address, so its position in the
+         *  list does not matter, but its absence is an error rather than a skipped check.
+         */
+        heightIndex: Address;
         /** 15. one-time PolicyApproval (writable) */
         policyApproval: Address;
     };
@@ -944,6 +1012,8 @@ export declare function buildCompleteDepositPermissionedInstructionData(options:
  * 13. token_config        (writable)
  * 14. pool_config         (readonly)
  * 15. policy_approval     (writable)
+ * 16. policy_program      (readonly)
+ * 17. height_index        (readonly) — canonicality re-check, located by address
  */
 export declare function buildCompleteDepositPermissionedInstruction(options: CompleteDepositPermissionedOptions): Instruction;
 /** shieldPermissioned instruction options */

package/packages/sdk/dist/instructions.js

@@ -33,15 +33,19 @@ const INSTRUCTION = {
     REGISTER_TOKEN: 8,
     UPDATE_TOKEN_CONFIG: 9,
     CLAIM_FEES: 10,
-    // Deposit (11-12)
+    // Deposit (11-12, 25)
     COMPLETE_DEPOSIT: 11,
     SHIELD: 12,
+    /** OP_RETURN-free deposit: note keys ride in instruction data, proven by the
+     *  deposit address's Taproot tweak. */
+    VERIFY_DEPOSIT: 25,
     // JoinSplit (13-15) — all share n_in + n_out + n_pub + proof_source header
     TRANSACT: 13,
     UNSHIELD: 14,
     REDEEM: 15,
-    // Redemption lifecycle (16-19)
-    RESERVED_REQUEST_REDEMPTION: 16,
+    // VK registry freeze (16) — NOT part of the redemption range below
+    FREEZE_VK_REGISTRY: 16,
+    // Redemption lifecycle (17-19)
     COMPLETE_REDEMPTION: 17,
     MARK_PROCESSING: 18,
     CANCEL_REDEMPTION: 19,
@@ -308,6 +312,9 @@ export function buildCompleteRedemptionInstruction(options) {
         }
     }
     accounts.push({ address: options.accounts.tokenConfig, role: AccountRole.WRITABLE });
+    // Located by address, so the trailing position is free — this instruction already has a
+    // variable tail (change UTXO, consumed UTXOs) and the program scans rather than indexing.
+    accounts.push({ address: options.accounts.heightIndex, role: AccountRole.READONLY });
     return {
         programAddress: config.utxopiaProgramId,
         accounts,
@@ -1297,6 +1304,67 @@ export function buildCompleteDepositInstructionData(params) {
     return data;
 }
 // =============================================================================
+// UTXOpia Verify Deposit (disc=25) — OP_RETURN-free
+// =============================================================================
+/**
+ * Build utxopia verify_deposit instruction data (disc=25).
+ *
+ * The OP_RETURN-free deposit path. `notePublicKey` + `ephemeralPubkey` travel in
+ * instruction data instead of in the Bitcoin transaction, and the program proves
+ * them against the deposit output's Taproot tweak — a different key pair derives
+ * a different address, which the funding transaction did not pay. Nothing marks
+ * the deposit as a UTXOpia transaction on chain, so any wallet or exchange that
+ * can send to a P2TR address can fund it.
+ *
+ * The address must be derived from `depositTweakCommitment(npk, eph)`, NOT from
+ * the note key alone — the program hashes both, so that a caller cannot swap in
+ * an ephemeral key that leaves the note undiscoverable.
+ *
+ * Sweep mode only: `depositTxSize` must be non-zero. The receipt PDA is seeded
+ * `["deposit_receipt", txid, vout]`, so pass `depositVout` to
+ * `deriveDepositReceiptPDA` for this flow.
+ *
+ * Layout: disc(1) + sweep_txid(32) + block_height(u64 LE) + sweep_tx_size(u32 LE)
+ *         + deposit_tx_size(u32 LE) + deposit_txid(32) + ephemeral_pubkey(32)
+ *         + note_public_key(32) + deposit_vout(u32 LE) = 149 bytes
+ */
+export function buildVerifyDepositInstructionData(params) {
+    for (const [name, value] of [
+        ["sweepTxid", params.sweepTxid],
+        ["depositTxid", params.depositTxid],
+        ["ephemeralPubkey", params.ephemeralPubkey],
+        ["notePublicKey", params.notePublicKey],
+    ]) {
+        if (value.length !== 32) {
+            throw new Error(`${name} must be 32 bytes, got ${value.length}`);
+        }
+    }
+    if (params.depositTxSize === 0) {
+        throw new Error("verify_deposit is sweep-mode only: depositTxSize must be non-zero");
+    }
+    const data = new Uint8Array(149);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = INSTRUCTION.VERIFY_DEPOSIT;
+    data.set(params.sweepTxid, offset);
+    offset += 32;
+    view.setBigUint64(offset, BigInt(params.blockHeight), true);
+    offset += 8;
+    view.setUint32(offset, params.sweepTxSize, true);
+    offset += 4;
+    view.setUint32(offset, params.depositTxSize, true);
+    offset += 4;
+    data.set(params.depositTxid, offset);
+    offset += 32;
+    data.set(params.ephemeralPubkey, offset);
+    offset += 32;
+    data.set(params.notePublicKey, offset);
+    offset += 32;
+    view.setUint32(offset, params.depositVout, true);
+    offset += 4;
+    return data;
+}
+// =============================================================================
 // UTXOpia Set Pool Config (disc=2)
 // =============================================================================
 /** PoolConfig account discriminator (0x0a) */
@@ -1523,6 +1591,8 @@ export function buildCompleteDepositPermissionedInstructionData(options) {
  * 13. token_config        (writable)
  * 14. pool_config         (readonly)
  * 15. policy_approval     (writable)
+ * 16. policy_program      (readonly)
+ * 17. height_index        (readonly) — canonicality re-check, located by address
  */
 export function buildCompleteDepositPermissionedInstruction(options) {
     const config = getConfig();
@@ -1554,6 +1624,7 @@ export function buildCompleteDepositPermissionedInstruction(options) {
             { address: options.accounts.poolConfig, role: AccountRole.READONLY },
             { address: options.accounts.policyApproval, role: AccountRole.WRITABLE },
             { address: config.policyProgramId ?? config.utxopiaProgramId, role: AccountRole.READONLY },
+            { address: options.accounts.heightIndex, role: AccountRole.READONLY },
         ],
         data,
     };

package/packages/sdk/dist/spend-doc.d.ts

@@ -0,0 +1,63 @@
+/**
+ * "What am I proving?" — a canonical sentence for a shielded spend.
+ *
+ * The text is not the point. The point is that `renderSpendDoc` recomputes the
+ * proof's public signals from the numbers it is about to print and throws if
+ * they disagree, so a UI cannot caption a proof with an amount or a destination
+ * the proof does not actually contain.
+ *
+ * Nothing here changes the circuit. Every value below is already bound to the
+ * user's spending key by the in-circuit EdDSA over
+ * Poseidon(merkleRoot, boundParamsHash, nullifiers.., commitmentsOut..).
+ */
+import { type SolanaPrivacyDomainContext } from "./bound-params";
+export interface SpendDoc {
+    mode: "transfer" | "unshield" | "redeem";
+    /** Display label, e.g. "Solana Devnet". */
+    network: string;
+    /** Display label, e.g. "zkBTC". */
+    asset: string;
+    decimals: number;
+    /** Destination as shown to the user (a .sol name, a BTC address, a pubkey). */
+    recipient: string;
+    /**
+     * The destination bytes actually folded into boundParamsHash: 32-byte Solana
+     * owner for `unshield`, raw scriptPubKey for `redeem`. Omitted for `transfer`,
+     * where the destination is private and provably absent from the signals.
+     */
+    recipientBytes?: Uint8Array;
+    /** Raw units the recipient receives. */
+    amount: bigint;
+    relayerFee: bigint;
+    change: bigint;
+}
+/** The public signals of the proof about to be generated, plus what built them. */
+export interface SpendSignals {
+    /** `outputs.map(o => o.value)` from JoinSplitProofInputs. */
+    outputValues: bigint[];
+    /** The boundParamsHash going into the proof. */
+    boundParamsHash: bigint;
+    stealthDataHash: Uint8Array;
+    chainId: bigint;
+    domain: SolanaPrivacyDomainContext;
+    /** Redeem only: the on-chain requester bound into the proof. */
+    requester?: Uint8Array;
+    treeNumber?: number;
+}
+export declare class SpendDocMismatch extends Error {
+}
+/**
+ * The statement itself. Show this before the user commits; pass the same `doc`
+ * to `renderSpendDoc` when the proof is built so the string they read is the
+ * string that gets checked.
+ */
+export declare function formatSpendDoc(doc: SpendDoc): string;
+/**
+ * Render the statement, or throw if it does not describe `signals`.
+ *
+ * Checked: every amount on screen is an output value of the proof and there are
+ * no other outputs; the destination reproduces boundParamsHash.
+ * Not checked: that `recipient` (a label) names `recipientBytes` — the doc
+ * prints the bound bytes so that stays verifiable by eye.
+ */
+export declare function renderSpendDoc(doc: SpendDoc, signals: SpendSignals): string;

package/packages/sdk/dist/spend-doc.js

@@ -0,0 +1,100 @@
+/**
+ * "What am I proving?" — a canonical sentence for a shielded spend.
+ *
+ * The text is not the point. The point is that `renderSpendDoc` recomputes the
+ * proof's public signals from the numbers it is about to print and throws if
+ * they disagree, so a UI cannot caption a proof with an amount or a destination
+ * the proof does not actually contain.
+ *
+ * Nothing here changes the circuit. Every value below is already bound to the
+ * user's spending key by the in-circuit EdDSA over
+ * Poseidon(merkleRoot, boundParamsHash, nullifiers.., commitmentsOut..).
+ */
+import { computeSolanaDomainBoundParamsHash, createRedeemBoundParams, createTransferBoundParams, createUnshieldBoundParams, } from "./bound-params";
+export class SpendDocMismatch extends Error {
+}
+function fmt(raw, decimals) {
+    const neg = raw < 0n;
+    const s = (neg ? -raw : raw).toString().padStart(decimals + 1, "0");
+    const whole = s.slice(0, s.length - decimals);
+    const frac = decimals === 0 ? "" : s.slice(s.length - decimals).replace(/0+$/, "");
+    return `${neg ? "-" : ""}${whole}${frac ? `.${frac}` : ""}`;
+}
+const hex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+function sortedValues(v) {
+    return [...v].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).join(",");
+}
+function expectedBoundParamsHash(doc, s) {
+    const tree = s.treeNumber ?? 0;
+    switch (doc.mode) {
+        case "transfer":
+            return computeSolanaDomainBoundParamsHash(createTransferBoundParams(s.stealthDataHash, s.chainId, tree), s.domain);
+        case "unshield":
+            if (!doc.recipientBytes)
+                throw new SpendDocMismatch("unshield doc has no recipientBytes");
+            return computeSolanaDomainBoundParamsHash(createUnshieldBoundParams(doc.recipientBytes, s.stealthDataHash, s.chainId, tree), s.domain);
+        case "redeem":
+            if (!doc.recipientBytes)
+                throw new SpendDocMismatch("redeem doc has no recipientBytes");
+            if (!s.requester)
+                throw new SpendDocMismatch("redeem doc has no requester");
+            return computeSolanaDomainBoundParamsHash(createRedeemBoundParams(doc.recipientBytes, s.stealthDataHash, s.requester, s.chainId, tree), s.domain);
+    }
+}
+/**
+ * The statement itself. Show this before the user commits; pass the same `doc`
+ * to `renderSpendDoc` when the proof is built so the string they read is the
+ * string that gets checked.
+ */
+export function formatSpendDoc(doc) {
+    const amt = (v) => `${fmt(v, doc.decimals)} ${doc.asset}`;
+    const action = doc.mode === "redeem"
+        ? `Withdraw ${amt(doc.amount)} to Bitcoin`
+        : doc.mode === "unshield"
+            ? `Unshield ${amt(doc.amount)}`
+            : `Send ${amt(doc.amount)} privately`;
+    const lines = [
+        "UTXOpia Proof",
+        "",
+        "I AM PROVING",
+        action,
+        "",
+        "DETAILS",
+        `Network: ${doc.network}`,
+        `Amount leaving the pool: ${amt(doc.amount)}`,
+        `To: ${doc.recipient}`,
+    ];
+    if (doc.recipientBytes)
+        lines.push(`Bound destination: ${hex(doc.recipientBytes)}`);
+    if (doc.relayerFee > 0n)
+        lines.push(`Relayer fee: ${amt(doc.relayerFee)}`);
+    if (doc.change > 0n)
+        lines.push(`Change back to me: ${amt(doc.change)}`);
+    lines.push("", "ENFORCED BY THE PROOF", "Amounts: these are every output this proof creates", doc.mode === "transfer"
+        ? "Destination: private — not in the public signals. Confirm it with the recipient."
+        : "Destination: bound into boundParamsHash and re-derived onchain");
+    if (doc.mode !== "transfer") {
+        lines.push("Protocol fee: deducted onchain from pool policy, not part of this statement");
+    }
+    lines.push("", "Protocol: utxopia-spend-doc-v1");
+    return lines.join("\n");
+}
+/**
+ * Render the statement, or throw if it does not describe `signals`.
+ *
+ * Checked: every amount on screen is an output value of the proof and there are
+ * no other outputs; the destination reproduces boundParamsHash.
+ * Not checked: that `recipient` (a label) names `recipientBytes` — the doc
+ * prints the bound bytes so that stays verifiable by eye.
+ */
+export function renderSpendDoc(doc, signals) {
+    const shown = [doc.amount, doc.relayerFee, doc.change].filter((v) => v > 0n);
+    if (sortedValues(shown) !== sortedValues(signals.outputValues)) {
+        throw new SpendDocMismatch(`amounts do not match the proof outputs: doc [${sortedValues(shown)}] vs proof [${sortedValues(signals.outputValues)}]`);
+    }
+    const expected = expectedBoundParamsHash(doc, signals);
+    if (expected !== signals.boundParamsHash) {
+        throw new SpendDocMismatch("destination does not match the proof's boundParamsHash");
+    }
+    return formatSpendDoc(doc);
+}

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

@@ -200,6 +200,34 @@ export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAd
  * credits the note from that transaction.
  */
 export declare function createDirectVaultDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest", opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+/** A deposit whose address alone binds the note keys — no OP_RETURN. */
+export interface TweakDepositResult {
+    /** Taproot address to send BTC to */
+    btcAddress: string;
+    /** 32-byte x-only output key for the deposit P2TR output */
+    depositOutputKey: Uint8Array;
+    /** 32-byte note public key */
+    npk: Uint8Array;
+    /** 32-byte Ed25519 ephemeral public key */
+    ephemeralPub: Uint8Array;
+    /** sha256(npk || ephemeralPub) — the commitment the address is tweaked by */
+    tweakCommitment: Uint8Array;
+}
+/**
+ * Create a deposit for the OP_RETURN-free flow (`verify_deposit`, disc 25).
+ *
+ * The transaction carries nothing but a payment, so anything that can send to a
+ * P2TR address can fund it — a hardware wallet, an exchange withdrawal, a faucet.
+ * The note keys are recovered from instruction data at completion time and proven
+ * against this address's Taproot tweak, so substituting either key derives a
+ * different address that the funding transaction never paid.
+ *
+ * Sweep mode: the pool sweeps this address into its own custody, and that sweep
+ * is what gets SPV-verified. Register the address with the tracker BEFORE any
+ * coins are sent — a deposit with no OP_RETURN is invisible to block scanning,
+ * so an unregistered address is one nobody is watching.
+ */
+export declare function createTweakDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest"): Promise<TweakDepositResult>;
 /**
  * Create a non-interactive deposit using the current SDK config.
  *

package/packages/sdk/dist/stealth.js

@@ -248,6 +248,42 @@ export async function createDirectVaultDeposit(recipientMeta, vaultXOnlyPubkey,
         ephemeralPub,
     };
 }
+/**
+ * Create a deposit for the OP_RETURN-free flow (`verify_deposit`, disc 25).
+ *
+ * The transaction carries nothing but a payment, so anything that can send to a
+ * P2TR address can fund it — a hardware wallet, an exchange withdrawal, a faucet.
+ * The note keys are recovered from instruction data at completion time and proven
+ * against this address's Taproot tweak, so substituting either key derives a
+ * different address that the funding transaction never paid.
+ *
+ * Sweep mode: the pool sweeps this address into its own custody, and that sweep
+ * is what gets SPV-verified. Register the address with the tracker BEFORE any
+ * coins are sent — a deposit with no OP_RETURN is invisible to block scanning,
+ * so an unregistered address is one nobody is watching.
+ */
+export async function createTweakDeposit(recipientMeta, vaultXOnlyPubkey, network = "testnet") {
+    if (vaultXOnlyPubkey.length !== 32) {
+        throw new Error("vaultXOnlyPubkey must be 32 bytes");
+    }
+    const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
+    const ephemeral = ed25519GenerateKeyPair();
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, viewingPubKey);
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    const recipientMPK = bytesToBigint(recipientMeta.mpk);
+    const npk = bigintToBytes(computeNPKSync(recipientMPK, stealthScalar));
+    const ephemeralPub = new Uint8Array(ephemeral.pubKey);
+    const { depositTweakCommitment, deriveTaprootAddress } = await import("./taproot");
+    const tweakCommitment = depositTweakCommitment(npk, ephemeralPub);
+    const { address, outputKey } = deriveTaprootAddress(tweakCommitment, network, vaultXOnlyPubkey);
+    return {
+        btcAddress: address,
+        depositOutputKey: outputKey,
+        npk,
+        ephemeralPub,
+        tweakCommitment,
+    };
+}
 /**
  * Create a non-interactive deposit using the current SDK config.
  *

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

@@ -23,6 +23,17 @@ export declare function deriveTaprootAddress(commitment: Uint8Array, network?: "
     outputKey: Uint8Array;
     tweak: Uint8Array;
 };
+/**
+ * Commitment a `verify_deposit` (disc 25) deposit address is derived from.
+ *
+ * Both keys are hashed in. Binding the note key alone would leave the ephemeral
+ * pubkey caller-chosen on the Solana side: the credited amount and owner would
+ * still be right, but a substituted ephemeral key makes the stealth announcement
+ * undecryptable and the recipient never finds their note.
+ *
+ * Feed the result to `deriveTaprootAddress` as the commitment.
+ */
+export declare function depositTweakCommitment(notePublicKey: Uint8Array, ephemeralPubkey: Uint8Array): Uint8Array;
 /**
  * Verify that a Taproot address is correctly derived from a commitment
  *

package/packages/sdk/dist/taproot.js

@@ -70,6 +70,25 @@ export function deriveTaprootAddress(commitment, network = "testnet", internalKe
         tweak,
     };
 }
+/**
+ * Commitment a `verify_deposit` (disc 25) deposit address is derived from.
+ *
+ * Both keys are hashed in. Binding the note key alone would leave the ephemeral
+ * pubkey caller-chosen on the Solana side: the credited amount and owner would
+ * still be right, but a substituted ephemeral key makes the stealth announcement
+ * undecryptable and the recipient never finds their note.
+ *
+ * Feed the result to `deriveTaprootAddress` as the commitment.
+ */
+export function depositTweakCommitment(notePublicKey, ephemeralPubkey) {
+    if (notePublicKey.length !== 32 || ephemeralPubkey.length !== 32) {
+        throw new Error("notePublicKey and ephemeralPubkey must be 32 bytes");
+    }
+    const material = new Uint8Array(64);
+    material.set(notePublicKey, 0);
+    material.set(ephemeralPubkey, 32);
+    return sha256(material);
+}
 /**
  * Verify that a Taproot address is correctly derived from a commitment
  *