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

package/packages/btc-client/src/esplora-client.ts

@@ -1,153 +0,0 @@
-import type {
-  BitcoinAddressInfo,
-  BitcoinClient,
-  BitcoinDepositCandidate,
-  BitcoinMerkleProof,
-  BitcoinNetwork,
-  BitcoinOutspend,
-  BitcoinTransaction,
-  BitcoinTxStatus,
-  BitcoinUtxo,
-} from "./types";
-import { extractUtxopiaDepositOpReturn } from "./op-return";
-
-const NETWORK_URLS: Record<BitcoinNetwork, string> = {
-  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 interface EsploraClientOptions {
-  network?: BitcoinNetwork;
-  baseUrl?: string;
-  fetchImpl?: typeof fetch;
-}
-
-export class EsploraBitcoinClient implements BitcoinClient {
-  readonly network: BitcoinNetwork;
-  private readonly baseUrl: string;
-  private readonly fetchImpl: typeof fetch;
-
-  constructor(options: EsploraClientOptions = {}) {
-    this.network = options.network ?? "testnet";
-    this.baseUrl = (options.baseUrl ?? NETWORK_URLS[this.network]).replace(/\/$/, "");
-    this.fetchImpl = options.fetchImpl ?? fetch;
-  }
-
-  async getAddress(address: string): Promise<BitcoinAddressInfo> {
-    return this.getJson(`/address/${address}`);
-  }
-
-  async getAddressTxs(address: string, lastSeenTxid?: string): Promise<BitcoinTransaction[]> {
-    return this.getJson(lastSeenTxid ? `/address/${address}/txs/chain/${lastSeenTxid}` : `/address/${address}/txs`);
-  }
-
-  async getAddressTxsMempool(address: string): Promise<BitcoinTransaction[]> {
-    return this.getJson(`/address/${address}/txs/mempool`);
-  }
-
-  async getAddressUtxos(address: string): Promise<BitcoinUtxo[]> {
-    return this.getJson(`/address/${address}/utxo`);
-  }
-
-  async getTransaction(txid: string): Promise<BitcoinTransaction> {
-    return this.getJson(`/tx/${txid}`);
-  }
-
-  async getTxStatus(txid: string): Promise<BitcoinTxStatus> {
-    return this.getJson(`/tx/${txid}/status`);
-  }
-
-  async getTxHex(txid: string): Promise<string> {
-    return this.getText(`/tx/${txid}/hex`);
-  }
-
-  async getTxMerkleProof(txid: string): Promise<BitcoinMerkleProof> {
-    return this.getJson(`/tx/${txid}/merkle-proof`);
-  }
-
-  async getTxOutspend(txid: string, vout: number): Promise<BitcoinOutspend> {
-    return this.getJson(`/tx/${txid}/outspend/${vout}`);
-  }
-
-  async getBlockHeight(): Promise<number> {
-    return Number.parseInt(await this.getText("/blocks/tip/height"), 10);
-  }
-
-  async getBlockHash(height: number): Promise<string> {
-    return this.getText(`/block-height/${height}`);
-  }
-
-  async getBlockHeader(hash: string): Promise<string> {
-    return this.getText(`/block/${hash}/header`);
-  }
-
-  async broadcastTx(txHex: string): Promise<string> {
-    const res = await this.fetchImpl(`${this.baseUrl}/tx`, {
-      method: "POST",
-      headers: { "content-type": "text/plain" },
-      body: txHex,
-    });
-    if (!res.ok) {
-      throw new Error(`Esplora broadcast failed: ${res.status} ${res.statusText}: ${await res.text()}`);
-    }
-    return res.text();
-  }
-
-  async getConfirmations(txid: string): Promise<number> {
-    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 findDepositCandidates(address: string, minConfirmations = 1): Promise<BitcoinDepositCandidate[]> {
-    const [utxos, tipHeight, txs] = await Promise.all([
-      this.getAddressUtxos(address),
-      this.getBlockHeight(),
-      this.getAddressTxs(address),
-    ]);
-    const txById = new Map(txs.map((tx) => [tx.txid, tx]));
-
-    return utxos
-      .map((utxo) => ({
-        address,
-        txid: utxo.txid,
-        vout: utxo.vout,
-        value: utxo.value,
-        confirmations: confirmationsForStatus(utxo.status, tipHeight),
-        status: utxo.status,
-        opReturn: extractUtxopiaDepositOpReturn(txById.get(utxo.txid)),
-      }))
-      .filter((candidate) => candidate.confirmations >= minConfirmations);
-  }
-
-  private async getJson<T>(endpoint: string): Promise<T> {
-    const res = await this.fetchImpl(`${this.baseUrl}${endpoint}`);
-    if (!res.ok) {
-      throw new Error(`Esplora API failed: ${res.status} ${res.statusText}`);
-    }
-    return res.json() as Promise<T>;
-  }
-
-  private async getText(endpoint: string): Promise<string> {
-    const res = await this.fetchImpl(`${this.baseUrl}${endpoint}`);
-    if (!res.ok) {
-      throw new Error(`Esplora API failed: ${res.status} ${res.statusText}`);
-    }
-    return res.text();
-  }
-}
-
-function confirmationsForStatus(status: BitcoinTxStatus, tipHeight: number): number {
-  if (!status.confirmed || status.block_height === undefined) {
-    return 0;
-  }
-
-  return tipHeight - status.block_height + 1;
-}

package/packages/btc-client/src/index.ts

@@ -1,3 +0,0 @@
-export * from "./esplora-client";
-export * from "./op-return";
-export * from "./types";

package/packages/btc-client/src/op-return.ts

@@ -1,93 +0,0 @@
-import type { BitcoinTransaction, UtxopiaDepositOpReturn } from "./types";
-
-export const UTXOPIA_DEPOSIT_OP_RETURN_SIZE = 73;
-export const UTXOPIA_DEPOSIT_OP_RETURN_VERSION = 1;
-export const DESTINATION_CHAIN_SOLANA = 1;
-export const BITCOIN_NETWORK_MAINNET = 0;
-export const BITCOIN_NETWORK_TESTNET4 = 2;
-export const BITCOIN_NETWORK_REGTEST = 3;
-
-export function extractUtxopiaDepositOpReturn(
-  tx: BitcoinTransaction | undefined,
-): UtxopiaDepositOpReturn | undefined {
-  if (!tx) {
-    return undefined;
-  }
-
-  for (const output of tx.vout) {
-    const payload = parseOpReturnPayload(output.scriptpubkey);
-    if (payload?.length !== UTXOPIA_DEPOSIT_OP_RETURN_SIZE) {
-      continue;
-    }
-
-    const header = decodeDepositHeader(payload[0]);
-    if (!header) {
-      continue;
-    }
-
-    const ephemeralPubkey = payload.slice(9, 41);
-    const notePublicKey = payload.slice(41, 73);
-    return {
-      ...header,
-      poolTag: payload.slice(1, 9),
-      ephemeralPubkey,
-      notePublicKey,
-      rawPayload: payload,
-    };
-  }
-
-  return undefined;
-}
-
-export function decodeDepositHeader(header: number): {
-  version: number;
-  destinationChain: number;
-  bitcoinNetwork: number;
-} | undefined {
-  const version = header >> 6;
-  const destinationChain = (header >> 4) & 0x03;
-  const bitcoinNetwork = header & 0x0f;
-  if (version !== UTXOPIA_DEPOSIT_OP_RETURN_VERSION) return undefined;
-  if (destinationChain !== DESTINATION_CHAIN_SOLANA) return undefined;
-  if (
-    bitcoinNetwork !== BITCOIN_NETWORK_MAINNET
-    && bitcoinNetwork !== BITCOIN_NETWORK_TESTNET4
-    && bitcoinNetwork !== BITCOIN_NETWORK_REGTEST
-  ) {
-    return undefined;
-  }
-  return { version, destinationChain, bitcoinNetwork };
-}
-
-export function parseOpReturnPayload(scriptPubkeyHex: string): Uint8Array | undefined {
-  const script = hexToBytes(scriptPubkeyHex);
-  if (script.length < 2 || script[0] !== 0x6a) {
-    return undefined;
-  }
-
-  const pushOpcode = script[1];
-  if (pushOpcode > 0 && pushOpcode <= 75) {
-    const end = 2 + pushOpcode;
-    return end === script.length ? script.slice(2, end) : undefined;
-  }
-
-  if (pushOpcode === 0x4c && script.length >= 3) {
-    const len = script[2];
-    const end = 3 + len;
-    return end === script.length ? script.slice(3, end) : undefined;
-  }
-
-  return undefined;
-}
-
-export function hexToBytes(hex: string): Uint8Array {
-  if (hex.length % 2 !== 0) {
-    throw new Error("Invalid hex string length");
-  }
-
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < bytes.length; i += 1) {
-    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-  }
-  return bytes;
-}

package/packages/btc-client/src/types.ts

@@ -1,112 +0,0 @@
-export type BitcoinNetwork = "mainnet" | "testnet" | "testnet4" | "signet" | "regtest";
-
-export interface BitcoinTxStatus {
-  confirmed: boolean;
-  block_height?: number;
-  block_hash?: string;
-  block_time?: number;
-}
-
-export interface BitcoinTxInput {
-  txid: string;
-  vout: number;
-  prevout: BitcoinTxOutput | null;
-  scriptsig: string;
-  scriptsig_asm: string;
-  witness?: string[];
-  is_coinbase: boolean;
-  sequence: number;
-}
-
-export interface BitcoinTxOutput {
-  scriptpubkey: string;
-  scriptpubkey_asm: string;
-  scriptpubkey_type: string;
-  scriptpubkey_address?: string;
-  value: number;
-}
-
-export interface BitcoinTransaction {
-  txid: string;
-  version: number;
-  locktime: number;
-  vin: BitcoinTxInput[];
-  vout: BitcoinTxOutput[];
-  size: number;
-  weight: number;
-  fee: number;
-  status: BitcoinTxStatus;
-}
-
-export interface BitcoinAddressInfo {
-  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 BitcoinUtxo {
-  txid: string;
-  vout: number;
-  status: BitcoinTxStatus;
-  value: number;
-}
-
-export interface BitcoinMerkleProof {
-  block_height: number;
-  merkle: string[];
-  pos: number;
-}
-
-export interface BitcoinOutspend {
-  spent: boolean;
-  txid?: string;
-  vin?: number;
-  status?: BitcoinTxStatus;
-}
-
-export interface BitcoinDepositCandidate {
-  address: string;
-  txid: string;
-  vout: number;
-  value: number;
-  confirmations: number;
-  status: BitcoinTxStatus;
-  opReturn?: UtxopiaDepositOpReturn;
-}
-
-export interface UtxopiaDepositOpReturn {
-  version: number;
-  destinationChain: number;
-  bitcoinNetwork: number;
-  poolTag: Uint8Array;
-  ephemeralPubkey: Uint8Array;
-  notePublicKey: Uint8Array;
-  rawPayload: Uint8Array;
-}
-
-export interface BitcoinClient {
-  getAddress(address: string): Promise<BitcoinAddressInfo>;
-  getAddressTxs(address: string, lastSeenTxid?: string): Promise<BitcoinTransaction[]>;
-  getAddressUtxos(address: string): Promise<BitcoinUtxo[]>;
-  getTransaction(txid: string): Promise<BitcoinTransaction>;
-  getTxStatus(txid: string): Promise<BitcoinTxStatus>;
-  getTxHex(txid: string): Promise<string>;
-  getTxMerkleProof(txid: string): Promise<BitcoinMerkleProof>;
-  getTxOutspend(txid: string, vout: number): Promise<BitcoinOutspend>;
-  getBlockHeight(): Promise<number>;
-  getBlockHash(height: number): Promise<string>;
-  getBlockHeader(hash: string): Promise<string>;
-  broadcastTx(txHex: string): Promise<string>;
-}

package/packages/sdk/README.md

@@ -1,277 +0,0 @@
-# @utxopia/sdk
-
-TypeScript SDK for interacting with the UTXOpia protocol - a privacy-preserving Bitcoin-to-Solana bridge using Zero-Knowledge Proofs.
-
-## Installation
-
-```bash
-bun add @utxopia/sdk
-# or
-npm install @utxopia/sdk
-```
-
-## Quick Start
-
-```typescript
-import {
-  deriveKeysFromWallet,
-  createStealthDeposit,
-  scanAnnouncements,
-  resolveSnsName,
-} from '@utxopia/sdk';
-
-// 1. Derive keys from wallet
-const keys = await deriveKeysFromWallet(walletAdapter);
-
-// 2. Look up recipient by .utxopia.sol name
-const recipient = await resolveSnsName(connection, 'alice');
-
-// 3. Create stealth deposit
-const deposit = await createStealthDeposit(recipient, 100000n);
-
-// 4. Scan for incoming deposits
-const notes = await scanAnnouncements(keys, announcements);
-```
-
-## Core Features
-
-### Key Derivation
-
-Derive spending and viewing keys from a Solana wallet signature (RAILGUN-style):
-
-```typescript
-import { deriveKeysFromWallet, type UTXOpiaKeys } from '@utxopia/sdk';
-
-const keys: UTXOpiaKeys = await deriveKeysFromWallet(walletAdapter);
-// keys.spendingPubKey - for receiving funds
-// keys.viewingPubKey  - for scanning deposits
-// keys.spendingPrivKey - for claiming (keep secret!)
-// keys.viewingPrivKey  - for scanning (can delegate)
-```
-
-### Stealth Addresses (EIP-5564/DKSAP Pattern)
-
-Create private deposits that only the recipient can detect and claim:
-
-```typescript
-import {
-  createStealthDeposit,
-  scanAnnouncements,
-  prepareClaimInputs,
-} from '@utxopia/sdk';
-
-// Sender: Create stealth deposit
-const deposit = await createStealthDeposit(recipientMeta, amountSats);
-// deposit.ephemeralPub - publish on-chain
-// deposit.commitment   - add to Merkle tree
-// deposit.amountSats   - verified BTC amount
-
-// Recipient: Scan for deposits
-const notes = await scanAnnouncements(keys, onChainAnnouncements);
-
-// Recipient: Prepare claim inputs for ZK proof
-const claimInputs = await prepareClaimInputs(keys, note, merkleProof);
-```
-
-### Note Generation
-
-Create and manage shielded notes:
-
-```typescript
-import {
-  generateNote,
-  deriveNote,
-  createClaimLink,
-  parseClaimLink,
-} from '@utxopia/sdk';
-
-// Generate random note
-const note = generateNote(100000n);
-
-// Derive deterministic note from seed
-const note = deriveNote('my-secret-phrase', 0, 100000n);
-
-// Create shareable claim link
-const link = createClaimLink(note);
-
-// Parse claim link
-const parsed = parseClaimLink(link);
-```
-
-### Taproot Address Derivation
-
-Generate BTC deposit addresses:
-
-```typescript
-import { deriveTaprootAddress, verifyTaprootAddress } from '@utxopia/sdk';
-
-// Use the configured FROST/Ika custody public key; there is no safe default.
-const custodyInternalKey = getConfiguredCustodyInternalKey();
-const { address } = deriveTaprootAddress(
-  commitment,
-  'testnet',
-  custodyInternalKey,
-);
-
-// Verify address matches commitment
-const isValid = verifyTaprootAddress(address, commitment, custodyInternalKey);
-```
-
-### Merkle Proofs
-
-Work with the on-chain commitment tree:
-
-```typescript
-import {
-  createMerkleProof,
-  proofToNoirFormat,
-  TREE_DEPTH,
-} from '@utxopia/sdk';
-
-const proof = createMerkleProof(leaves, leafIndex);
-const noirProof = proofToNoirFormat(proof);
-```
-
-## API Reference
-
-### Stealth Module
-
-| Function | Description |
-|----------|-------------|
-| `createStealthDeposit(recipient, amount)` | Create stealth deposit for recipient |
-| `scanAnnouncements(keys, announcements)` | Scan for deposits using viewing key |
-| `prepareClaimInputs(keys, note, proof)` | Prepare inputs for ZK claim proof |
-| `scanUnifiedNotes(keys, announcements)` | Scan announcement events for owned notes |
-| `resolveSnsName(conn, name)` | Look up .utxopia.sol name to stealth address |
-
-### Key Derivation Module
-
-| Function | Description |
-|----------|-------------|
-| `deriveKeysFromWallet(wallet)` | Derive keys from wallet signature |
-| `deriveKeysFromSignature(sig)` | Derive keys from raw signature |
-| `deriveKeysFromSeed(seed)` | Derive keys from seed bytes |
-| `createStealthMetaAddress(keys)` | Create stealth meta-address |
-| `createDelegatedViewKey(keys, perms, expiry)` | Create delegated view key |
-
-### Constants
-
-```typescript
-// Program IDs
-UTXOPIA_PROGRAM_ID        // Main UTXOpia program (devnet)
-CHADBUFFER_PROGRAM_ID    // ChadBuffer for SPV proofs
-
-// Merkle Tree
-TREE_DEPTH              // 20
-MAX_LEAVES              // 2^20
-ZERO_VALUE              // Empty leaf value
-
-```
-
-## Types
-
-### UTXOpiaKeys
-
-```typescript
-interface UTXOpiaKeys {
-  spendingPubKey: BabyJubPoint;
-  spendingPrivKey: bigint;
-  viewingPubKey: Uint8Array;
-  viewingPrivKey: Uint8Array;
-  nullifyingKey: bigint;
-}
-```
-
-### StealthDeposit
-
-```typescript
-interface StealthDeposit {
-  ephemeralPub: Uint8Array;  // 32 bytes (Ed25519)
-  amountSats: bigint;
-  commitment: Uint8Array;    // 32 bytes
-  createdAt: number;
-}
-```
-
-### ScannedNote
-
-```typescript
-interface ScannedNote {
-  amount: bigint;
-  ephemeralPub: Uint8Array;
-  stealthPub: BabyJubPoint;
-  leafIndex: number;
-  commitment: Uint8Array;
-}
-```
-
-### ConnectionAdapter
-
-```typescript
-interface ConnectionAdapter {
-  getAccountInfo: (
-    pubkey: { toBytes(): Uint8Array }
-  ) => Promise<{ data: Uint8Array } | null>;
-}
-```
-
-## Security Considerations
-
-1. **Never expose spending private key** - Only needed for claiming
-2. **Viewing key can be delegated** - For balance monitoring without spend capability
-3. **Nullifiers prevent double-spending** - Derived from spending key + leaf index
-4. **Commitments hide amounts** - Poseidon hash of NPK, token, and amount
-
-## Development
-
-```bash
-# Install dependencies
-bun install
-
-# Build
-bun run build
-
-# Run tests
-bun test
-```
-
-## Verify it yourself: rebuild the tree from chain
-
-Spending a note needs a Merkle proof, and a Merkle proof needs the whole leaf
-set — which normally comes from our indexer. If the leaves weren't recoverable
-from the chain itself, "you can exit without the operator" would be a promise
-rather than a property.
-
-This script rebuilds a pool's entire leaf set from Solana transaction logs and
-checks the result against the root the program is verifying against. It talks to
-a public RPC endpoint and nothing else — no backend, no indexer, no API key:
-
-```bash
-TREE=<commitment-tree-pda> bun run scripts/rebuild-tree-from-chain.ts
-```
-
-```
-on-chain: 123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
-  134/134 scanned, 123 leaves
-recovered 123/123 leaves from logs
-rebuilt:  123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
-
-MATCH — the leaf set is recoverable from chain alone
-```
-
-It exits non-zero on a mismatch or on missing leaves, so it works as a check in
-CI as well as by hand.
-
-| Env | Default | |
-|---|---|---|
-| `RPC` | devnet | Any Solana RPC endpoint |
-| `TREE` | `DEVNET_CONFIG.commitmentTreePda` | Commitment tree PDA to rebuild |
-| `EPOCH_SIG` | — | Tree's `INITIALIZE` signature. Optional; set it to skip a dead epoch if the PDA was closed and recreated |
-| `PACE_MS` | `120` | Delay between requests. Raise it if your endpoint throttles you |
-
-Public endpoints rate-limit this scan aggressively — the script paces itself and
-backs off, so expect it to take a minute or two rather than to fail.
-
-## License
-
-MIT