@arkade-os/sdk 0.4.26 → 0.4.28

package/dist/esm/wallet/unroll.js

@@ -1,285 +0,0 @@
-import { base64, hex } from "@scure/base";
-import { SigHash, TaprootControlBlock } from "@scure/btc-signer";
-import { timelockToSequence } from "../utils/timelock.js";
-import { ChainTxType } from "../providers/indexer.js";
-import { VtxoScript } from "../script/base.js";
-import { TxWeightEstimator } from "../utils/txSizeEstimator.js";
-import { Wallet } from "./wallet.js";
-import { Transaction } from "../utils/transaction.js";
-import { DUST_AMOUNT } from "./utils.js";
-export var Unroll;
-(function (Unroll) {
-    let StepType;
-    (function (StepType) {
-        StepType[StepType["UNROLL"] = 0] = "UNROLL";
-        StepType[StepType["WAIT"] = 1] = "WAIT";
-        StepType[StepType["DONE"] = 2] = "DONE";
-    })(StepType = Unroll.StepType || (Unroll.StepType = {}));
-    /**
-     * Manages the unrolling process of a virtual output back to the Bitcoin blockchain.
-     *
-     * The Session class implements an async iterator that processes the unrolling steps:
-     * 1. **WAIT**: Waits for a transaction to be confirmed onchain (if it's in mempool)
-     * 2. **UNROLL**: Broadcasts the next transaction in the chain to the blockchain
-     * 3. **DONE**: Indicates the unrolling process is complete
-     *
-     * The unrolling process works by traversing the transaction chain from the root (most recent)
-     * to the leaf (oldest), broadcasting each transaction that isn't already onchain.
-     *
-     * @example
-     * ```typescript
-     * const session = await Unroll.Session.create(vtxoOutpoint, bumper, explorer, indexer);
-     *
-     * // iterate over the steps
-     * for await (const doneStep of session) {
-     *   switch (doneStep.type) {
-     *     case Unroll.StepType.WAIT:
-     *       console.log(`Transaction ${doneStep.txid} confirmed`);
-     *       break;
-     *     case Unroll.StepType.UNROLL:
-     *       console.log(`Broadcasting transaction ${doneStep.tx.id}`);
-     *       break;
-     *     case Unroll.StepType.DONE:
-     *       console.log(`Unrolling complete for virtual output ${doneStep.vtxoTxid}`);
-     *       break;
-     *   }
-     * }
-     * ```
-     **/
-    class Session {
-        /** Create an unroll session from a virtual output outpoint and its dependency chain. */
-        constructor(toUnroll, bumper, explorer, indexer) {
-            this.toUnroll = toUnroll;
-            this.bumper = bumper;
-            this.explorer = explorer;
-            this.indexer = indexer;
-        }
-        /** Create an unroll session by loading the virtual output chain from the indexer. */
-        static async create(toUnroll, bumper, explorer, indexer) {
-            const { chain } = await indexer.getVtxoChain(toUnroll);
-            return new Session({ ...toUnroll, chain }, bumper, explorer, indexer);
-        }
-        /**
-         * Get the next step to be executed
-         * @returns The next step to be executed + the function to execute it
-         */
-        async next() {
-            let nextTxToBroadcast;
-            const chain = this.toUnroll.chain;
-            // Iterate through the chain from the end (root) to the beginning (leaf)
-            for (let i = chain.length - 1; i >= 0; i--) {
-                const chainTx = chain[i];
-                // Skip commitment transactions as they are always onchain
-                if (chainTx.type === ChainTxType.COMMITMENT ||
-                    chainTx.type === ChainTxType.UNSPECIFIED) {
-                    continue;
-                }
-                try {
-                    // Check if the transaction is confirmed onchain
-                    const txInfo = await this.explorer.getTxStatus(chainTx.txid);
-                    // If found but not confirmed, it means the tx is in the mempool
-                    // An unilateral exit is running, we must wait for it to be confirmed
-                    if (!txInfo.confirmed) {
-                        return {
-                            type: StepType.WAIT,
-                            txid: chainTx.txid,
-                            do: doWait(this.explorer, chainTx.txid),
-                        };
-                    }
-                }
-                catch (e) {
-                    // If the tx is not found, it's offchain, let's break
-                    nextTxToBroadcast = chainTx;
-                    break;
-                }
-            }
-            if (!nextTxToBroadcast) {
-                return {
-                    type: StepType.DONE,
-                    vtxoTxid: this.toUnroll.txid,
-                    do: () => Promise.resolve(),
-                };
-            }
-            // Get the virtual transaction data
-            const virtualTxs = await this.indexer.getVirtualTxs([
-                nextTxToBroadcast.txid,
-            ]);
-            if (virtualTxs.txs.length === 0) {
-                throw new Error(`Tx ${nextTxToBroadcast.txid} not found`);
-            }
-            const tx = Transaction.fromPSBT(base64.decode(virtualTxs.txs[0]));
-            // finalize the tree transaction
-            if (nextTxToBroadcast.type === ChainTxType.TREE) {
-                const input = tx.getInput(0);
-                if (!input) {
-                    throw new Error("Input not found");
-                }
-                const tapKeySig = input.tapKeySig;
-                if (!tapKeySig) {
-                    throw new Error("Tap key sig not found");
-                }
-                tx.updateInput(0, {
-                    finalScriptWitness: [tapKeySig],
-                });
-            }
-            else {
-                // finalize Arkade transaction
-                tx.finalize();
-            }
-            const pkg = await this.bumper.bumpP2A(tx);
-            return {
-                type: StepType.UNROLL,
-                tx,
-                pkg,
-                do: doUnroll(this.explorer, pkg),
-            };
-        }
-        /**
-         * Iterate over the steps to be executed and execute them
-         * @returns An async iterator over the executed steps
-         */
-        async *[Symbol.asyncIterator]() {
-            let lastStep;
-            do {
-                if (lastStep !== undefined) {
-                    // wait 1 second before trying the next step in order to give time to the
-                    // explorer to update the tx status
-                    await sleep(1000);
-                }
-                const step = await this.next();
-                await step.do();
-                yield step;
-                lastStep = step.type;
-            } while (lastStep !== StepType.DONE);
-        }
-    }
-    Unroll.Session = Session;
-    /**
-     * Complete the unroll of a virtual output by broadcasting the transaction that spends the CSV path.
-     * @param wallet the wallet owning the virtual output(s)
-     * @param vtxoTxids the txids of the virtual output(s) to complete unroll
-     * @param outputAddress the address to send the unrolled funds to
-     * @throws if the virtual output(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
-     * @returns the txid of the transaction spending the unrolled funds
-     */
-    async function completeUnroll(wallet, vtxoTxids, outputAddress) {
-        const signedTx = await prepareUnrollTransaction(wallet, vtxoTxids, outputAddress);
-        await wallet.onchainProvider.broadcastTransaction(signedTx.hex);
-        return signedTx.id;
-    }
-    Unroll.completeUnroll = completeUnroll;
-})(Unroll || (Unroll = {}));
-/**
- * Prepares the transaction that spends the CSV path to complete unrolling a VTXO.
- * @param wallet the wallet owning the VTXO(s)
- * @param vtxoTxIds the txids of the VTXO(s) to complete unroll
- * @param outputAddress the address to send the unrolled funds to
- * @throws if the VTXO(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
- * @returns the transaction spending the unrolled funds
- */
-export async function prepareUnrollTransaction(wallet, vtxoTxIds, outputAddress) {
-    const chainTip = await wallet.onchainProvider.getChainTip();
-    let vtxos = await wallet.getVtxos({ withUnrolled: true });
-    vtxos = vtxos.filter((vtxo) => vtxoTxIds.includes(vtxo.txid));
-    if (vtxos.length === 0) {
-        throw new Error("No vtxos to complete unroll");
-    }
-    const inputs = [];
-    let totalAmount = 0n;
-    const txWeightEstimator = TxWeightEstimator.create();
-    for (const vtxo of vtxos) {
-        if (!vtxo.isUnrolled) {
-            throw new Error(`Vtxo ${vtxo.txid}:${vtxo.vout} is not fully unrolled, use unroll first`);
-        }
-        const txStatus = await wallet.onchainProvider.getTxStatus(vtxo.txid);
-        if (!txStatus.confirmed) {
-            throw new Error(`tx ${vtxo.txid} is not confirmed`);
-        }
-        const exit = availableExitPath({ height: txStatus.blockHeight, time: txStatus.blockTime }, chainTip, vtxo);
-        if (!exit) {
-            throw new Error(`no available exit path found for vtxo ${vtxo.txid}:${vtxo.vout}`);
-        }
-        const spendingLeaf = VtxoScript.decode(vtxo.tapTree).findLeaf(hex.encode(exit.script));
-        if (!spendingLeaf) {
-            throw new Error(`spending leaf not found for vtxo ${vtxo.txid}:${vtxo.vout}`);
-        }
-        totalAmount += BigInt(vtxo.value);
-        const sequence = timelockToSequence(exit.params.timelock);
-        inputs.push({
-            txid: vtxo.txid,
-            index: vtxo.vout,
-            tapLeafScript: [spendingLeaf],
-            sequence,
-            witnessUtxo: {
-                amount: BigInt(vtxo.value),
-                script: VtxoScript.decode(vtxo.tapTree).pkScript,
-            },
-            sighashType: SigHash.DEFAULT,
-        });
-        txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, TaprootControlBlock.encode(spendingLeaf[0]).length);
-    }
-    const tx = new Transaction({ version: 2 });
-    for (const input of inputs) {
-        tx.addInput(input);
-    }
-    txWeightEstimator.addOutputAddress(outputAddress, wallet.network);
-    let feeRate = await wallet.onchainProvider.getFeeRate();
-    if (!feeRate || feeRate < Wallet.MIN_FEE_RATE) {
-        feeRate = Wallet.MIN_FEE_RATE;
-    }
-    const feeAmount = txWeightEstimator.vsize().fee(BigInt(feeRate));
-    if (feeAmount > totalAmount) {
-        throw new Error("fee amount is greater than the total amount");
-    }
-    const sendAmount = totalAmount - feeAmount;
-    if (sendAmount < BigInt(DUST_AMOUNT)) {
-        throw new Error("send amount is less than dust amount");
-    }
-    tx.addOutputAddress(outputAddress, sendAmount, wallet.network);
-    const signedTx = await wallet.identity.sign(tx);
-    signedTx.finalize();
-    return signedTx;
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function doUnroll(onchainProvider, pkg) {
-    return () => onchainProvider.broadcastTransaction(...pkg).then(() => undefined);
-}
-function doWait(onchainProvider, txid) {
-    return () => {
-        return new Promise((resolve, reject) => {
-            const interval = setInterval(async () => {
-                try {
-                    const txInfo = await onchainProvider.getTxStatus(txid);
-                    if (txInfo.confirmed) {
-                        clearInterval(interval);
-                        resolve();
-                    }
-                }
-                catch (e) {
-                    clearInterval(interval);
-                    reject(e);
-                }
-            }, 5000);
-        });
-    };
-}
-function availableExitPath(confirmedAt, current, vtxo) {
-    const exits = VtxoScript.decode(vtxo.tapTree).exitPaths();
-    for (const exit of exits) {
-        if (exit.params.timelock.type === "blocks") {
-            if (current.height >=
-                confirmedAt.height + Number(exit.params.timelock.value)) {
-                return exit;
-            }
-        }
-        else {
-            if (current.time >=
-                confirmedAt.time + Number(exit.params.timelock.value)) {
-                return exit;
-            }
-        }
-    }
-    return undefined;
-}

