@arkade-os/sdk 0.1.4 → 0.2.0

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

package/dist/esm/wallet/ramps.js

@@ -0,0 +1,91 @@
+/**
+ * Ramps is a class wrapping IWallet.settle method to provide a more convenient interface for onboarding and offboarding operations.
+ *
+ * @example
+ * ```typescript
+ * const ramps = new Ramps(wallet);
+ * await ramps.onboard(); // onboard all boarding utxos
+ * await ramps.offboard(myOnchainAddress); // collaborative exit all vtxos to onchain address
+ * ```
+ */
+export class Ramps {
+    constructor(wallet) {
+        this.wallet = wallet;
+    }
+    /**
+     * Onboard boarding utxos.
+     *
+     * @param boardingUtxos - The boarding utxos to onboard. If not provided, all boarding utxos will be used.
+     * @param amount - The amount to onboard. If not provided, the total amount of boarding utxos will be onboarded.
+     * @param eventCallback - The callback to receive settlement events. optional.
+     */
+    async onboard(boardingUtxos, amount, eventCallback) {
+        boardingUtxos = boardingUtxos ?? (await this.wallet.getBoardingUtxos());
+        const totalAmount = boardingUtxos.reduce((acc, coin) => acc + BigInt(coin.value), 0n);
+        let change = 0n;
+        if (amount) {
+            if (amount > totalAmount) {
+                throw new Error("Amount is greater than total amount of boarding utxos");
+            }
+            change = totalAmount - amount;
+        }
+        amount = amount ?? totalAmount;
+        const offchainAddress = await this.wallet.getAddress();
+        const outputs = [
+            {
+                address: offchainAddress,
+                amount,
+            },
+        ];
+        if (change > 0n) {
+            const boardingAddress = await this.wallet.getBoardingAddress();
+            outputs.push({
+                address: boardingAddress,
+                amount: change,
+            });
+        }
+        return this.wallet.settle({
+            inputs: boardingUtxos,
+            outputs,
+        }, eventCallback);
+    }
+    /**
+     * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
+     *
+     * @param destinationAddress - The destination address to offboard to.
+     * @param amount - The amount to offboard. If not provided, the total amount of vtxos will be offboarded.
+     * @param eventCallback - The callback to receive settlement events. optional.
+     */
+    async offboard(destinationAddress, amount, eventCallback) {
+        const vtxos = await this.wallet.getVtxos({
+            withRecoverable: true,
+            withUnrolled: false,
+        });
+        const totalAmount = vtxos.reduce((acc, coin) => acc + BigInt(coin.value), 0n);
+        let change = 0n;
+        if (amount) {
+            if (amount > totalAmount) {
+                throw new Error("Amount is greater than total amount of vtxos");
+            }
+            change = totalAmount - amount;
+        }
+        amount = amount ?? totalAmount;
+        const outputs = [
+            {
+                address: destinationAddress,
+                amount,
+            },
+        ];
+        if (change > 0n) {
+            const offchainAddress = await this.wallet.getAddress();
+            outputs.push({
+                address: offchainAddress,
+                amount: change,
+            });
+        }
+        return this.wallet.settle({
+            inputs: vtxos,
+            outputs,
+        }, eventCallback);
+    }
+}

package/dist/esm/wallet/serviceWorker/db/vtxo/idb.js

@@ -108,6 +108,38 @@ export class IndexedDBVtxoRepository {
             request.onerror = () => reject(request.error);
         });
     }
