@arkade-os/sdk 0.1.4 → 0.2.1

package/dist/esm/providers/onchain.js

@@ -1,3 +1,6 @@
+/**
+ * The default base URLs for esplora API providers.
+ */
 export const ESPLORA_URL = {
     bitcoin: "https://mempool.space/api",
     testnet: "https://mempool.space/testnet/api",
@@ -5,6 +8,15 @@ export const ESPLORA_URL = {
     mutinynet: "https://mutinynet.com/api",
     regtest: "http://localhost:3000",
 };
+/**
+ * Implementation of the onchain provider interface for esplora REST API.
+ * @see https://mempool.space/docs/api/rest
+ * @example
+ * ```typescript
+ * const provider = new EsploraProvider("https://mempool.space/api");
+ * const utxos = await provider.getCoins("bcrt1q679zsd45msawvr7782r0twvmukns3drlstjt77");
+ * ```
+ */
 export class EsploraProvider {
     constructor(baseUrl) {
         this.baseUrl = baseUrl;
@@ -17,26 +29,22 @@ export class EsploraProvider {
         return response.json();
     }
     async getFeeRate() {
-        const response = await fetch(`${this.baseUrl}/v1/fees/recommended`);
+        const response = await fetch(`${this.baseUrl}/fee-estimates`);
         if (!response.ok) {
             throw new Error(`Failed to fetch fee rate: ${response.statusText}`);
         }
-        const fees = await response.json();
-        return fees.halfHourFee; // Return the "medium" priority fee rate
+        const fees = (await response.json());
+        return fees["1"] ?? undefined;
     }
-    async broadcastTransaction(txHex) {
-        const response = await fetch(`${this.baseUrl}/tx`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "text/plain",
-            },
-            body: txHex,
-        });
-        if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`Failed to broadcast transaction: ${error}`);
+    async broadcastTransaction(...txs) {
+        switch (txs.length) {
+            case 1:
+                return this.broadcastTx(txs[0]);
+            case 2:
+                return this.broadcastPackage(txs[0], txs[1]);
+            default:
+                throw new Error("Only 1 or 1C1P package can be broadcast");
         }
-        return response.text(); // Returns the txid
     }
     async getTxOutspends(txid) {
         const response = await fetch(`${this.baseUrl}/tx/${txid}/outspends`);
@@ -55,15 +63,185 @@ export class EsploraProvider {
         return response.json();
     }
     async getTxStatus(txid) {
+        // make sure tx exists in mempool or in block
+        const txresponse = await fetch(`${this.baseUrl}/tx/${txid}`);
+        if (!txresponse.ok) {
+            throw new Error(txresponse.statusText);
+        }
+        const tx = await txresponse.json();
+        if (!tx.status.confirmed) {
+            return { confirmed: false };
+        }
         const response = await fetch(`${this.baseUrl}/tx/${txid}/status`);
         if (!response.ok) {
             throw new Error(`Failed to get transaction status: ${response.statusText}`);
         }
         const data = await response.json();
+        if (!data.confirmed) {
+            return { confirmed: false };
+        }
         return {
             confirmed: data.confirmed,
             blockTime: data.block_time,
             blockHeight: data.block_height,
         };
     }
+    async watchAddresses(addresses, callback) {
+        let intervalId = null;
+        const wsUrl = this.baseUrl.replace(/^http(s)?:/, "ws$1:") + "/v1/ws";
+        const poll = async () => {
+            // websocket is not reliable, so we will fallback to polling
+            const pollingInterval = 5000; // 5 seconds
+            const getAllTxs = () => {
+                return Promise.all(addresses.map((address) => this.getTransactions(address))).then((txArrays) => txArrays.flat());
+            };
+            // initial fetch to get existing transactions
+            const initialTxs = await getAllTxs();
+            // we use block_time in key to also notify when a transaction is confirmed
+            const txKey = (tx) => `${tx.txid}_${tx.status.block_time}`;
+            // polling for new transactions
+            intervalId = setInterval(async () => {
+                try {
+                    // get current transactions
+                    // we will compare with initialTxs to find new ones
+                    const currentTxs = await getAllTxs();
+                    // create a set of existing transactions to avoid duplicates
+                    const existingTxs = new Set(initialTxs.map(txKey));
+                    // filter out transactions that are already in initialTxs
+                    const newTxs = currentTxs.filter((tx) => !existingTxs.has(txKey(tx)));
+                    if (newTxs.length > 0) {
+                        // Update the tracking set instead of growing the array
+                        initialTxs.push(...newTxs);
+                        callback(newTxs);
+                    }
+                }
+                catch (error) {
+                    console.error("Error in polling mechanism:", error);
+                }
+            }, pollingInterval);
+        };
+        let ws = null;
+        try {
+            ws = new WebSocket(wsUrl);
+            ws.addEventListener("open", () => {
+                // subscribe to address updates
+                const subscribeMsg = {
+                    "track-addresses": addresses,
+                };
+                ws.send(JSON.stringify(subscribeMsg));
+            });
+            ws.addEventListener("message", (event) => {
+                try {
+                    const newTxs = [];
+                    const message = JSON.parse(event.data.toString());
+                    if (!message["multi-address-transactions"])
+                        return;
+                    const aux = message["multi-address-transactions"];
+                    for (const address in aux) {
+                        for (const type of [
+                            "mempool",
+                            "confirmed",
+                            "removed",
+                        ]) {
+                            if (!aux[address][type])
+                                continue;
+                            newTxs.push(...aux[address][type].filter(isExplorerTransaction));
+                        }
+                    }
+                    // callback with new transactions
+                    if (newTxs.length > 0)
+                        callback(newTxs);
+                }
+                catch (error) {
+                    console.error("Failed to process WebSocket message:", error);
+                }
+            });
+            ws.addEventListener("error", async () => {
+                // if websocket is not available, fallback to polling
+                await poll();
+            });
+        }
+        catch {
+            if (intervalId)
+                clearInterval(intervalId);
+            // if websocket is not available, fallback to polling
+            await poll();
+        }
+        const stopFunc = () => {
+            if (ws && ws.readyState === WebSocket.OPEN)
+                ws.close();
+            if (intervalId)
+                clearInterval(intervalId);
+        };
+        return stopFunc;
+    }
+    async getChainTip() {
+        const tipBlocks = await fetch(`${this.baseUrl}/blocks/tip`);
+        if (!tipBlocks.ok) {
+            throw new Error(`Failed to get chain tip: ${tipBlocks.statusText}`);
+        }
+        const tip = await tipBlocks.json();
+        if (!isValidBlocksTip(tip)) {
+            throw new Error(`Invalid chain tip: ${JSON.stringify(tip)}`);
+        }
+        if (tip.length === 0) {
+            throw new Error("No chain tip found");
+        }
+        const hash = tip[0].id;
+        return {
+            height: tip[0].height,
+            time: tip[0].mediantime,
+            hash,
+        };
+    }
+    async broadcastPackage(parent, child) {
+        const response = await fetch(`${this.baseUrl}/txs/package`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify([parent, child]),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Failed to broadcast package: ${error}`);
+        }
+        return response.json();
+    }
+    async broadcastTx(tx) {
+        const response = await fetch(`${this.baseUrl}/tx`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "text/plain",
+            },
+            body: tx,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Failed to broadcast transaction: ${error}`);
+        }
+        return response.text();
+    }
 }
