@arkade-os/sdk 0.1.4 → 0.2.1

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 };
+}

package/dist/esm/tree/validation.js

@@ -3,177 +3,100 @@ import { Transaction } from "@scure/btc-signer";
 import { base64 } from "@scure/base";
 import { sha256x2 } from "@scure/btc-signer/utils";
 import { aggregateKeys } from '../musig2/index.js';
-import { getCosignerKeys, TxTreeError } from './vtxoTree.js';
-export const ErrInvalidSettlementTx = new TxTreeError("invalid settlement transaction");
-export const ErrInvalidSettlementTxOutputs = new TxTreeError("invalid settlement transaction outputs");
-export const ErrEmptyTree = new TxTreeError("empty tree");
-export const ErrInvalidRootLevel = new TxTreeError("invalid root level");
-export const ErrNumberOfInputs = new TxTreeError("invalid number of inputs");
-export const ErrWrongSettlementTxid = new TxTreeError("wrong settlement txid");
-export const ErrInvalidAmount = new TxTreeError("invalid amount");
-export const ErrNoLeaves = new TxTreeError("no leaves");
-export const ErrNodeTxEmpty = new TxTreeError("node transaction empty");
-export const ErrNodeTxidEmpty = new TxTreeError("node txid empty");
-export const ErrNodeParentTxidEmpty = new TxTreeError("node parent txid empty");
-export const ErrNodeTxidDifferent = new TxTreeError("node txid different");
-export const ErrParentTxidInput = new TxTreeError("parent txid input mismatch");
-export const ErrLeafChildren = new TxTreeError("leaf node has children");
-export const ErrInvalidTaprootScript = new TxTreeError("invalid taproot script");
-export const ErrInternalKey = new TxTreeError("invalid internal key");
-export const ErrInvalidControlBlock = new TxTreeError("invalid control block");
-export const ErrInvalidRootTransaction = new TxTreeError("invalid root transaction");
-export const ErrInvalidNodeTransaction = new TxTreeError("invalid node transaction");
-const SHARED_OUTPUT_INDEX = 0;
-const CONNECTORS_OUTPUT_INDEX = 1;
-export function validateConnectorsTree(settlementTxB64, connectorsTree) {
-    connectorsTree.validate();
-    const rootNode = connectorsTree.root();
-    if (!rootNode)
-        throw ErrEmptyTree;
-    const rootTx = Transaction.fromPSBT(base64.decode(rootNode.tx));
-    if (rootTx.inputsLength !== 1)
+import { CosignerPublicKey, getArkPsbtFields } from '../utils/unknownFields.js';
+export const ErrInvalidSettlementTx = (tx) => new Error(`invalid settlement transaction: ${tx}`);
+export const ErrInvalidSettlementTxOutputs = new Error("invalid settlement transaction outputs");
+export const ErrEmptyTree = new Error("empty tree");
+export const ErrNumberOfInputs = new Error("invalid number of inputs");
+export const ErrWrongSettlementTxid = new Error("wrong settlement txid");
+export const ErrInvalidAmount = new Error("invalid amount");
+export const ErrNoLeaves = new Error("no leaves");
+export const ErrInvalidTaprootScript = new Error("invalid taproot script");
+export const ErrInvalidRoundTxOutputs = new Error("invalid round transaction outputs");
+export const ErrWrongCommitmentTxid = new Error("wrong commitment txid");
+export const ErrMissingCosignersPublicKeys = new Error("missing cosigners public keys");
+const BATCH_OUTPUT_VTXO_INDEX = 0;
+const BATCH_OUTPUT_CONNECTORS_INDEX = 1;
+export function validateConnectorsTxGraph(settlementTxB64, connectorsGraph) {
+    connectorsGraph.validate();
+    if (connectorsGraph.root.inputsLength !== 1)
         throw ErrNumberOfInputs;
-    const rootInput = rootTx.getInput(0);
+    const rootInput = connectorsGraph.root.getInput(0);
     const settlementTx = Transaction.fromPSBT(base64.decode(settlementTxB64));
-    if (settlementTx.outputsLength <= CONNECTORS_OUTPUT_INDEX)
+    if (settlementTx.outputsLength <= BATCH_OUTPUT_CONNECTORS_INDEX)
         throw ErrInvalidSettlementTxOutputs;
     const expectedRootTxid = hex.encode(sha256x2(settlementTx.toBytes(true)).reverse());
     if (!rootInput.txid)
         throw ErrWrongSettlementTxid;
     if (hex.encode(rootInput.txid) !== expectedRootTxid)
         throw ErrWrongSettlementTxid;
-    if (rootInput.index !== CONNECTORS_OUTPUT_INDEX)
+    if (rootInput.index !== BATCH_OUTPUT_CONNECTORS_INDEX)
         throw ErrWrongSettlementTxid;
 }
-export function validateVtxoTree(settlementTx, vtxoTree, sweepTapTreeRoot) {
-    vtxoTree.validate();
-    // Parse settlement transaction
-    let settlementTransaction;
-    try {
-        settlementTransaction = Transaction.fromPSBT(base64.decode(settlementTx));
-    }
-    catch {
-        throw ErrInvalidSettlementTx;
-    }
-    if (settlementTransaction.outputsLength <= SHARED_OUTPUT_INDEX) {
-        throw ErrInvalidSettlementTxOutputs;
-    }
-    const sharedOutput = settlementTransaction.getOutput(SHARED_OUTPUT_INDEX);
-    if (!sharedOutput?.amount)
-        throw ErrInvalidSettlementTxOutputs;
-    const sharedOutputAmount = sharedOutput.amount;
-    const nbNodes = vtxoTree.numberOfNodes();
-    if (nbNodes === 0) {
+// ValidateVtxoTxGraph checks if the given vtxo graph is valid.
+// The function validates:
+// - the number of nodes
+// - the number of leaves
+// - children coherence with parent.
+// - every control block and taproot output scripts.
+// - input and output amounts.
+export function validateVtxoTxGraph(graph, roundTransaction, sweepTapTreeRoot) {
+    if (roundTransaction.outputsLength < BATCH_OUTPUT_VTXO_INDEX + 1) {
+        throw ErrInvalidRoundTxOutputs;
+    }
+    const batchOutputAmount = roundTransaction.getOutput(BATCH_OUTPUT_VTXO_INDEX)?.amount;
+    if (!batchOutputAmount) {
+        throw ErrInvalidRoundTxOutputs;
+    }
+    if (!graph.root) {
         throw ErrEmptyTree;
     }
-    if (vtxoTree.levels[0].length !== 1) {
-        throw ErrInvalidRootLevel;
-    }
-    // Check root input is connected to settlement tx
-    const rootNode = vtxoTree.levels[0][0];
-    let rootTx;
-    try {
-        rootTx = Transaction.fromPSBT(base64.decode(rootNode.tx));
+    const rootInput = graph.root.getInput(0);
+    const commitmentTxid = hex.encode(sha256x2(roundTransaction.toBytes(true)).reverse());
+    if (!rootInput.txid ||
+        hex.encode(rootInput.txid) !== commitmentTxid ||
+        rootInput.index !== BATCH_OUTPUT_VTXO_INDEX) {
+        throw ErrWrongCommitmentTxid;
     }
-    catch {
-        throw ErrInvalidRootTransaction;
-    }
-    if (rootTx.inputsLength !== 1) {
-        throw ErrNumberOfInputs;
-    }
-    const rootInput = rootTx.getInput(0);
-    if (!rootInput.txid || rootInput.index === undefined)
-        throw ErrWrongSettlementTxid;
-    const settlementTxid = hex.encode(sha256x2(settlementTransaction.toBytes(true)).reverse());
-    if (hex.encode(rootInput.txid) !== settlementTxid ||
-        rootInput.index !== SHARED_OUTPUT_INDEX) {
-        throw ErrWrongSettlementTxid;
-    }
-    // Check root output amounts
     let sumRootValue = 0n;
-    for (let i = 0; i < rootTx.outputsLength; i++) {
-        const output = rootTx.getOutput(i);
-        if (!output?.amount)
-            continue;
-        sumRootValue += output.amount;
+    for (let i = 0; i < graph.root.outputsLength; i++) {
+        const output = graph.root.getOutput(i);
+        if (output?.amount) {
+            sumRootValue += output.amount;
+        }
     }
-    if (sumRootValue >= sharedOutputAmount) {
+    if (sumRootValue !== batchOutputAmount) {
         throw ErrInvalidAmount;
     }
-    if (vtxoTree.leaves().length === 0) {
+    const leaves = graph.leaves();
+    if (leaves.length === 0) {
         throw ErrNoLeaves;
     }
-    // Validate each node in the tree
-    for (const level of vtxoTree.levels) {
-        for (const node of level) {
-            validateNode(vtxoTree, node, sweepTapTreeRoot);
-        }
-    }
-}
-function validateNode(vtxoTree, node, tapTreeRoot) {
-    if (!node.tx)
-        throw ErrNodeTxEmpty;
-    if (!node.txid)
-        throw ErrNodeTxidEmpty;
-    if (!node.parentTxid)
-        throw ErrNodeParentTxidEmpty;
-    // Parse node transaction
-    let tx;
-    try {
-        tx = Transaction.fromPSBT(base64.decode(node.tx));
-    }
-    catch {
-        throw ErrInvalidNodeTransaction;
-    }
-    const txid = hex.encode(sha256x2(tx.toBytes(true)).reverse());
-    if (txid !== node.txid) {
-        throw ErrNodeTxidDifferent;
-    }
-    if (tx.inputsLength !== 1) {
-        throw ErrNumberOfInputs;
-    }
-    const input = tx.getInput(0);
-    if (!input.txid)
-        throw ErrParentTxidInput;
-    if (hex.encode(input.txid) !== node.parentTxid) {
-        throw ErrParentTxidInput;
-    }
-    const children = vtxoTree.children(node.txid);
-    if (node.leaf && children.length >= 1) {
-        throw ErrLeafChildren;
-    }
-    // Validate each child
-    for (let childIndex = 0; childIndex < children.length; childIndex++) {
-        const child = children[childIndex];
-        const childTx = Transaction.fromPSBT(base64.decode(child.tx));
-        const parentOutput = tx.getOutput(childIndex);
-        if (!parentOutput?.script)
-            throw ErrInvalidTaprootScript;
-        const previousScriptKey = parentOutput.script.slice(2);
-        if (previousScriptKey.length !== 32) {
-            throw ErrInvalidTaprootScript;
-        }
-        // Get cosigner keys from input
-        const cosignerKeys = getCosignerKeys(childTx);
-        // Aggregate keys
-        const { finalKey } = aggregateKeys(cosignerKeys, true, {
-            taprootTweak: tapTreeRoot,
-        });
-        if (hex.encode(finalKey) !== hex.encode(previousScriptKey.slice(2))) {
-            throw ErrInternalKey;
-        }
-        // Check amounts
-        let sumChildAmount = 0n;
-        for (let i = 0; i < childTx.outputsLength; i++) {
-            const output = childTx.getOutput(i);
-            if (!output?.amount)
-                continue;
-            sumChildAmount += output.amount;
-        }
-        if (!parentOutput.amount)
-            throw ErrInvalidAmount;
-        if (sumChildAmount >= parentOutput.amount) {
-            throw ErrInvalidAmount;
+    // validate the graph structure
+    graph.validate();
+    // iterates over all the nodes of the graph to verify that cosigners public keys are corresponding to the parent output
+    for (const g of graph) {
+        for (const [childIndex, child] of g.children) {
+            const parentOutput = g.root.getOutput(childIndex);
+            if (!parentOutput?.script) {
+                throw new Error(`parent output ${childIndex} not found`);
+            }
+            const previousScriptKey = parentOutput.script.slice(2);
+            if (previousScriptKey.length !== 32) {
+                throw new Error(`parent output ${childIndex} has invalid script`);
+            }
+            const cosigners = getArkPsbtFields(child.root, 0, CosignerPublicKey);
+            if (cosigners.length === 0) {
+                throw ErrMissingCosignersPublicKeys;
+            }
+            const cosignerKeys = cosigners.map((c) => c.key);
+            const { finalKey } = aggregateKeys(cosignerKeys, true, {
+                taprootTweak: sweepTapTreeRoot,
+            });
+            if (!finalKey ||
+                hex.encode(finalKey.slice(1)) !== hex.encode(previousScriptKey)) {
+                throw ErrInvalidTaprootScript;
+            }
         }
     }
 }

package/dist/esm/utils/anchor.js

@@ -0,0 +1,31 @@
+import { hex } from "@scure/base";
+export const ANCHOR_VALUE = 0n;
+export const ANCHOR_PKSCRIPT = new Uint8Array([0x51, 0x02, 0x4e, 0x73]);
+/**
+ * A zero-value anchor output.
+ */
+export const P2A = {
+    script: ANCHOR_PKSCRIPT,
+    amount: ANCHOR_VALUE,
+};
+const hexP2Ascript = hex.encode(P2A.script);
+/**
+ * search for anchor in the given transaction.
+ * @throws {Error} if the anchor is not found or has the wrong amount
+ */
+export function findP2AOutput(tx) {
+    for (let i = 0; i < tx.outputsLength; i++) {
+        const output = tx.getOutput(i);
+        if (output.script && hex.encode(output.script) === hexP2Ascript) {
+            if (output.amount !== P2A.amount) {
+                throw new Error(`P2A output has wrong amount, expected ${P2A.amount} got ${output.amount}`);
+            }
+            return {
+                txid: tx.id,
+                index: i,
+                witnessUtxo: P2A,
+            };
+        }
+    }
+    throw new Error("P2A output not found");
+}

package/dist/esm/utils/arkTransaction.js

@@ -0,0 +1,105 @@
+import { DEFAULT_SEQUENCE, Transaction } from "@scure/btc-signer";
+import { CLTVMultisigTapscript, decodeTapscript } from '../script/tapscript.js';
+import { scriptFromTapLeafScript, VtxoScript, } from '../script/base.js';
+import { P2A } from './anchor.js';
+import { hex } from "@scure/base";
+import { sha256x2 } from "@scure/btc-signer/utils";
+import { setArkPsbtField, VtxoTaprootTree } from './unknownFields.js';
+/**
+ * Builds an offchain transaction with checkpoint transactions.
+ *
+ * Creates one checkpoint transaction per input and a virtual transaction that
+ * combines all the checkpoints, sending to the specified outputs. This is the
+ * core function for creating Ark transactions.
+ *
+ * @param inputs - Array of virtual transaction inputs
+ * @param outputs - Array of transaction outputs
+ * @param serverUnrollScript - Server unroll script for checkpoint transactions
+ * @returns Object containing the virtual transaction and checkpoint transactions
+ */
+export function buildOffchainTx(inputs, outputs, serverUnrollScript) {
+    const checkpoints = inputs.map((input) => buildCheckpointTx(input, serverUnrollScript));
+    const arkTx = buildVirtualTx(checkpoints.map((c) => c.input), outputs);
+    return {
+        arkTx,
+        checkpoints: checkpoints.map((c) => c.tx),
+    };
+}
+function buildVirtualTx(inputs, outputs) {
+    let lockTime = 0n;
+    for (const input of inputs) {
+        const tapscript = decodeTapscript(scriptFromTapLeafScript(input.tapLeafScript));
+        if (CLTVMultisigTapscript.is(tapscript)) {
+            if (lockTime !== 0n) {
+                // if a locktime is already set, check if the new locktime is in the same unit
+                if (isSeconds(lockTime) !==
+                    isSeconds(tapscript.params.absoluteTimelock)) {
+                    throw new Error("cannot mix seconds and blocks locktime");
+                }
+            }
+            if (tapscript.params.absoluteTimelock > lockTime) {
+                lockTime = tapscript.params.absoluteTimelock;
+            }
+        }
+    }
+    const tx = new Transaction({
+        version: 3,
+        allowUnknown: true,
+        allowUnknownOutputs: true,
+        lockTime: Number(lockTime),
+    });
+    for (const [i, input] of inputs.entries()) {
+        tx.addInput({
+            txid: input.txid,
+            index: input.vout,
+            sequence: lockTime ? DEFAULT_SEQUENCE - 1 : undefined,
+            witnessUtxo: {
+                script: VtxoScript.decode(input.tapTree).pkScript,
+                amount: BigInt(input.value),
+            },
+            tapLeafScript: [input.tapLeafScript],
+        });
+        setArkPsbtField(tx, i, VtxoTaprootTree, input.tapTree);
+    }
+    for (const output of outputs) {
+        tx.addOutput(output);
+    }
+    // add the anchor output
+    tx.addOutput(P2A);
+    return tx;
+}
+function buildCheckpointTx(vtxo, serverUnrollScript) {
+    // create the checkpoint vtxo script from collaborative closure
+    const collaborativeClosure = decodeTapscript(vtxo.checkpointTapLeafScript ??
+        scriptFromTapLeafScript(vtxo.tapLeafScript));
+    // create the checkpoint vtxo script combining collaborative closure and server unroll script
+    const checkpointVtxoScript = new VtxoScript([
+        serverUnrollScript.script,
+        collaborativeClosure.script,
+    ]);
+    // build the checkpoint virtual tx
+    const checkpointTx = buildVirtualTx([vtxo], [
+        {
+            amount: BigInt(vtxo.value),
+            script: checkpointVtxoScript.pkScript,
+        },
+    ]);
+    // get the collaborative leaf proof
+    const collaborativeLeafProof = checkpointVtxoScript.findLeaf(hex.encode(collaborativeClosure.script));
+    // create the checkpoint input that will be used as input of the virtual tx
+    const checkpointInput = {
+        txid: hex.encode(sha256x2(checkpointTx.toBytes(true)).reverse()),
+        vout: 0,
+        value: vtxo.value,
+        tapLeafScript: collaborativeLeafProof,
+        tapTree: checkpointVtxoScript.encode(),
+    };
+    return {
+        tx: checkpointTx,
+        input: checkpointInput,
+    };
+}
+const nLocktimeMinSeconds = 500000000n;
+function isSeconds(locktime) {
+    return locktime >= nLocktimeMinSeconds;
+}