+    async getSweptVtxos() {
+        if (!this.db) {
+            throw new Error("Database not opened");
+        }
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(IndexedDBVtxoRepository.STORE_NAME, "readonly");
+            const store = transaction.objectStore(IndexedDBVtxoRepository.STORE_NAME);
+            const stateIndex = store.index("state");
+            // Get vtxos where state is "swept"
+            const request = stateIndex.getAll(IDBKeyRange.only("swept"));
+            request.onsuccess = () => {
+                resolve(request.result);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async getSpentVtxos() {
+        if (!this.db) {
+            throw new Error("Database not opened");
+        }
+        return new Promise((resolve, reject) => {
+            const transaction = this.db.transaction(IndexedDBVtxoRepository.STORE_NAME, "readonly");
+            const store = transaction.objectStore(IndexedDBVtxoRepository.STORE_NAME);
+            const spentByIndex = store.index("spentBy");
+            // Get vtxos where spentBy is not empty string
+            const request = spentByIndex.getAll(IDBKeyRange.lowerBound("", true));
+            request.onsuccess = () => {
+                resolve(request.result);
+            };
+            request.onerror = () => reject(request.error);
+        });
+    }
     async getAllVtxos() {
         if (!this.db) {
             throw new Error("Database not opened");

package/dist/esm/wallet/serviceWorker/request.js

@@ -1,3 +1,6 @@
+/**
+ * Request is the namespace that contains the request types for the service worker.
+ */
 export var Request;
 (function (Request) {
     function isBase(message) {
@@ -10,8 +13,6 @@ export var Request;
             typeof message.privateKey === "string" &&
             "arkServerUrl" in message &&
             typeof message.arkServerUrl === "string" &&
-            "network" in message &&
-            typeof message.network === "string" &&
             ("arkServerPublicKey" in message
                 ? typeof message.arkServerPublicKey === "string" ||
                     message.arkServerPublicKey === undefined
@@ -26,18 +27,14 @@ export var Request;
         return message.type === "GET_ADDRESS";
     }
     Request.isGetAddress = isGetAddress;
-    function isGetAddressInfo(message) {
-        return message.type === "GET_ADDRESS_INFO";
+    function isGetBoardingAddress(message) {
+        return message.type === "GET_BOARDING_ADDRESS";
     }
-    Request.isGetAddressInfo = isGetAddressInfo;
+    Request.isGetBoardingAddress = isGetBoardingAddress;
     function isGetBalance(message) {
         return message.type === "GET_BALANCE";
     }
     Request.isGetBalance = isGetBalance;
-    function isGetCoins(message) {
-        return message.type === "GET_COINS";
-    }
-    Request.isGetCoins = isGetCoins;
     function isGetVtxos(message) {
         return message.type === "GET_VTXOS";
     }
@@ -69,8 +66,14 @@ export var Request;
         return message.type === "GET_STATUS";
     }
     Request.isGetStatus = isGetStatus;
-    function isExit(message) {
-        return message.type === "EXIT";
+    function isSign(message) {
+        return (message.type === "SIGN" &&
+            "tx" in message &&
+            typeof message.tx === "string" &&
+            ("inputIndexes" in message
+                ? Array.isArray(message.inputIndexes) &&
+                    message.inputIndexes.every((index) => typeof index === "number")
+                : true));
     }
-    Request.isExit = isExit;
+    Request.isSign = isSign;
 })(Request || (Request = {}));

package/dist/esm/wallet/serviceWorker/response.js

@@ -1,3 +1,6 @@
+/**
+ * Response is the namespace that contains the response types for the service worker.
+ */
 export var Response;
 (function (Response) {
     Response.walletInitialized = (id) => ({
@@ -40,28 +43,28 @@ export var Response;
         return response.type === "ADDRESS" && response.success === true;
     }
     Response.isAddress = isAddress;
-    function addresses(id, addresses) {
+    function isBoardingAddress(response) {
+        return (response.type === "BOARDING_ADDRESS" && response.success === true);
+    }
+    Response.isBoardingAddress = isBoardingAddress;
+    function address(id, address) {
         return {
             type: "ADDRESS",
             success: true,
-            addresses,
+            address,
             id,
         };
     }
-    Response.addresses = addresses;
-    function isAddressInfo(response) {
-        return response.type === "ADDRESS_INFO" && response.success === true;
-    }
-    Response.isAddressInfo = isAddressInfo;
-    function addressInfo(id, addressInfo) {
+    Response.address = address;
+    function boardingAddress(id, address) {
         return {
-            type: "ADDRESS_INFO",
+            type: "BOARDING_ADDRESS",
             success: true,
-            addressInfo,
+            address,
             id,
         };
     }
-    Response.addressInfo = addressInfo;
+    Response.boardingAddress = boardingAddress;
     function isBalance(response) {
         return response.type === "BALANCE" && response.success === true;
     }
@@ -75,19 +78,6 @@ export var Response;
         };
     }
     Response.balance = balance;
-    function isCoins(response) {
-        return response.type === "COINS" && response.success === true;
-    }
-    Response.isCoins = isCoins;
-    function coins(id, coins) {
-        return {
-            type: "COINS",
-            success: true,
-            coins,
-            id,
-        };
-    }
-    Response.coins = coins;
     function isVtxos(response) {
         return response.type === "VTXOS" && response.success === true;
     }
@@ -181,12 +171,17 @@ export var Response;
         };
     }
     Response.clearResponse = clearResponse;
-    function exitSuccess(id) {
+    function signSuccess(id, tx) {
         return {
-            type: "EXIT_SUCCESS",
+            type: "SIGN_SUCCESS",
             success: true,
+            tx,
             id,
         };
     }
-    Response.exitSuccess = exitSuccess;
+    Response.signSuccess = signSuccess;
+    function isSignSuccess(response) {
+        return response.type === "SIGN_SUCCESS" && response.success === true;
+    }
+    Response.isSignSuccess = isSignSuccess;
 })(Response || (Response = {}));

package/dist/esm/wallet/serviceWorker/utils.js

@@ -1,3 +1,11 @@
+/**
+ * setupServiceWorker sets up the service worker.
+ * @param path - the path to the service worker script
+ * @example
+ * ```typescript
+ * const serviceWorker = await setupServiceWorker("/service-worker.js");
+ * ```
+ */
 export async function setupServiceWorker(path) {
     // check if service workers are supported
     if (!("serviceWorker" in navigator)) {