@arkade-os/sdk 0.1.4 → 0.2.1

package/dist/esm/utils/transactionHistory.js

@@ -1,55 +1,11 @@
 import { TxType } from '../wallet/index.js';
 /**
- * Helper function to find vtxos that were spent in a settlement
- */
-function findVtxosSpentInSettlement(vtxos, vtxo) {
-    if (vtxo.virtualStatus.state === "pending") {
-        return [];
-    }
-    return vtxos.filter((v) => {
-        if (!v.spentBy)
-            return false;
-        return v.spentBy === vtxo.virtualStatus.batchTxID;
-    });
-}
-/**
- * Helper function to find vtxos that were spent in a payment
- */
-function findVtxosSpentInPayment(vtxos, vtxo) {
-    return vtxos.filter((v) => {
-        if (!v.spentBy)
-            return false;
-        return v.spentBy === vtxo.txid;
-    });
-}
-/**
- * Helper function to find vtxos that resulted from a spentBy transaction
- */
-function findVtxosResultedFromSpentBy(vtxos, spentBy) {
-    return vtxos.filter((v) => {
-        if (v.virtualStatus.state !== "pending" &&
-            v.virtualStatus.batchTxID === spentBy) {
-            return true;
-        }
-        return v.txid === spentBy;
-    });
-}
-/**
- * Helper function to reduce vtxos to their total amount
+ * @param spendable - Vtxos that are spendable
+ * @param spent - Vtxos that are spent
+ * @param boardingBatchTxids - Set of boarding batch txids
+ * @returns Ark transactions
  */