package/dist/esm/wallet/utils.js

@@ -1,103 +0,0 @@
-import { ArkAddress, } from "../index.js";
-import { contractHandlers } from "../contracts/handlers/index.js";
-import { hex } from "@scure/base";
-export const DUST_AMOUNT = 546; // sats
-export function extendCoin(wallet, utxo) {
-    return {
-        ...utxo,
-        forfeitTapLeafScript: wallet.boardingTapscript.forfeit(),
-        intentTapLeafScript: wallet.boardingTapscript.forfeit(),
-        tapTree: wallet.boardingTapscript.encode(),
-    };
-}
-function extendVtxoFromContract(vtxo, contract) {
-    const handler = contractHandlers.get(contract.type);
-    if (!handler) {
-        throw new Error(`No handler for contract type '${contract.type}'`);
-    }
-    const script = handler.createScript(contract.params);
-    return {
-        ...vtxo,
-        forfeitTapLeafScript: script.forfeit(),
-        intentTapLeafScript: script.forfeit(),
-        tapTree: script.encode(),
-    };
-}
-/**
- * Extend a VirtualCoin with the tap scripts of whichever contract locks it.
- *
- * The second argument accepts either form, so each callsite passes what it
- * already has:
- * - a single `Contract` (when the caller already knows the owning contract,
- *   e.g. the contract manager iterating its own `scriptToContract` map), or
- * - a `ReadonlyMap<script, Contract>` (when the caller resolves by
- *   `vtxo.script`, populated by the indexer).
- *
- * Throws when no contract can be resolved — there is intentionally no
- * default-tapscript fallback. When the wallet owns multiple contracts
- * (default + delegate, several active vHTLCs, etc.) a default-tapscript path
- * silently stamps every VTXO with the same forfeit/intent data, overwriting
- * the correct data for any VTXO locked to a non-default contract. Callers
- * must feed a Contract or a populated script→Contract map; otherwise the
- * caller (typically `ContractManager.annotateVtxos`) should fetch the owning
- * contract first.
- */
-export function extendVirtualCoinForContract(vtxo, contractOrMap) {
-    const contract = resolveContract(vtxo, contractOrMap);
-    if (!contract) {
-        throw new Error("extendVirtualCoinForContract: no contract matched vtxo.script — callers must resolve the owning contract before annotating");
-    }
-    return extendVtxoFromContract(vtxo, contract);
-}
-function isContractMap(value) {
-    // A `Contract` is a plain object with a string `type`. `ReadonlyMap` is
-    // an interface so `instanceof Map` is not enough to narrow it — but a
-    // contract has no `get` method, so duck-typing on that is unambiguous.
-    return typeof value.get === "function";
-}
-function resolveContract(vtxo, contractOrMap) {
-    if (!contractOrMap)
-        return undefined;
-    if (isContractMap(contractOrMap)) {
-        return contractOrMap.get(vtxo.script);
-    }
-    return contractOrMap;
-}
-export function getRandomId() {
-    const randomValue = crypto.getRandomValues(new Uint8Array(16));
-    return hex.encode(randomValue);
-}
-export function isValidArkAddress(address) {
-    try {
-        ArkAddress.decode(address);
-        return true;
-    }
-    catch (e) {
-        return false;
-    }
-}
-export function validateRecipients(recipients, dustAmount) {
-    const validatedRecipients = [];
-    for (const recipient of recipients) {
-        let address;
-        try {
-            address = ArkAddress.decode(recipient.address);
-        }
-        catch (e) {
-            throw new Error(`Invalid Arkade address: ${recipient.address}`);
-        }
-        const amount = recipient.amount || dustAmount;
-        if (amount <= 0) {
-            throw new Error("Amount must be positive");
-        }
-        validatedRecipients.push({
-            address: recipient.address,
-            assets: recipient.assets ?? [],
-            amount,
-            script: amount < dustAmount
-                ? address.subdustPkScript
-                : address.pkScript,
-        });
-    }
-    return validatedRecipients;
-}

