@utxopia/sdk 0.1.0-alpha.1

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

@@ -0,0 +1,177 @@
+/**
+ * UTXOPIA SDK Configuration
+ *
+ * Centralized configuration for all network-specific addresses, endpoints, and settings.
+ * This is the SINGLE SOURCE OF TRUTH for all on-chain addresses and configuration.
+ *
+ * When deploying to a new network or updating addresses:
+ * 1. Update the relevant network config below
+ * 2. Bump SDK version
+ * 3. Publish to npm
+ *
+ * @module config
+ */
+import { type Address } from "@solana/kit";
+/**
+ * Safe address wrapper — catches codec validation errors that occur during
+ * Vercel's build phase when @solana/kit validates byte lengths at module load.
+ * Returns the input string cast as Address on failure (safe for config objects
+ * that are only used at runtime, not build time).
+ */
+export declare function address(input: string): Address;
+export type NetworkType = "devnet" | "mainnet" | "localnet";
+export type AppNetworkId = NetworkType | "devnet-regtest";
+export interface NetworkConfig {
+    /** Network identifier */
+    network: NetworkType;
+    /** UTXOpia main program ID */
+    utxopiaProgramId: Address;
+    /** Minimal PER PolicyApproval coprocessor. Falls back to the asset program on older networks. */
+    policyProgramId?: Address;
+    /** BTC Light Client program ID (manages light client + block headers for SPV) */
+    btcLightClientProgramId: Address;
+    /** ChadBuffer program ID (for SPV verification) */
+    chadbufferProgramId: Address;
+    /** Token-2022 program ID */
+    token2022ProgramId: Address;
+    /** Associated Token Account program ID */
+    ataProgramId: Address;
+    /** Pool State PDA address */
+    poolStatePda: Address;
+    /** Commitment Tree PDA address */
+    commitmentTreePda: Address;
+    /** zkBTC Mint address (Token-2022) */
+    zkbtcMint: Address;
+    /** Pool Vault (ATA for pool holding zkBTC) */
+    poolVault: Address;
+    /** Solana RPC endpoint */
+    solanaRpcUrl: string;
+    /** Solana WebSocket endpoint */
+    solanaWsUrl: string;
+    /** Bitcoin network */
+    bitcoinNetwork: "mainnet" | "testnet" | "testnet4" | "signet" | "regtest";
+    /** Esplora API endpoint */
+    esploraUrl: string;
+    /** Base URL for circuit artifacts */
+    circuitCdnUrl: string;
+    /** Groth16 verifier program ID (browser proof generation via snarkjs) */
+    groth16VerifierProgramId: Address;
+    /** VK hashes for each circuit type (32 bytes each, hex-encoded) */
+    vkHashes: {
+        claim: string;
+        split: string;
+        spendPartialPublic: string;
+    };
+    /** VK hashes for JoinSplit variants, keyed by "NxM" (e.g., "1x2" -> "abc...") */
+    joinSplitVkHashes: Record<string, string>;
+    /** Ika dWallet x-only secp256k1 pubkey (hex, 64 chars = 32 bytes).
+     *  The sole Taproot internal key for deposit-address derivation. Read from
+     *  `pool_config.ika_dwallet_xonly_pubkey` (offset 68..100) on chain. All-zero
+     *  indicates the pool's PoolConfig has not been initialized yet. */
+    ikaDwalletXOnlyPubkey: string;
+    /** BTC deposit custody mode.
+     *  "sweep" keeps legacy per-deposit tweaked Taproot addresses.
+     *  "direct" sends deposits directly to the Ika raw x-only vault address. */
+    depositMode?: "sweep" | "direct" | "direct_vault" | "ika_direct";
+    /** SPL Name Service program ID (stores name records / PDAs) */
+    snsNameServiceProgramId: string;
+    /** SNS Registrar program ID (for domain registration) */
+    snsRegistrarProgramId: string;
+    /** SNS Sub-Registrar program ID (for subdomain registration) */
+    snsSubRegistrarProgramId: string;
+    /** SNS root domain account (.sol TLD — differs per network) */
+    snsRootDomain: string;
+    /** Parent domain for stealth address subdomains (e.g., "utxopia" for *.utxopia.sol) */
+    snsParentDomain: string;
+    /** SNS reverse lookup class key (used for reverse name resolution) */
+    snsReverseLookupClass: string;
+    /** Stealth data version expected in SNS records */
+    snsStealthDataVersion: number;
+}
+/** Legacy Token Program ID */
+export declare const TOKEN_PROGRAM_ID: Address;
+/** Token-2022 Program ID */
+export declare const TOKEN_2022_PROGRAM_ID: Address;
+/** Associated Token Account Program ID */
+export declare const ATA_PROGRAM_ID: Address;
+/** ChadBuffer Program ID (deployed to devnet 2025-01-30) */
+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.
+ */
+export declare const DEVNET_CONFIG: NetworkConfig;
+/**
+ * Mainnet Configuration (placeholder - not yet deployed)
+ */
+export declare const MAINNET_CONFIG: NetworkConfig;
+/**
+ * Localnet Configuration (for local development)
+ * Synced with .localnet-config.json (2026-02-22)
+ */
+export declare const LOCALNET_CONFIG: NetworkConfig;
+/**
+ * Get the current network configuration.
+ * Respects NEXT_PUBLIC_BTC_NETWORK env var to override Bitcoin network
+ * (e.g., "testnet" for testnet3, "testnet4" for testnet4).
+ */
+export declare function getConfig(): NetworkConfig;
+/**
+ * Set the network configuration
+ *
+ * @param network - Network type or custom config
+ * @throws Error if mainnet is selected (not yet deployed)
+ */
+export declare function setConfig(network: AppNetworkId | NetworkConfig): void;
+/**
+ * Create a custom configuration by overriding specific values
+ *
+ * @param base - Base configuration to extend
+ * @param overrides - Values to override
+ */
+export declare function createConfig(base: NetworkConfig, overrides: Partial<NetworkConfig>): NetworkConfig;
+/**
+ * Initialize SDK configuration with optional overrides.
+ *
+ * Reads `utxopiaProgramId` and `zkbtcMint` from params, then env vars, then
+ * falls back to DEVNET_CONFIG defaults. All PDAs are auto-derived from these
+ * two values.
+ *
+ * Env vars checked (in order):
+ * - NEXT_PUBLIC_UTXOPIA_PROGRAM_ID / UTXOPIA_PROGRAM_ID
+ * - NEXT_PUBLIC_ZKBTC_MINT / UTXOPIA_ZKBTC_MINT
+ *
+ * @example
+ * // Use env vars (set NEXT_PUBLIC_UTXOPIA_PROGRAM_ID + NEXT_PUBLIC_ZKBTC_MINT)
+ * await initConfig();
+ *
+ * // Or pass explicitly
+ * await initConfig({ utxopiaProgramId: "...", zkbtcMint: "..." });
+ */
+export type NetworkId = AppNetworkId;
+export declare function initConfig(overrides?: {
+    network?: NetworkId;
+    utxopiaProgramId?: string;
+    policyProgramId?: string;
+    zkbtcMint?: string;
+    solanaRpcUrl?: string;
+    ikaDwalletXOnlyPubkey?: string;
+    depositMode?: "sweep" | "direct" | "direct_vault" | "ika_direct";
+}): Promise<NetworkConfig>;
+/** Default UTXOpia program ID (from current config) */
+export declare const UTXOPIA_PROGRAM_ID: Address;
+export declare const UTXOPIA_POLICY_PROGRAM_ID: Address;
+/** BTC Light Client program ID (manages light client + block headers) */
+export declare const BTC_LIGHT_CLIENT_PROGRAM_ID: Address;
+export declare const SDK_VERSION = "3.3.0";
+/** JoinSplit Merkle tree depth */
+export declare const JOINSPLIT_TREE_DEPTH = 16;
+export declare const DEPLOYMENT_INFO: {
+    version: string;
+    deployedAt: string;
+    network: NetworkType;
+    features: string[];
+    notes: string;
+};

