@arkade-os/sdk 0.3.3 → 0.3.5

package/dist/esm/wallet/ramps.js

@@ -53,10 +53,11 @@ export class Ramps {
      * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
      *
      * @param destinationAddress - The destination address to offboard to.
+     * @param feeInfo - The fee info to deduct from the offboard amount.
      * @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) {
+    async offboard(destinationAddress, feeInfo, amount, eventCallback) {
         const vtxos = await this.wallet.getVtxos({
             withRecoverable: true,
             withUnrolled: false,
@@ -70,6 +71,11 @@ export class Ramps {
             change = totalAmount - amount;
         }
         amount = amount ?? totalAmount;
+        const fees = feeInfo.intentFee.onchainOutput;
+        if (fees > amount) {
+            throw new Error(`can't deduct fees from offboard amount (${fees} > ${amount})`);
+        }
+        amount -= fees;
         const outputs = [
             {
                 address: destinationAddress,

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

@@ -74,7 +74,6 @@ export class Worker {
             const { boardingTxs, commitmentsToIgnore: roundsToIgnore } = await this.wallet.getBoardingTxs();
             const { spendable, spent } = await this.getAllVtxos();
             // convert VTXOs to offchain transactions
-            console.log("getTransactionHistory - vtxosToTxs:", spendable);
             const offchainTxs = vtxosToTxs(spendable, spent, roundsToIgnore);
             txs = [...boardingTxs, ...offchainTxs];
             // sort transactions by creation time in descending order (newest first)

package/dist/esm/wallet/wallet.js

@@ -109,12 +109,29 @@ export class Wallet {
         const esploraUrl = config.esploraUrl || ESPLORA_URL[info.network];
         // Use provided onchainProvider instance or create a new one
         const onchainProvider = config.onchainProvider || new EsploraProvider(esploraUrl);
-        // Generate timelocks
-        const exitTimelock = {
+        // validate unilateral exit timelock passed in config if any
+        if (config.exitTimelock) {
+            const { value, type } = config.exitTimelock;
+            if ((value < 512n && type !== "blocks") ||
+                (value >= 512n && type !== "seconds")) {
+                throw new Error("invalid exitTimelock");
+            }
+        }
+        // create unilateral exit timelock
+        const exitTimelock = config.exitTimelock ?? {
             value: info.unilateralExitDelay,
             type: info.unilateralExitDelay < 512n ? "blocks" : "seconds",
         };
-        const boardingTimelock = {
+        // validate boarding timelock passed in config if any
+        if (config.boardingTimelock) {
+            const { value, type } = config.boardingTimelock;
+            if ((value < 512n && type !== "blocks") ||
+                (value >= 512n && type !== "seconds")) {
+                throw new Error("invalid boardingTimelock");
+            }
+        }
+        // create boarding timelock
+        const boardingTimelock = config.boardingTimelock ?? {
             value: info.boardingExitDelay,
             type: info.boardingExitDelay < 512n ? "blocks" : "seconds",
         };
@@ -377,14 +394,13 @@ export class Wallet {
             });
         }
         const tapTree = this.offchainTapscript.encode();
-        let offchainTx = buildOffchainTx(selected.inputs.map((input) => ({
+        const offchainTx = buildOffchainTx(selected.inputs.map((input) => ({
             ...input,
             tapLeafScript: selectedLeaf,
             tapTree,
         })), outputs, this.serverUnrollScript);
         const signedVirtualTx = await this.identity.sign(offchainTx.arkTx);
         const { arkTxid, signedCheckpointTxs } = await this.arkProvider.submitTx(base64.encode(signedVirtualTx.toPSBT()), offchainTx.checkpoints.map((c) => base64.encode(c.toPSBT())));
-        // TODO persist final virtual tx and checkpoints to repository
         // sign the checkpoints
         const finalCheckpoints = await Promise.all(signedCheckpointTxs.map(async (c) => {
             const tx = Transaction.fromPSBT(base64.decode(c));
@@ -392,7 +408,78 @@ export class Wallet {
             return base64.encode(signedCheckpoint.toPSBT());
         }));
         await this.arkProvider.finalizeTx(arkTxid, finalCheckpoints);
-        return arkTxid;
+        try {
+            // mark VTXOs as spent and optionally add the change VTXO
+            const spentVtxos = [];
+            const commitmentTxIds = new Set();
+            let batchExpiry = Number.MAX_SAFE_INTEGER;
+            for (const [inputIndex, input] of selected.inputs.entries()) {
+                const vtxo = extendVirtualCoin(this, input);
+                const checkpointB64 = signedCheckpointTxs[inputIndex];
+                const checkpoint = Transaction.fromPSBT(base64.decode(checkpointB64));
+                spentVtxos.push({
+                    ...vtxo,
+                    virtualStatus: { ...vtxo.virtualStatus, state: "spent" },
+                    spentBy: checkpoint.id,
+                    arkTxId: arkTxid,
+                    isSpent: true,
+                });
+                if (vtxo.virtualStatus.commitmentTxIds) {
+                    for (const commitmentTxId of vtxo.virtualStatus
+                        .commitmentTxIds) {
+                        commitmentTxIds.add(commitmentTxId);
+                    }
+                }
+                if (vtxo.virtualStatus.batchExpiry) {
+                    batchExpiry = Math.min(batchExpiry, vtxo.virtualStatus.batchExpiry);
+                }
+            }
+            const createdAt = Date.now();
+            const addr = this.arkAddress.encode();
+            if (selected.changeAmount > 0n &&
+                batchExpiry !== Number.MAX_SAFE_INTEGER) {
+                const changeVtxo = {
+                    txid: arkTxid,
+                    vout: outputs.length - 1,
+                    createdAt: new Date(createdAt),
+                    forfeitTapLeafScript: this.offchainTapscript.forfeit(),
+                    intentTapLeafScript: this.offchainTapscript.exit(),
+                    isUnrolled: false,
+                    isSpent: false,
+                    tapTree: this.offchainTapscript.encode(),
+                    value: Number(selected.changeAmount),
+                    virtualStatus: {
+                        state: "preconfirmed",
+                        commitmentTxIds: Array.from(commitmentTxIds),
+                        batchExpiry,
+                    },
+                    status: {
+                        confirmed: false,
+                    },
+                };
+                await this.walletRepository.saveVtxos(addr, [changeVtxo]);
+            }
+            await this.walletRepository.saveVtxos(addr, spentVtxos);
+            await this.walletRepository.saveTransactions(addr, [
+                {
+                    key: {
+                        boardingTxid: "",
+                        commitmentTxid: "",
+                        arkTxid: arkTxid,
+                    },
+                    amount: params.amount,
+                    type: TxType.TxSent,
+                    settled: false,
+                    createdAt: Date.now(),
+                },
+            ]);
+        }
+        catch (e) {
+            console.warn("error saving offchain tx to repository", e);
+        }
+        finally {
+            return arkTxid;
+        }
     }
     async settle(params, eventCallback) {
         if (params?.inputs) {
@@ -665,7 +752,8 @@ export class Wallet {
             (async () => {
                 try {
                     for await (const update of subscription) {
-                        if (update.newVtxos?.length > 0) {
+                        if (update.newVtxos?.length > 0 ||
+                            update.spentVtxos?.length > 0) {
                             eventCallback({
                                 type: "vtxo",
                                 newVtxos: update.newVtxos.map((vtxo) => extendVirtualCoin(this, vtxo)),
@@ -832,13 +920,12 @@ export class Wallet {
         }
     }
     async makeRegisterIntentSignature(coins, outputs, onchainOutputsIndexes, cosignerPubKeys) {
-        const nowSeconds = Math.floor(Date.now() / 1000);
         const inputs = this.prepareIntentProofInputs(coins);
         const message = {
             type: "register",
             onchain_output_indexes: onchainOutputsIndexes,
-            valid_at: nowSeconds,
-            expire_at: nowSeconds + 2 * 60, // valid for 2 minutes
+            valid_at: 0,
+            expire_at: 0,
             cosigners_public_keys: cosignerPubKeys,
         };
         const encodedMessage = JSON.stringify(message, null, 0);
@@ -850,11 +937,10 @@ export class Wallet {
         };
     }
     async makeDeleteIntentSignature(coins) {
-        const nowSeconds = Math.floor(Date.now() / 1000);
         const inputs = this.prepareIntentProofInputs(coins);
         const message = {
             type: "delete",
-            expire_at: nowSeconds + 2 * 60, // valid for 2 minutes
+            expire_at: 0,
         };
         const encodedMessage = JSON.stringify(message, null, 0);
         const proof = Intent.create(encodedMessage, inputs, []);

package/dist/types/index.d.ts

@@ -18,9 +18,9 @@ import { Worker } from "./wallet/serviceWorker/worker";
 import { Request } from "./wallet/serviceWorker/request";
 import { Response } from "./wallet/serviceWorker/response";
 import { ESPLORA_URL, EsploraProvider, OnchainProvider, ExplorerTransaction } from "./providers/onchain";
-import { RestArkProvider, ArkProvider, SettlementEvent, SettlementEventType, ArkInfo, SignedIntent, Output, TxNotification, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession } from "./providers/ark";
+import { RestArkProvider, ArkProvider, SettlementEvent, SettlementEventType, ArkInfo, SignedIntent, Output, TxNotification, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, FeeInfo } from "./providers/ark";
 import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, decodeTapscript, MultisigTapscript, TapscriptType, ArkTapscript, RelativeTimelock } from "./script/tapscript";
-import { hasBoardingTxExpired, buildOffchainTx, verifyTapscriptSignatures, ArkTxInput, OffchainTx } from "./utils/arkTransaction";
+import { hasBoardingTxExpired, buildOffchainTx, verifyTapscriptSignatures, ArkTxInput, OffchainTx, combineTapscriptSigs } from "./utils/arkTransaction";
 import { VtxoTaprootTree, ConditionWitness, getArkPsbtFields, setArkPsbtField, ArkPsbtFieldCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, CosignerPublicKey, VtxoTreeExpiry } from "./utils/unknownFields";
 import { Intent } from "./intent";
 import { ArkNote } from "./arknote";
@@ -33,5 +33,5 @@ import { Unroll } from "./wallet/unroll";
 import { WalletRepositoryImpl } from "./repositories/walletRepository";
 import { ContractRepositoryImpl } from "./repositories/contractRepository";
 import { ArkError, maybeArkError } from "./providers/errors";
-export { Wallet, SingleKey, OnchainWallet, Ramps, VtxoManager, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, Worker, ServiceWorkerWallet, Request, Response, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, ArkNote, networks, WalletRepositoryImpl, ContractRepositoryImpl, Intent, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, };
-export type { Identity, IWallet, WalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, Recipient, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, IndexerProvider, PageResponse, Batch, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, };
+export { Wallet, SingleKey, OnchainWallet, Ramps, VtxoManager, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, Worker, ServiceWorkerWallet, Request, Response, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, ArkNote, networks, WalletRepositoryImpl, ContractRepositoryImpl, Intent, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, };
+export type { Identity, IWallet, WalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, Recipient, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, IndexerProvider, PageResponse, Batch, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, };

package/dist/types/providers/ark.d.ts

@@ -75,8 +75,8 @@ export interface ScheduledSession {
 export interface IntentFeeInfo {
     offchainInput: string;
     offchainOutput: string;
-    onchainInput: string;
-    onchainOutput: string;
+    onchainInput: bigint;
+    onchainOutput: bigint;
 }
 export interface FeeInfo {
     intentFee: IntentFeeInfo;

package/dist/types/repositories/contractRepository.d.ts

@@ -10,7 +10,6 @@ export interface ContractRepository {
 }
 export declare class ContractRepositoryImpl implements ContractRepository {
     private storage;
-    private cache;
     constructor(storage: StorageAdapter);
     getContractData<T>(contractId: string, key: string): Promise<T | null>;
     setContractData<T>(contractId: string, key: string, data: T): Promise<void>;

package/dist/types/repositories/walletRepository.d.ts

@@ -21,7 +21,6 @@ export interface WalletRepository {
 }
 export declare class WalletRepositoryImpl implements WalletRepository {
     private storage;
-    private cache;
     constructor(storage: StorageAdapter);
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;
     saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;

package/dist/types/utils/arkTransaction.d.ts

@@ -35,3 +35,9 @@ export declare function hasBoardingTxExpired(coin: ExtendedCoin, boardingTimeloc
  * @throws Error if verification fails
  */
 export declare function verifyTapscriptSignatures(tx: Transaction, inputIndex: number, requiredSigners: string[], excludePubkeys?: string[], allowedSighashTypes?: number[]): void;
+/**
+ * Merges the signed transaction with the original transaction
+ * @param signedTx signed transaction
+ * @param originalTx original transaction
+ */
+export declare function combineTapscriptSigs(signedTx: Transaction, originalTx: Transaction): Transaction;

package/dist/types/wallet/ramps.d.ts

@@ -1,5 +1,5 @@
 import { ExtendedCoin, IWallet } from ".";
-import { SettlementEvent } from "../providers/ark";
+import { FeeInfo, SettlementEvent } from "../providers/ark";
 /**
  * Ramps is a class wrapping IWallet.settle method to provide a more convenient interface for onboarding and offboarding operations.
  *
@@ -25,8 +25,9 @@ export declare class Ramps {
      * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
      *
      * @param destinationAddress - The destination address to offboard to.
+     * @param feeInfo - The fee info to deduct from the offboard amount.
      * @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.
      */
-    offboard(destinationAddress: string, amount?: bigint, eventCallback?: (event: SettlementEvent) => void): ReturnType<IWallet["settle"]>;
+    offboard(destinationAddress: string, feeInfo: FeeInfo, amount?: bigint, eventCallback?: (event: SettlementEvent) => void): ReturnType<IWallet["settle"]>;
 }

package/dist/types/wallet/wallet.d.ts

@@ -1,9 +1,10 @@
+import { TransactionOutput } from "@scure/btc-signer/psbt.js";
 import { Bytes } from "@scure/btc-signer/utils.js";
 import { ArkAddress } from "../script/address";
 import { DefaultVtxo } from "../script/default";
 import { Network, NetworkName } from "../networks";
 import { OnchainProvider } from "../providers/onchain";
-import { SettlementEvent, ArkProvider } from "../providers/ark";
+import { SettlementEvent, ArkProvider, SignedIntent } from "../providers/ark";
 import { Identity } from "../identity";
 import { ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IWallet, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig } from ".";
 import { CSVMultisigTapscript } from "../script/tapscript";
@@ -93,8 +94,8 @@ export declare class Wallet implements IWallet {
     private handleSettlementSigningEvent;
     private handleSettlementTreeNoncesEvent;
     private handleSettlementFinalizationEvent;
-    private makeRegisterIntentSignature;
-    private makeDeleteIntentSignature;
+    makeRegisterIntentSignature(coins: ExtendedCoin[], outputs: TransactionOutput[], onchainOutputsIndexes: number[], cosignerPubKeys: string[]): Promise<SignedIntent>;
+    makeDeleteIntentSignature(coins: ExtendedCoin[]): Promise<SignedIntent>;
     private prepareIntentProofInputs;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -63,8 +63,8 @@
     "@types/node": "24.3.1",
     "@vitest/coverage-v8": "3.2.4",
     "esbuild": "^0.25.9",
-    "expo": "~52.0.47",
     "eventsource": "4.0.0",
+    "expo": "~52.0.47",
     "glob": "11.0.3",
     "husky": "9.1.7",
     "prettier": "3.6.2",