@utxopia/sdk 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UTXOpia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# UTXOpia SDK
+
+TypeScript client for [UTXOpia](https://utxopia.com) — a privacy-preserving Bitcoin-to-Solana
+bridge. Deposits arrive as commitments in a Merkle tree, transfers move between commitments with
+Groth16 JoinSplit proofs, and an amount only becomes public when someone withdraws.
+
+> **Alpha.** `0.1.0-alpha.1`. The protocol has not been deployed to mainnet — do not point this at
+> funds you cannot lose.
+>
+> **The export surface is not a contract yet.** Roughly 430 things are exported; about a third are
+> exercised by the reference apps, and the rest is protocol surface nobody has needed yet or
+> helpers that were never deliberately made public. Being pre-1.0 is what makes that survivable:
+> the surface will be narrowed to the workflows below before 1.0, and anything outside them may
+> disappear in a minor release. Build against what `docs/API-MAP.md` marks as used; if you need
+> something else, open an issue so it gets kept on purpose rather than by accident.
+
+## Install
+
+```bash
+bun add @utxopia/sdk
+```
+
+Installing from git instead? Pin a commit, never a branch. A floating `#main` means two apps that
+installed a week apart disagree about the note format, and the failure surfaces as a proof that
+will not verify rather than as an install error:
+
+```jsonc
+// package.json
+"@utxopia/sdk": "github:UTXOpia/utxopia-sdk#<full-commit-sha>"
+```
+
+`snarkjs` and `react` are optional peers — install `snarkjs` only if you generate proofs, `react`
+only if you use the hooks.
+
+## What the pieces are
+
+| Concept | What it means here |
+|---|---|
+| **Note** | A commitment `Poseidon(npk, token, amount)` in the tree. Owning one means knowing the key behind `npk`. |
+| **Nullifier** | `Poseidon(nullifyingKey, leafIndex)`. Published on spend so a note cannot be spent twice; it reveals nothing about which note it was. |
+| **Stealth address** | A recipient publishes a meta-address; each sender derives a fresh one-time `npk` from it, so payments to the same person are unlinkable on-chain. |
+| **JoinSplit(N,M)** | One proof spends N notes and creates M. Shapes with `N + M ≤ 10` are accepted on-chain, 45 in total. |
+| **Viewing key** | Decrypts incoming announcements. Separate from the spending key, so scanning can be delegated. |
+
+## Quick start
+
+```typescript
+import {
+  deriveKeysFromWallet,
+  resolveSnsName,
+  createStealthDeposit,
+  scanAnnouncements,
+} from "@utxopia/sdk";
+
+// Keys come from a wallet signature over a fixed message — nothing to store.
+const keys = await deriveKeysFromWallet(walletAdapter);
+
+// Recipients can be a .utxopia.sol name instead of a raw meta-address.
+const recipient = await resolveSnsName(connection, "alice");
+
+const deposit = await createStealthDeposit(recipient, 100_000n);
+
+// Scanning is a local trial-decrypt of every announcement — there is no
+// "my transactions" endpoint to ask, by design.
+const notes = await scanAnnouncements(keys, announcements);
+```
+
+`docs/API-MAP.md` lists every export grouped by what you are building — config, keys, PDAs,
+notes, stealth, Bitcoin, proving, instructions, chain reads, disclosure — and marks which ones
+the reference apps actually use. `packages/sdk/README.md` covers each area in depth;
+`packages/sdk/docs/SDK.md` has the full type reference.
+
+## Entry points
+
+```typescript
+import { … } from "@utxopia/sdk";                 // everything below is re-exported here
+import { … } from "@utxopia/sdk/prover/web";      // browser proving (snarkjs + WebAssembly)
+import { … } from "@utxopia/sdk/prover/mobile";   // React Native proving
+import { … } from "@utxopia/sdk/bitcoin";         // taproot, Ika custody
+import { … } from "@utxopia/sdk/stealth";         // stealth addresses on their own
+import { … } from "@utxopia/sdk/btc-client";      // Esplora client, OP_RETURN encoding
+```
+
+The root export is the whole surface. The subpaths exist so a bundle that only needs, say,
+Esplora does not pull in the prover.
+
+## Naming
+
+The prefix tells you what a call costs, so you can read an import list without opening anything:
+
+| prefix | meaning |
+|---|---|
+| `derive*PDA` | pure address math, synchronous |
+| `fetch*` | hits the network — always async |
+| `get*` | reads local or already-fetched state — synchronous |
+| `parse*` | bytes in, typed object out; no IO |
+| `build*InstructionData` / `build*Instruction` | encode instruction data / assemble the full instruction |
+| `compute*Sync` | Poseidon hashes. Only the `Sync` form exists — poseidon-lite has nothing to await |
+| `encode`/`decode`, `pack`/`unpack`, `serialize`/`deserialize` | symmetric pairs, always both directions |
+
+`PDA` is spelled in caps. Seven MagicBlock helpers used to say `Pda` and two RPC calls were named
+`get*`; they were renamed before the first publish, while doing so was still free.
+
+## Proving
+
+Proof generation needs circuit artifacts — a `.wasm` witness generator and a `.zkey` — which are
+too large to ship in the package. Point the prover at a host serving them:
+
+```typescript
+import { setCircuitPath, generateJoinSplitProof } from "@utxopia/sdk/prover/web";
+
+setCircuitPath("https://circuit.utxopia.com/circuits/v2/groth16");
+const proof = await generateJoinSplitProof(inputs);
+```
+
+**Pin the artifacts you are willing to prove with.** The `.wasm` is the witness generator: it
+receives every private input a JoinSplit has — spending key, nullifying key, note randomness,
+amounts, the full Merkle path — in the clear. It arrives over plain `fetch`, where subresource
+integrity does not apply, and CDNs serve it `immutable, max-age=31536000`, so a substituted file
+survives in browser and edge caches long after the origin is cleaned. Proofs built from a poisoned
+generator still verify, so nothing fails and no user notices.
+
+```typescript
+import { setCircuitArtifactDigests } from "@utxopia/sdk/prover/web";
+import digests from "./circuit-manifest.json"; // generated by your build, committed
+
+setCircuitArtifactDigests(digests.artifacts);
+```
+
+Keys are paths under the circuit base (`joinsplit_1x1/joinsplit_1x1_js/joinsplit_1x1.wasm`), so one
+manifest covers local dev and the CDN. Once set it fails closed: an artifact with no recorded
+digest is refused rather than trusted, so the manifest has to cover every shape your origin serves.
+The SDK cannot ship these — they change whenever circuits are rebuilt.
+
+## Layout
+
+```
+packages/sdk/          the SDK — keys, notes, stealth, proving, Solana instructions
+packages/btc-client/   standalone Esplora client and deposit OP_RETURN encoding
+```
+
+## Development
+
+```bash
+bun install
+bun run test     # 782 tests
+bun run build    # tsc
+```
+
+Tests are pure unit tests — no network, no validator, no proving. They run in about eight seconds,
+so there is no reason to skip them.
+
+## Security
+
+Two things worth knowing before you build on this:
+
+- **`createDelegatedViewKey` currently hands over the `nullifyingKey`.** Because
+  `nullifier = Poseidon(nullifyingKey, leafIndex)` does not depend on note contents and leaf
+  indices are small public integers, anyone holding it can compute every nullifier that key will
+  ever produce and link the owner's entire spend history, retroactively and permanently. The
+  `fromSlot`/`toSlot` and FULL/SCAN/INCOMING_ONLY fields on a delegated key are metadata, not
+  enforcement. Treat a delegated viewing key as handing over the whole account, not a slice of it.
+  `extractViewOnlyBundle` correctly omits the key and is the safer thing to reach for.
+- Keys derive from a wallet signature, so **any party who can make that wallet sign the derivation
+  message can reconstruct the shielded identity.** A hardware wallet does not change this.
+
+Report anything else privately rather than in a public issue.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@utxopia/sdk",
+  "version": "0.1.0-alpha.1",
+  "description": "UTXOpia public SDK workspace",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UTXOpia/utxopia-sdk.git"
+  },
+  "homepage": "https://github.com/UTXOpia/utxopia-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/UTXOpia/utxopia-sdk/issues"
+  },
+  "type": "module",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "packages/sdk/dist",
+    "packages/btc-client/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "main": "./packages/sdk/dist/index.js",
+  "module": "./packages/sdk/dist/index.js",
+  "types": "./packages/sdk/dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./packages/sdk/dist/index.d.ts",
+      "import": "./packages/sdk/dist/index.js",
+      "default": "./packages/sdk/dist/index.js"
+    },
+    "./prover": {
+      "types": "./packages/sdk/dist/prover/index.d.ts",
+      "import": "./packages/sdk/dist/prover/index.js",
+      "default": "./packages/sdk/dist/prover/index.js"
+    },
+    "./prover/web": {
+      "types": "./packages/sdk/dist/prover/web.d.ts",
+      "import": "./packages/sdk/dist/prover/web.js",
+      "default": "./packages/sdk/dist/prover/web.js"
+    },
+    "./prover/mobile": {
+      "types": "./packages/sdk/dist/prover/mobile.d.ts",
+      "import": "./packages/sdk/dist/prover/mobile.js",
+      "default": "./packages/sdk/dist/prover/mobile.js"
+    },
+    "./bitcoin": {
+      "types": "./packages/sdk/dist/bitcoin/index.d.ts",
+      "import": "./packages/sdk/dist/bitcoin/index.js",
+      "default": "./packages/sdk/dist/bitcoin/index.js"
+    },
+    "./stealth": {
+      "types": "./packages/sdk/dist/stealth.d.ts",
+      "import": "./packages/sdk/dist/stealth.js",
+      "default": "./packages/sdk/dist/stealth.js"
+    },
+    "./btc-client": {
+      "types": "./packages/btc-client/src/index.ts",
+      "import": "./packages/btc-client/src/index.ts",
+      "default": "./packages/btc-client/src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "cd packages/sdk && bunx tsc",
+    "test": "cd packages/sdk && bun install --ignore-scripts && bun test",
+    "prepare": "cd packages/sdk && bunx tsc",
+    "copy-circuits": "cd packages/sdk && bun run copy-circuits"
+  },
+  "dependencies": {
+    "@magicblock-labs/ephemeral-rollups-kit": "0.16.2",
+    "@noble/ciphers": "^2.2.0",
+    "@noble/curves": "2.0.1",
+    "@noble/hashes": "1.8.0",
+    "@scure/base": "2.0.0",
+    "@scure/btc-signer": "2.0.1",
+    "@solana-program/system": "^0.10.0",
+    "@solana/kit": "^5.5.0",
+    "bech32": "^2.0.0",
+    "circomlibjs": "^0.1.7",
+    "poseidon-lite": "0.3.0"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "snarkjs": "^0.7.5"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "snarkjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@solana/web3.js": "^1.98.4",
+    "@types/node": "^20.10.0",
+    "@types/react": "^19",
+    "typescript": "^5.3.0"
+  },
+  "overrides": {
+    "uuid": "11.1.1",
+    "valibot": "1.4.2",
+    "ws": "8.21.1"
+  }
+}

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

@@ -0,0 +1,153 @@
+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

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

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

@@ -0,0 +1,93 @@
+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

@@ -0,0 +1,112 @@
+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>;
+}