@arkade-os/sdk 0.1.4 → 0.2.1

package/dist/types/wallet/wallet.d.ts

@@ -1,42 +1,88 @@
 import { ArkAddress } from "../script/address";
 import { DefaultVtxo } from "../script/default";
-import { SettlementEvent } from "../providers/ark";
-import { Addresses, AddressInfo, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, IWallet, Outpoint, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig } from ".";
+import { Network, NetworkName } from "../networks";
+import { OnchainProvider } from "../providers/onchain";
+import { SettlementEvent, ArkProvider } from "../providers/ark";
+import { Identity } from "../identity";
+import { ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IWallet, SendBitcoinParams, SettleParams, VirtualCoin, WalletBalance, WalletConfig } from ".";
+import { Bytes } from "@scure/btc-signer/utils";
+import { CSVMultisigTapscript } from "../script/tapscript";
+import { IndexerProvider } from "../providers/indexer";
+export type IncomingFunds = {
+    type: "utxo";
+    coins: Coin[];
+} | {
+    type: "vtxo";
+    vtxos: VirtualCoin[];
+};
+/**
+ * Main wallet implementation for Bitcoin transactions with Ark protocol support.
+ * The wallet does not store any data locally and relies on Ark and onchain
+ * providers to fetch UTXOs and VTXOs.
+ *
+ * @example
+ * ```typescript
+ * // Create a wallet
+ * const wallet = await Wallet.create({
+ *   identity: SingleKey.fromHex('your_private_key'),
+ *   arkServerUrl: 'https://ark.example.com',
+ *   esploraUrl: 'https://mempool.space/api'
+ * });
+ *
+ * // Get addresses
+ * const arkAddress = await wallet.getAddress();
+ * const boardingAddress = await wallet.getBoardingAddress();
+ *
+ * // Send bitcoin
+ * const txid = await wallet.sendBitcoin({
+ *   address: 'tb1...',
+ *   amount: 50000
+ * });
+ * ```
+ */
 export declare class Wallet implements IWallet {
-    private identity;
-    private network;
-    private onchainProvider;
-    private onchainP2TR;
-    private arkProvider?;
-    private arkServerPublicKey?;
-    readonly offchainTapscript?: DefaultVtxo.Script | undefined;
-    readonly boardingTapscript?: DefaultVtxo.Script | undefined;
-    static FEE_RATE: number;
+    readonly identity: Identity;
+    readonly network: Network;
+    readonly networkName: NetworkName;
+    readonly onchainProvider: OnchainProvider;
+    readonly arkProvider: ArkProvider;
+    readonly indexerProvider: IndexerProvider;
+    readonly arkServerPublicKey: Bytes;
+    readonly offchainTapscript: DefaultVtxo.Script;
+    readonly boardingTapscript: DefaultVtxo.Script;
+    readonly serverUnrollScript: CSVMultisigTapscript.Type;
+    readonly forfeitOutputScript: Bytes;
+    readonly dustAmount: bigint;
+    static MIN_FEE_RATE: number;
     private constructor();
     static create(config: WalletConfig): Promise<Wallet>;
-    get onchainAddress(): string;
-    get boardingAddress(): ArkAddress;
-    get boardingOnchainAddress(): string;
-    get offchainAddress(): ArkAddress;
-    getAddress(): Promise<Addresses>;
-    getAddressInfo(): Promise<AddressInfo>;
+    get arkAddress(): ArkAddress;
+    getAddress(): Promise<string>;
+    getBoardingAddress(): Promise<string>;
     getBalance(): Promise<WalletBalance>;
-    getCoins(): Promise<Coin[]>;
-    getVtxos(): Promise<ExtendedVirtualCoin[]>;
+    getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
     private getVirtualCoins;
     getTransactionHistory(): Promise<ArkTransaction[]>;
     getBoardingTxs(): Promise<{
         boardingTxs: ArkTransaction[];
-        roundsToIgnore: Set<string>;
+        commitmentsToIgnore: Set<string>;
     }>;
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
-    sendBitcoin(params: SendBitcoinParams, zeroFee?: boolean): Promise<string>;
-    private isOffchainSuitable;
-    private sendOnchain;
-    private sendOffchain;
+    sendBitcoin(params: SendBitcoinParams): Promise<string>;
     settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
-    exit(outpoints?: Outpoint[]): Promise<void>;
+    notifyIncomingFunds(eventCallback: (coins: IncomingFunds) => void): Promise<() => void>;
+    private handleBatchStartedEvent;
     private handleSettlementSigningEvent;
     private handleSettlementSigningNoncesGeneratedEvent;
     private handleSettlementFinalizationEvent;
+    private makeRegisterIntentSignature;
+    private makeDeleteIntentSignature;
+    private prepareBIP322Inputs;
+    private makeBIP322Signature;
 }