-function reduceVtxosAmount(vtxos) {
-    return vtxos.reduce((sum, v) => sum + v.value, 0);
-}
-/**
- * Helper function to get a vtxo from a list of vtxos
- */
-function getVtxo(resultedVtxos, spentVtxos) {
-    if (resultedVtxos.length === 0) {
-        return spentVtxos[0];
-    }
-    return resultedVtxos[0];
-}
-export function vtxosToTxs(spendable, spent, boardingRounds) {
+export function vtxosToTxs(spendable, spent, boardingBatchTxids) {
     const txs = [];
     // Receive case
     // All vtxos are received unless:
@@ -57,8 +13,9 @@ export function vtxosToTxs(spendable, spent, boardingRounds) {
     // - they are the change of a spend tx
     let vtxosLeftToCheck = [...spent];
     for (const vtxo of [...spendable, ...spent]) {
-        if (vtxo.virtualStatus.state !== "pending" &&
-            boardingRounds.has(vtxo.virtualStatus.batchTxID || "")) {
+        if (vtxo.virtualStatus.state !== "preconfirmed" &&
+            vtxo.virtualStatus.commitmentTxIds &&
+            vtxo.virtualStatus.commitmentTxIds.some((txid) => boardingBatchTxids.has(txid))) {
             continue;
         }
         const settleVtxos = findVtxosSpentInSettlement(vtxosLeftToCheck, vtxo);
@@ -74,13 +31,13 @@ export function vtxosToTxs(spendable, spent, boardingRounds) {
             continue; // settlement or change, ignore
         }
         const txKey = {
-            roundTxid: vtxo.virtualStatus.batchTxID || "",
+            commitmentTxid: vtxo.spentBy || "",
             boardingTxid: "",
-            redeemTxid: "",
+            arkTxid: "",
         };
-        let settled = vtxo.virtualStatus.state !== "pending";
-        if (vtxo.virtualStatus.state === "pending") {
-            txKey.redeemTxid = vtxo.txid;
+        let settled = vtxo.virtualStatus.state !== "preconfirmed";
+        if (vtxo.virtualStatus.state === "preconfirmed") {
+            txKey.arkTxid = vtxo.txid;
             if (vtxo.spentBy) {
                 settled = true;
             }
@@ -93,22 +50,27 @@ export function vtxosToTxs(spendable, spent, boardingRounds) {
             settled,
         });
     }
-    // send case
-    // All "spentBy" vtxos are payments unless:
-    // - they are settlements
-    // aggregate spent by spentId
-    const vtxosBySpentBy = new Map();
+    // vtxos by settled by or ark txid
+    const vtxosByTxid = new Map();
     for (const v of spent) {
-        if (!v.spentBy)
+        if (v.settledBy) {
+            if (!vtxosByTxid.has(v.settledBy)) {
+                vtxosByTxid.set(v.settledBy, []);
+            }
+            const currentVtxos = vtxosByTxid.get(v.settledBy);
+            vtxosByTxid.set(v.settledBy, [...currentVtxos, v]);
+        }
+        if (!v.arkTxId) {
             continue;
-        if (!vtxosBySpentBy.has(v.spentBy)) {
-            vtxosBySpentBy.set(v.spentBy, []);
         }
-        const currentVtxos = vtxosBySpentBy.get(v.spentBy);
-        vtxosBySpentBy.set(v.spentBy, [...currentVtxos, v]);
+        if (!vtxosByTxid.has(v.arkTxId)) {
+            vtxosByTxid.set(v.arkTxId, []);
+        }
+        const currentVtxos = vtxosByTxid.get(v.arkTxId);
+        vtxosByTxid.set(v.arkTxId, [...currentVtxos, v]);
     }
-    for (const [sb, vtxos] of vtxosBySpentBy) {
-        const resultedVtxos = findVtxosResultedFromSpentBy([...spendable, ...spent], sb);
+    for (const [sb, vtxos] of vtxosByTxid) {
+        const resultedVtxos = findVtxosResultedFromTxid([...spendable, ...spent], sb);
         const resultedAmount = reduceVtxosAmount(resultedVtxos);
         const spentAmount = reduceVtxosAmount(vtxos);
         if (spentAmount <= resultedAmount) {
@@ -116,12 +78,12 @@ export function vtxosToTxs(spendable, spent, boardingRounds) {
         }
         const vtxo = getVtxo(resultedVtxos, vtxos);
         const txKey = {
-            roundTxid: vtxo.virtualStatus.batchTxID || "",
+            commitmentTxid: vtxo.virtualStatus.commitmentTxIds?.[0] || "",
             boardingTxid: "",
-            redeemTxid: "",
+            arkTxid: "",
         };
-        if (vtxo.virtualStatus.state === "pending") {
-            txKey.redeemTxid = vtxo.txid;
+        if (vtxo.virtualStatus.state === "preconfirmed") {
+            txKey.arkTxid = vtxo.txid;
         }
         txs.push({
             key: txKey,
@@ -133,6 +95,56 @@ export function vtxosToTxs(spendable, spent, boardingRounds) {
     }
     return txs;
 }
+/**
+ * Helper function to find vtxos that were spent in a settlement
+ */
+function findVtxosSpentInSettlement(vtxos, vtxo) {
+    if (vtxo.virtualStatus.state === "preconfirmed") {
+        return [];
+    }
+    return vtxos.filter((v) => {
+        if (!v.settledBy)
+            return false;
+        return (vtxo.virtualStatus.commitmentTxIds?.includes(v.settledBy) ?? false);
+    });
+}
+/**
+ * Helper function to find vtxos that were spent in a payment
+ */
+function findVtxosSpentInPayment(vtxos, vtxo) {
+    return vtxos.filter((v) => {
+        if (!v.arkTxId)
+            return false;
+        return v.arkTxId === vtxo.txid;
+    });
+}
+/**
+ * Helper function to find vtxos that resulted from a spentBy transaction
+ */
+function findVtxosResultedFromTxid(vtxos, txid) {
+    return vtxos.filter((v) => {
+        if (v.virtualStatus.state !== "preconfirmed" &&
+            v.virtualStatus.commitmentTxIds?.includes(txid)) {
+            return true;
+        }
+        return v.txid === txid;
+    });
+}
+/**
+ * Helper function to reduce vtxos to their total amount
+ */
+function reduceVtxosAmount(vtxos) {
+    return vtxos.reduce((sum, v) => sum + v.value, 0);
+}
+/**
+ * Helper function to get a vtxo from a list of vtxos
+ */
+function getVtxo(resultedVtxos, spentVtxos) {
+    if (resultedVtxos.length === 0) {
+        return spentVtxos[0];
+    }
+    return resultedVtxos[0];
+}
 function removeVtxosFromList(vtxos, vtxosToRemove) {
     return vtxos.filter((v) => {
         for (const vtxoToRemove of vtxosToRemove) {

package/dist/esm/utils/txSizeEstimator.js

@@ -10,6 +10,11 @@ export class TxWeightEstimator {
     static create() {
         return new TxWeightEstimator(false, 0, 0, 0, 0, 0);
     }
+    addP2AInput() {
+        this.inputCount++;
+        this.inputSize += TxWeightEstimator.INPUT_SIZE;
+        return this;
+    }
     addKeySpendInput(isDefault = true) {
         this.inputCount++;
         this.inputWitnessSize += 64 + 1 + (isDefault ? 0 : 1);
@@ -45,6 +50,12 @@ export class TxWeightEstimator {
             TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2WKH_OUTPUT_SIZE;
         return this;
     }
+    addP2TROutput() {
+        this.outputCount++;
+        this.outputSize +=
+            TxWeightEstimator.OUTPUT_SIZE + TxWeightEstimator.P2TR_OUTPUT_SIZE;
+        return this;
+    }
     vsize() {
         const getVarIntSize = (n) => {
             if (n < 0xfd)
@@ -82,6 +93,7 @@ TxWeightEstimator.P2WKH_OUTPUT_SIZE = 1 + 1 + 20;
 TxWeightEstimator.BASE_TX_SIZE = 8 + 2; // Version + LockTime
 TxWeightEstimator.WITNESS_HEADER_SIZE = 2; // Flag + Marker
 TxWeightEstimator.WITNESS_SCALE_FACTOR = 4;
+TxWeightEstimator.P2TR_OUTPUT_SIZE = 1 + 1 + 32;
 const vsize = (weight) => {
     const value = BigInt(Math.ceil(weight / TxWeightEstimator.WITNESS_SCALE_FACTOR));
     return {

package/dist/esm/utils/unknownFields.js

@@ -0,0 +1,173 @@
+import * as bip68 from "bip68";
+import { RawWitness, ScriptNum } from "@scure/btc-signer";
+import { hex } from "@scure/base";
+/**
+ * ArkPsbtFieldKey is the key values for ark psbt fields.
+ */
+export var ArkPsbtFieldKey;
+(function (ArkPsbtFieldKey) {
+    ArkPsbtFieldKey["VtxoTaprootTree"] = "taptree";
+    ArkPsbtFieldKey["VtxoTreeExpiry"] = "expiry";
+    ArkPsbtFieldKey["Cosigner"] = "cosigner";
+    ArkPsbtFieldKey["ConditionWitness"] = "condition";
+})(ArkPsbtFieldKey || (ArkPsbtFieldKey = {}));
+/**
+ * ArkPsbtFieldKeyType is the type of the ark psbt field key.
+ * Every ark psbt field has key type 255.
+ */
+export const ArkPsbtFieldKeyType = 255;
+/**
+ * setArkPsbtField appends a new unknown field to the input at inputIndex
+ *
+ * @example
+ * ```typescript
+ * setArkPsbtField(tx, 0, VtxoTaprootTree, myTaprootTree);
+ * setArkPsbtField(tx, 0, VtxoTreeExpiry, myVtxoTreeExpiry);
+ * ```
+ */
+export function setArkPsbtField(tx, inputIndex, coder, value) {
+    tx.updateInput(inputIndex, {
+        unknown: [
+            ...(tx.getInput(inputIndex)?.unknown ?? []),
+            coder.encode(value),
+        ],
+    });
+}
+/**
+ * getArkPsbtFields returns all the values of the given coder for the input at inputIndex
+ * Multiple fields of the same type can exist in a single input.
+ *
+ * @example
+ * ```typescript
+ * const vtxoTaprootTreeFields = getArkPsbtFields(tx, 0, VtxoTaprootTree);
+ * console.log(`input has ${vtxoTaprootTreeFields.length} vtxoTaprootTree fields`);
+ */
+export function getArkPsbtFields(tx, inputIndex, coder) {
+    const unknown = tx.getInput(inputIndex)?.unknown ?? [];
+    const fields = [];
+    for (const u of unknown) {
+        const v = coder.decode(u);
+        if (v)
+            fields.push(v);
+    }
+    return fields;
+}
+/**
+ * VtxoTaprootTree is set to pass all spending leaves of the vtxo input
+ *
+ * @example
+ * ```typescript
+ * const vtxoTaprootTree = VtxoTaprootTree.encode(myTaprootTree);
+ */
+export const VtxoTaprootTree = {
+    key: ArkPsbtFieldKey.VtxoTaprootTree,
+    encode: (value) => [
+        {
+            type: ArkPsbtFieldKeyType,
+            key: encodedPsbtFieldKey[ArkPsbtFieldKey.VtxoTaprootTree],
+        },
+        value,
+    ],
+    decode: (value) => nullIfCatch(() => {
+        if (!checkKeyIncludes(value[0], ArkPsbtFieldKey.VtxoTaprootTree))
+            return null;
+        return value[1];
+    }),
+};
+/**
+ * ConditionWitness is set to pass the witness data used to finalize the conditionMultisigClosure
+ *
+ * @example
+ * ```typescript
+ * const conditionWitness = ConditionWitness.encode(myConditionWitness);
+ */
+export const ConditionWitness = {
+    key: ArkPsbtFieldKey.ConditionWitness,
+    encode: (value) => [
+        {
+            type: ArkPsbtFieldKeyType,
+            key: encodedPsbtFieldKey[ArkPsbtFieldKey.ConditionWitness],
+        },
+        RawWitness.encode(value),
+    ],
+    decode: (value) => nullIfCatch(() => {
+        if (!checkKeyIncludes(value[0], ArkPsbtFieldKey.ConditionWitness))
+            return null;
+        return RawWitness.decode(value[1]);
+    }),
+};
+/**
+ * CosignerPublicKey is set on every TxGraph transactions to identify the musig2 public keys
+ *
+ * @example
+ * ```typescript
+ * const cosignerPublicKey = CosignerPublicKey.encode(myCosignerPublicKey);
+ */
+export const CosignerPublicKey = {
+    key: ArkPsbtFieldKey.Cosigner,
+    encode: (value) => [
+        {
+            type: ArkPsbtFieldKeyType,
+            key: new Uint8Array([
+                ...encodedPsbtFieldKey[ArkPsbtFieldKey.Cosigner],
+                value.index,
+            ]),
+        },
+        value.key,
+    ],
+    decode: (unknown) => nullIfCatch(() => {
+        if (!checkKeyIncludes(unknown[0], ArkPsbtFieldKey.Cosigner))
+            return null;
+        return {
+            index: unknown[0].key[unknown[0].key.length - 1],
+            key: unknown[1],
+        };
+    }),
+};
+/**
+ * VtxoTreeExpiry is set to pass the expiry time of the input
+ *
+ * @example
+ * ```typescript
+ * const vtxoTreeExpiry = VtxoTreeExpiry.encode(myVtxoTreeExpiry);
+ */
+export const VtxoTreeExpiry = {
+    key: ArkPsbtFieldKey.VtxoTreeExpiry,
+    encode: (value) => [
+        {
+            type: ArkPsbtFieldKeyType,
+            key: encodedPsbtFieldKey[ArkPsbtFieldKey.VtxoTreeExpiry],
+        },
+        ScriptNum(6, true).encode(value.value === 0n ? 0n : value.value),
+    ],
+    decode: (unknown) => nullIfCatch(() => {
+        if (!checkKeyIncludes(unknown[0], ArkPsbtFieldKey.VtxoTreeExpiry))
+            return null;
+        const v = ScriptNum(6, true).decode(unknown[1]);
+        if (!v)
+            return null;
+        const { blocks, seconds } = bip68.decode(Number(v));
+        return {
+            type: blocks ? "blocks" : "seconds",
+            value: BigInt(blocks ?? seconds ?? 0),
+        };
+    }),
+};
+const encodedPsbtFieldKey = Object.fromEntries(Object.values(ArkPsbtFieldKey).map((key) => [
+    key,
+    new TextEncoder().encode(key),
+]));
+const nullIfCatch = (fn) => {
+    try {
+        return fn();
+    }
+    catch (err) {
+        return null;
+    }
+};
+function checkKeyIncludes(key, arkPsbtFieldKey) {
+    const expected = hex.encode(encodedPsbtFieldKey[arkPsbtFieldKey]);
+    return hex
+        .encode(new Uint8Array([key.type, ...key.key]))
+        .includes(expected);
+}

package/dist/esm/wallet/index.js

@@ -3,3 +3,12 @@ export var TxType;
     TxType["TxSent"] = "SENT";
     TxType["TxReceived"] = "RECEIVED";
 })(TxType || (TxType = {}));
+export function isSpendable(vtxo) {
+    return vtxo.spentBy === undefined || vtxo.spentBy === "";
+}
+export function isRecoverable(vtxo) {
+    return vtxo.virtualStatus.state === "swept" && isSpendable(vtxo);
+}
+export function isSubdust(vtxo, dust) {
+    return vtxo.value < dust;
+}

package/dist/esm/wallet/onchain.js

@@ -0,0 +1,196 @@
+import { p2tr } from "@scure/btc-signer/payment";
+import { getNetwork } from '../networks.js';
+import { ESPLORA_URL, EsploraProvider, } from '../providers/onchain.js';
+import { Transaction } from "@scure/btc-signer";
+import { findP2AOutput, P2A } from '../utils/anchor.js';
+import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
+/**
+ * Onchain Bitcoin wallet implementation for traditional Bitcoin transactions.
+ *
+ * This wallet handles regular Bitcoin transactions on the blockchain without
+ * using the Ark protocol. It supports P2TR (Pay-to-Taproot) addresses and
+ * provides basic Bitcoin wallet functionality.
+ *
+ * @example
+ * ```typescript
+ * const wallet = new OnchainWallet(identity, 'mainnet');
+ * const balance = await wallet.getBalance();
+ * const txid = await wallet.send({
+ *   address: 'bc1...',
+ *   amount: 50000
+ * });
+ * ```
+ */
+export class OnchainWallet {
+    constructor(identity, network, provider) {
+        this.identity = identity;
+        const pubkey = identity.xOnlyPublicKey();
+        if (!pubkey) {
+            throw new Error("Invalid configured public key");
+        }
+        this.provider = provider || new EsploraProvider(ESPLORA_URL[network]);
+        this.network = getNetwork(network);
+        this.onchainP2TR = p2tr(pubkey, undefined, this.network);
+    }
+    get address() {
+        return this.onchainP2TR.address || "";
+    }
+    async getCoins() {
+        return this.provider.getCoins(this.address);
+    }
+    async getBalance() {
+        const coins = await this.getCoins();
+        const onchainConfirmed = coins
+            .filter((coin) => coin.status.confirmed)
+            .reduce((sum, coin) => sum + coin.value, 0);
+        const onchainUnconfirmed = coins
+            .filter((coin) => !coin.status.confirmed)
+            .reduce((sum, coin) => sum + coin.value, 0);
+        const onchainTotal = onchainConfirmed + onchainUnconfirmed;
+        return onchainTotal;
+    }
+    async send(params) {
+        if (params.amount <= 0) {
+            throw new Error("Amount must be positive");
+        }
+        if (params.amount < OnchainWallet.DUST_AMOUNT) {
+            throw new Error("Amount is below dust limit");
+        }
+        const coins = await this.getCoins();
+        let feeRate = params.feeRate;
+        if (!feeRate) {
+            feeRate = await this.provider.getFeeRate();
+        }
+        if (!feeRate || feeRate < OnchainWallet.MIN_FEE_RATE) {
+            feeRate = OnchainWallet.MIN_FEE_RATE;
+        }
+        // Ensure fee is an integer by rounding up
+        const estimatedFee = Math.ceil(174 * feeRate);
+        const totalNeeded = params.amount + estimatedFee;
+        // Select coins
+        const selected = selectCoins(coins, totalNeeded);
+        // Create transaction
+        let tx = new Transaction();
+        // Add inputs
+        for (const input of selected.inputs) {
+            tx.addInput({
+                txid: input.txid,
+                index: input.vout,
+                witnessUtxo: {
+                    script: this.onchainP2TR.script,
+                    amount: BigInt(input.value),
+                },
+                tapInternalKey: this.onchainP2TR.tapInternalKey,
+            });
+        }
+        // Add payment output
+        tx.addOutputAddress(params.address, BigInt(params.amount), this.network);
+        // Add change output if needed
+        if (selected.changeAmount > 0n) {
+            tx.addOutputAddress(this.address, selected.changeAmount, this.network);
+        }
+        // Sign inputs and Finalize
+        tx = await this.identity.sign(tx);
+        tx.finalize();
+        // Broadcast
+        const txid = await this.provider.broadcastTransaction(tx.hex);
+        return txid;
+    }
+    async bumpP2A(parent) {
+        const parentVsize = parent.vsize;
+        let child = new Transaction({
+            allowUnknownInputs: true,
+            allowLegacyWitnessUtxo: true,
+            version: 3,
+        });
+        child.addInput(findP2AOutput(parent)); // throws if not found
+        const childVsize = TxWeightEstimator.create()
+            .addKeySpendInput(true)
+            .addP2AInput()
+            .addP2TROutput()
+            .vsize().value;
+        const packageVSize = parentVsize + Number(childVsize);
+        let feeRate = await this.provider.getFeeRate();
+        if (!feeRate || feeRate < OnchainWallet.MIN_FEE_RATE) {
+            feeRate = OnchainWallet.MIN_FEE_RATE;
+        }
+        const fee = Math.ceil(feeRate * packageVSize);
+        if (!fee) {
+            throw new Error(`invalid fee, got ${fee} with vsize ${packageVSize}, feeRate ${feeRate}`);
+        }
+        // Select coins
+        const coins = await this.getCoins();
+        const selected = selectCoins(coins, fee, true);
+        for (const input of selected.inputs) {
+            child.addInput({
+                txid: input.txid,
+                index: input.vout,
+                witnessUtxo: {
+                    script: this.onchainP2TR.script,
+                    amount: BigInt(input.value),
+                },
+                tapInternalKey: this.onchainP2TR.tapInternalKey,
+            });
+        }
+        child.addOutputAddress(this.address, P2A.amount + selected.changeAmount, this.network);
+        // Sign inputs and Finalize
+        child = await this.identity.sign(child);
+        for (let i = 1; i < child.inputsLength; i++) {
+            child.finalizeIdx(i);
+        }
+        try {
+            await this.provider.broadcastTransaction(parent.hex, child.hex);
+        }
+        catch (error) {
+            console.error(error);
+        }
+        finally {
+            return [parent.hex, child.hex];
+        }
+    }
+}
+OnchainWallet.MIN_FEE_RATE = 1; // sat/vbyte
+OnchainWallet.DUST_AMOUNT = 546; // sats
+/**
+ * Select coins to reach a target amount, prioritizing those closer to expiry
+ * @param coins List of coins to select from
+ * @param targetAmount Target amount to reach in satoshis
+ * @param forceChange If true, ensure the coin selection will require a change output
+ * @returns Selected coins and change amount, or null if insufficient funds
+ */
+export function selectCoins(coins, targetAmount, forceChange = false) {
+    if (isNaN(targetAmount)) {
+        throw new Error("Target amount is NaN, got " + targetAmount);
+    }
+    if (targetAmount < 0) {
+        throw new Error("Target amount is negative, got " + targetAmount);
+    }
+    if (targetAmount === 0) {
+        return { inputs: [], changeAmount: 0n };
+    }
+    // Sort coins by amount (descending)
+    const sortedCoins = [...coins].sort((a, b) => b.value - a.value);
+    const selectedCoins = [];
+    let selectedAmount = 0;
+    // Select coins until we have enough
+    for (const coin of sortedCoins) {
+        selectedCoins.push(coin);
+        selectedAmount += coin.value;
+        if (forceChange
+            ? selectedAmount > targetAmount
+            : selectedAmount >= targetAmount) {
+            break;
+        }
+    }
+    if (selectedAmount === targetAmount) {
+        return { inputs: selectedCoins, changeAmount: 0n };
+    }
+    if (selectedAmount < targetAmount) {
+        throw new Error("Insufficient funds");
+    }
+    const changeAmount = BigInt(selectedAmount - targetAmount);
+    return {
+        inputs: selectedCoins,
+        changeAmount,
+    };
+}