@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/core/esplora.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Esplora Client - Platform-agnostic HTTP client for Bitcoin blockchain queries
+ *
+ * Uses standard fetch API (works in browser, Node.js 18+, React Native)
+ * Supports mempool.space API for testnet/mainnet
+ */
+export interface EsploraTransaction {
+    txid: string;
+    version: number;
+    locktime: number;
+    vin: EsploraVin[];
+    vout: EsploraVout[];
+    size: number;
+    weight: number;
+    fee: number;
+    status: EsploraStatus;
+}
+export interface EsploraVin {
+    txid: string;
+    vout: number;
+    prevout: EsploraVout | null;
+    scriptsig: string;
+    scriptsig_asm: string;
+    witness?: string[];
+    is_coinbase: boolean;
+    sequence: number;
+}
+export interface EsploraVout {
+    scriptpubkey: string;
+    scriptpubkey_asm: string;
+    scriptpubkey_type: string;
+    scriptpubkey_address?: string;
+    value: number;
+}
+export interface EsploraStatus {
+    confirmed: boolean;
+    block_height?: number;
+    block_hash?: string;
+    block_time?: number;
+}
+export interface EsploraAddressInfo {
+    address: string;
+    chain_stats: {
+        funded_txo_count: number;
+        funded_txo_sum: number;
+        spent_txo_count: number;
+        spent_txo_sum: number;
+        tx_count: number;
+    };
+    mempool_stats: {
+        funded_txo_count: number;
+        funded_txo_sum: number;
+        spent_txo_count: number;
+        spent_txo_sum: number;
+        tx_count: number;
+    };
+}
+export interface EsploraUtxo {
+    txid: string;
+    vout: number;
+    status: EsploraStatus;
+    value: number;
+}
+export interface EsploraMerkleProof {
+    block_height: number;
+    merkle: string[];
+    pos: number;
+}
+export type EsploraNetwork = "mainnet" | "testnet" | "testnet4" | "signet" | "regtest";
+export declare class EsploraClient {
+    private baseUrl;
+    private network;
+    constructor(networkOrUrl?: EsploraNetwork | string, customBaseUrl?: string);
+    private fetch;
+    getAddress(address: string): Promise<EsploraAddressInfo>;
+    getAddressTxs(address: string, lastSeenTxid?: string): Promise<EsploraTransaction[]>;
+    getAddressTxsMempool(address: string): Promise<EsploraTransaction[]>;
+    getAddressUtxos(address: string): Promise<EsploraUtxo[]>;
+    getTransaction(txid: string): Promise<EsploraTransaction>;
+    getTxStatus(txid: string): Promise<EsploraStatus>;
+    getTxHex(txid: string): Promise<string>;
+    getTxRaw(txid: string): Promise<Uint8Array>;
+    getTxMerkleProof(txid: string): Promise<EsploraMerkleProof>;
+    getTxOutspend(txid: string, vout: number): Promise<{
+        spent: boolean;
+        txid?: string;
+        vin?: number;
+        status?: EsploraStatus;
+    }>;
+    getBlockHeight(): Promise<number>;
+    getBlockHash(height: number): Promise<string>;
+    getBlockHeader(hash: string): Promise<string>;
+    getBlockTxids(hash: string): Promise<string[]>;
+    getConfirmations(txid: string): Promise<number>;
+    waitForTransaction(address: string, timeoutMs?: number, pollIntervalMs?: number): Promise<EsploraTransaction | null>;
+    waitForConfirmations(txid: string, requiredConfirmations?: number, timeoutMs?: number, pollIntervalMs?: number): Promise<number>;
+    /**
+     * Find a deposit to a specific address matching the expected amount
+     */
+    findDeposit(address: string, expectedAmount?: bigint): Promise<{
+        tx: EsploraTransaction;
+        vout: number;
+        amount: number;
+    } | null>;
+    private findMatchingOutput;
+    getNetwork(): EsploraNetwork;
+    getBaseUrl(): string;
+}
+export declare const esploraTestnet: EsploraClient;
+export declare const esploraMainnet: EsploraClient;

package/packages/sdk/dist/core/esplora.js

