@utxopia/sdk 0.1.0-alpha.1

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

@@ -0,0 +1,233 @@
+/**
+ * UTXOpiaClient — high-level SDK entry point.
+ *
+ * Initialize once, use simple methods everywhere. Encapsulates config,
+ * keys, Poseidon init, token IDs, and note scanning so consumers don't
+ * chain low-level SDK calls.
+ *
+ * ```typescript
+ * const client = await UTXOpiaClient.init({ network: "devnet" });
+ * await client.loginWithWallet(wallet);
+ * const notes = await client.getNotes();
+ * const balance = client.getBalance();
+ * ```
+ *
+ * Phase 1: Init + auth + balance scanning
+ * Phase 2: Deposit + shield (future)
+ * Phase 3: Transfer + relay (future)
+ */
+import { type NetworkConfig, type NetworkId } from "./config";
+import { type AuthSignatureKeyDerivationOptions, type UTXOpiaKeys, type StealthMetaAddress, type WalletSignerAdapter, type KeySetupResult } from "./keys";
+import { type ViewOnlyKeys, type StealthOutputWithKeys, type NonInteractiveDepositResult } from "./stealth";
+import { type UtxoDescriptor } from "./psbt";
+import { type DepositOpReturnContext } from "./taproot";
+export interface UTXOpiaClientConfig {
+    network?: NetworkId;
+    /** Override backend URL (default: from network config) */
+    backendUrl?: string;
+}
+export interface TokenDefinition {
+    symbol: string;
+    shieldedSymbol: string;
+    mint: string;
+}
+export interface InboxNote {
+    id: string;
+    commitmentHex: string;
+    amount: bigint;
+    leafIndex: number;
+    tokenSymbol: string;
+    isSpent: boolean;
+    createdAt: number;
+    ephemeralPub?: Uint8Array;
+    stealthPub?: {
+        x: bigint;
+        y: bigint;
+    };
+    commitment: Uint8Array;
+}
+export declare class UTXOpiaClient {
+    private _keys;
+    private _viewOnlyKeys;
+    private _isViewOnly;
+    private _stealthAddress;
+    private _stealthAddressEncoded;
+    private _tokenIdCache;
+    private _eventClient;
+    private _backendUrl;
+    private _appNetworkId;
+    private constructor();
+    /**
+     * Initialize the SDK. Call once at app startup.
+     * Sets up config, initializes Poseidon hash, creates singleton.
+     */
+    static init(opts?: UTXOpiaClientConfig): Promise<UTXOpiaClient>;
+    /**
+     * Get the initialized singleton. Throws if init() hasn't been called.
+     */
+    static instance(): UTXOpiaClient;
+    /**
+     * Check if the client has been initialized.
+     */
+    static get isInitialized(): boolean;
+    /**
+     * Reset the singleton (for testing only).
+     */
+    static reset(): void;
+    /**
+     * Derive keys from a Solana wallet signature.
+     */
+    loginWithWallet(wallet: WalletSignerAdapter): Promise<KeySetupResult>;
+    /**
+     * Derive keys from a seed (passkey PRF output or secret phrase).
+     */
+    loginWithSeed(seed: Uint8Array): Promise<KeySetupResult>;
+    /**
+     * Derive keys from a chain-specific auth signature (wallet personal-message signing).
+     */
+    loginWithAuthSignature(signature: Uint8Array, options?: AuthSignatureKeyDerivationOptions): Promise<KeySetupResult>;
+    /**
+     * Restore keys from previously serialized storage (e.g., localStorage).
+     * @param serialized — the object from serializeKeys()
+     * @param solanaPublicKey — the wallet public key bytes (needed for key reconstruction)
+     */
+    restoreKeys(serialized: Record<string, unknown>, solanaPublicKey: Uint8Array): void;
+    /**
+     * Login with view-only keys (can scan but not spend).
+     */
+    loginViewOnly(viewOnlyKeys: ViewOnlyKeys): void;
+    /**
+     * Clear all keys and reset auth state.
+     */
+    logout(): void;
+    /**
+     * Serialize current keys for encrypted storage.
+     */
+    serializeKeys(): Record<string, unknown> | null;
+    get keys(): UTXOpiaKeys | null;
+    get stealthAddress(): StealthMetaAddress | null;
+    get stealthAddressEncoded(): string | null;
+    get isAuthenticated(): boolean;
+    get isViewOnly(): boolean;
+    get config(): NetworkConfig;
+    /**
+     * Get token ID for a mint address. Cached after first computation.
+     */
+    getTokenId(mintAddress: string): bigint;
+    /**
+     * Register multiple tokens for scanning. Caches their token IDs.
+     */
+    registerTokens(tokens: TokenDefinition[]): void;
+    /**
+     * Scan for all notes belonging to the authenticated user.
+     * Fetches announcements from backend, scans locally for privacy.
+     */
+    getNotes(tokens: TokenDefinition[]): Promise<InboxNote[]>;
+    /**
+     * Get balance per token from unspent notes.
+     */
+    getBalance(notes: InboxNote[]): Map<string, bigint>;
+    /**
+     * Check if a deposit announcement belongs to this user (hex string inputs).
+     */
+    isMyDeposit(ephemeralPubHex: string, npkHex: string): boolean;
+    /**
+     * Compute nullifier bytes for a note (for PDA existence checking).
+     */
+    computeNullifier(note: {
+        leafIndex: number;
+    }): Uint8Array;
+    /**
+     * Prepare a BTC deposit: generate stealth deposit address + OP_RETURN.
+     * Returns the deposit result (btcAddress, opReturnPayload) ready for PSBT building.
+     */
+    prepareDeposit(opts: {
+        recipient?: StealthMetaAddress;
+        network?: "mainnet" | "testnet" | "regtest";
+        opReturnContext: DepositOpReturnContext;
+    }): Promise<NonInteractiveDepositResult>;
+    /**
+     * Select UTXOs for a deposit amount. Returns the selected UTXO set.
+     */
+    selectUtxos(utxos: UtxoDescriptor[], targetSats: number, feeRate?: number): UtxoDescriptor[];
+    /**
+     * Prepare a stealth output for shielding (SPL token → shielded commitment).
+     * Returns npkBytes, ephemeralPub, commitment, tokenId — everything needed
+     * for the on-chain shield instruction.
+     */
+    prepareShieldOutput(opts: {
+        amount: bigint;
+        mintAddress: string;
+        recipient?: UTXOpiaKeys;
+    }): Promise<StealthOutputWithKeys & {
+        tokenId: bigint;
+    }>;
+    /**
+     * Fetch merkle proofs for multiple commitments.
+     * Used before proof generation to get the on-chain tree state.
+     *
+     * @param commitmentHexes - Array of commitment hex strings
+     * @param apiBaseUrl - Base URL for the merkle proof API (default: "" for same-origin)
+     */
+    fetchMerkleProofs(commitmentHexes: string[], apiBaseUrl?: string): Promise<Array<{
+        commitmentHex: string;
+        root: bigint;
+        pathElements: bigint[];
+        pathIndices: number[];
+    }>>;
+    /**
+     * Hash transaction inputs and sign with EdDSA-Poseidon.
+     *
+     * @param msgHashInputs - Array of bigints to hash (merkleRoot, boundParamsHash, nullifiers, commitments)
+     * @param eddsaSeed - The EdDSA seed bytes (from UTXOpiaKeys.eddsaSeed)
+     */
+    signTransaction(msgHashInputs: bigint[], eddsaSeed: Uint8Array): Promise<{
+        sigR8x: bigint;
+        sigR8y: bigint;
+        sigS: bigint;
+        msgHash: bigint;
+    }>;
+    /**
+     * Submit a JoinSplit transaction to the relay backend.
+     *
+     * @param payload - Transaction data including proof, nullifiers, commitments, and mode-specific fields
+     * @param relayUrl - URL for the relay endpoint (default is chain-aware from init network)
+     */
+    submitToRelay(payload: {
+        mode: "transfer" | "unshield" | "redeem";
+        nInputs: number;
+        nOutputs: number;
+        proof: string;
+        merkleRoot: string;
+        boundParamsHash: string;
+        nullifiers: string[];
+        commitmentsOut: string[];
+        stealthData: string[];
+        relayerFeeOutputIndex?: number;
+        /**
+         * Optional Phase 2 sender memos — one 80-byte hex string per output
+         * (nonce(24) || ciphertext_and_tag(56)). Compose with the SDK helper
+         * `buildSenderMemosForTransact(viewingPrivKey, outputs)`. The relay
+         * forwards them opaquely; viewing keys stay client-side.
+         */
+        senderMemos?: string[];
+        unshieldAmounts?: string[];
+        recipientAddresses?: string[];
+        recipientTokenAccounts?: string[];
+        redeemAmounts?: string[];
+        btcScripts?: string[];
+        requestNonces?: string[];
+        /**
+         * Optional frozen source-tree PDA (base58). Set only when a spent note was committed in a
+         * commitment tree that has since been rotated out; the relay inserts it before the proof
+         * buffer so the program can prove membership against that tree. Omit otherwise.
+         */
+        sourceTree?: string;
+    }, relayUrl?: string): Promise<{
+        success: boolean;
+        signature?: string;
+        error?: string;
+    }>;
+    private getEventClient;
+    private defaultRelayUrl;
+}