+/**
+ * Wait for incoming funds to the wallet
+ * @param wallet - The wallet to wait for incoming funds
+ * @returns A promise that resolves the next new coins received by the wallet's address
+ */
+export declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -22,6 +22,37 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "scripts": {
+    "build": "rimraf dist && pnpm run build:esm && node scripts/add-extensions.js && pnpm run build:cjs && pnpm run build:types && node scripts/generate-package-files.js",
+    "build:esm": "tsc -p tsconfig.esm.json --outDir dist/esm",
+    "build:cjs": "tsc -p tsconfig.cjs.json --outDir dist/cjs",
+    "build:types": "tsc -p tsconfig.json --outDir dist/types --emitDeclarationOnly",
+    "build:browser": "node scripts/build-browser.js",
+    "docs:build": "pnpm run build:types && pnpm typedoc",
+    "docs:open": "open ./docs/index.html",
+    "test": "vitest run",
+    "test:master": "ARK_ENV=master vitest run",
+    "test:unit": "vitest run --exclude test/e2e",
+    "test:setup": "node test/setup.js",
+    "test:setup-docker": "node test/setup.js docker",
+    "test:build-docker": "docker compose -f docker-compose.yml build --no-cache",
+    "test:up-docker": "docker compose -f docker-compose.yml up -d",
+    "test:down-docker": "docker compose -f docker-compose.yml down",
+    "test:integration": "vitest run test/e2e/**",
+    "test:integration-docker": "ARK_ENV=docker vitest run test/e2e/**",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:sw": "pnpm run build:browser && node test/serviceWorker/serve.js",
+    "format": "prettier --write src test examples",
+    "lint": "prettier --check src test examples",
+    "audit": "pnpm audit",
+    "preinstall": "npx only-allow pnpm",
+    "prepare": "husky",
+    "prepublishOnly": "pnpm run build",
+    "release": "bash scripts/release.sh",
+    "release:dry-run": "bash scripts/release.sh --dry-run",
+    "release:cleanup": "bash scripts/release.sh --cleanup"
+  },
   "dependencies": {
     "@noble/curves": "1.9.1",
     "@noble/hashes": "1.8.0",
@@ -32,17 +63,13 @@
   },
   "devDependencies": {
     "rimraf": "^5.0.0",
-    "@eslint/js": "^9.17.0",
     "@types/node": "22.10.2",
-    "@typescript-eslint/eslint-plugin": "8.18.2",
-    "@typescript-eslint/parser": "8.18.2",
     "@vitest/coverage-v8": "2.1.9",
     "esbuild": "^0.20.1",
-    "eslint": "^9.17.0",
     "glob": "11.0.1",
     "husky": "9.1.7",
-    "lint-staged": "15.3.0",
     "prettier": "3.4.2",
+    "typedoc": "^0.27.1",
     "typescript": "5.7.2",
     "vitest": "2.1.9"
   },
@@ -51,38 +78,13 @@
     "wallet",
     "taproot",
     "ark",
-    "sdk"
+    "sdk",
+    "arkade"
   ],
   "author": "Ark Labs",
   "license": "MIT",
