@arkade-os/sdk 0.3.8 → 0.3.10

package/dist/esm/identity/singleKey.js

@@ -83,4 +83,35 @@ export class SingleKey {
             return signAsync(message, this.key, { prehash: false });
         return schnorr.signAsync(message, this.key);
     }
+    async toReadonly() {
+        return new ReadonlySingleKey(await this.compressedPublicKey());
+    }
+}
+export class ReadonlySingleKey {
+    constructor(publicKey) {
+        this.publicKey = publicKey;
+        if (publicKey.length !== 33) {
+            throw new Error("Invalid public key length");
+        }
+    }
+    /**
+     * Create a ReadonlySingleKey from a compressed public key.
+     *
+     * @param publicKey - 33-byte compressed public key (02/03 prefix + 32-byte x coordinate)
+     * @returns A new ReadonlySingleKey instance
+     * @example
+     * ```typescript
+     * const pubkey = new Uint8Array(33); // your compressed public key
+     * const readonlyKey = ReadonlySingleKey.fromPublicKey(pubkey);
+     * ```
+     */
+    static fromPublicKey(publicKey) {
+        return new ReadonlySingleKey(publicKey);
+    }
+    xOnlyPublicKey() {
+        return Promise.resolve(this.publicKey.slice(1));
+    }
+    compressedPublicKey() {
+        return Promise.resolve(this.publicKey);
+    }
 }

package/dist/esm/index.js

@@ -1,15 +1,16 @@
 import { Transaction } from './utils/transaction.js';
-import { SingleKey } from './identity/singleKey.js';
+import { SingleKey, ReadonlySingleKey } from './identity/singleKey.js';
 import { ArkAddress } from './script/address.js';
 import { VHTLC } from './script/vhtlc.js';
 import { DefaultVtxo } from './script/default.js';
 import { VtxoScript, TapTreeCoder, } from './script/base.js';
-import { TxType, } from './wallet/index.js';
-import { Wallet, waitForIncomingFunds } from './wallet/wallet.js';
+import { TxType, isSpendable, isSubdust, isRecoverable, isExpired, } from './wallet/index.js';
+import { Batch } from './wallet/batch.js';
+import { Wallet, ReadonlyWallet, waitForIncomingFunds, getSequence, } from './wallet/wallet.js';
 import { TxTree } from './tree/txTree.js';
 import { Ramps } from './wallet/ramps.js';
 import { isVtxoExpiringSoon, VtxoManager } from './wallet/vtxo-manager.js';
-import { ServiceWorkerWallet } from './wallet/serviceWorker/wallet.js';
+import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet, } from './wallet/serviceWorker/wallet.js';
 import { OnchainWallet } from './wallet/onchain.js';
 import { setupServiceWorker } from './wallet/serviceWorker/utils.js';
 import { Worker } from './wallet/serviceWorker/worker.js';
@@ -29,9 +30,11 @@ import { Unroll } from './wallet/unroll.js';
 import { WalletRepositoryImpl } from './repositories/walletRepository.js';
 import { ContractRepositoryImpl } from './repositories/contractRepository.js';
 import { ArkError, maybeArkError } from './providers/errors.js';
+import { validateVtxoTxGraph, validateConnectorsTxGraph, } from './tree/validation.js';
+import { buildForfeitTx } from './forfeit.js';
 export { 
 // Wallets
-Wallet, SingleKey, OnchainWallet, Ramps, VtxoManager, 
+Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, OnchainWallet, Ramps, VtxoManager, 
 // Providers
 ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, 
 // Script-related
@@ -39,7 +42,7 @@ ArkAddress, DefaultVtxo, VtxoScript, VHTLC,
 // Enums
 TxType, IndexerTxType, ChainTxType, SettlementEventType, 
 // Service Worker
-setupServiceWorker, Worker, ServiceWorkerWallet, Request, Response, 
+setupServiceWorker, Worker, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, Request, Response, 
 // Tapscript
 decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, 
 // Ark PSBT fields
@@ -59,4 +62,6 @@ TxTree,
 // Anchor
 P2A, Unroll, Transaction, 
 // Errors
-ArkError, maybeArkError, };
+ArkError, maybeArkError, 
+// Batch session
+Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, };