package/packages/sdk/dist/client.js

@@ -0,0 +1,416 @@
+/**
+ * UTXOpiaClient — high-level SDK entry point.
+ *
+ * Initialize once, use simple methods everywhere. Encapsulates config,
+ * keys, Poseidon init, token IDs, and note scanning so consumers don't
+ * chain low-level SDK calls.
+ *
+ * ```typescript
+ * const client = await UTXOpiaClient.init({ network: "devnet" });
+ * await client.loginWithWallet(wallet);
+ * const notes = await client.getNotes();
+ * const balance = client.getBalance();
+ * ```
+ *
+ * Phase 1: Init + auth + balance scanning
+ * Phase 2: Deposit + shield (future)
+ * Phase 3: Transfer + relay (future)
+ */
+import { initPoseidon, poseidonHashSync } from "./poseidon";
+import { computeTokenId } from "./poseidon";
+import { initConfig, getConfig } from "./config";
+import { parseMerkleProofResponse } from "./merkle";
+import { eddsaPoseidonSign } from "./keys";
+import { setupKeysFromWallet, setupKeysFromSeed, setupKeysFromAuthSignature, recreateStealthAddress, serializeKeysForStorage, deserializeKeysFromStorage, clearUTXOpiaKeys, } from "./keys";
+import { scanUnifiedNotesMulti, scanAnnouncementsViewOnlyMulti, computeNullifierHashForNote, computeNullifierBytes, isDepositForViewerHex, createDepositFromConfig, createStealthOutputWithKeys, } from "./stealth";
+import { selectUtxos } from "./psbt";
+import { hexToBytes } from "./crypto";
+import { EventClient } from "./event-client";
+// ─── Client ─────────────────────────────────────────────────────────
+let _instance = null;
+export class UTXOpiaClient {
+    constructor(backendUrl, appNetworkId) {
+        this._keys = null;
+        this._viewOnlyKeys = null;
+        this._isViewOnly = false;
+        this._stealthAddress = null;
+        this._stealthAddressEncoded = null;
+        this._tokenIdCache = new Map();
+        this._eventClient = null;
+        this._backendUrl = backendUrl;
+        this._appNetworkId = appNetworkId;
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────
+    /**
+     * Initialize the SDK. Call once at app startup.
+     * Sets up config, initializes Poseidon hash, creates singleton.
+     */
+    static async init(opts = {}) {
+        // Init config (reads env vars, sets up network)
+        if (opts.network) {
+            await initConfig({ network: opts.network });
+        }
+        // Init Poseidon (required before any hashing)
+        await initPoseidon();
+        const backendUrl = opts.backendUrl || "";
+        const appNetworkId = opts.network ||
+            (typeof process !== "undefined" && (process.env?.NEXT_PUBLIC_NETWORK || process.env?.UTXOPIA_NETWORK)) ||
+            "devnet";
+        const client = new UTXOpiaClient(backendUrl, appNetworkId);
+        _instance = client;
+        return client;
+    }
+    /**
+     * Get the initialized singleton. Throws if init() hasn't been called.
+     */
+    static instance() {
+        if (!_instance) {
+            throw new Error("UTXOpiaClient not initialized. Call UTXOpiaClient.init() first.");
+        }
+        return _instance;
+    }
+    /**
+     * Check if the client has been initialized.
+     */
+    static get isInitialized() {
+        return _instance !== null;
+    }
+    /**
+     * Reset the singleton (for testing only).
+     */
+    static reset() {
+        if (_instance) {
+            _instance.logout();
+            _instance._eventClient = null;
+        }
+        _instance = null;
+    }
+    // ─── Auth ───────────────────────────────────────────────────────
+    /**
+     * Derive keys from a Solana wallet signature.
+     */
+    async loginWithWallet(wallet) {
+        const result = await setupKeysFromWallet(wallet);
+        this._keys = result.keys;
+        this._stealthAddress = result.stealthAddress;
+        this._stealthAddressEncoded = result.stealthAddressEncoded;
+        this._isViewOnly = false;
+        this._viewOnlyKeys = null;
+        return result;
+    }
+    /**
+     * Derive keys from a seed (passkey PRF output or secret phrase).
+     */
+    async loginWithSeed(seed) {
+        const result = await setupKeysFromSeed(seed);
+        this._keys = result.keys;
+        this._stealthAddress = result.stealthAddress;
+        this._stealthAddressEncoded = result.stealthAddressEncoded;
+        this._isViewOnly = false;
+        this._viewOnlyKeys = null;
+        return result;
+    }
+    /**
+     * Derive keys from a chain-specific auth signature (wallet personal-message signing).
+     */
+    async loginWithAuthSignature(signature, options = {}) {
+        const result = await setupKeysFromAuthSignature(signature, options);
+        this._keys = result.keys;
+        this._stealthAddress = result.stealthMetaAddress;
+        this._stealthAddressEncoded = result.encodedStealthAddress;
+        this._isViewOnly = false;
+        this._viewOnlyKeys = null;
+        return {
+            keys: result.keys,
+            stealthAddress: result.stealthMetaAddress,
+            stealthAddressEncoded: result.encodedStealthAddress,
+        };
+    }
+    /**
+     * Restore keys from previously serialized storage (e.g., localStorage).
+     * @param serialized — the object from serializeKeys()
+     * @param solanaPublicKey — the wallet public key bytes (needed for key reconstruction)
+     */
+    restoreKeys(serialized, solanaPublicKey) {
+        const keys = deserializeKeysFromStorage(serialized, solanaPublicKey);
+        const { stealthAddress, stealthAddressEncoded } = recreateStealthAddress(keys);
+        this._keys = keys;
+        this._stealthAddress = stealthAddress;
+        this._stealthAddressEncoded = stealthAddressEncoded;
+        this._isViewOnly = false;
+    }
+    /**
+     * Login with view-only keys (can scan but not spend).
+     */
+    loginViewOnly(viewOnlyKeys) {
+        this._viewOnlyKeys = viewOnlyKeys;
+        this._isViewOnly = true;
+        this._keys = null;
+    }
+    /**
+     * Clear all keys and reset auth state.
+     */
+    logout() {
+        if (this._keys) {
+            clearUTXOpiaKeys(this._keys);
+        }
+        this._keys = null;
+        this._viewOnlyKeys = null;
+        this._isViewOnly = false;
+        this._stealthAddress = null;
+        this._stealthAddressEncoded = null;
+    }
+    /**
+     * Serialize current keys for encrypted storage.
+     */
+    serializeKeys() {
+        if (!this._keys)
+            return null;
+        return { ...serializeKeysForStorage(this._keys) };
+    }
+    // ─── Getters ────────────────────────────────────────────────────
+    get keys() { return this._keys; }
+    get stealthAddress() { return this._stealthAddress; }
+    get stealthAddressEncoded() { return this._stealthAddressEncoded; }
+    get isAuthenticated() { return this._keys !== null || this._viewOnlyKeys !== null; }
+    get isViewOnly() { return this._isViewOnly; }
+    get config() { return getConfig(); }
+    // ─── Token IDs ──────────────────────────────────────────────────
+    /**
+     * Get token ID for a mint address. Cached after first computation.
+     */
+    getTokenId(mintAddress) {
+        const cached = this._tokenIdCache.get(mintAddress);
+        if (cached !== undefined)
+            return cached;
+        // Requires PublicKey — import dynamically to avoid hard dep
+        const mintBytes = hexToBytes(mintAddress.padStart(64, "0"));
+        // If it's a base58 address, convert via PublicKey
+        let bytes;
+        try {
+            // Try as raw hex first (64 chars)
+            if (mintAddress.length === 64 && /^[0-9a-fA-F]+$/.test(mintAddress)) {
+                bytes = hexToBytes(mintAddress);
+            }
+            else {
+                // Assume base58 PublicKey — need to decode
+                // Use the SDK's reduceToField which handles the conversion
+                const { PublicKey } = require("@solana/web3.js");
+                bytes = new PublicKey(mintAddress).toBytes();
+            }
+        }
+        catch {
+            bytes = mintBytes;
+        }
+        const tokenId = computeTokenId(bytes);
+        this._tokenIdCache.set(mintAddress, tokenId);
+        return tokenId;
+    }
+    /**
+     * Register multiple tokens for scanning. Caches their token IDs.
+     */
+    registerTokens(tokens) {
+        const config = getConfig();
+        for (const token of tokens) {
+            let mint = token.mint;
+            if (!mint && (token.symbol === "BTC" || token.symbol === "zkBTC")) {
+                mint = config.zkbtcMint;
+            }
+            if (!mint)
+                continue;
+            this.getTokenId(mint); // triggers computation + cache
+        }
+    }
+    // ─── Note Scanning ─────────────────────────────────────────────
+    /**
+     * Scan for all notes belonging to the authenticated user.
+     * Fetches announcements from backend, scans locally for privacy.
+     */
+    async getNotes(tokens) {
+        if (!this._keys && !this._viewOnlyKeys)
+            return [];
+        // Fetch announcements via EventClient
+        const client = this.getEventClient();
+        const announcements = await client.fetchAll();
+        // One trial-decrypt per announcement, tested against every token id — not
+        // one full scan pass per token.
+        const config = getConfig();
+        const symbolByTokenId = new Map();
+        for (const token of tokens) {
+            let mint = token.mint;
+            if (!mint && (token.symbol === "BTC" || token.symbol === "zkBTC")) {
+                mint = config.zkbtcMint;
+            }
+            if (!mint)
+                continue;
+            const tokenId = this.getTokenId(mint);
+            // First token wins the id, matching the old loop's dedup order.
+            if (!symbolByTokenId.has(tokenId))
+                symbolByTokenId.set(tokenId, token.shieldedSymbol);
+        }
+        const tokenIds = [...symbolByTokenId.keys()];
+        const matches = this._isViewOnly && this._viewOnlyKeys
+            ? await scanAnnouncementsViewOnlyMulti(this._viewOnlyKeys, announcements, tokenIds)
+            : await scanUnifiedNotesMulti(this._keys, announcements, tokenIds);
+        const scanned = matches.map((note) => ({
+            ...note,
+            tokenSymbol: symbolByTokenId.get(note.tokenId),
+        }));
+        // Convert to InboxNote format
+        return scanned.map((note, index) => {
+            const rawHex = Buffer.from(note.commitment).toString("hex");
+            const commitmentHex = rawHex.toLowerCase().padStart(64, "0");
+            return {
+                id: `${commitmentHex.slice(0, 16)}-${index}`,
+                commitmentHex,
+                amount: typeof note.amount === "bigint" ? note.amount : BigInt(note.amount),
+                leafIndex: note.leafIndex,
+                tokenSymbol: note.tokenSymbol,
+                isSpent: false, // caller checks spent status separately
+                createdAt: note.blockTime ? note.blockTime * 1000 : Date.now(),
+                ephemeralPub: note.ephemeralPub,
+                stealthPub: note.stealthPub,
+                commitment: note.commitment,
+            };
+        });
+    }
+    /**
+     * Get balance per token from unspent notes.
+     */
+    getBalance(notes) {
+        const balances = new Map();
+        for (const note of notes) {
+            if (note.isSpent)
+                continue;
+            const current = balances.get(note.tokenSymbol) ?? 0n;
+            balances.set(note.tokenSymbol, current + note.amount);
+        }
+        return balances;
+    }
+    /**
+     * Check if a deposit announcement belongs to this user (hex string inputs).
+     */
+    isMyDeposit(ephemeralPubHex, npkHex) {
+        if (!this._keys)
+            return false;
+        return isDepositForViewerHex(this._keys, ephemeralPubHex, npkHex);
+    }
+    /**
+     * Compute nullifier bytes for a note (for PDA existence checking).
+     */
+    computeNullifier(note) {
+        if (this._isViewOnly && this._viewOnlyKeys) {
+            return computeNullifierBytes(this._viewOnlyKeys.nullifyingKey, note.leafIndex);
+        }
+        if (this._keys) {
+            return computeNullifierHashForNote(this._keys, note);
+        }
+        throw new Error("Not authenticated");
+    }
+    // ─── Phase 2: Deposit + Shield ─────────────────────────────────
+    /**
+     * Prepare a BTC deposit: generate stealth deposit address + OP_RETURN.
+     * Returns the deposit result (btcAddress, opReturnPayload) ready for PSBT building.
+     */
+    async prepareDeposit(opts) {
+        const meta = opts.recipient ?? this._stealthAddress;
+        if (!meta)
+            throw new Error("No recipient stealth address (login first or provide recipient)");
+        const network = opts.network ?? sdkBitcoinNetworkToAddressNetwork(this.config.bitcoinNetwork);
+        if (!opts.opReturnContext) {
+            throw new Error("deposit OP_RETURN context is required");
+        }
+        return createDepositFromConfig(meta, network, opts.opReturnContext);
+    }
+    /**
+     * Select UTXOs for a deposit amount. Returns the selected UTXO set.
+     */
+    selectUtxos(utxos, targetSats, feeRate = 2) {
+        return selectUtxos(utxos, targetSats, feeRate);
+    }
+    /**
+     * Prepare a stealth output for shielding (SPL token → shielded commitment).
+     * Returns npkBytes, ephemeralPub, commitment, tokenId — everything needed
+     * for the on-chain shield instruction.
+     */
+    async prepareShieldOutput(opts) {
+        const keys = opts.recipient ?? this._keys;
+        if (!keys)
+            throw new Error("No keys (login first or provide recipient)");
+        const tokenId = this.getTokenId(opts.mintAddress);
+        const output = await createStealthOutputWithKeys(keys, opts.amount, tokenId);
+        return { ...output, tokenId };
+    }
+    // ─── Phase 3: Transfer + Relay ─────────────────────────────────
+    /**
+     * Fetch merkle proofs for multiple commitments.
+     * Used before proof generation to get the on-chain tree state.
+     *
+     * @param commitmentHexes - Array of commitment hex strings
+     * @param apiBaseUrl - Base URL for the merkle proof API (default: "" for same-origin)
+     */
+    async fetchMerkleProofs(commitmentHexes, apiBaseUrl = "") {
+        const results = await Promise.all(commitmentHexes.map(async (hex) => {
+            const resp = await fetch(`${apiBaseUrl}/api/merkle/proof?commitment=${hex}`);
+            const data = await resp.json();
+            if (!data.success) {
+                throw new Error(`Note ${hex.slice(0, 16)}... not found on-chain`);
+            }
+            const parsed = parseMerkleProofResponse(data);
+            return { commitmentHex: hex, ...parsed };
+        }));
+        // Validate all proofs share the same root
+        const roots = results.map((r) => r.root);
+        if (new Set(roots.map((r) => r.toString())).size > 1) {
+            throw new Error("Input notes have different Merkle roots — tree may have changed");
+        }
+        return results;
+    }
+    /**
+     * Hash transaction inputs and sign with EdDSA-Poseidon.
+     *
+     * @param msgHashInputs - Array of bigints to hash (merkleRoot, boundParamsHash, nullifiers, commitments)
+     * @param eddsaSeed - The EdDSA seed bytes (from UTXOpiaKeys.eddsaSeed)
+     */
+    async signTransaction(msgHashInputs, eddsaSeed) {
+        const msgHash = poseidonHashSync(msgHashInputs);
+        const [sigR8x, sigR8y, sigS] = await eddsaPoseidonSign(eddsaSeed, msgHash);
+        return { sigR8x, sigR8y, sigS, msgHash };
+    }
+    /**
+     * Submit a JoinSplit transaction to the relay backend.
+     *
+     * @param payload - Transaction data including proof, nullifiers, commitments, and mode-specific fields
+     * @param relayUrl - URL for the relay endpoint (default is chain-aware from init network)
+     */
+    async submitToRelay(payload, relayUrl = this.defaultRelayUrl()) {
+        const resp = await fetch(relayUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(payload),
+        });
+        return resp.json();
+    }
+    // ─── Private helpers ────────────────────────────────────────────
+    getEventClient() {
+        if (!this._eventClient) {
+            const config = getConfig();
+            this._eventClient = new EventClient({
+                backendUrl: this._backendUrl,
+                solanaRpcUrl: config.solanaRpcUrl || "",
+                programId: config.utxopiaProgramId,
+            });
+        }
+        return this._eventClient;
+    }
+    defaultRelayUrl() {
+        return `/api/sol/relay?network=${encodeURIComponent(this._appNetworkId)}`;
+    }
+}
+function sdkBitcoinNetworkToAddressNetwork(network) {
+    if (network === "mainnet")
+        return "mainnet";
+    if (network === "regtest")
+        return "regtest";
+    return "testnet";
+}