+  "packageManager": "pnpm@9.15.2+sha512.93e57b0126f0df74ce6bff29680394c0ba54ec47246b9cf321f0121d8d9bb03f750a705f24edc3c1180853afd7c2c3b94196d0a3d53d3e069d9e2793ef11f321",
   "engines": {
     "node": "^14.17.0 || ^16.13.0 || >=18.0.0"
-  },
-  "scripts": {
-    "build": "rimraf dist && pnpm run build:esm && node scripts/add-extensions.js && pnpm run build:cjs && pnpm run build:types && node scripts/generate-package-files.js",
-    "build:esm": "tsc -p tsconfig.esm.json --outDir dist/esm",
-    "build:cjs": "tsc -p tsconfig.cjs.json --outDir dist/cjs",
-    "build:types": "tsc -p tsconfig.json --outDir dist/types --emitDeclarationOnly",
-    "build:browser": "node scripts/build-browser.js",
-    "test": "vitest run",
-    "test:master": "ARK_ENV=master vitest run",
-    "test:unit": "vitest run --exclude test/integration.test.ts",
-    "test:setup": "node test/setup.js",
-    "test:setup-master": "node test/setup.js master",
-    "test:up-master": "docker compose -f docker-compose.yml up -d --build",
-    "test:down-master": "docker compose -f docker-compose.yml down",
-    "test:integration": "vitest run test/integration.test.ts",
-    "test:integration-master": "ARK_ENV=master vitest run test/integration.test.ts",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:sw": "pnpm run build:browser && node test/serviceWorker/serve.js",
-    "format": "prettier --write src test examples",
-    "lint": "prettier --check src test examples",
-    "audit": "pnpm audit",
-    "preinstall": "npx only-allow pnpm",
-    "release": "bash scripts/release.sh",
-    "release:dry-run": "bash scripts/release.sh --dry-run",
-    "release:cleanup": "bash scripts/release.sh --cleanup",
-    "precommit": "lint-staged"
   }
-}
+}

package/dist/cjs/identity/inMemoryKey.js

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryKey = void 0;
-const utils_1 = require("@scure/btc-signer/utils");
-const base_1 = require("@scure/base");
-const signingSession_1 = require("../tree/signingSession");
-const ZERO_32 = new Uint8Array(32).fill(0);
-class InMemoryKey {
-    constructor(key) {
-        this.key = key || (0, utils_1.randomPrivateKeyBytes)();
-    }
-    static fromPrivateKey(privateKey) {
-        return new InMemoryKey(privateKey);
-    }
-    static fromHex(privateKeyHex) {
-        return new InMemoryKey(base_1.hex.decode(privateKeyHex));
-    }
-    async sign(tx, inputIndexes) {
-        const txCpy = tx.clone();
-        if (!inputIndexes) {
-            if (!txCpy.sign(this.key, undefined, ZERO_32)) {
-                throw new Error("Failed to sign transaction");
-            }
-            return txCpy;
-        }
-        for (const inputIndex of inputIndexes) {
-            if (!txCpy.signIdx(this.key, inputIndex, undefined, ZERO_32)) {
-                throw new Error(`Failed to sign input #${inputIndex}`);
-            }
-        }
-        return txCpy;
-    }
-    xOnlyPublicKey() {
-        return (0, utils_1.pubSchnorr)(this.key);
-    }
-    signerSession() {
-        return signingSession_1.TreeSignerSession.random();
-    }
-}
-exports.InMemoryKey = InMemoryKey;

package/dist/cjs/tree/vtxoTree.js