@@ -0,0 +1,187 @@
+/**
+ * Esplora Client - Platform-agnostic HTTP client for Bitcoin blockchain queries
+ *
+ * Uses standard fetch API (works in browser, Node.js 18+, React Native)
+ * Supports mempool.space API for testnet/mainnet
+ */
+import { hexToBytes } from "../crypto";
+const NETWORK_URLS = {
+    mainnet: "https://mempool.space/api",
+    testnet: "https://mempool.space/testnet/api",
+    testnet4: "https://mempool.space/testnet4/api",
+    signet: "https://mempool.space/signet/api",
+    regtest: "http://localhost:2140",
+};
+export class EsploraClient {
+    constructor(networkOrUrl = "testnet", customBaseUrl) {
+        if (customBaseUrl) {
+            this.baseUrl = customBaseUrl.replace(/\/$/, "");
+            this.network = networkOrUrl;
+        }
+        else if (networkOrUrl in NETWORK_URLS) {
+            this.network = networkOrUrl;
+            this.baseUrl = NETWORK_URLS[this.network];
+        }
+        else {
+            // Assume it's a custom URL
+            this.baseUrl = networkOrUrl.replace(/\/$/, "");
+            this.network = "testnet";
+        }
+    }
+    async fetch(endpoint) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const res = await fetch(url);
+        if (!res.ok) {
+            throw new Error(`Esplora API error: ${res.status} ${res.statusText}`);
+        }
+        const contentType = res.headers.get("content-type");
+        if (contentType?.includes("application/json")) {
+            return res.json();
+        }
+        // For text responses (like block height)
+        const text = await res.text();
+        return text;
+    }
+    // =========================================================================
+    // Address endpoints
+    // =========================================================================
+    async getAddress(address) {
+        return this.fetch(`/address/${address}`);
+    }
+    async getAddressTxs(address, lastSeenTxid) {
+        const endpoint = lastSeenTxid
+            ? `/address/${address}/txs/chain/${lastSeenTxid}`
+            : `/address/${address}/txs`;
+        return this.fetch(endpoint);
+    }
+    async getAddressTxsMempool(address) {
+        return this.fetch(`/address/${address}/txs/mempool`);
+    }
+    async getAddressUtxos(address) {
+        return this.fetch(`/address/${address}/utxo`);
+    }
+    // =========================================================================
+    // Transaction endpoints
+    // =========================================================================
+    async getTransaction(txid) {
+        return this.fetch(`/tx/${txid}`);
+    }
+    async getTxStatus(txid) {
+        return this.fetch(`/tx/${txid}/status`);
+    }
+    async getTxHex(txid) {
+        return this.fetch(`/tx/${txid}/hex`);
+    }
+    async getTxRaw(txid) {
+        const hex = await this.getTxHex(txid);
+        return hexToBytes(hex);
+    }
+    async getTxMerkleProof(txid) {
+        return this.fetch(`/tx/${txid}/merkle-proof`);
+    }
+    async getTxOutspend(txid, vout) {
+        return this.fetch(`/tx/${txid}/outspend/${vout}`);
+    }
+    // =========================================================================
+    // Block endpoints
+    // =========================================================================
+    async getBlockHeight() {
+        const height = await this.fetch("/blocks/tip/height");
+        return parseInt(height, 10);
+    }
+    async getBlockHash(height) {
+        return this.fetch(`/block-height/${height}`);
+    }
+    async getBlockHeader(hash) {
+        return this.fetch(`/block/${hash}/header`);
+    }
+    async getBlockTxids(hash) {
+        return this.fetch(`/block/${hash}/txids`);
+    }
+    // =========================================================================
+    // Helper methods
+    // =========================================================================
+    async getConfirmations(txid) {
+        const status = await this.getTxStatus(txid);
+        if (!status.confirmed || status.block_height === undefined) {
+            return 0;
+        }
+        const tipHeight = await this.getBlockHeight();
+        return tipHeight - status.block_height + 1;
+    }
+    async waitForTransaction(address, timeoutMs = 600000, pollIntervalMs = 5000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            // Check mempool first
+            const mempoolTxs = await this.getAddressTxsMempool(address);
+            if (mempoolTxs.length > 0) {
+                return mempoolTxs[0];
+            }
+            // Check confirmed
+            const confirmedTxs = await this.getAddressTxs(address);
+            if (confirmedTxs.length > 0) {
+                return confirmedTxs[0];
+            }
+            await sleep(pollIntervalMs);
+        }
+        return null;
+    }
+    async waitForConfirmations(txid, requiredConfirmations = 6, timeoutMs = 3600000, pollIntervalMs = 30000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            const confirmations = await this.getConfirmations(txid);
+            if (confirmations >= requiredConfirmations) {
+                return confirmations;
+            }
+            await sleep(pollIntervalMs);
+        }
+        return await this.getConfirmations(txid);
+    }
+    /**
+     * Find a deposit to a specific address matching the expected amount
+     */
+    async findDeposit(address, expectedAmount) {
+        // Check mempool first
+        const mempoolTxs = await this.getAddressTxsMempool(address);
+        for (const tx of mempoolTxs) {
+            const result = this.findMatchingOutput(tx, address, expectedAmount);
+            if (result)
+                return result;
+        }
+        // Check confirmed transactions
+        const confirmedTxs = await this.getAddressTxs(address);
+        for (const tx of confirmedTxs) {
+            const result = this.findMatchingOutput(tx, address, expectedAmount);
+            if (result)
+                return result;
+        }
+        return null;
+    }
+    findMatchingOutput(tx, address, expectedAmount) {
+        for (let i = 0; i < tx.vout.length; i++) {
+            const output = tx.vout[i];
+            if (output.scriptpubkey_address === address) {
+                if (expectedAmount === undefined ||
+                    BigInt(output.value) === expectedAmount) {
+                    return { tx, vout: i, amount: output.value };
+                }
+            }
+        }
+        return null;
+    }
+    getNetwork() {
+        return this.network;
+    }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+}
+// =========================================================================
+// Utility functions
+// =========================================================================
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Default client for testnet
+export const esploraTestnet = new EsploraClient("testnet");
+export const esploraMainnet = new EsploraClient("mainnet");