package/dist/esm/intent/index.js

@@ -33,12 +33,15 @@ export var Intent;
      * ownership of VTXOs and UTXOs. The proof includes the message to be
      * signed and the inputs/outputs that demonstrate ownership.
      *
-     * @param message - The Intent message to be signed
+     * @param message - The Intent message to be signed, either raw string of Message object
      * @param inputs - Array of transaction inputs to prove ownership of
      * @param outputs - Optional array of transaction outputs
      * @returns An unsigned Intent proof transaction
      */
     function create(message, inputs, outputs = []) {
+        if (typeof message !== "string") {
+            message = encodeMessage(message);
+        }
         if (inputs.length == 0)
             throw new Error("intent proof requires at least one input");
         if (!validateInputs(inputs))
@@ -51,6 +54,29 @@ export var Intent;
         return craftToSignTx(toSpend, inputs, outputs);
     }
     Intent.create = create;
+    function encodeMessage(message) {
+        switch (message.type) {
+            case "register":
+                return JSON.stringify({
+                    type: "register",
+                    onchain_output_indexes: message.onchain_output_indexes,
+                    valid_at: message.valid_at,
+                    expire_at: message.expire_at,
+                    cosigners_public_keys: message.cosigners_public_keys,
+                });
+            case "delete":
+                return JSON.stringify({
+                    type: "delete",
+                    expire_at: message.expire_at,
+                });
+            case "get-pending-tx":
+                return JSON.stringify({
+                    type: "get-pending-tx",
+                    expire_at: message.expire_at,
+                });
+        }
+    }
+    Intent.encodeMessage = encodeMessage;
 })(Intent || (Intent = {}));
 const OP_RETURN_EMPTY_PKSCRIPT = new Uint8Array([OP.RETURN]);
 const ZERO_32 = new Uint8Array(32).fill(0);