@@ -1,231 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TxTree = exports.ErrParentNotFound = exports.ErrLeafNotFound = exports.TxTreeError = void 0;
-exports.getVtxoTreeExpiry = getVtxoTreeExpiry;
-exports.getCosignerKeys = getCosignerKeys;
-const bip68 = __importStar(require("bip68"));
-const btc_signer_1 = require("@scure/btc-signer");
-const utils_1 = require("@scure/btc-signer/utils");
-const base_1 = require("@scure/base");
-class TxTreeError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "TxTreeError";
-    }
-}
-exports.TxTreeError = TxTreeError;
-exports.ErrLeafNotFound = new TxTreeError("leaf not found in tx tree");
-exports.ErrParentNotFound = new TxTreeError("parent not found");
-// TxTree is represented as a matrix of Node objects
-// the first level of the matrix is the root of the tree
-class TxTree {
-    constructor(tree) {
-        this.tree = tree;
-    }
-    get levels() {
-        return this.tree;
-    }
-    // Returns the root node of the vtxo tree
-    root() {
-        if (this.tree.length <= 0 || this.tree[0].length <= 0) {
-            throw new TxTreeError("empty vtxo tree");
-        }
-        return this.tree[0][0];
-    }
-    // Returns the leaves of the vtxo tree
-    leaves() {
-        const leaves = [...this.tree[this.tree.length - 1]];
-        // Check other levels for leaf nodes
-        for (let i = 0; i < this.tree.length - 1; i++) {
-            for (const node of this.tree[i]) {
-                if (node.leaf) {
-                    leaves.push(node);
-                }
-            }
-        }
-        return leaves;
-    }
-    // Returns all nodes that have the given node as parent
-    children(nodeTxid) {
-        const children = [];
-        for (const level of this.tree) {
-            for (const node of level) {
-                if (node.parentTxid === nodeTxid) {
-                    children.push(node);
-                }
-            }
-        }
-        return children;
-    }
-    // Returns the total number of nodes in the vtxo tree
-    numberOfNodes() {
-        return this.tree.reduce((count, level) => count + level.length, 0);
-    }
-    // Returns the branch of the given vtxo txid from root to leaf
-    branch(vtxoTxid) {
-        const branch = [];
-        const leaves = this.leaves();
-        // Check if the vtxo is a leaf
-        const leaf = leaves.find((leaf) => leaf.txid === vtxoTxid);
-        if (!leaf) {
-            throw exports.ErrLeafNotFound;
-        }
-        branch.push(leaf);
-        const rootTxid = this.root().txid;
-        while (branch[0].txid !== rootTxid) {
-            const parent = this.findParent(branch[0]);
-            branch.unshift(parent);
-        }
-        return branch;
-    }
-    // Returns the remaining transactions to broadcast in order to exit the vtxo
-    async exitBranch(vtxoTxid, isTxConfirmed) {
-        const offchainPart = await getOffchainPart(this.branch(vtxoTxid), isTxConfirmed);
-        return offchainPart.map(getExitTransaction);
-    }
-    // Helper method to find parent of a node
-    findParent(node) {
-        for (const level of this.tree) {
-            for (const potentialParent of level) {
-                if (potentialParent.txid === node.parentTxid) {
-                    return potentialParent;
-                }
-            }
-        }
-        throw exports.ErrParentNotFound;
-    }
-    // Validates that the tree is coherent by checking txids and parent relationships
-    validate() {
-        // Skip the root level, validate from level 1 onwards
-        for (let i = 1; i < this.tree.length; i++) {
-            for (const node of this.tree[i]) {
-                // Verify that the node's transaction matches its claimed txid
-                const tx = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(node.tx));
-                const txid = base_1.hex.encode((0, utils_1.sha256x2)(tx.toBytes(true)).reverse());
-                if (txid !== node.txid) {
-                    throw new TxTreeError(`node ${node.txid} has txid ${node.txid}, but computed txid is ${txid}`);
-                }
-                // Verify that the node has a valid parent
-                try {
-                    this.findParent(node);
-                }
-                catch (err) {
-                    throw new TxTreeError(`node ${node.txid} has no parent: ${err instanceof Error ? err.message : String(err)}`);
-                }
-            }
-        }
-    }
-}
-exports.TxTree = TxTree;
-const COSIGNER_KEY_PREFIX = new Uint8Array("cosigner".split("").map((c) => c.charCodeAt(0)));
-const VTXO_TREE_EXPIRY_PSBT_KEY = new Uint8Array("expiry".split("").map((c) => c.charCodeAt(0)));
-function getVtxoTreeExpiry(input) {
-    if (!input.unknown)
-        return null;
-    for (const u of input.unknown) {
-        // Check if key contains the VTXO tree expiry key
-        if (u.key.length < VTXO_TREE_EXPIRY_PSBT_KEY.length)
-            continue;
-        let found = true;
-        for (let i = 0; i < VTXO_TREE_EXPIRY_PSBT_KEY.length; i++) {
-            if (u.key[i] !== VTXO_TREE_EXPIRY_PSBT_KEY[i]) {
-                found = false;
-                break;
-            }
-        }
-        if (found) {
-            const value = (0, btc_signer_1.ScriptNum)(6, true).decode(u.value);
-            const { blocks, seconds } = bip68.decode(Number(value));
-            return {
-                type: blocks ? "blocks" : "seconds",
-                value: BigInt(blocks ?? seconds ?? 0),
-            };
-        }
-    }
-    return null;
-}
-function parsePrefixedCosignerKey(key) {
-    if (key.length < COSIGNER_KEY_PREFIX.length)
-        return false;
-    for (let i = 0; i < COSIGNER_KEY_PREFIX.length; i++) {
-        if (key[i] !== COSIGNER_KEY_PREFIX[i])
-            return false;
-    }
-    return true;
-}
-function getCosignerKeys(tx) {
-    const keys = [];
-    const input = tx.getInput(0);
-    if (!input.unknown)
-        return keys;
-    for (const unknown of input.unknown) {
-        const ok = parsePrefixedCosignerKey(new Uint8Array([unknown[0].type, ...unknown[0].key]));
-        if (!ok)
-            continue;
-        // Assuming the value is already a valid public key in compressed format
-        keys.push(unknown[1]);
-    }
-    return keys;
-}
-async function getOffchainPart(branch, isTxConfirmed) {
-    let offchainPath = [...branch];
-    // Iterate from the end of the branch (leaf) to the beginning (root)
-    for (let i = branch.length - 1; i >= 0; i--) {
-        const node = branch[i];
-        // check if the transaction is confirmed on-chain
-        if (await isTxConfirmed(node.txid)) {
-            // if this is the leaf node, return empty array as everything is confirmed
-            if (i === branch.length - 1) {
-                return [];
-            }
-            // otherwise, return the unconfirmed part of the branch
-            return branch.slice(i + 1);
-        }
-    }
-    // no confirmation: everything is offchain
-    return offchainPath;
-}
-// getExitTransaction finalizes the psbt's input using the musig2 tapkey signature
-function getExitTransaction(treeNode) {
-    const tx = btc_signer_1.Transaction.fromPSBT(base_1.base64.decode(treeNode.tx));
-    const input = tx.getInput(0);
-    if (!input.tapKeySig)
-        throw new TxTreeError("missing tapkey signature");
-    const rawTx = btc_signer_1.RawTx.decode(tx.unsignedTx);
-    rawTx.witnesses = [[input.tapKeySig]];
-    rawTx.segwitFlag = true;
-    return base_1.hex.encode(btc_signer_1.RawTx.encode(rawTx));
-}