package/packages/sdk/dist/core/mempool.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Mempool.space API Client for SPV Verification
+ *
+ * Extended client for fetching Bitcoin SPV proof data.
+ * Builds on EsploraClient with additional SPV-specific methods.
+ */
+import { EsploraClient, type EsploraNetwork, type EsploraMerkleProof } from "./esplora";
+export interface BlockHeader {
+    height: number;
+    hash: string;
+    version: number;
+    previousBlockHash: string;
+    merkleRoot: string;
+    timestamp: number;
+    bits: number;
+    nonce: number;
+    /** Raw 80-byte header in hex */
+    rawHeader: string;
+}
+export interface TransactionInfo {
+    txid: string;
+    confirmed: boolean;
+    blockHeight?: number;
+    blockHash?: string;
+    blockTime?: number;
+}
+export interface SPVProofData {
+    txInfo: TransactionInfo;
+    blockHeader: BlockHeader;
+    merkleProof: EsploraMerkleProof & {
+        blockHash: string;
+    };
+    confirmations: number;
+}
+export declare class MempoolClient extends EsploraClient {
+    constructor(network?: EsploraNetwork);
+    /**
+     * Get transaction info including block hash
+     */
+    getTransactionInfo(txid: string): Promise<TransactionInfo>;
+    /**
+     * Get block header with raw 80-byte header
+     */
+    getBlockHeaderFull(blockHash: string): Promise<BlockHeader>;
+    /**
+     * Get block header by height
+     */
+    getBlockHeaderByHeight(height: number): Promise<BlockHeader>;
+    /**
+     * Get all data needed for SPV verification
+     */
+    getSPVProofData(txid: string): Promise<SPVProofData>;
+}
+/**
+ * Reverse bytes (for Bitcoin internal byte order)
+ */
+export declare function reverseBytes(bytes: Uint8Array): Uint8Array;
+export { hexToBytes, bytesToHex } from "../crypto";
+export declare const mempoolTestnet: MempoolClient;
+export declare const mempoolMainnet: MempoolClient;