package/packages/sdk/dist/config.js

@@ -0,0 +1,426 @@
+/**
+ * UTXOPIA SDK Configuration
+ *
+ * Centralized configuration for all network-specific addresses, endpoints, and settings.
+ * This is the SINGLE SOURCE OF TRUTH for all on-chain addresses and configuration.
+ *
+ * When deploying to a new network or updating addresses:
+ * 1. Update the relevant network config below
+ * 2. Bump SDK version
+ * 3. Publish to npm
+ *
+ * @module config
+ */
+import { address as _address, getAddressEncoder, getProgramDerivedAddress } from "@solana/kit";
+/**
+ * Safe address wrapper — catches codec validation errors that occur during
+ * Vercel's build phase when @solana/kit validates byte lengths at module load.
+ * Returns the input string cast as Address on failure (safe for config objects
+ * that are only used at runtime, not build time).
+ */
+export function address(input) {
+    try {
+        return _address(input);
+    }
+    catch {
+        console.warn(`[utxopia-sdk] address() failed for "${input.slice(0, 12)}..." — returning raw string (build-time fallback)`);
+        return input;
+    }
+}
+// =============================================================================
+// Program IDs (Constants)
+// =============================================================================
+/** Legacy Token Program ID */
+export const TOKEN_PROGRAM_ID = address("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+/** Token-2022 Program ID */
+export const TOKEN_2022_PROGRAM_ID = address("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");
+/** Associated Token Account Program ID */
+export const ATA_PROGRAM_ID = address("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+/** ChadBuffer Program ID (deployed to devnet 2025-01-30) */
+export const CHADBUFFER_PROGRAM_ID = address("C5RpjtTMFXKVZCtXSzKXD4CDNTaWBg3dVeMfYvjZYHDF");
+/** ChadBuffer Program ID for localnet testing */
+export const LOCALNET_CHADBUFFER_PROGRAM_ID = address("EgWyMVFZewHmjJ9GGvVBTyaC376Xp7qu7CAFjWYPYYDv");
+// =============================================================================
+// Network Configurations
+// =============================================================================
+/**
+ * Fresh multi-pool devnet deployment (2026-07-26).
+ * The default domain is public; institution pools are selected explicitly.
+ */
+export const DEVNET_CONFIG = {
+    network: "devnet",
+    utxopiaProgramId: address("CvfSyACR8xemPdeJsB3D8Xh15rKUQ3b5c1PvnmABCBJp"),
+    policyProgramId: address("9asWYKVriWGpExW5xM44ChHjZtispkLCiWKkM8SQi8Rs"),
+    btcLightClientProgramId: address("859B7kw1xDyY8rzSXY6pAPNxaAsPWrsaAPJk3iivd43g"),
+    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"),
+    // RPC Endpoints
+    solanaRpcUrl: "https://api.devnet.solana.com",
+    solanaWsUrl: "wss://api.devnet.solana.com",
+    // Bitcoin Network
+    bitcoinNetwork: "testnet4",
+    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
+    // VK Hashes (SHA256 of serialized VK bytes, generated from circom trusted setup)
+    vkHashes: {
+        claim: "7af0e702e7b595fbdb62fd268e6c529481003e07957e0f60e4fb23cd9fe6a77f",
+        split: "00fb9e4c3fcc7b99fec5191370b516537f74831ad868a18c4ab2d519f332cc4f",
+        spendPartialPublic: "732126aaec8355efdfb1b96aee1c9014506c99815a81057edbefd775b1b10663",
+    },
+    // JoinSplit VK hashes (populated after trusted setup for new circuits)
+    joinSplitVkHashes: {
+        "1x1": "745d536fb3a86424ee9560cb7b630bb0eb3d3c3af06c85bcda1eb7bcc5b1a07a",
+        "1x2": "f782d4bc2f696417688cdec3cb4f822d6961892192e13e8842505bd8d119fa6d",
+        "2x1": "3af6cdad3c1f4de9e088975a1ac5b20e0445d7f3fea0a5038f300102cf98fd98",
+        "2x2": "6fffc4962028d0ac69f4d7877badc9f5adea4b83e6224ebb8db22657e847e7b8",
+        "1x3": "ca396f36bbd1b07255b7a2f5585cedb4a51f925149747dd6ab4f695d19aa6ff8",
+        "3x1": "4e0c5cbea0ccf80302d2589e41a2f22e19287f5acc5d0577451680fd909e1942",
+        "2x3": "bf398583f064de96560cb9092b1357b0d742991a88f18a351e5b8793fed4b7a7",
+        "3x2": "9da8d33d57896e76aadf3f5c66295774bd3273511af6e733ca7f9446ab58d42e",
+        "1x4": "01728b82e810a8ba604cc66aa6a563444d18f4598c402d11767d0a7e5049a9be",
+        "4x1": "0362b306b17dae916d836d9448a26c97e51b1b0a1a0ed052ebfbd4800e5000cf",
+    },
+    // Ika dWallet x-only pubkey — populated by ./scripts/sync-env.sh from devnet-state.json.
+    ikaDwalletXOnlyPubkey: "0000000000000000000000000000000000000000000000000000000000000000",
+    // SNS Subdomain Resolution (devnet)
+    snsNameServiceProgramId: "namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX", // SPL Name Service (devnet)
+    snsRegistrarProgramId: "snshBoEQ9jx4QoHBpZDQPYdNCtw7RMxJvYrKFEhwaPJ", // SNS Registrar (devnet)
+    snsSubRegistrarProgramId: "31tT5CmpphAtRL3mstu962zeYH7C6TEkJWLB5nYxciBB", // Sub-Registrar (devnet)
+    snsRootDomain: "5eoDkP6vCQBXqDV9YN2NdUs3nmML3dMRNmEYpiyVNBm2", // .sol TLD (devnet)
+    snsParentDomain: "utxopia",
+    snsReverseLookupClass: "7NbD1vprif6apthEZAqhRfYuhrqnuderB8qpnfXGCc8H", // Reverse lookup class (devnet)
+    snsStealthDataVersion: 1,
+};
+/**
+ * Mainnet Configuration (placeholder - not yet deployed)
+ */
+export const MAINNET_CONFIG = {
+    network: "mainnet",
+    // Program IDs (placeholder - update when deployed)
+    utxopiaProgramId: address("11111111111111111111111111111111"),
+    btcLightClientProgramId: address("11111111111111111111111111111111"),
+    chadbufferProgramId: CHADBUFFER_PROGRAM_ID,
+    token2022ProgramId: TOKEN_2022_PROGRAM_ID,
+    ataProgramId: ATA_PROGRAM_ID,
+    // Deployed Accounts (placeholder - update when deployed)
+    poolStatePda: address("11111111111111111111111111111111"),
+    commitmentTreePda: address("11111111111111111111111111111111"),
+    zkbtcMint: address("11111111111111111111111111111111"),
+    poolVault: address("11111111111111111111111111111111"),
+    // RPC Endpoints
+    solanaRpcUrl: "https://api.mainnet-beta.solana.com",
+    solanaWsUrl: "wss://api.mainnet-beta.solana.com",
+    // Bitcoin Network
+    bitcoinNetwork: "mainnet",
+    esploraUrl: "https://mempool.space/api",
+    // Circuit CDN
+    circuitCdnUrl: "https://circuit.utxopia.com",
+    // Groth16 Verifier (placeholder)
+    groth16VerifierProgramId: address("11111111111111111111111111111111"),
+    // VK Hashes (placeholder - update when deployed)
+    vkHashes: {
+        claim: "0000000000000000000000000000000000000000000000000000000000000000",
+        split: "0000000000000000000000000000000000000000000000000000000000000000",
+        spendPartialPublic: "171daac7e5ff45e2d0e736ac0d28f5fe8e0cc8fc9961efa4dd9ee18e4413f755",
+    },
+    joinSplitVkHashes: {},
+    ikaDwalletXOnlyPubkey: "0000000000000000000000000000000000000000000000000000000000000000",
+    // SNS Subdomain Resolution (mainnet)
+    snsNameServiceProgramId: "namesLPneVptA9Z5rqUDD9tMTWEJwofgaYwp8cawRkX", // SPL Name Service (mainnet)
+    snsRegistrarProgramId: "jCebN34bUfdeUYJT13J1yG16XWQpt5PDx6Mse9GUqhR", // SNS Registrar (mainnet)
+    snsSubRegistrarProgramId: "2KkyPzjaAYaz2ojQZ9P3xYakLd96B5UH6a2isLaZ4Cgs", // Sub-Registrar (mainnet)
+    snsRootDomain: "58PwtjSDuFHuUkYjH9BYod9SZaELfsvdrNMryy9iYNvo", // .sol TLD (mainnet)
+    snsParentDomain: "utxopia",
+    snsReverseLookupClass: "33m47vH6Eav6jr5Ry86XjhRft2jRBLDnDgPSHoquXi2Z", // Reverse lookup class (mainnet)
+    snsStealthDataVersion: 1,
+};
+/**
+ * Localnet Configuration (for local development)
+ * Synced with .localnet-config.json (2026-02-22)
+ */
+export const LOCALNET_CONFIG = {
+    network: "localnet",
+    // Program IDs
+    utxopiaProgramId: address("2dBmKyfLibkqdxgyEWUhHos3g56oU2wXLVrucY2dCpGV"),
+    btcLightClientProgramId: address("Ho6UTeF8yFnRdCK15tSZtcJozvkDABJZWYxkgGyWAfyq"),
+    chadbufferProgramId: LOCALNET_CHADBUFFER_PROGRAM_ID,
+    token2022ProgramId: TOKEN_2022_PROGRAM_ID,
+    ataProgramId: ATA_PROGRAM_ID,
+    // Deployed Accounts (synced with .localnet-config.json 2026-02-23)
+    poolStatePda: address("E6DVestxC5dn5ixvLa3FcYodcVtwUAyanpVPbs4y3p16"),
+    commitmentTreePda: address("JCiGqC1a1rjfqk2dqcybU2e3FQjAQ19x8ts9fQCtTFCq"),
+    zkbtcMint: address("CHg1f85uxw4HrVkj3ianLezVAJTv29VcCWiBxjZ4YFdF"),
+    poolVault: address("7vpuYKngG75Km1bbZ5TZJZzRn2BBtkh9BaqPS814tPLg"),
+    // RPC Endpoints
+    solanaRpcUrl: "http://127.0.0.1:8899",
+    solanaWsUrl: "ws://127.0.0.1:8900",
+    // Bitcoin Network (regtest for local dev)
+    bitcoinNetwork: "regtest",
+    esploraUrl: "http://localhost:2140",
+    // Circuit CDN (use local files for development)
+    circuitCdnUrl: "/circuits",
+    // Groth16 Verifier: verification is inline in the UTXOpia program
+    groth16VerifierProgramId: address("RoqAPQgZ5ztdhV3jHBKgTmeLBAfyYcaBsjKiXHNwXf3"),
+    // VK Hashes (same as devnet - generated from same trusted setup)
+    vkHashes: {
+        claim: "7af0e702e7b595fbdb62fd268e6c529481003e07957e0f60e4fb23cd9fe6a77f",
+        split: "00fb9e4c3fcc7b99fec5191370b516537f74831ad868a18c4ab2d519f332cc4f",
+        spendPartialPublic: "732126aaec8355efdfb1b96aee1c9014506c99815a81057edbefd775b1b10663",
+    },
+    joinSplitVkHashes: {
+        "1x1": "745d536fb3a86424ee9560cb7b630bb0eb3d3c3af06c85bcda1eb7bcc5b1a07a",
+        "1x2": "f782d4bc2f696417688cdec3cb4f822d6961892192e13e8842505bd8d119fa6d",
+        "2x1": "3af6cdad3c1f4de9e088975a1ac5b20e0445d7f3fea0a5038f300102cf98fd98",
+        "2x2": "6fffc4962028d0ac69f4d7877badc9f5adea4b83e6224ebb8db22657e847e7b8",
+    },
+    // Ika dWallet x-only pubkey — populated by ./scripts/sync-env.sh from localnet-state.json.
+    ikaDwalletXOnlyPubkey: "0000000000000000000000000000000000000000000000000000000000000000",
+    // SNS Subdomain Resolution (not available on localnet)
+    snsNameServiceProgramId: "",
+    snsRegistrarProgramId: "",
+    snsSubRegistrarProgramId: "",
+    snsRootDomain: "",
+    snsParentDomain: "",
+    snsReverseLookupClass: "",
+    snsStealthDataVersion: 1,
+};
+// =============================================================================
+// Default Configuration
+// =============================================================================
+/** Current active configuration (defaults to devnet, overridden by env vars) */
+let currentConfig = DEVNET_CONFIG;
+// Eagerly apply env var overrides synchronously (program ID + mint only).
+// PDA derivation happens async in initConfig(), but at least getConfig()
+// returns the correct program ID immediately.
+if (typeof process !== "undefined") {
+    const _pid = process.env?.NEXT_PUBLIC_UTXOPIA_PROGRAM_ID || process.env?.UTXOPIA_PROGRAM_ID;
+    const _mint = process.env?.NEXT_PUBLIC_ZKBTC_MINT || process.env?.UTXOPIA_ZKBTC_MINT;
+    if (_pid) {
+        currentConfig = { ...currentConfig, utxopiaProgramId: address(_pid), groth16VerifierProgramId: address(_pid) };
+    }
+    if (_mint) {
+        currentConfig = { ...currentConfig, zkbtcMint: address(_mint) };
+    }
+}
+/** Esplora URL for a given Bitcoin network */
+function esploraUrlForNetwork(net) {
+    switch (net) {
+        case "mainnet": return "https://mempool.space/api";
+        case "testnet": return "https://mempool.space/testnet/api";
+        case "testnet4": return "https://mempool.space/testnet4/api";
+        case "signet": return "https://mempool.space/signet/api";
+        case "regtest": return "http://localhost:2140";
+        default: return `https://mempool.space/${net}/api`;
+    }
+}
+function normalizeAppNetwork(network) {
+    switch (network) {
+        case "mainnet":
+            return "mainnet";
+        case "localnet":
+            return "localnet";
+        case "devnet":
+        case "devnet-regtest":
+        default:
+            return "devnet";
+    }
+}
+function bitcoinNetworkForAppNetwork(network) {
+    switch (network) {
+        case "localnet":
+        case "devnet-regtest":
+            return "regtest";
+        case "devnet":
+            return "testnet4";
+        case "mainnet":
+            return "mainnet";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Get the current network configuration.
+ * Respects NEXT_PUBLIC_BTC_NETWORK env var to override Bitcoin network
+ * (e.g., "testnet" for testnet3, "testnet4" for testnet4).
+ */
+export function getConfig() {
+    const btcNetOverride = typeof process !== "undefined" && process.env?.NEXT_PUBLIC_BTC_NETWORK;
+    if (btcNetOverride && btcNetOverride !== currentConfig.bitcoinNetwork) {
+        return {
+            ...currentConfig,
+            bitcoinNetwork: btcNetOverride,
+            esploraUrl: esploraUrlForNetwork(btcNetOverride),
+        };
+    }
+    return currentConfig;
+}
+/**
+ * Set the network configuration
+ *
+ * @param network - Network type or custom config
+ * @throws Error if mainnet is selected (not yet deployed)
+ */
+export function setConfig(network) {
+    if (typeof network === "string") {
+        const baseNetwork = normalizeAppNetwork(network);
+        switch (baseNetwork) {
+            case "devnet":
+                currentConfig = DEVNET_CONFIG;
+                break;
+            case "mainnet":
+                throw new Error("Mainnet is not yet deployed. " +
+                    "UTXOpia is currently available on devnet only. " +
+                    "Use setConfig('devnet') or wait for mainnet deployment announcement.");
+            case "localnet":
+                currentConfig = LOCALNET_CONFIG;
+                break;
+            default:
+                throw new Error(`Unknown network: ${network}`);
+        }
+        const bitcoinNetwork = bitcoinNetworkForAppNetwork(network);
+        if (bitcoinNetwork) {
+            currentConfig = {
+                ...currentConfig,
+                bitcoinNetwork,
+                esploraUrl: esploraUrlForNetwork(bitcoinNetwork),
+            };
+        }
+    }
+    else {
+        // Check if custom config is using placeholder mainnet addresses
+        if (network.network === "mainnet" && network.utxopiaProgramId === MAINNET_CONFIG.utxopiaProgramId) {
+            throw new Error("Cannot use placeholder mainnet configuration. " +
+                "Mainnet is not yet deployed.");
+        }
+        currentConfig = network;
+    }
+}
+/**
+ * Create a custom configuration by overriding specific values
+ *
+ * @param base - Base configuration to extend
+ * @param overrides - Values to override
+ */
+export function createConfig(base, overrides) {
+    return { ...base, ...overrides };
+}
+export async function initConfig(overrides) {
+    // Pick base config from network: param > env > devnet
+    const appNetworkId = overrides?.network ||
+        (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 config = { ...baseConfig };
+    const appBitcoinNetwork = bitcoinNetworkForAppNetwork(appNetworkId);
+    const btcNetOverride = typeof process !== "undefined" && process.env?.NEXT_PUBLIC_BTC_NETWORK;
+    const bitcoinNetwork = btcNetOverride || appBitcoinNetwork;
+    if (bitcoinNetwork) {
+        config.bitcoinNetwork = bitcoinNetwork;
+        config.esploraUrl = esploraUrlForNetwork(bitcoinNetwork);
+    }
+    // Resolve program ID: param > env > base config default
+    const programId = overrides?.utxopiaProgramId ||
+        (typeof process !== "undefined" && (process.env?.NEXT_PUBLIC_UTXOPIA_PROGRAM_ID || process.env?.UTXOPIA_PROGRAM_ID)) ||
+        undefined;
+    const policyProgramId = overrides?.policyProgramId ||
+        (typeof process !== "undefined" &&
+            (process.env?.NEXT_PUBLIC_UTXOPIA_POLICY_PROGRAM_ID ||
+                process.env?.UTXOPIA_POLICY_PROGRAM_ID)) ||
+        undefined;
+    if (policyProgramId) {
+        config.policyProgramId = address(policyProgramId);
+    }
+    // Resolve mint: param > env > default
+    const mint = overrides?.zkbtcMint ||
+        (typeof process !== "undefined" && (process.env?.NEXT_PUBLIC_ZKBTC_MINT || process.env?.UTXOPIA_ZKBTC_MINT)) ||
+        config.zkbtcMint;
+    // Resolve RPC URL for on-chain fetching
+    const rpcUrl = overrides?.solanaRpcUrl ||
+        (typeof process !== "undefined" && (process.env?.NEXT_PUBLIC_SOLANA_RPC_URL || process.env?.UTXOPIA_SOLANA_RPC)) ||
+        undefined;
+    if (programId) {
+        config.utxopiaProgramId = address(programId);
+        config.groth16VerifierProgramId = address(programId); // same program
+        // Fresh multi-pool deployments use zkBTC mint as the pool namespace.
+        const encoder = getAddressEncoder();
+        config.zkbtcMint = address(mint);
+        const [poolStatePda] = await getProgramDerivedAddress({
+            programAddress: config.utxopiaProgramId,
+            seeds: [
+                new TextEncoder().encode("pool_state"),
+                encoder.encode(config.zkbtcMint),
+            ],
+        });
+        const treeIndex = new Uint8Array(4);
+        const [commitmentTreePda] = await getProgramDerivedAddress({
+            programAddress: config.utxopiaProgramId,
+            seeds: [
+                new TextEncoder().encode("commitment_tree"),
+                encoder.encode(poolStatePda),
+                treeIndex,
+            ],
+        });
+        config.poolStatePda = poolStatePda;
+        config.commitmentTreePda = commitmentTreePda;
+    }
+    if (mint) {
+        config.zkbtcMint = address(mint);
+        // Derive pool vault (ATA: seeds = [owner, TOKEN_2022, mint] under ATA program)
+        const encoder = getAddressEncoder();
+        const [poolVault] = await getProgramDerivedAddress({
+            programAddress: config.ataProgramId,
+            seeds: [
+                encoder.encode(config.poolStatePda),
+                encoder.encode(config.token2022ProgramId),
+                encoder.encode(config.zkbtcMint),
+            ],
+        });
+        config.poolVault = poolVault;
+    }
+    // Apply Ika dWallet x-only pubkey override (sole Taproot custody key)
+    if (overrides?.ikaDwalletXOnlyPubkey) {
+        config.ikaDwalletXOnlyPubkey = overrides.ikaDwalletXOnlyPubkey;
+    }
+    if (overrides?.depositMode) {
+        config.depositMode = overrides.depositMode;
+    }
+    currentConfig = config;
+    return config;
+}
+// =============================================================================
+// Convenience Exports
+// =============================================================================
+/** Default UTXOpia program ID (from current config) */
+export const UTXOPIA_PROGRAM_ID = DEVNET_CONFIG.utxopiaProgramId;
+export const UTXOPIA_POLICY_PROGRAM_ID = DEVNET_CONFIG.policyProgramId ?? DEVNET_CONFIG.utxopiaProgramId;
+/** BTC Light Client program ID (manages light client + block headers) */
+export const BTC_LIGHT_CLIENT_PROGRAM_ID = DEVNET_CONFIG.btcLightClientProgramId;
+// =============================================================================
+// Version Info
+// =============================================================================
+export const SDK_VERSION = "3.3.0";
+/** JoinSplit Merkle tree depth */
+export const JOINSPLIT_TREE_DEPTH = 16;
+export const DEPLOYMENT_INFO = {
+    version: SDK_VERSION,
+    deployedAt: "2026-03-03",
+    network: "devnet",
+    features: [
+        "stealth-addresses",
+        "groth16-browser-proving",
+    ],
+    notes: "Client-side Groth16 proof generation via snarkjs",
+};