@@ -105,9 +131,12 @@ function craftToSpendTx(message, pkScript) {
 // craftToSignTx creates the transaction that will be signed for the proof
 function craftToSignTx(toSpend, inputs, outputs) {
     const firstInput = inputs[0];
+    const lockTime = inputs
+        .map((input) => input.sequence || 0)
+        .reduce((a, b) => Math.max(a, b), 0);
     const tx = new Transaction({
         version: 2,
-        lockTime: 0,
+        lockTime,
     });
     // add the first "toSpend" input
     tx.addInput({

package/dist/esm/providers/ark.js

@@ -1,6 +1,7 @@
 import { hex } from "@scure/base";
 import { eventSourceIterator } from './utils.js';
 import { maybeArkError } from './errors.js';
+import { Intent } from '../intent/index.js';
 export var SettlementEventType;
 (function (SettlementEventType) {
     SettlementEventType["BatchStarted"] = "batch_started";
@@ -45,8 +46,12 @@ export class RestArkProvider {
             fees: {
                 intentFee: {
                     ...fromServer.fees?.intentFee,
-                    onchainInput: BigInt(fromServer.fees?.intentFee?.onchainInput ?? 0),
-                    onchainOutput: BigInt(fromServer.fees?.intentFee?.onchainOutput ?? 0),
+                    onchainInput: BigInt(
+                    // split(".")[0] to remove the decimal part
+                    (fromServer.fees?.intentFee?.onchainInput ?? "0").split(".")[0] ?? 0),
+                    onchainOutput: BigInt(
+                    // split(".")[0] to remove the decimal part
+                    (fromServer.fees?.intentFee?.onchainOutput ?? "0").split(".")[0] ?? 0),
                 },
                 txFeeRate: fromServer?.fees?.txFeeRate ?? "",
             },
@@ -123,7 +128,7 @@ export class RestArkProvider {
             body: JSON.stringify({
                 intent: {
                     proof: intent.proof,
-                    message: intent.message,
+                    message: Intent.encodeMessage(intent.message),
                 },
             }),
         });
@@ -144,7 +149,7 @@ export class RestArkProvider {
             body: JSON.stringify({
                 intent: {
                     proof: intent.proof,
-                    message: intent.message,
+                    message: Intent.encodeMessage(intent.message),
                 },
             }),
         });
@@ -324,7 +329,12 @@ export class RestArkProvider {
             headers: {
                 "Content-Type": "application/json",
             },
-            body: JSON.stringify({ intent }),
+            body: JSON.stringify({
+                intent: {
+                    proof: intent.proof,
+                    message: Intent.encodeMessage(intent.message),
+                },
+            }),
         });
         if (!response.ok) {
             const errorText = await response.text();

package/dist/esm/providers/indexer.js

@@ -361,7 +361,7 @@ function convertVtxo(vtxo) {
 // Unexported namespace for type guards only
 var Response;
 (function (Response) {
-    function isBatch(data) {
+    function isBatchInfo(data) {
         return (typeof data === "object" &&
             typeof data.totalOutputAmount === "string" &&
             typeof data.totalOutputVtxos === "number" &&
@@ -385,7 +385,7 @@ var Response;
             typeof data.totalOutputAmount === "string" &&
             typeof data.totalOutputVtxos === "number" &&
             typeof data.batches === "object" &&
-            Object.values(data.batches).every(isBatch));
+            Object.values(data.batches).every(isBatchInfo));
     }
     Response.isCommitmentTx = isCommitmentTx;
     function isOutpoint(data) {

package/dist/esm/wallet/batch.js

@@ -0,0 +1,180 @@
+import { SettlementEventType } from '../providers/ark.js';
+import { TxTree } from '../tree/txTree.js';
+import { hex } from "@scure/base";
+/**
+ * Batch namespace provides utilities for joining and processing batch session.
+ * The batch settlement process involves multiple events, this namespace provides abstractions and types to handle them.
+ * @see https://docs.arkadeos.com/learn/pillars/batch-swaps
+ * @example
+ * ```typescript
+ * // use wallet handler or create a custom one
+ * const handler = wallet.createBatchHandler(intentId, inputs, musig2session);
+ *
+ * const abortController = new AbortController();
+ * // Get event stream from Ark provider
+ * const eventStream = arkProvider.getEventStream(
+ *   abortController.signal,
+ *   ['your-topic-1', 'your-topic-2']
+ * );
+ *
+ * // Join the batch and process events
+ * try {
+ *   const commitmentTxid = await Batch.join(eventStream, handler);
+ *   console.log('Batch completed with commitment:', commitmentTxid);
+ * } catch (error) {
+ *   console.error('Batch processing failed:', error);
+ * } finally {
+ *   abortController.abort();
+ * }
+ * ```
+ */
+export var Batch;
+(function (Batch) {
+    // State machine steps for batch session
+    let Step;
+    (function (Step) {
+        Step["Start"] = "start";
+        Step["BatchStarted"] = "batch_started";
+        Step["TreeSigningStarted"] = "tree_signing_started";
+        Step["TreeNoncesAggregated"] = "tree_nonces_aggregated";
+        Step["BatchFinalization"] = "batch_finalization";
+    })(Step || (Step = {}));
+    /**
+     * Start the state machine that will process the batch events and join a batch.
+     * @param eventIterator - The events stream to process.
+     * @param handler - How to react to events.
+     * @param options - Options.
+     */
+    async function join(eventIterator, handler, options = {}) {
+        const { abortController, skipVtxoTreeSigning = false, eventCallback, } = options;
+        let step = Step.Start;
+        // keep track of tree transactions as they arrive
+        const flatVtxoTree = [];
+        const flatConnectorTree = [];
+        // once everything is collected, the TxTree objects are created
+        let vtxoTree = undefined;
+        let connectorTree = undefined;
+        for await (const event of eventIterator) {
+            if (abortController?.signal.aborted) {
+                throw new Error("canceled");
+            }
+            if (eventCallback) {
+                // don't wait for the callback to complete and ignore errors
+                eventCallback(event).catch(() => { });
+            }
+            switch (event.type) {
+                case SettlementEventType.BatchStarted: {
+                    const e = event;
+                    const { skip } = await handler.onBatchStarted(e);
+                    if (!skip) {
+                        step = Step.BatchStarted;
+                        if (skipVtxoTreeSigning) {
+                            // skip TxTree events and musig2 signatures and nonces
+                            step = Step.TreeNoncesAggregated;
+                        }
+                    }
+                    continue;
+                }
+                case SettlementEventType.BatchFinalized: {
+                    if (step !== Step.BatchFinalization) {
+                        continue;
+                    }
+                    if (handler.onBatchFinalized) {
+                        await handler.onBatchFinalized(event);
+                    }
+                    return event.commitmentTxid;
+                }
+                case SettlementEventType.BatchFailed: {
+                    if (handler.onBatchFailed) {
+                        await handler.onBatchFailed(event);
+                        continue;
+                    }
+                    throw new Error(event.reason);
+                }
+                case SettlementEventType.TreeTx: {
+                    if (step !== Step.BatchStarted &&
+                        step !== Step.TreeNoncesAggregated) {
+                        continue;
+                    }
+                    // batchIndex 0 = vtxo tree, batchIndex 1 = connector tree
+                    if (event.batchIndex === 0) {
+                        flatVtxoTree.push(event.chunk);
+                    }
+                    else {
+                        flatConnectorTree.push(event.chunk);
+                    }
+                    if (handler.onTreeTxEvent) {
+                        await handler.onTreeTxEvent(event);
+                    }
+                    continue;
+                }
+                case SettlementEventType.TreeSignature: {
+                    if (step !== Step.TreeNoncesAggregated) {
+                        continue;
+                    }
+                    if (!vtxoTree) {
+                        throw new Error("vtxo tree not initialized");
+                    }
+                    // push signature to the vtxo tree
+                    const tapKeySig = hex.decode(event.signature);
+                    vtxoTree.update(event.txid, (tx) => {
+                        tx.updateInput(0, {
+                            tapKeySig,
+                        });
+                    });
+                    if (handler.onTreeSignatureEvent) {
+                        await handler.onTreeSignatureEvent(event);
+                    }
+                    continue;
+                }
+                case SettlementEventType.TreeSigningStarted: {
+                    if (step !== Step.BatchStarted) {
+                        continue;
+                    }
+                    // create vtxo tree from collected chunks
+                    vtxoTree = TxTree.create(flatVtxoTree);
+                    const { skip } = await handler.onTreeSigningStarted(event, vtxoTree);
+                    if (!skip) {
+                        step = Step.TreeSigningStarted;
+                    }
+                    continue;
+                }
+                case SettlementEventType.TreeNonces: {
+                    if (step !== Step.TreeSigningStarted) {
+                        continue;
+                    }
+                    const { fullySigned } = await handler.onTreeNonces(event);
+                    if (fullySigned) {
+                        step = Step.TreeNoncesAggregated;
+                    }
+                    continue;
+                }
+                case SettlementEventType.BatchFinalization: {
+                    if (step !== Step.TreeNoncesAggregated) {
+                        continue;
+                    }
+                    // Build vtxo tree if it hasn't been built yet
+                    if (!vtxoTree && flatVtxoTree.length > 0) {
+                        vtxoTree = TxTree.create(flatVtxoTree);
+                    }
+                    if (!vtxoTree && !skipVtxoTreeSigning) {
+                        throw new Error("vtxo tree not initialized");
+                    }
+                    // Build connector tree if we have chunks
+                    if (flatConnectorTree.length > 0) {
+                        connectorTree = TxTree.create(flatConnectorTree);
+                    }
+                    await handler.onBatchFinalization(event, vtxoTree, connectorTree);
+                    step = Step.BatchFinalization;
+                    continue;
+                }
+                default:
+                    // unknown event type, continue
+                    continue;
+            }
+        }
+        // iterator closed without finalization, something went wrong
+        throw new Error("event stream closed");
+    }
+    Batch.join = join;
+})(Batch || (Batch = {}));

package/dist/esm/wallet/index.js

@@ -9,6 +9,20 @@ export function isSpendable(vtxo) {
 export function isRecoverable(vtxo) {
     return vtxo.virtualStatus.state === "swept" && isSpendable(vtxo);
 }
+export function isExpired(vtxo) {
+    if (vtxo.virtualStatus.state === "swept")
+        return true; // swept by server = expired
+    const expiry = vtxo.virtualStatus.batchExpiry;
+    if (!expiry)
+        return false;
+    // we use this as a workaround to avoid issue on regtest where expiry date is expressed in blockheight instead of timestamp
+    // if expiry, as Date, is before 2025, then we admit it's too small to be a timestamp
+    // TODO: API should return the expiry unit
+    const expireAt = new Date(expiry);
+    if (expireAt.getFullYear() < 2025)
+        return false;
+    return expiry <= Date.now();
+}
 export function isSubdust(vtxo, dust) {
     return vtxo.value < dust;
 }

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

@@ -11,8 +11,6 @@ export var Request;
         return (message.type === "INIT_WALLET" &&
             "arkServerUrl" in message &&
             typeof message.arkServerUrl === "string" &&
-            "privateKey" in message &&
-            typeof message.privateKey === "string" &&
             ("arkServerPublicKey" in message
                 ? message.arkServerPublicKey === undefined ||
                     typeof message.arkServerPublicKey === "string"

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

@@ -13,7 +13,16 @@ class UnexpectedResponseError extends Error {
         this.name = "UnexpectedResponseError";
     }
 }
-export class ServiceWorkerWallet {
+const createCommon = (options) => {
+    // Default to IndexedDB for service worker context
+    const storage = new IndexedDBStorageAdapter(options.dbName || DEFAULT_DB_NAME, options.dbVersion);
+    // Create repositories
+    return {
+        walletRepo: new WalletRepositoryImpl(storage),
+        contractRepo: new ContractRepositoryImpl(storage),
+    };
+};
+export class ServiceWorkerReadonlyWallet {
     constructor(serviceWorker, identity, walletRepository, contractRepository) {
         this.serviceWorker = serviceWorker;
         this.identity = identity;
@@ -21,27 +30,17 @@ export class ServiceWorkerWallet {
         this.contractRepository = contractRepository;
     }
     static async create(options) {
-        // Default to IndexedDB for service worker context
-        const storage = new IndexedDBStorageAdapter(options.dbName || DEFAULT_DB_NAME, options.dbVersion);
-        // Create repositories
-        const walletRepo = new WalletRepositoryImpl(storage);
-        const contractRepo = new ContractRepositoryImpl(storage);
-        // Extract identity and check if it can expose private key
-        const identity = isPrivateKeyIdentity(options.identity)
-            ? options.identity
-            : null;
-        if (!identity) {
-            throw new Error("ServiceWorkerWallet.create() requires a Identity that can expose a single private key");
-        }
-        // Extract private key for service worker initialization
-        const privateKey = identity.toHex();
+        const { walletRepo, contractRepo } = createCommon(options);
         // Create the wallet instance
-        const wallet = new ServiceWorkerWallet(options.serviceWorker, identity, walletRepo, contractRepo);
+        const wallet = new ServiceWorkerReadonlyWallet(options.serviceWorker, options.identity, walletRepo, contractRepo);
+        const publicKey = await options.identity
+            .compressedPublicKey()
+            .then(hex.encode);
         // Initialize the service worker with the config
         const initMessage = {
             type: "INIT_WALLET",
             id: getRandomId(),
-            privateKey,
+            key: { publicKey },
             arkServerUrl: options.arkServerUrl,
             arkServerPublicKey: options.arkServerPublicKey,
         };
@@ -56,14 +55,14 @@ export class ServiceWorkerWallet {
      * @example
      * ```typescript
      * // One-liner setup - handles everything automatically!
-     * const wallet = await ServiceWorkerWallet.setup({
+     * const wallet = await ServiceWorkerReadonlyWallet.setup({
      *   serviceWorkerPath: '/service-worker.js',
      *   arkServerUrl: 'https://mutinynet.arkade.sh'
      * });
      *
-     * // With custom identity
-     * const identity = SingleKey.fromHex('your_private_key_hex');
-     * const wallet = await ServiceWorkerWallet.setup({
+     * // With custom readonly identity
+     * const identity = ReadonlySingleKey.fromPublicKey('your_public_key_hex');
+     * const wallet = await ServiceWorkerReadonlyWallet.setup({
      *   serviceWorkerPath: '/service-worker.js',
      *   arkServerUrl: 'https://mutinynet.arkade.sh',
      *   identity
@@ -74,7 +73,7 @@ export class ServiceWorkerWallet {
         // Register and setup the service worker
         const serviceWorker = await setupServiceWorker(options.serviceWorkerPath);
         // Use the existing create method
-        return ServiceWorkerWallet.create({
+        return ServiceWorkerReadonlyWallet.create({
             ...options,
             serviceWorker,
         });
@@ -226,6 +225,81 @@ export class ServiceWorkerWallet {
             throw new Error(`Failed to get vtxos: ${error}`);
         }
     }
+    async reload() {
+        const message = {
+            type: "RELOAD_WALLET",
+            id: getRandomId(),
+        };
+        const response = await this.sendMessage(message);
+        if (Response.isWalletReloaded(response)) {
+            return response.success;
+        }
+        throw new UnexpectedResponseError(response);
+    }
+}
+export class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet {
+    constructor(serviceWorker, identity, walletRepository, contractRepository) {
+        super(serviceWorker, identity, walletRepository, contractRepository);
+        this.serviceWorker = serviceWorker;
+        this.identity = identity;
+        this.walletRepository = walletRepository;
+        this.contractRepository = contractRepository;
+    }
+    static async create(options) {
+        const { walletRepo, contractRepo } = createCommon(options);
+        // Extract identity and check if it can expose private key
+        const identity = isPrivateKeyIdentity(options.identity)
+            ? options.identity
+            : null;
+        if (!identity) {
+            throw new Error("ServiceWorkerWallet.create() requires a Identity that can expose a single private key");
+        }
+        // Extract private key for service worker initialization
+        const privateKey = identity.toHex();
+        // Create the wallet instance
+        const wallet = new ServiceWorkerWallet(options.serviceWorker, identity, walletRepo, contractRepo);
+        // Initialize the service worker with the config
+        const initMessage = {
+            type: "INIT_WALLET",
+            id: getRandomId(),
+            key: { privateKey },
+            arkServerUrl: options.arkServerUrl,
+            arkServerPublicKey: options.arkServerPublicKey,
+        };
+        // Initialize the service worker
+        await wallet.sendMessage(initMessage);
+        return wallet;
+    }
+    /**
+     * Simplified setup method that handles service worker registration,
+     * identity creation, and wallet initialization automatically.
+     *
+     * @example
+     * ```typescript
+     * // One-liner setup - handles everything automatically!
+     * const wallet = await ServiceWorkerWallet.setup({
+     *   serviceWorkerPath: '/service-worker.js',
+     *   arkServerUrl: 'https://mutinynet.arkade.sh'
+     * });
+     *
+     * // With custom identity
+     * const identity = SingleKey.fromHex('your_private_key_hex');
+     * const wallet = await ServiceWorkerWallet.setup({
+     *   serviceWorkerPath: '/service-worker.js',
+     *   arkServerUrl: 'https://mutinynet.arkade.sh',
+     *   identity
+     * });
+     * ```
+     */
+    static async setup(options) {
+        // Register and setup the service worker
+        const serviceWorker = await setupServiceWorker(options.serviceWorkerPath);
+        // Use the existing create method
+        return ServiceWorkerWallet.create({
+            ...options,
+            serviceWorker,
+        });
+    }
     async sendBitcoin(params) {
         const message = {
             type: "SEND_BITCOIN",
@@ -283,17 +357,6 @@ export class ServiceWorkerWallet {
             throw new Error(`Settlement failed: ${error}`);
         }
     }
-    async reload() {
-        const message = {
-            type: "RELOAD_WALLET",
-            id: getRandomId(),
-        };
-        const response = await this.sendMessage(message);
-        if (Response.isWalletReloaded(response)) {
-            return response.success;
-        }
-        throw new UnexpectedResponseError(response);
-    }
 }
 function getRandomId() {
     const randomValue = crypto.getRandomValues(new Uint8Array(16));