@arkade-os/sdk 0.1.4 → 0.2.1

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 && message.inputIndexes != undefined
+                ? 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)) {

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

@@ -1,12 +1,37 @@
 import { Response } from './response.js';
-import { hex } from "@scure/base";
+import { base64, hex } from "@scure/base";
+import { SingleKey } from '../../identity/singleKey.js';
+import { TreeSignerSession } from '../../tree/signingSession.js';
+import { Transaction } from "@scure/btc-signer";
 class UnexpectedResponseError extends Error {
     constructor(response) {
         super(`Unexpected response type. Got: ${JSON.stringify(response, null, 2)}`);
         this.name = "UnexpectedResponseError";
     }
 }
-// ServiceWorkerWallet is a wallet that uses a service worker as "backend" to handle the wallet logic
+/**
+ * Service Worker-based wallet implementation for browser environments.
+ *
+ * This wallet uses a service worker as a backend to handle wallet logic,
+ * providing secure key storage and transaction signing in web applications.
+ * The service worker runs in a separate thread and can persist data between
+ * browser sessions.
+ *
+ * @example
+ * ```typescript
+ * // Create and initialize the service worker wallet
+ * const serviceWorker = await setupServiceWorker("/service-worker.js");
+ * const wallet = new ServiceWorkerWallet(serviceWorker);
+ * await wallet.init({
+ *   privateKey: 'your_private_key_hex',
+ *   arkServerUrl: 'https://ark.example.com'
+ * });
+ *
+ * // Use like any other wallet
+ * const address = await wallet.getAddress();
+ * const balance = await wallet.getBalance();
+ * ```
+ */
 export class ServiceWorkerWallet {
     constructor(serviceWorker) {
         this.serviceWorker = serviceWorker;
@@ -41,11 +66,14 @@ export class ServiceWorkerWallet {
             type: "INIT_WALLET",
             id: getRandomId(),
             privateKey: config.privateKey,
-            network: config.network,
-            arkServerUrl: config.arkServerUrl || "",
+            arkServerUrl: config.arkServerUrl,
             arkServerPublicKey: config.arkServerPublicKey,
         };
         await this.sendMessage(message);
+        const privKeyBytes = hex.decode(config.privateKey);
+        // cache the identity xOnlyPublicKey
+        this.cachedXOnlyPublicKey =
+            SingleKey.fromPrivateKey(privKeyBytes).xOnlyPublicKey();
     }
     async clear() {
         const message = {
@@ -53,6 +81,8 @@ export class ServiceWorkerWallet {
             id: getRandomId(),
         };
         await this.sendMessage(message);
+        // clear the cached xOnlyPublicKey
+        this.cachedXOnlyPublicKey = undefined;
     }
     // send a message and wait for a response
     async sendMessage(message) {
@@ -86,7 +116,7 @@ export class ServiceWorkerWallet {
         try {
             const response = await this.sendMessage(message);
             if (Response.isAddress(response)) {
-                return response.addresses;
+                return response.address;
             }
             throw new UnexpectedResponseError(response);
         }
@@ -94,20 +124,20 @@ export class ServiceWorkerWallet {
             throw new Error(`Failed to get address: ${error}`);
         }
     }
-    async getAddressInfo() {
+    async getBoardingAddress() {
         const message = {
-            type: "GET_ADDRESS_INFO",
+            type: "GET_BOARDING_ADDRESS",
             id: getRandomId(),
         };
         try {
             const response = await this.sendMessage(message);
-            if (Response.isAddressInfo(response)) {
-                return response.addressInfo;
+            if (Response.isBoardingAddress(response)) {
+                return response.address;
             }
             throw new UnexpectedResponseError(response);
         }
         catch (error) {
-            throw new Error(`Failed to get address info: ${error}`);
+            throw new Error(`Failed to get boarding address: ${error}`);
         }
     }
     async getBalance() {
@@ -126,26 +156,11 @@ export class ServiceWorkerWallet {
             throw new Error(`Failed to get balance: ${error}`);
         }
     }
-    async getCoins() {
-        const message = {
-            type: "GET_COINS",
-            id: getRandomId(),
-        };
-        try {
-            const response = await this.sendMessage(message);
-            if (Response.isCoins(response)) {
-                return response.coins;
-            }
-            throw new UnexpectedResponseError(response);
-        }
-        catch (error) {
-            throw new Error(`Failed to get coins: ${error}`);
-        }
-    }
-    async getVtxos() {
+    async getVtxos(filter) {
         const message = {
             type: "GET_VTXOS",
             id: getRandomId(),
+            filter,
         };
         try {
             const response = await this.sendMessage(message);
@@ -174,11 +189,10 @@ export class ServiceWorkerWallet {
             throw new Error(`Failed to get boarding UTXOs: ${error}`);
         }
     }
-    async sendBitcoin(params, zeroFee) {
+    async sendBitcoin(params) {
         const message = {
             type: "SEND_BITCOIN",
             params,
-            zeroFee,
             id: getRandomId(),
         };
         try {
@@ -245,21 +259,34 @@ export class ServiceWorkerWallet {
             throw new Error(`Failed to get transaction history: ${error}`);
         }
     }
-    async exit(outpoints) {
+    xOnlyPublicKey() {
+        if (!this.cachedXOnlyPublicKey) {
+            throw new Error("Wallet not initialized");
+        }
+        return this.cachedXOnlyPublicKey;
+    }
+    signerSession() {
+        return TreeSignerSession.random();
+    }
+    async sign(tx, inputIndexes) {
         const message = {
-            type: "EXIT",
-            outpoints,
+            type: "SIGN",
+            tx: base64.encode(tx.toPSBT()),
+            inputIndexes,
             id: getRandomId(),
         };
         try {
             const response = await this.sendMessage(message);
-            if (response.type === "EXIT_SUCCESS") {
-                return;
+            if (Response.isSignSuccess(response)) {
+                return Transaction.fromPSBT(base64.decode(response.tx), {
+                    allowUnknown: true,
+                    allowUnknownInputs: true,
+                });
             }
             throw new UnexpectedResponseError(response);
         }
         catch (error) {
-            throw new Error(`Failed to exit: ${error}`);
+            throw new Error(`Failed to sign: ${error}`);
         }
     }
 }