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

package/README.md

@@ -1,170 +1,276 @@
-# UTXOpia SDK
+# @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.
+TypeScript SDK for interacting with the UTXOpia protocol - a privacy-preserving Bitcoin-to-Solana bridge using Zero-Knowledge Proofs.
 
-> **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
+## Installation
 
 ```bash
 bun add @utxopia/sdk
+# or
+npm install @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:
+## Quick Start
+
+```typescript
+import {
+  deriveKeysFromWallet,
+  createStealthDeposit,
+  scanAnnouncements,
+  resolveSnsName,
+} from '@utxopia/sdk';
 
-```jsonc
-// package.json
-"@utxopia/sdk": "github:UTXOpia/utxopia-sdk#<full-commit-sha>"
+// 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);
 ```
 
-`snarkjs` and `react` are optional peers — install `snarkjs` only if you generate proofs, `react`
-only if you use the hooks.
+## Core Features
+
+### Key Derivation
+
+Derive spending and viewing keys from a Solana wallet signature (RAILGUN-style):
 
-## What the pieces are
+```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)
+```
 
-| 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. |
+### Stealth Addresses (EIP-5564/DKSAP Pattern)
 
-## Quick start
+Create private deposits that only the recipient can detect and claim:
 
 ```typescript
 import {
-  deriveKeysFromWallet,
-  resolveSnsName,
   createStealthDeposit,
   scanAnnouncements,
-} from "@utxopia/sdk";
+  prepareClaimInputs,
+} from '@utxopia/sdk';
 
-// Keys come from a wallet signature over a fixed message — nothing to store.
-const keys = await deriveKeysFromWallet(walletAdapter);
+// 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
 
-// Recipients can be a .utxopia.sol name instead of a raw meta-address.
-const recipient = await resolveSnsName(connection, "alice");
+// Recipient: Scan for deposits
+const notes = await scanAnnouncements(keys, onChainAnnouncements);
 
-const deposit = await createStealthDeposit(recipient, 100_000n);
+// Recipient: Prepare claim inputs for ZK proof
+const claimInputs = await prepareClaimInputs(keys, note, merkleProof);
+```
 
-// 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);
+### 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);
 ```
 
-`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.
+### Taproot Address Derivation
 
-## Entry points
+Generate BTC deposit addresses:
 
 ```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
+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);
 ```
 
-The root export is the whole surface. The subpaths exist so a bundle that only needs, say,
-Esplora does not pull in the prover.
+### 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);
+```
 
-## Naming
+## API Reference
 
-The prefix tells you what a call costs, so you can read an import list without opening anything:
+### Stealth Module
 
-| 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 |
+| 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 |
 
-`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.
+### Key Derivation Module
 
-## Proving
+| 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 |
 
-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:
+### Constants
 
 ```typescript
-import { setCircuitPath, generateJoinSplitProof } from "@utxopia/sdk/prover/web";
+// 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
 
-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.
+## Types
 
-```typescript
-import { setCircuitArtifactDigests } from "@utxopia/sdk/prover/web";
-import digests from "./circuit-manifest.json"; // generated by your build, committed
+### UTXOpiaKeys
 
-setCircuitArtifactDigests(digests.artifacts);
+```typescript
+interface UTXOpiaKeys {
+  spendingPubKey: BabyJubPoint;
+  spendingPrivKey: bigint;
+  viewingPubKey: Uint8Array;
+  viewingPrivKey: Uint8Array;
+  nullifyingKey: bigint;
+}
 ```
 
-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.
+### StealthDeposit
 
-## Layout
+```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;
+}
 ```
-packages/sdk/          the SDK — keys, notes, stealth, proving, Solana instructions
-packages/btc-client/   standalone Esplora client and deposit OP_RETURN encoding
+
+### 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
-bun run test     # 782 tests
-bun run build    # tsc
+
+# 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
 ```
 
-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.
+```
+on-chain: 123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
+  134/134 scanned, 123 leaves
+recovered 123/123 leaves from logs
+rebuilt:  123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
 