+function isValidBlocksTip(tip) {
+    return (Array.isArray(tip) &&
+        tip.every((t) => {
+            t &&
+                typeof t === "object" &&
+                typeof t.id === "string" &&
+                t.id.length > 0 &&
+                typeof t.height === "number" &&
+                t.height >= 0 &&
+                typeof t.mediantime === "number" &&
+                t.mediantime > 0;
+        }));
+}
+const isExplorerTransaction = (tx) => {
+    return (typeof tx.txid === "string" &&
+        Array.isArray(tx.vout) &&
+        tx.vout.every((vout) => typeof vout.scriptpubkey_address === "string" &&
+            typeof vout.value === "string") &&
+        typeof tx.status === "object" &&
+        typeof tx.status.confirmed === "boolean" &&
+        typeof tx.status.block_time === "number");
+};

package/dist/esm/script/address.js

@@ -1,16 +1,40 @@
 import { bech32m } from "@scure/base";
 import { Script } from "@scure/btc-signer";
-// ArkAddress is a bech32m encoded address with a custom HRP (ark/tark)
+/**
+ * ArkAddress allows to create and decode bech32m encoded ark address.
+ * An ark address is composed of:
+ * - a human readable prefix (hrp)
+ * - a version byte (1 byte)
+ * - a server public key (32 bytes)
+ * - a vtxo taproot public key (32 bytes)
+ *
+ * @example
+ * ```typescript
+ * const address = new ArkAddress(
+ *     new Uint8Array(32), // server public key
+ *     new Uint8Array(32), // vtxo taproot public key
+ *     "ark"
+ * );
+ *
+ * const encoded = address.encode();
+ * console.log("address: ", encoded);
+ *
+ * const decoded = ArkAddress.decode(encoded);
+ * ```
+ */
 export class ArkAddress {
-    constructor(serverPubKey, tweakedPubKey, hrp) {
+    constructor(serverPubKey, vtxoTaprootKey, hrp, version = 0) {
         this.serverPubKey = serverPubKey;
-        this.tweakedPubKey = tweakedPubKey;
+        this.vtxoTaprootKey = vtxoTaprootKey;
         this.hrp = hrp;
+        this.version = version;
         if (serverPubKey.length !== 32) {
-            throw new Error("Invalid server public key length");
+            throw new Error("Invalid server public key length, expected 32 bytes, got " +
+                serverPubKey.length);
         }
-        if (tweakedPubKey.length !== 32) {
-            throw new Error("Invalid tweaked public key length");
+        if (vtxoTaprootKey.length !== 32) {
+            throw new Error("Invalid vtxo taproot public key length, expected 32 bytes, got " +
+                vtxoTaprootKey.length);
         }
     }
     static decode(address) {
@@ -19,23 +43,30 @@ export class ArkAddress {
             throw new Error("Invalid address");
         }
         const data = new Uint8Array(bech32m.fromWords(decoded.words));
-        // First 32 bytes are server pubkey, next 32 bytes are tweaked pubkey
-        if (data.length !== 64) {
-            throw new Error("Invalid data length");
+        // First the version byte, then 32 bytes server pubkey, then 32 bytes vtxo taproot pubkey
+        if (data.length !== 1 + 32 + 32) {
+            throw new Error("Invalid data length, expected 65 bytes, got " + data.length);
         }
-        const serverPubKey = data.slice(0, 32);
-        const tweakedPubKey = data.slice(32, 64);
-        return new ArkAddress(serverPubKey, tweakedPubKey, decoded.prefix);
+        const version = data[0];
+        const serverPubKey = data.slice(1, 33);
+        const vtxoTaprootPubKey = data.slice(33, 65);
+        return new ArkAddress(serverPubKey, vtxoTaprootPubKey, decoded.prefix, version);
     }
     encode() {
-        // Combine server pubkey and tweaked pubkey
-        const data = new Uint8Array(64);
-        data.set(this.serverPubKey, 0);
-        data.set(this.tweakedPubKey, 32);
+        // Combine version byte, server pubkey, and vtxo taproot pubkey
+        const data = new Uint8Array(1 + 32 + 32);
+        data[0] = this.version;
+        data.set(this.serverPubKey, 1);
+        data.set(this.vtxoTaprootKey, 33);
         const words = bech32m.toWords(data);
         return bech32m.encode(this.hrp, words, 1023);
     }
+    // pkScript is the script that should be used to send non-dust funds to the address
     get pkScript() {
-        return Script.encode(["OP_1", this.tweakedPubKey]);
+        return Script.encode(["OP_1", this.vtxoTaprootKey]);
+    }
+    // subdustPkScript is the script that should be used to send sub-dust funds to the address
+    get subdustPkScript() {
+        return Script.encode(["RETURN", this.vtxoTaprootKey]);
     }
 }

package/dist/esm/script/base.js

@@ -3,12 +3,22 @@ import { TAPROOT_UNSPENDABLE_KEY, } from "@scure/btc-signer/utils";
 import { ArkAddress } from './address.js';
 import { Script } from "@scure/btc-signer";
 import { hex } from "@scure/base";
+import { ConditionCSVMultisigTapscript, CSVMultisigTapscript, } from './tapscript.js';
 export function scriptFromTapLeafScript(leaf) {
     return leaf[1].subarray(0, leaf[1].length - 1); // remove the version byte
 }
+/**
+ * VtxoScript is a script that contains a list of tapleaf scripts.
+ * It is used to create vtxo scripts.
+ *
+ * @example
+ * ```typescript
+ * const vtxoScript = new VtxoScript([new Uint8Array(32), new Uint8Array(32)]);
+ */
 export class VtxoScript {
-    static decode(scripts) {
-        return new VtxoScript(scripts.map(hex.decode));
+    static decode(tapTree) {
+        const leaves = decodeTaprootTree(tapTree);
+        return new VtxoScript(leaves);
     }
     constructor(scripts) {
         this.scripts = scripts;
@@ -22,7 +32,8 @@ export class VtxoScript {
         this.tweakedPublicKey = payment.tweakedPubkey;
     }
     encode() {
-        return this.scripts.map(hex.encode);
+        const tapTree = encodeTaprootTree(this.scripts);
+        return tapTree;
     }
     address(prefix, serverPubKey) {
         return new ArkAddress(serverPubKey, this.tweakedPublicKey, prefix);
@@ -43,4 +54,110 @@ export class VtxoScript {
         }
         return leaf;
     }
+    exitPaths() {
+        const paths = [];
+        for (const leaf of this.leaves) {
+            try {
+                const tapscript = CSVMultisigTapscript.decode(scriptFromTapLeafScript(leaf));
+                paths.push(tapscript);
+                continue;
+            }
+            catch (e) {
+                try {
+                    const tapscript = ConditionCSVMultisigTapscript.decode(scriptFromTapLeafScript(leaf));
+                    paths.push(tapscript);
+                }
+                catch (e) {
+                    continue;
+                }
+            }
+        }
+        return paths;
+    }
+}
+function decodeTaprootTree(tapTree) {
+    let offset = 0;
+    const scripts = [];
+    // Read number of leaves
+    const [numLeaves, numLeavesSize] = decodeCompactSizeUint(tapTree, offset);
+    offset += numLeavesSize;
+    // Read each leaf
+    for (let i = 0; i < numLeaves; i++) {
+        // Skip depth (1 byte)
+        offset += 1;
+        // Skip leaf version (1 byte)
+        offset += 1;
+        // Read script length
+        const [scriptLength, scriptLengthSize] = decodeCompactSizeUint(tapTree, offset);
+        offset += scriptLengthSize;
+        // Read script content
+        const script = tapTree.slice(offset, offset + scriptLength);
+        scripts.push(script);
+        offset += scriptLength;
+    }
+    return scripts;
+}
+function decodeCompactSizeUint(data, offset) {
+    const firstByte = data[offset];
+    if (firstByte < 0xfd) {
+        return [firstByte, 1];
+    }
+    else if (firstByte === 0xfd) {
+        const value = new DataView(data.buffer).getUint16(offset + 1, true);
+        return [value, 3];
+    }
+    else if (firstByte === 0xfe) {
+        const value = new DataView(data.buffer).getUint32(offset + 1, true);
+        return [value, 5];
+    }
+    else {
+        const value = Number(new DataView(data.buffer).getBigUint64(offset + 1, true));
+        return [value, 9];
+    }
+}
+function encodeTaprootTree(leaves) {
+    const chunks = [];
+    // Write number of leaves as compact size uint
+    chunks.push(encodeCompactSizeUint(leaves.length));
+    for (const tapscript of leaves) {
+        // Write depth (always 1 for now)
+        chunks.push(new Uint8Array([1]));
+        // Write leaf version (0xc0 for tapscript)
+        chunks.push(new Uint8Array([0xc0]));
+        // Write script length and script
+        chunks.push(encodeCompactSizeUint(tapscript.length));
+        chunks.push(tapscript);
+    }
+    // Concatenate all chunks
+    const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}
+function encodeCompactSizeUint(value) {
+    if (value < 0xfd) {
+        return new Uint8Array([value]);
+    }
+    else if (value <= 0xffff) {
+        const buffer = new Uint8Array(3);
+        buffer[0] = 0xfd;
+        new DataView(buffer.buffer).setUint16(1, value, true);
+        return buffer;
+    }
+    else if (value <= 0xffffffff) {
+        const buffer = new Uint8Array(5);
+        buffer[0] = 0xfe;
+        new DataView(buffer.buffer).setUint32(1, value, true);
+        return buffer;
+    }
+    else {
+        const buffer = new Uint8Array(9);
+        buffer[0] = 0xff;
+        new DataView(buffer.buffer).setBigUint64(1, BigInt(value), true);
+        return buffer;
+    }
 }

package/dist/esm/script/default.js

@@ -1,12 +1,26 @@
 import { VtxoScript } from './base.js';
 import { CSVMultisigTapscript, MultisigTapscript, } from './tapscript.js';
 import { hex } from "@scure/base";
-// DefaultVtxo is the default implementation of a VtxoScript.
-// it contains 1 forfeit path and 1 exit path.
-// forfeit = (Alice + Server)
-// exit = (Alice) after csvTimelock
+/**
+ * DefaultVtxo is the default implementation of a VtxoScript.
+ * It contains 1 forfeit path and 1 exit path.
+ * - forfeit = (Alice + Server)
+ * - exit = (Alice) after csvTimelock
+ */
 export var DefaultVtxo;
 (function (DefaultVtxo) {
+    /**
+     * DefaultVtxo.Script is the class letting to create the vtxo script.
+     * @example
+     * ```typescript
+     * const vtxoScript = new DefaultVtxo.Script({
+     *     pubKey: new Uint8Array(32),
+     *     serverPubKey: new Uint8Array(32),
+     * });
+     *
+     * console.log("script pub key:", vtxoScript.pkScript)
+     * ```
+     */
     class Script extends VtxoScript {
         constructor(options) {
             const { pubKey, serverPubKey, csvTimelock = Script.DEFAULT_TIMELOCK, } = options;