@arkade-os/sdk 0.4.27 → 0.4.28

package/dist/esm/tree/txTree.js

@@ -1,188 +0,0 @@
-import { Transaction } from "@scure/btc-signer/transaction.js";
-import { base64 } from "@scure/base";
-import { hex } from "@scure/base";
-/**
- * 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 = decodedChunk.tx.id;
-            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 = this.root.id;
-            // 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 this.root.id;
-    }
-    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}`);
-    }
-    *iterator() {
-        for (const child of this.children.values()) {
-            yield* child.iterator();
-        }
-        yield this;
-    }
-}
-// 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

@@ -1,101 +0,0 @@
-import { hex } from "@scure/base";
-import { Transaction } from "@scure/btc-signer/transaction.js";
-import { base64 } from "@scure/base";
-import { aggregateKeys } from "../musig2/index.js";
-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 = connectorsGraph.root.getInput(0);
-    const settlementTx = Transaction.fromPSBT(base64.decode(settlementTxB64));
-    if (settlementTx.outputsLength <= BATCH_OUTPUT_CONNECTORS_INDEX)
-        throw ErrInvalidSettlementTxOutputs;
-    const expectedRootTxid = settlementTx.id;
-    if (!rootInput.txid)
-        throw ErrWrongSettlementTxid;
-    if (hex.encode(rootInput.txid) !== expectedRootTxid)
-        throw ErrWrongSettlementTxid;
-    if (rootInput.index !== BATCH_OUTPUT_CONNECTORS_INDEX)
-        throw ErrWrongSettlementTxid;
-}
-// ValidateVtxoTxGraph checks if the given virtual output tx 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;
-    }
-    const rootInput = graph.root.getInput(0);
-    const commitmentTxid = roundTransaction.id;
-    if (!rootInput.txid ||
-        hex.encode(rootInput.txid) !== commitmentTxid ||
-        rootInput.index !== BATCH_OUTPUT_VTXO_INDEX) {
-        throw ErrWrongCommitmentTxid;
-    }
-    let sumRootValue = 0n;
-    for (let i = 0; i < graph.root.outputsLength; i++) {
-        const output = graph.root.getOutput(i);
-        if (output?.amount) {
-            sumRootValue += output.amount;
-        }
-    }
-    if (sumRootValue !== batchOutputAmount) {
-        throw ErrInvalidAmount;
-    }
-    const leaves = graph.leaves();
-    if (leaves.length === 0) {
-        throw ErrNoLeaves;
-    }
-    // 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.iterator()) {
-        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

@@ -1,31 +0,0 @@
-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

@@ -1,264 +0,0 @@
-import { schnorr } from "@noble/curves/secp256k1.js";
-import { hex } from "@scure/base";
-import { DEFAULT_SEQUENCE, Script, SigHash } from "@scure/btc-signer";
-import { tapLeafHash } from "@scure/btc-signer/payment.js";
-import { CLTVMultisigTapscript, decodeTapscript, } from "../script/tapscript.js";
-import { scriptFromTapLeafScript, VtxoScript, } from "../script/base.js";
-import { P2A } from "./anchor.js";
-import { setArkPsbtField, VtxoTaprootTree } from "./unknownFields.js";
-import { Transaction } from "./transaction.js";
-import { ArkAddress } from "../script/address.js";
-import { Extension } from "../extension/index.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 Arkade 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) {
-    // TODO: use arkd /info
-    const MAX_OP_RETURN = 2;
-    let countOpReturn = 0;
-    let hasExtensionOutput = false;
-    for (const [index, output] of outputs.entries()) {
-        if (!output.script)
-            throw new Error(`missing output script ${index}`);
-        const isExtension = Extension.isExtension(output.script);
-        const isOpReturn = isExtension || Script.decode(output.script)[0] === "RETURN";
-        if (isOpReturn) {
-            countOpReturn++;
-        }
-        if (!isExtension)
-            continue;
-        if (hasExtensionOutput)
-            throw new Error("multiple extension outputs");
-        hasExtensionOutput = true;
-    }
-    if (countOpReturn > MAX_OP_RETURN) {
-        throw new Error(`too many OP_RETURN outputs: ${countOpReturn} > ${MAX_OP_RETURN}`);
-    }
-    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,
-        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 virtual output script from collaborative closure
-    const collaborativeClosure = decodeTapscript(scriptFromTapLeafScript(vtxo.tapLeafScript));
-    // create the checkpoint virtual output 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: checkpointTx.id,
-        vout: 0,
-        value: vtxo.value,
-        tapLeafScript: collaborativeLeafProof,
-        tapTree: checkpointVtxoScript.encode(),
-    };
-    return {
-        tx: checkpointTx,
-        input: checkpointInput,
-    };
-}
-const nLocktimeMinSeconds = 500000000n;
-function isSeconds(locktime) {
-    return locktime >= nLocktimeMinSeconds;
-}
-export function hasBoardingTxExpired(coin, boardingTimelock, chainTipHeight) {
-    if (!coin.status.block_time)
-        return false;
-    if (boardingTimelock.value === 0n)
-        return true;
-    if (boardingTimelock.type === "blocks") {
-        if (chainTipHeight === undefined || !coin.status.block_height)
-            return false;
-        return (BigInt(chainTipHeight - coin.status.block_height) >=
-            boardingTimelock.value);
-    }
-    // validate expiry in terms of seconds
-    const now = BigInt(Math.floor(Date.now() / 1000));
-    const blockTime = BigInt(Math.floor(coin.status.block_time));
-    return blockTime + boardingTimelock.value <= now;
-}
-/**
- * Formats a sighash type as a hex string (e.g., 0x01)
- */
-function formatSighash(type) {
-    return `0x${type.toString(16).padStart(2, "0")}`;
-}
-/**
- * Verify tapscript signatures on a transaction input
- * @param tx Transaction to verify
- * @param inputIndex Index of the input to verify
- * @param requiredSigners List of required signer pubkeys (hex encoded)
- * @param excludePubkeys List of pubkeys to exclude from verification (hex encoded, e.g., server key not yet signed)
- * @param allowedSighashTypes List of allowed sighash types (defaults to [SigHash.DEFAULT])
- * @throws Error if verification fails
- */
-export function verifyTapscriptSignatures(tx, inputIndex, requiredSigners, excludePubkeys = [], allowedSighashTypes = [SigHash.DEFAULT]) {
-    const input = tx.getInput(inputIndex);
-    // Collect prevout scripts and amounts for ALL inputs (required for preimageWitnessV1)
-    const prevoutScripts = [];
-    const prevoutAmounts = [];
-    for (let i = 0; i < tx.inputsLength; i++) {
-        const inp = tx.getInput(i);
-        if (!inp.witnessUtxo) {
-            throw new Error(`Input ${i} is missing witnessUtxo`);
-        }
-        prevoutScripts.push(inp.witnessUtxo.script);
-        prevoutAmounts.push(inp.witnessUtxo.amount);
-    }
-    // Verify tapScriptSig signatures
-    if (!input.tapScriptSig || input.tapScriptSig.length === 0) {
-        throw new Error(`Input ${inputIndex} is missing tapScriptSig`);
-    }
-    // Verify each signature in tapScriptSig
-    for (const [tapScriptSigData, signature] of input.tapScriptSig) {
-        const pubKey = tapScriptSigData.pubKey;
-        const pubKeyHex = hex.encode(pubKey);
-        // Skip verification for excluded pubkeys
-        if (excludePubkeys.includes(pubKeyHex)) {
-            continue;
-        }
-        // Extract sighash type from signature
-        // Schnorr signatures are 64 bytes, with optional 1-byte sighash appended
-        const sighashType = signature.length === 65 ? signature[64] : SigHash.DEFAULT;
-        const sig = signature.subarray(0, 64);
-        // Verify sighash type is allowed
-        if (!allowedSighashTypes.includes(sighashType)) {
-            const sighashName = formatSighash(sighashType);
-            throw new Error(`Unallowed sighash type ${sighashName} for input ${inputIndex}, pubkey ${pubKeyHex}.`);
-        }
-        // Find the tapLeafScript that matches this signature's leafHash
-        if (!input.tapLeafScript || input.tapLeafScript.length === 0) {
-            throw new Error();
-        }
-        // Search for the leaf that matches the leafHash in tapScriptSigData
-        const leafHash = tapScriptSigData.leafHash;
-        const leafHashHex = hex.encode(leafHash);
-        let matchingScript;
-        let matchingVersion;
-        for (const [_, scriptWithVersion] of input.tapLeafScript) {
-            const script = scriptWithVersion.subarray(0, -1);
-            const version = scriptWithVersion[scriptWithVersion.length - 1];
-            // Compute the leaf hash for this script and compare as hex strings
-            const computedLeafHash = tapLeafHash(script, version);
-            const computedHex = hex.encode(computedLeafHash);
-            if (computedHex === leafHashHex) {
-                matchingScript = script;
-                matchingVersion = version;
-                break;
-            }
-        }
-        if (!matchingScript || matchingVersion === undefined) {
-            throw new Error(`Input ${inputIndex}: No tapLeafScript found matching leafHash ${hex.encode(leafHash)}`);
-        }
-        // Reconstruct the message that was signed
-        // Note: preimageWitnessV1 requires ALL input prevout scripts and amounts
-        const message = tx.preimageWitnessV1(inputIndex, prevoutScripts, sighashType, prevoutAmounts, undefined, matchingScript, matchingVersion);
-        // Verify the schnorr signature
-        const isValid = schnorr.verify(sig, message, pubKey);
-        if (!isValid) {
-            throw new Error(`Invalid signature for input ${inputIndex}, pubkey ${pubKeyHex}`);
-        }
-    }
-    // Verify we have signatures from all required signers (excluding those we're skipping)
-    const signedPubkeys = input.tapScriptSig.map(([data]) => hex.encode(data.pubKey));
-    const requiredNotExcluded = requiredSigners.filter((pk) => !excludePubkeys.includes(pk));
-    const missingSigners = requiredNotExcluded.filter((pk) => !signedPubkeys.includes(pk));
-    if (missingSigners.length > 0) {
-        throw new Error(`Missing signatures from: ${missingSigners.map((pk) => pk.slice(0, 16)).join(", ")}...`);
-    }
-}
-/**
- * Merges the signed transaction with the original transaction
- * @param signedTx signed transaction
- * @param originalTx original transaction
- */
-export function combineTapscriptSigs(signedTx, originalTx) {
-    for (let i = 0; i < signedTx.inputsLength; i++) {
-        const input = originalTx.getInput(i);
-        const signedInput = signedTx.getInput(i);
-        if (!input.tapScriptSig)
-            throw new Error("No tapScriptSig");
-        originalTx.updateInput(i, {
-            tapScriptSig: input.tapScriptSig?.concat(signedInput.tapScriptSig),
-        });
-    }
-    return originalTx;
-}
-/**
- * Validates if a given string is a valid Arkade address by attempting to decode it.
- * @param address The Arkade address to validate.
- * @returns True if the address is valid, false otherwise.
- */
-export function isValidArkAddress(address) {
-    try {
-        ArkAddress.decode(address);
-        return true;
-    }
-    catch (e) {
-        return false;
-    }
-}