package/dist/cjs/utils/coinselect.js

@@ -1,73 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectCoins = selectCoins;
-exports.selectVirtualCoins = selectVirtualCoins;
-/**
- * Select coins to reach a target amount, prioritizing those closer to expiry
- * @param coins List of coins to select from
- * @param targetAmount Target amount to reach in satoshis
- * @returns Selected coins and change amount, or null if insufficient funds
- */
-function selectCoins(coins, targetAmount) {
-    // Sort coins by amount (descending)
-    const sortedCoins = [...coins].sort((a, b) => b.value - a.value);
-    const selectedCoins = [];
-    let selectedAmount = 0;
-    // Select coins until we have enough
-    for (const coin of sortedCoins) {
-        selectedCoins.push(coin);
-        selectedAmount += coin.value;
-        if (selectedAmount >= targetAmount) {
-            break;
-        }
-    }
-    // Check if we have enough
-    if (selectedAmount < targetAmount) {
-        return { inputs: null, changeAmount: 0 };
-    }
-    // Calculate change
-    const changeAmount = selectedAmount - targetAmount;
-    return {
-        inputs: selectedCoins,
-        changeAmount,
-    };
-}
-/**
- * Select virtual coins to reach a target amount, prioritizing those closer to expiry
- * @param coins List of virtual coins to select from
- * @param targetAmount Target amount to reach in satoshis
- * @returns Selected coins and change amount, or null if insufficient funds
- */
-function selectVirtualCoins(coins, targetAmount) {
-    // Sort VTXOs by expiry (ascending) and amount (descending)
-    const sortedCoins = [...coins].sort((a, b) => {
-        // First sort by expiry if available
-        const expiryA = a.virtualStatus.batchExpiry || Number.MAX_SAFE_INTEGER;
-        const expiryB = b.virtualStatus.batchExpiry || Number.MAX_SAFE_INTEGER;
-        if (expiryA !== expiryB) {
-            return expiryA - expiryB; // Earlier expiry first
-        }
-        // Then sort by amount
-        return b.value - a.value; // Larger amount first
-    });
-    const selectedCoins = [];
-    let selectedAmount = 0;
-    // Select coins until we have enough
-    for (const coin of sortedCoins) {
-        selectedCoins.push(coin);
-        selectedAmount += coin.value;
-        if (selectedAmount >= targetAmount) {
-            break;
-        }
-    }
-    // Check if we have enough
-    if (selectedAmount < targetAmount) {
-        return { inputs: null, changeAmount: 0 };
-    }
-    // Calculate change
-    const changeAmount = selectedAmount - targetAmount;
-    return {
-        inputs: selectedCoins,
-        changeAmount,
-    };
-}