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

package/{packages/sdk/dist → 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 → 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,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, 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";
 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, 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";
@@ -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, 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, 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
 // ==========================================================================
@@ -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, depositEphemeralKeyPair, depositViewingNode, outgoingViewingNode, outgoingEphemeralKeyPair, findNextSendIndex, 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, buildVerifyDepositPermissionedInstructionData, 
 // Pool config (disc 2) builder + parser
 buildSetPoolConfigInstructionData, parsePoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, } from "./instructions";
 // ==========================================================================

package/{packages/sdk/dist → 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 tapleaf. */
+    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,55 @@ 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 tapleaf — a different key pair derives a
+ * different leaf, and so 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.
+ *
+ * Derive the address with `deriveDepositAddress(depositTweakCommitment(npk, eph),
+ * ikaXOnlyPubkey)`. Both keys are hashed into the leaf, so a caller cannot swap
+ * in an ephemeral key that leaves the note undiscoverable.
+ *
+ * No sweep: the deposit output's tapleaf names the pool's own dWallet key, so it
+ * is already under pool custody and is recorded as a pool UTXO directly. The
+ * SPV-verified transaction must therefore BE the deposit — `depositTxSize` is 0
+ * and `depositTxid` defaults to `sweepTxid`. 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;
+/**
+ * Build utxopia verify_deposit_permissioned instruction data (disc=26).
+ *
+ * `buildVerifyDepositInstructionData`'s payload with a different discriminator
+ * and an auditor ciphertext appended. The tapleaf already tells the pools apart —
+ * each carries its own Ika custody key — but that is not the same as clearing the
+ * pool's policy, which is what a permissioned pool exists for.
+ *
+ * The one-time PolicyApproval is bound to the WHOLE payload, ciphertext included,
+ * so these exact bytes must be the ones approved.
+ */
+export declare function buildVerifyDepositPermissionedInstructionData(params: Parameters<typeof buildVerifyDepositInstructionData>[0] & {
+    auditorCiphertext?: Uint8Array;
+}): Uint8Array;
 /** PoolConfig account discriminator (0x0a) */
 export declare const POOL_CONFIG_DISCRIMINATOR = 10;
 /** Serialized PoolConfig account length (bytes) */
@@ -901,6 +975,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 +1029,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 → dist}/instructions.js

@@ -8,6 +8,7 @@
  */
 import { AccountRole, } from "@solana/kit";
 import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex as toHex } from "./crypto";
 import { address, getConfig, TOKEN_2022_PROGRAM_ID } from "./config";
 import { resolveAuditorCiphertext } from "./auditor-ciphertext";
 import { MAGICBLOCK_EPHEMERAL_VAULT_ID, MAGICBLOCK_DELEGATION_PROGRAM_ID, MAGICBLOCK_MAGIC_CONTEXT_ID, MAGICBLOCK_MAGIC_PROGRAM_ID, MAGICBLOCK_MAX_PER_MEMBERS, MAGICBLOCK_PERMISSION_PROGRAM_ID, MAGICBLOCK_PER_MEMBER_FLAGS, } from "./magicblock";
@@ -33,15 +34,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 tapleaf. */
+    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,
@@ -68,6 +73,8 @@ const INSTRUCTION = {
 const PERMISSIONED_DISC = {
     INITIALIZE_PERMISSIONED: 21,
     COMPLETE_DEPOSIT_PERMISSIONED: 22,
+    /** Same binding as VERIFY_DEPOSIT, plus the permissioned pool's policy gate. */
+    VERIFY_DEPOSIT_PERMISSIONED: 26,
     SHIELD_PERMISSIONED: 23,
     REGISTER_EXIT_DESTINATION: 39,
 };
@@ -308,6 +315,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 +1307,94 @@ 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 tapleaf — a different key pair derives a
+ * different leaf, and so 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.
+ *
+ * Derive the address with `deriveDepositAddress(depositTweakCommitment(npk, eph),
+ * ikaXOnlyPubkey)`. Both keys are hashed into the leaf, so a caller cannot swap
+ * in an ephemeral key that leaves the note undiscoverable.
+ *
+ * No sweep: the deposit output's tapleaf names the pool's own dWallet key, so it
+ * is already under pool custody and is recorded as a pool UTXO directly. The
+ * SPV-verified transaction must therefore BE the deposit — `depositTxSize` is 0
+ * and `depositTxid` defaults to `sweepTxid`. 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) {
+    const depositTxid = params.depositTxid ?? params.sweepTxid;
+    for (const [name, value] of [
+        ["sweepTxid", params.sweepTxid],
+        ["depositTxid", 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) {
+        throw new Error("verify_deposit takes no second transaction: depositTxSize must be 0");
+    }
+    if (toHex(depositTxid) !== toHex(params.sweepTxid)) {
+        throw new Error("verify_deposit proves the deposit itself: depositTxid must equal sweepTxid");
+    }
+    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, 0, true);
+    offset += 4; // no second transaction
+    data.set(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;
+}
+/**
+ * Build utxopia verify_deposit_permissioned instruction data (disc=26).
+ *
+ * `buildVerifyDepositInstructionData`'s payload with a different discriminator
+ * and an auditor ciphertext appended. The tapleaf already tells the pools apart —
+ * each carries its own Ika custody key — but that is not the same as clearing the
+ * pool's policy, which is what a permissioned pool exists for.
+ *
+ * The one-time PolicyApproval is bound to the WHOLE payload, ciphertext included,
+ * so these exact bytes must be the ones approved.
+ */
+export function buildVerifyDepositPermissionedInstructionData(params) {
+    const base = buildVerifyDepositInstructionData(params);
+    const ciphertext = params.auditorCiphertext ?? new Uint8Array(0);
+    const data = new Uint8Array(base.length + ciphertext.length);
+    data.set(base, 0);
+    data.set(ciphertext, base.length);
+    data[0] = PERMISSIONED_DISC.VERIFY_DEPOSIT_PERMISSIONED;
+    return data;
+}
+// =============================================================================
 // UTXOpia Set Pool Config (disc=2)
 // =============================================================================
 /** PoolConfig account discriminator (0x0a) */
@@ -1523,6 +1621,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 +1654,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,
     };