package/dist/esm/wallet/validation.js

@@ -1,142 +0,0 @@
-import { equalBytes } from "@scure/btc-signer/utils.js";
-import { ArkAddress } from "../script/address.js";
-import { Extension } from "../extension/index.js";
-import { Address, OutScript } from "@scure/btc-signer";
-export const ErrOffchainOutputNotFound = (address) => new Error(`offchain send output not found: ${address}`);
-export const ErrInvalidAssetOutputAmount = (got, want, assetId) => new Error(`invalid asset output amount for ${assetId}: got ${got}, want ${want}`);
-export const ErrAssetGroupNotFound = (assetId) => new Error(`asset group not found in batch leaf: ${assetId}`);
-export const ErrAssetOutputNotFound = (assetId, outputIndex) => new Error(`asset output not found in asset group ${assetId} at index ${outputIndex}`);
-export const ErrInvalidOnchainOutputAmount = (address) => new Error(`invalid onchain output amount: ${address}`);
-export const ErrInvalidOnchainOutputAssets = (address) => new Error(`onchain output ${address} cannot have assets`);
-export const ErrOnchainOutputNotFound = (address) => new Error(`onchain output not found: ${address}`);
-export const ErrInvalidOffchainOutputAmount = (address) => new Error(`invalid offchain output ${address}, missing amount`);
-/**
- * Validates both offchain and onchain recipients.
- * Offchain recipients are checked against vtxo tree leaves for correct amounts and assets.
- * Onchain recipients are validated against the round transaction outputs (amounts and scripts)
- * via validateOnchainRecipient.
- *
- * @param commitmentTx - The commitment transaction to validate against
- * @param vtxoTreeLeaves - The vtxo tree leaves to validate against
- * @param recipients - The expected recipients to validate (both offchain and onchain)
- * @param network - Network for decoding onchain addresses (e.g. mainnet, testnet)
- * @throws {Error} if a recipient is not present or invalid in the vtxo tree or commitment tx
- */
-export function validateBatchRecipients(commitmentTx, vtxoTreeLeaves, recipients, network) {
-    // usedOutputs is used to track which outputs are validated to handle
-    // duplicate recipients in the list
-    const usedOutputs = new Set();
-    const usedOnchainOutputs = new Set();
-    for (const recipient of recipients) {
-        let arkAddress;
-        try {
-            arkAddress = ArkAddress.decode(recipient.address);
-        }
-        catch {
-            validateOnchainRecipient(commitmentTx, recipient, network, usedOnchainOutputs);
-            continue;
-        }
-        validateOffchainRecipient(vtxoTreeLeaves, arkAddress, recipient, usedOutputs);
-    }
-}
-// validateOnchainRecipient verifies the given recipient is present in the commitment tx outputs list
-function validateOnchainRecipient(commitmentTx, recipient, network, usedOutputs) {
-    const addr = Address(network).decode(recipient.address);
-    const expectedPkScript = OutScript.encode(addr);
-    if (!recipient.amount) {
-        throw ErrInvalidOnchainOutputAmount(recipient.address);
-    }
-    if (recipient.assets && recipient.assets.length > 0) {
-        throw ErrInvalidOnchainOutputAssets(recipient.address);
-    }
-    for (let i = 0; i < commitmentTx.outputsLength; i++) {
-        if (usedOutputs.has(i)) {
-            continue;
-        }
-        const output = commitmentTx.getOutput(i);
-        if (!output?.script || output.script.length === 0) {
-            continue;
-        }
-        if (equalBytes(output.script, expectedPkScript)) {
-            if (output.amount !== BigInt(recipient.amount)) {
-                continue; // if amount does not match, continue
-            }
-            // we found the right output, recipient is valid, return
-            usedOutputs.add(i);
-            return;
-        }
-    }
-    // if we get here, the recipient is not present in the commitment tx outputs list
-    throw ErrOnchainOutputNotFound(recipient.address);
-}
-// validate the offchain recipient is present in one of the leaf output
-// also verify the asset packet is here, and point the same output index
-function validateOffchainRecipient(leaves, arkAddress, recipient, usedOutputs // leafIndex:outputIndex
-) {
-    const expectedPkScript = arkAddress.pkScript;
-    if (!recipient.amount) {
-        throw ErrInvalidOffchainOutputAmount(recipient.address);
-    }
-    const expectedAmount = BigInt(recipient.amount);
-    let found = false;
-    for (let leafIdx = 0; leafIdx < leaves.length; leafIdx++) {
-        const leaf = leaves[leafIdx];
-        for (let outputIndex = 0; outputIndex < leaf.outputsLength; outputIndex++) {
-            const output = leaf.getOutput(outputIndex);
-            if (!output?.script || output.script.length === 0) {
-                continue;
-            }
-            if (!equalBytes(output.script, expectedPkScript)) {
-                continue;
-            }
-            if (output.amount !== expectedAmount) {
-                continue;
-            }
-            const key = `${leafIdx}:${outputIndex}`;
-            if (usedOutputs.has(key)) {
-                continue;
-            }
-            usedOutputs.add(key);
-            found = true;
-            // if assets, validate the asset packet
-            if (recipient.assets && recipient.assets.length > 0) {
-                validateAssetOutputs(leaf, outputIndex, recipient.assets);
-            }
-            break;
-        }
-        if (found) {
-            break;
-        }
-    }
-    if (!found) {
-        throw ErrOffchainOutputNotFound(recipient.address);
-    }
-}
-function validateAssetOutputs(leafTx, outputIndex, expectedAssets) {
-    const ext = Extension.fromTx(leafTx);
-    const assetPacket = ext.getAssetPacket();
-    if (!assetPacket) {
-        throw new Error("no asset packet found in extension");
-    }
-    for (const { assetId, amount } of expectedAssets) {
-        validateAssetGroupOutput(assetPacket, outputIndex, assetId, amount);
-    }
-}
-function validateAssetGroupOutput(packet, outputIndex, assetId, expectedAmount) {
-    const assetGroup = packet.groups.find((group) => {
-        if (group.isIssuance())
-            return false;
-        return group.assetId.toString() === assetId;
-    });
-    if (!assetGroup) {
-        throw ErrAssetGroupNotFound(assetId);
-    }
-    // find the output at the expected index
-    const assetOutput = assetGroup.outputs.find((output) => output.vout === outputIndex);
-    if (!assetOutput) {
-        throw ErrAssetOutputNotFound(assetId, outputIndex);
-    }
-    if (assetOutput.amount !== expectedAmount) {
-        throw ErrInvalidAssetOutputAmount(assetOutput.amount, expectedAmount, assetId);
-    }
-}