-## Security
+MATCH — the leaf set is recoverable from chain alone
+```
 
-Two things worth knowing before you build on this:
+It exits non-zero on a mismatch or on missing leaves, so it works as a check in
+CI as well as by hand.
 
-- **`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.
+| 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 |
 
-Report anything else privately rather than in a public issue.
+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
 

package/{packages/sdk/dist → dist}/client.d.ts

@@ -18,7 +18,7 @@
  */
 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 ViewOnlyKeys, type StealthOutputWithKeys, type NonInteractiveDepositResult, type TweakDepositResult } from "./stealth";
 import { type UtxoDescriptor } from "./psbt";
 import { type DepositOpReturnContext } from "./taproot";
 export interface UTXOpiaClientConfig {
@@ -137,6 +137,30 @@ export declare class UTXOpiaClient {
     computeNullifier(note: {
         leafIndex: number;
     }): Uint8Array;
+    /**
+     * Prepare an OP_RETURN-free BTC deposit address (`verify_deposit`, disc 25).
+     *
+     * The ephemeral key is derived from this wallet's own viewing node and
+     * `depositIndex`, never randomly. A deposit address commits to the ephemeral
+     * key through its tapleaf and its key path is a NUMS point, so an address whose
+     * ephemeral key is lost is one nobody can ever spend. Indexing it makes the
+     * viewing key a complete backup: walk `depositIndex` upward and every address
+     * comes back.
+     *
+     * Self-deposit only. The address is recovered by whoever holds the viewing key
+     * it was derived from, so generating one *for someone else* would hand them a
+     * note they own but coins they could never recover. Pay a third party with a
+     * shielded transfer instead.
+     *
+     * `depositIndex` must be persisted and monotonic. Reusing one re-derives the
+     * same address, which is safe on chain but links the two deposits.
+     */
+    prepareTweakDeposit(opts: {
+        depositIndex: number;
+        ikaXOnlyPubkey: Uint8Array;
+        recipient?: StealthMetaAddress;
+        network?: "mainnet" | "testnet" | "regtest";
+    }): Promise<TweakDepositResult>;
     /**
      * Prepare a BTC deposit: generate stealth deposit address + OP_RETURN.
      * Returns the deposit result (btcAddress, opReturnPayload) ready for PSBT building.

package/{packages/sdk/dist → dist}/client.js

@@ -22,7 +22,7 @@ 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 { scanUnifiedNotesMulti, scanAnnouncementsViewOnlyMulti, computeNullifierHashForNote, computeNullifierBytes, isDepositForViewerHex, createDepositFromConfig, createTweakDeposit, depositViewingNode, createStealthOutputWithKeys, } from "./stealth";
 import { selectUtxos } from "./psbt";
 import { hexToBytes } from "./crypto";
 import { EventClient } from "./event-client";
@@ -308,6 +308,41 @@ export class UTXOpiaClient {
         throw new Error("Not authenticated");
     }
     // ─── Phase 2: Deposit + Shield ─────────────────────────────────
+    /**
+     * Prepare an OP_RETURN-free BTC deposit address (`verify_deposit`, disc 25).
+     *
+     * The ephemeral key is derived from this wallet's own viewing node and
+     * `depositIndex`, never randomly. A deposit address commits to the ephemeral
+     * key through its tapleaf and its key path is a NUMS point, so an address whose
+     * ephemeral key is lost is one nobody can ever spend. Indexing it makes the
+     * viewing key a complete backup: walk `depositIndex` upward and every address
+     * comes back.
+     *
+     * Self-deposit only. The address is recovered by whoever holds the viewing key
+     * it was derived from, so generating one *for someone else* would hand them a
+     * note they own but coins they could never recover. Pay a third party with a
+     * shielded transfer instead.
+     *
+     * `depositIndex` must be persisted and monotonic. Reusing one re-derives the
+     * same address, which is safe on chain but links the two deposits.
+     */
+    async prepareTweakDeposit(opts) {
+        if (!this._keys) {
+            throw new Error("No keys (login first)");
+        }
+        const meta = opts.recipient ?? this._stealthAddress;
+        if (!meta)
+            throw new Error("No recipient stealth address (login first or provide recipient)");
+        if (opts.recipient && this._stealthAddress && opts.recipient !== this._stealthAddress) {
+            throw new Error("prepareTweakDeposit is self-deposit only: the recipient must be able to derive the " +
+                "ephemeral key to recover the coins, and only this wallet's viewing key can");
+        }
+        const network = opts.network ?? sdkBitcoinNetworkToAddressNetwork(this.config.bitcoinNetwork);
+        return createTweakDeposit(meta, opts.ikaXOnlyPubkey, {
+            viewingNode: depositViewingNode(this._keys.viewingPrivKey),
+            depositIndex: opts.depositIndex,
+        }, network);
+    }
     /**
      * Prepare a BTC deposit: generate stealth deposit address + OP_RETURN.
      * Returns the deposit result (btcAddress, opReturnPayload) ready for PSBT building.

package/{packages/sdk/dist → dist}/config.d.ts

@@ -20,7 +20,7 @@ import { type Address } from "@solana/kit";
  */
 export declare function address(input: string): Address;
 export type NetworkType = "devnet" | "mainnet" | "localnet";
-export type AppNetworkId = NetworkType | "devnet-regtest";
+export type AppNetworkId = NetworkType | "devnet-regtest" | "devnet-testnet4";
 export interface NetworkConfig {
     /** Network identifier */
     network: NetworkType;
@@ -99,10 +99,41 @@ 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.
+ * Greenfield devnet + Bitcoin testnet4 deployment (2026-08-26).
+ *
+ * The previous deployment's programs were closed on chain, so this is not a redeploy and none
+ * of the old addresses resolve any more — anything still pinned to CvfSyACR… is talking to a
+ * program that no longer exists.
+ *
+ * Two pools were deployed, each with its own Ika DKG and therefore its own dWallet. The default
+ * below is the OPEN pool. Select the verified pool by overriding `zkbtcMint` and
+ * `ikaDwalletXOnlyPubkey` — `getConfig` re-derives poolStatePda, commitmentTreePda and poolVault
+ * from the mint, so those two values are all a caller needs:
+ *
+ *   verified  mint  G78CTddWGDaNaSKQayAt7m3pzcMyaUNxgR8y3R34YvEv
+ *             state Eqn9SmFYtacrdfPE9Shbi8bDXLjCNNz3WhHfqtJnwbKY
+ *             xonly 16c563baa11bfc8fe93acafe8fe169b954b3ead3ecda7754c615dec9e840b5a5
+ *
+ * Read off chain, not from the deploy notes: Eqn9SmFY… is the pool whose PoolState flags carry
+ * the permissioned bit (0b10 at offset 2). The deployment also contains a THIRD pool —
+ * 3chHiDqM… / 7wDtDd1u… — which the deploy notes name as the verified one but which is not
+ * permissioned and whose mint has zero supply. Treat it as abandoned; do not wire it up.
  */
 export declare const DEVNET_CONFIG: NetworkConfig;
+/**
+ * Solana devnet + Bitcoin **regtest** deployment — the environment app.utxopia.com serves.
+ *
+ * This is a different deployment from DEVNET_CONFIG above, not a Bitcoin-side variation of it:
+ * a different program (CvfSyACR…), a different pool, a different Ika dWallet. It used to share
+ * DEVNET_CONFIG and differ only by bitcoinNetwork, which worked while one program hosted both.
+ * It no longer does — after 2026-08-26 there are two programs — so `devnet-regtest` resolving
+ * to DEVNET_CONFIG would silently point this environment at testnet4's program and pool.
+ *
+ * Pool addresses derived from the mint with the same seeds getConfig uses, then confirmed on
+ * devnet: pool_state and commitment_tree owned by CvfSyACR… at 332 and 8816 bytes, the vault by
+ * Token-2022 at 170.
+ */
+export declare const DEVNET_REGTEST_CONFIG: NetworkConfig;
 /**
  * Mainnet Configuration (placeholder - not yet deployed)
  */