@arkade-os/sdk 0.1.4 → 0.2.0

package/dist/esm/script/vhtlc.js

@@ -2,13 +2,33 @@ import { Script } from "@scure/btc-signer";
 import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, MultisigTapscript, } from './tapscript.js';
 import { hex } from "@scure/base";
 import { VtxoScript } from './base.js';
-// VHTLC is an Hashed Timelock Contract VtxoScript implementation
-// - claim (preimage + receiver)
-// - refund (sender + receiver + server)
-// - refundWithoutReceiver (at refundLocktime, sender + receiver + server)
-// - unilateralClaim (preimage + receiver after unilateralClaimDelay)
-// - unilateralRefund (sender + receiver after unilateralRefundDelay)
-// - unilateralRefundWithoutReceiver (sender after unilateralRefundWithoutReceiverDelay)
+/**
+ * Virtual Hash Time Lock Contract (VHTLC) implementation.
+ *
+ * VHTLC is a contract that enables atomic swaps and conditional payments
+ * in the Ark protocol. It provides multiple spending paths:
+ *
+ * - **claim**: Receiver can claim funds by revealing the preimage
+ * - **refund**: Sender and receiver can collaboratively refund
+ * - **refundWithoutReceiver**: Sender can refund after locktime expires
+ * - **unilateralClaim**: Receiver can claim unilaterally after delay
+ * - **unilateralRefund**: Sender and receiver can refund unilaterally after delay
+ * - **unilateralRefundWithoutReceiver**: Sender can refund unilaterally after delay
+ *
+ * @example
+ * ```typescript
+ * const vhtlc = new VHTLC.Script({
+ *   sender: alicePubKey,
+ *   receiver: bobPubKey,
+ *   server: serverPubKey,
+ *   preimageHash: hash160(secret),
+ *   refundLocktime: BigInt(chainTip + 10),
+ *   unilateralClaimDelay: { type: 'blocks', value: 100n },
+ *   unilateralRefundDelay: { type: 'blocks', value: 102n },
+ *   unilateralRefundWithoutReceiverDelay: { type: 'blocks', value: 103n }
+ * });
+ * ```
+ */
 export var VHTLC;
 (function (VHTLC) {
     class Script extends VtxoScript {

package/dist/esm/tree/signingSession.js

@@ -1,17 +1,17 @@
 import * as musig2 from '../musig2/index.js';
-import { getCosignerKeys } from './vtxoTree.js';
-import { Script, SigHash, Transaction } from "@scure/btc-signer";
-import { base64, hex } from "@scure/base";
+import { Script, SigHash } from "@scure/btc-signer";
+import { hex } from "@scure/base";
 import { schnorr, secp256k1 } from "@noble/curves/secp256k1";
-import { randomPrivateKeyBytes } from "@scure/btc-signer/utils";
-export const ErrMissingVtxoTree = new Error("missing vtxo tree");
+import { randomPrivateKeyBytes, sha256x2 } from "@scure/btc-signer/utils";
+import { CosignerPublicKey, getArkPsbtFields } from '../utils/unknownFields.js';
+export const ErrMissingVtxoGraph = new Error("missing vtxo graph");
 export const ErrMissingAggregateKey = new Error("missing aggregate key");
 export class TreeSignerSession {
     constructor(secretKey) {
         this.secretKey = secretKey;
         this.myNonces = null;
         this.aggregateNonces = null;
-        this.tree = null;
+        this.graph = null;
         this.scriptRoot = null;
         this.rootSharedOutputAmount = null;
     }
@@ -20,7 +20,7 @@ export class TreeSignerSession {
         return new TreeSignerSession(secretKey);
     }
     init(tree, scriptRoot, rootInputAmount) {
-        this.tree = tree;
+        this.graph = tree;
         this.scriptRoot = scriptRoot;
         this.rootSharedOutputAmount = rootInputAmount;
     }
@@ -28,24 +28,16 @@ export class TreeSignerSession {
         return secp256k1.getPublicKey(this.secretKey);
     }
     getNonces() {
-        if (!this.tree)
-            throw ErrMissingVtxoTree;
+        if (!this.graph)
+            throw ErrMissingVtxoGraph;
         if (!this.myNonces) {
             this.myNonces = this.generateNonces();
         }
-        const nonces = [];
-        for (const levelNonces of this.myNonces) {
-            const levelPubNonces = [];
-            for (const nonce of levelNonces) {
-                if (!nonce) {
-                    levelPubNonces.push(null);
-                    continue;
-                }
-                levelPubNonces.push({ pubNonce: nonce.pubNonce });
-            }
-            nonces.push(levelPubNonces);
+        const publicNonces = new Map();
+        for (const [txid, nonces] of this.myNonces) {
+            publicNonces.set(txid, { pubNonce: nonces.pubNonce });
         }
-        return nonces;
+        return publicNonces;
     }
     setAggregatedNonces(nonces) {
         if (this.aggregateNonces)
@@ -53,71 +45,55 @@ export class TreeSignerSession {
         this.aggregateNonces = nonces;
     }
     sign() {
-        if (!this.tree)
-            throw ErrMissingVtxoTree;
+        if (!this.graph)
+            throw ErrMissingVtxoGraph;
         if (!this.aggregateNonces)
             throw new Error("nonces not set");
         if (!this.myNonces)
             throw new Error("nonces not generated");
-        const sigs = [];
-        for (let levelIndex = 0; levelIndex < this.tree.levels.length; levelIndex++) {
-            const levelSigs = [];
-            const level = this.tree.levels[levelIndex];
-            for (let nodeIndex = 0; nodeIndex < level.length; nodeIndex++) {
-                const node = level[nodeIndex];
-                const tx = Transaction.fromPSBT(base64.decode(node.tx));
-                const sig = this.signPartial(tx, levelIndex, nodeIndex);
-                if (sig) {
-                    levelSigs.push(sig);
-                }
-                else {
-                    levelSigs.push(null);
-                }
-            }
-            sigs.push(levelSigs);
+        const sigs = new Map();
+        for (const g of this.graph) {
+            const sig = this.signPartial(g);
+            sigs.set(g.txid, sig);
         }
         return sigs;
     }
     generateNonces() {
-        if (!this.tree)
-            throw ErrMissingVtxoTree;
-        const myNonces = [];
+        if (!this.graph)
+            throw ErrMissingVtxoGraph;
+        const myNonces = new Map();
         const publicKey = secp256k1.getPublicKey(this.secretKey);
-        for (const level of this.tree.levels) {
-            const levelNonces = [];
-            for (let i = 0; i < level.length; i++) {
-                const nonces = musig2.generateNonces(publicKey);
-                levelNonces.push(nonces);
-            }
-            myNonces.push(levelNonces);
+        for (const g of this.graph) {
+            const nonces = musig2.generateNonces(publicKey);
+            myNonces.set(g.txid, nonces);
         }
         return myNonces;
     }
-    signPartial(tx, levelIndex, nodeIndex) {
-        if (!this.tree || !this.scriptRoot || !this.rootSharedOutputAmount) {
+    signPartial(g) {
+        if (!this.graph || !this.scriptRoot || !this.rootSharedOutputAmount) {
             throw TreeSignerSession.NOT_INITIALIZED;
         }
         if (!this.myNonces || !this.aggregateNonces) {
             throw new Error("session not properly initialized");
         }
-        const myNonce = this.myNonces[levelIndex][nodeIndex];
+        const myNonce = this.myNonces.get(g.txid);
         if (!myNonce)
-            return null;
-        const aggNonce = this.aggregateNonces[levelIndex][nodeIndex];
+            throw new Error("missing private nonce");
+        const aggNonce = this.aggregateNonces.get(g.txid);
         if (!aggNonce)
             throw new Error("missing aggregate nonce");
         const prevoutAmounts = [];
         const prevoutScripts = [];
-        const cosigners = getCosignerKeys(tx);
+        const cosigners = getArkPsbtFields(g.root, 0, CosignerPublicKey).map((c) => c.key);
         const { finalKey } = musig2.aggregateKeys(cosigners, true, {
             taprootTweak: this.scriptRoot,
         });
-        for (let inputIndex = 0; inputIndex < tx.inputsLength; inputIndex++) {
-            const prevout = getPrevOutput(finalKey, this.tree, this.rootSharedOutputAmount, tx);
+        for (let inputIndex = 0; inputIndex < g.root.inputsLength; inputIndex++) {
+            const prevout = getPrevOutput(finalKey, this.graph, this.rootSharedOutputAmount, g.root);
             prevoutAmounts.push(prevout.amount);
             prevoutScripts.push(prevout.script);
         }
-        const message = tx.preimageWitnessV1(0, // always first input
+        const message = g.root.preimageWitnessV1(0, // always first input
         prevoutScripts, SigHash.DEFAULT, prevoutAmounts);
         return musig2.sign(myNonce.secNonce, this.secretKey, aggNonce.pubNonce, cosigners, message, {
             taprootTweak: this.scriptRoot,
@@ -129,66 +105,47 @@ TreeSignerSession.NOT_INITIALIZED = new Error("session not initialized, call ini
 // Helper function to validate tree signatures
 export async function validateTreeSigs(finalAggregatedKey, sharedOutputAmount, vtxoTree) {
     // Iterate through each level of the tree
-    for (const level of vtxoTree.levels) {
-        for (const node of level) {
-            // Parse the transaction
-            const tx = Transaction.fromPSBT(base64.decode(node.tx));
-            const input = tx.getInput(0);
-            // Check if input has signature
-            if (!input.tapKeySig) {
-                throw new Error("unsigned tree input");
-            }
-            // Get the previous output information
-            const prevout = getPrevOutput(finalAggregatedKey, vtxoTree, sharedOutputAmount, tx);
-            // Calculate the message that was signed
-            const message = tx.preimageWitnessV1(0, // always first input
-            [prevout.script], SigHash.DEFAULT, [prevout.amount]);
-            // Verify the signature
-            const isValid = schnorr.verify(input.tapKeySig, message, finalAggregatedKey);
-            if (!isValid) {
-                throw new Error("invalid signature");
-            }
+    for (const g of vtxoTree) {
+        // Parse the transaction
+        const input = g.root.getInput(0);
+        // Check if input has signature
+        if (!input.tapKeySig) {
+            throw new Error("unsigned tree input");
+        }
+        // Get the previous output information
+        const prevout = getPrevOutput(finalAggregatedKey, vtxoTree, sharedOutputAmount, g.root);
+        // Calculate the message that was signed
+        const message = g.root.preimageWitnessV1(0, // always first input
+        [prevout.script], SigHash.DEFAULT, [prevout.amount]);
+        // Verify the signature
+        const isValid = schnorr.verify(input.tapKeySig, message, finalAggregatedKey);
+        if (!isValid) {
+            throw new Error("invalid signature");
         }
     }
 }
-function getPrevOutput(finalKey, vtxoTree, sharedOutputAmount, partial) {
-    // Generate P2TR script
+function getPrevOutput(finalKey, graph, sharedOutputAmount, tx) {
+    // generate P2TR script from musig2 final key
     const pkScript = Script.encode(["OP_1", finalKey.slice(1)]);
-    // Get root node
-    const rootNode = vtxoTree.levels[0][0];
-    if (!rootNode)
-        throw new Error("empty vtxo tree");
-    const input = partial.getInput(0);
-    if (!input.txid)
-        throw new Error("missing input txid");
-    const parentTxID = hex.encode(input.txid);
-    // Check if parent is root
-    if (rootNode.parentTxid === parentTxID) {
+    const txid = hex.encode(sha256x2(tx.toBytes(true)).reverse());
+    // if the input is the root input, return the shared output amount
+    if (txid === graph.txid) {
         return {
             amount: sharedOutputAmount,
             script: pkScript,
         };
     }
-    // Search for parent in tree
-    let parent = null;
-    for (const level of vtxoTree.levels) {
-        for (const node of level) {
-            if (node.txid === parentTxID) {
-                parent = node;
-                break;
-            }
-        }
-        if (parent)
-            break;
-    }
-    if (!parent) {
-        throw new Error("parent tx not found");
-    }
-    // Parse parent tx
-    const parentTx = Transaction.fromPSBT(base64.decode(parent.tx));
-    if (!input.index)
+    // find the parent transaction
+    const parentInput = tx.getInput(0);
+    if (!parentInput.txid)
+        throw new Error("missing parent input txid");
+    const parentTxid = hex.encode(new Uint8Array(parentInput.txid));
+    const parent = graph.find(parentTxid);
+    if (!parent)
+        throw new Error("parent  tx not found");
+    if (parentInput.index === undefined)
         throw new Error("missing input index");
-    const parentOutput = parentTx.getOutput(input.index);
+    const parentOutput = parent.root.getOutput(parentInput.index);
     if (!parentOutput)
         throw new Error("parent output not found");
     if (!parentOutput.amount)

package/dist/esm/tree/txTree.js

@@ -0,0 +1,189 @@
+import { Transaction } from "@scure/btc-signer";
+import { base64 } from "@scure/base";
+import { hex } from "@scure/base";
+import { sha256x2 } from "@scure/btc-signer/utils";
+/**
+ * TxTree is a graph of bitcoin transactions.
+ * It is used to represent batch tree created during settlement session
+ */
+export class TxTree {
+    constructor(root, children = new Map()) {
+        this.root = root;
+        this.children = children;
+    }
+    static create(chunks) {
+        if (chunks.length === 0) {
+            throw new Error("empty chunks");
+        }
+        // Create a map to store all chunks by their txid for easy lookup
+        const chunksByTxid = new Map();
+        for (const chunk of chunks) {
+            const decodedChunk = decodeNode(chunk);
+            const txid = hex.encode(sha256x2(decodedChunk.tx.toBytes(true)).reverse());
+            chunksByTxid.set(txid, decodedChunk);
+        }
+        // Find the root chunks (the ones that aren't referenced as a child)
+        const rootTxids = [];
+        for (const [txid] of chunksByTxid) {
+            let isChild = false;
+            for (const [otherTxid, otherChunk] of chunksByTxid) {
+                if (otherTxid === txid) {
+                    // skip self
+                    continue;
+                }
+                // check if the current chunk is a child of the other chunk
+                isChild = hasChild(otherChunk, txid);
+                if (isChild) {
+                    break;
+                }
+            }
+            // if the chunk is not a child of any other chunk, it is a root
+            if (!isChild) {
+                rootTxids.push(txid);
+                continue;
+            }
+        }
+        if (rootTxids.length === 0) {
+            throw new Error("no root chunk found");
+        }
+        if (rootTxids.length > 1) {
+            throw new Error(`multiple root chunks found: ${rootTxids.join(", ")}`);
+        }
+        const graph = buildGraph(rootTxids[0], chunksByTxid);
+        if (!graph) {
+            throw new Error(`chunk not found for root txid: ${rootTxids[0]}`);
+        }
+        // verify that the number of chunks is equal to the number node in the graph
+        if (graph.nbOfNodes() !== chunks.length) {
+            throw new Error(`number of chunks (${chunks.length}) is not equal to the number of nodes in the graph (${graph.nbOfNodes()})`);
+        }
+        return graph;
+    }
+    nbOfNodes() {
+        let count = 1; // count this node
+        for (const child of this.children.values()) {
+            count += child.nbOfNodes();
+        }
+        return count;
+    }
+    validate() {
+        if (!this.root) {
+            throw new Error("unexpected nil root");
+        }
+        const nbOfOutputs = this.root.outputsLength;
+        const nbOfInputs = this.root.inputsLength;
+        if (nbOfInputs !== 1) {
+            throw new Error(`unexpected number of inputs: ${nbOfInputs}, expected 1`);
+        }
+        // the children map can't be bigger than the number of outputs (excluding the P2A)
+        // a graph can be "partial" and specify only some of the outputs as children,
+        // that's why we allow len(g.Children) to be less than nbOfOutputs-1
+        if (this.children.size > nbOfOutputs - 1) {
+            throw new Error(`unexpected number of children: ${this.children.size}, expected maximum ${nbOfOutputs - 1}`);
+        }
+        // validate each child
+        for (const [outputIndex, child] of this.children) {
+            if (outputIndex >= nbOfOutputs) {
+                throw new Error(`output index ${outputIndex} is out of bounds (nb of outputs: ${nbOfOutputs})`);
+            }
+            child.validate();
+            const childInput = child.root.getInput(0);
+            const parentTxid = hex.encode(sha256x2(this.root.toBytes(true)).reverse());
+            // verify the input of the child is the output of the parent
+            if (!childInput.txid ||
+                hex.encode(childInput.txid) !== parentTxid ||
+                childInput.index !== outputIndex) {
+                throw new Error(`input of child ${outputIndex} is not the output of the parent`);
+            }
+            // verify the sum of the child's outputs is equal to the output of the parent
+            let childOutputsSum = 0n;
+            for (let i = 0; i < child.root.outputsLength; i++) {
+                const output = child.root.getOutput(i);
+                if (output?.amount) {
+                    childOutputsSum += output.amount;
+                }
+            }
+            const parentOutput = this.root.getOutput(outputIndex);
+            if (!parentOutput?.amount) {
+                throw new Error(`parent output ${outputIndex} has no amount`);
+            }
+            if (childOutputsSum !== parentOutput.amount) {
+                throw new Error(`sum of child's outputs is not equal to the output of the parent: ${childOutputsSum} != ${parentOutput.amount}`);
+            }
+        }
+    }
+    leaves() {
+        if (this.children.size === 0) {
+            return [this.root];
+        }
+        const leaves = [];
+        for (const child of this.children.values()) {
+            leaves.push(...child.leaves());
+        }
+        return leaves;
+    }
+    get txid() {
+        return hex.encode(sha256x2(this.root.toBytes(true)).reverse());
+    }
+    find(txid) {
+        if (txid === this.txid) {
+            return this;
+        }
+        for (const child of this.children.values()) {
+            const found = child.find(txid);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    }
+    update(txid, fn) {
+        if (txid === this.txid) {
+            fn(this.root);
+            return;
+        }
+        for (const child of this.children.values()) {
+            try {
+                child.update(txid, fn);
+                return;
+            }
+            catch (error) {
+                // Continue searching in other children if not found
+                continue;
+            }
+        }
+        throw new Error(`tx not found: ${txid}`);
+    }
+    *[Symbol.iterator]() {
+        yield this;
+        for (const child of this.children.values()) {
+            yield* child;
+        }
+    }
+}
+// Helper function to check if a chunk has a specific child
+function hasChild(chunk, childTxid) {
+    return Object.values(chunk.children).includes(childTxid);
+}
+// buildGraph recursively builds the TxGraph starting from the given txid
+function buildGraph(rootTxid, chunksByTxid) {
+    const chunk = chunksByTxid.get(rootTxid);
+    if (!chunk) {
+        return null;
+    }
+    const rootTx = chunk.tx;
+    const children = new Map();
+    // Recursively build children graphs
+    for (const [outputIndexStr, childTxid] of Object.entries(chunk.children)) {
+        const outputIndex = parseInt(outputIndexStr);
+        const childGraph = buildGraph(childTxid, chunksByTxid);
+        if (childGraph) {
+            children.set(outputIndex, childGraph);
+        }
+    }
+    return new TxTree(rootTx, children);
+}
+function decodeNode(chunk) {
+    const tx = Transaction.fromPSBT(base64.decode(chunk.tx));
+    return { tx, children: chunk.children };
+}