package/packages/sdk/dist/core/mempool.js

@@ -0,0 +1,107 @@
+/**
+ * Mempool.space API Client for SPV Verification
+ *
+ * Extended client for fetching Bitcoin SPV proof data.
+ * Builds on EsploraClient with additional SPV-specific methods.
+ */
+import { EsploraClient } from "./esplora";
+// =============================================================================
+// MempoolClient (extends EsploraClient with SPV methods)
+// =============================================================================
+export class MempoolClient extends EsploraClient {
+    constructor(network = "testnet") {
+        super(network);
+    }
+    /**
+     * Get transaction info including block hash
+     */
+    async getTransactionInfo(txid) {
+        const tx = await this.getTransaction(txid);
+        return {
+            txid: tx.txid,
+            confirmed: tx.status.confirmed,
+            blockHeight: tx.status.block_height,
+            blockHash: tx.status.block_hash,
+            blockTime: tx.status.block_time,
+        };
+    }
+    /**
+     * Get block header with raw 80-byte header
+     */
+    async getBlockHeaderFull(blockHash) {
+        const baseUrl = this.getBaseUrl();
+        // Fetch block info
+        const blockRes = await fetch(`${baseUrl}/block/${blockHash}`);
+        if (!blockRes.ok) {
+            throw new Error(`Failed to fetch block: ${blockRes.statusText}`);
+        }
+        const blockInfo = await blockRes.json();
+        // Fetch raw header (80 bytes hex)
+        const rawHeader = await this.getBlockHeader(blockHash);
+        return {
+            height: blockInfo.height,
+            hash: blockHash,
+            version: blockInfo.version,
+            previousBlockHash: blockInfo.previousblockhash,
+            merkleRoot: blockInfo.merkle_root,
+            timestamp: blockInfo.timestamp,
+            bits: blockInfo.bits,
+            nonce: blockInfo.nonce,
+            rawHeader,
+        };
+    }
+    /**
+     * Get block header by height
+     */
+    async getBlockHeaderByHeight(height) {
+        const blockHash = await this.getBlockHash(height);
+        return this.getBlockHeaderFull(blockHash);
+    }
+    /**
+     * Get all data needed for SPV verification
+     */
+    async getSPVProofData(txid) {
+        // Get transaction info
+        const txInfo = await this.getTransactionInfo(txid);
+        if (!txInfo.confirmed || !txInfo.blockHash) {
+            throw new Error("Transaction not confirmed yet");
+        }
+        // Get block header
+        const blockHeader = await this.getBlockHeaderFull(txInfo.blockHash);
+        // Get merkle proof
+        const merkleProof = await this.getTxMerkleProof(txid);
+        // Get confirmations
+        const tipHeight = await this.getBlockHeight();
+        const confirmations = tipHeight - txInfo.blockHeight + 1;
+        return {
+            txInfo,
+            blockHeader,
+            merkleProof: {
+                ...merkleProof,
+                blockHash: txInfo.blockHash,
+            },
+            confirmations,
+        };
+    }
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Reverse bytes (for Bitcoin internal byte order)
+ */
+export function reverseBytes(bytes) {
+    const reversed = new Uint8Array(bytes.length);
+    for (let i = 0; i < bytes.length; i++) {
+        reversed[i] = bytes[bytes.length - 1 - i];
+    }
+    return reversed;
+}
+// hexToBytes / bytesToHex live in ../crypto (single source); re-exported here
+// to preserve this module's public surface.
+export { hexToBytes, bytesToHex } from "../crypto";
+// =============================================================================
+// Default Instances
+// =============================================================================
+export const mempoolTestnet = new MempoolClient("testnet");
+export const mempoolMainnet = new MempoolClient("mainnet");

package/packages/sdk/dist/crypto-babyjub.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Baby Jubjub curve operations for UTXOpia
+ *
+ * Twisted Edwards curve matching circomlib's BabyJubjub:
+ *   a*x^2 + y^2 = 1 + d*x^2*y^2
+ *   a = 168700, d = 168696
+ *
+ * Over BN254 scalar field.
+ * Used for spending keys and in-circuit key derivation via BabyPbk().
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-2494
+ * @see circomlib/circuits/babyjub.circom
+ */
+/** BN254 scalar field prime (Baby Jubjub base field) */
+export declare const BABYJUB_FIELD_PRIME = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/** Baby Jubjub curve parameter a */
+export declare const BABYJUB_A = 168700n;
+/** Baby Jubjub curve parameter d */
+export declare const BABYJUB_D = 168696n;
+/**
+ * Baby Jubjub subgroup order (order of BASE8 generator)
+ * = field_prime / 8 (cofactor 8)
+ */
+export declare const BABYJUB_ORDER = 2736030358979909402780800718157159386076813972158567259200215660948447373041n;
+/**
+ * Baby Jubjub cofactor
+ */
+export declare const BABYJUB_COFACTOR = 8n;
+/**
+ * Generator point (BASE8) - matches circomlib's BabyPbk() generator
+ * This is the base point of the prime-order subgroup (cofactor-cleared).
+ */
+export declare const BABYJUB_BASE8: BabyJubPoint;
+/** Point on the Baby Jubjub curve (affine coordinates) */
+export interface BabyJubPoint {
+    x: bigint;
+    y: bigint;
+}
+/** Identity element (point at infinity for twisted Edwards) */
+export declare const BABYJUB_IDENTITY: BabyJubPoint;
+/**
+ * Check if a point is the identity element
+ */
+export declare function isIdentity(point: BabyJubPoint): boolean;
+/**
+ * Verify a point is on the Baby Jubjub curve
+ *
+ * a*x^2 + y^2 = 1 + d*x^2*y^2
+ */
+export declare function isOnBabyJubCurve(point: BabyJubPoint): boolean;
+/**
+ * Point addition on Baby Jubjub (twisted Edwards addition law)
+ *
+ * For twisted Edwards: a*x^2 + y^2 = 1 + d*x^2*y^2
+ * x3 = (x1*y2 + y1*x2) / (1 + d*x1*x2*y1*y2)
+ * y3 = (y1*y2 - a*x1*x2) / (1 - d*x1*x2*y1*y2)
+ */
+export declare function babyJubAdd(p1: BabyJubPoint, p2: BabyJubPoint): BabyJubPoint;
+/**
+ * Point doubling on Baby Jubjub
+ */
+export declare function babyJubDouble(point: BabyJubPoint): BabyJubPoint;
+/**
+ * Scalar multiplication using double-and-add (constant-time Montgomery ladder)
+ *
+ * SECURITY: Uses Montgomery ladder for constant-time execution.
+ */
+export declare function babyJubMul(scalar: bigint, point: BabyJubPoint): BabyJubPoint;
+/**
+ * Negate a point (flip x coordinate for twisted Edwards)
+ */
+export declare function babyJubNegate(point: BabyJubPoint): BabyJubPoint;
+/**
+ * Compress a Baby Jubjub point to 32 bytes
+ *
+ * Format: y-coordinate with sign of x stored in MSB of last byte
+ * This matches circomlib's pointbits.circom compression.
+ */
+export declare function babyJubCompress(point: BabyJubPoint): Uint8Array;
+/**
+ * Decompress a 32-byte representation to a Baby Jubjub point
+ */
+export declare function babyJubDecompress(bytes: Uint8Array): BabyJubPoint;
+/**
+ * Generate a random Baby Jubjub keypair
+ */
+export declare function generateBabyJubKeyPair(): {
+    privKey: bigint;
+    pubKey: BabyJubPoint;
+};
+/**
+ * Derive a Baby Jubjub keypair from a seed (deterministic)
+ */
+export declare function deriveBabyJubKeyFromSeed(seed: Uint8Array): {
+    privKey: bigint;
+    pubKey: BabyJubPoint;
+};
+/**
+ * Derive a scalar from bytes (reduces modulo Baby Jubjub order)
+ */
+export declare function babyJubScalarFromBytes(bytes: Uint8Array): bigint;
+/**
+ * Convert a Baby Jubjub scalar to 32 bytes (big-endian)
+ */
+export declare function babyJubScalarToBytes(scalar: bigint): Uint8Array;