@arkade-os/sdk 0.3.7 → 0.3.9

package/dist/types/identity/index.d.ts

@@ -1,10 +1,12 @@
 import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
-export interface Identity {
+export interface Identity extends ReadonlyIdentity {
     signerSession(): SignerSession;
-    xOnlyPublicKey(): Promise<Uint8Array>;
-    compressedPublicKey(): Promise<Uint8Array>;
     signMessage(message: Uint8Array, signatureType: "schnorr" | "ecdsa"): Promise<Uint8Array>;
     sign(tx: Transaction, inputIndexes?: number[]): Promise<Transaction>;
 }
+export interface ReadonlyIdentity {
+    xOnlyPublicKey(): Promise<Uint8Array>;
+    compressedPublicKey(): Promise<Uint8Array>;
+}
 export * from "./singleKey";

package/dist/types/identity/singleKey.d.ts

@@ -1,4 +1,4 @@
-import { Identity } from ".";
+import { Identity, ReadonlyIdentity } from ".";
 import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
 /**
@@ -36,4 +36,23 @@ export declare class SingleKey implements Identity {
     xOnlyPublicKey(): Promise<Uint8Array>;
     signerSession(): SignerSession;
     signMessage(message: Uint8Array, signatureType?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    toReadonly(): Promise<ReadonlySingleKey>;
+}
+export declare class ReadonlySingleKey implements ReadonlyIdentity {
+    private readonly publicKey;
+    constructor(publicKey: Uint8Array);
+    /**
+     * 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: Uint8Array): ReadonlySingleKey;
+    xOnlyPublicKey(): Promise<Uint8Array>;
+    compressedPublicKey(): Promise<Uint8Array>;
 }

package/dist/types/index.d.ts

@@ -1,17 +1,18 @@
 import { Transaction } from "./utils/transaction";
-import { SingleKey } from "./identity/singleKey";
-import { Identity } from "./identity";
+import { SingleKey, ReadonlySingleKey } from "./identity/singleKey";
+import { Identity, ReadonlyIdentity } from "./identity";
 import { ArkAddress } from "./script/address";
 import { VHTLC } from "./script/vhtlc";
 import { DefaultVtxo } from "./script/default";
 import { VtxoScript, EncodedVtxoScript, TapLeafScript, TapTreeCoder } from "./script/base";
-import { TxType, IWallet, WalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, Recipient, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, GetVtxosFilter, TapLeaves } from "./wallet";
-import { Wallet, waitForIncomingFunds, IncomingFunds } from "./wallet/wallet";
+import { TxType, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, Recipient, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, GetVtxosFilter, TapLeaves, isSpendable, isSubdust, isRecoverable, isExpired } from "./wallet";
+import { Batch } from "./wallet/batch";
+import { Wallet, ReadonlyWallet, waitForIncomingFunds, IncomingFunds, getSequence } from "./wallet/wallet";
 import { TxTree, TxTreeNode } from "./tree/txTree";
 import { SignerSession, TreeNonces, TreePartialSigs } from "./tree/signingSession";
 import { Ramps } from "./wallet/ramps";
 import { isVtxoExpiringSoon, VtxoManager } from "./wallet/vtxo-manager";
-import { ServiceWorkerWallet } from "./wallet/serviceWorker/wallet";
+import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet } from "./wallet/serviceWorker/wallet";
 import { OnchainWallet } from "./wallet/onchain";
 import { setupServiceWorker } from "./wallet/serviceWorker/utils";
 import { Worker } from "./wallet/serviceWorker/worker";
@@ -25,7 +26,7 @@ import { VtxoTaprootTree, ConditionWitness, getArkPsbtFields, setArkPsbtField, A
 import { Intent } from "./intent";
 import { ArkNote } from "./arknote";
 import { networks, Network, NetworkName } from "./networks";
-import { RestIndexerProvider, IndexerProvider, IndexerTxType, ChainTxType, PageResponse, Batch, ChainTx, CommitmentTx, TxHistoryRecord, VtxoChain, Tx, Vtxo, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent } from "./providers/indexer";
+import { RestIndexerProvider, IndexerProvider, IndexerTxType, ChainTxType, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, VtxoChain, Tx, Vtxo, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent } from "./providers/indexer";
 import { Nonces } from "./musig2/nonces";
 import { PartialSig } from "./musig2/sign";
 import { AnchorBumper, P2A } from "./utils/anchor";
@@ -33,5 +34,7 @@ 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, combineTapscriptSigs, isVtxoExpiringSoon, 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, };
+import { validateVtxoTxGraph, validateConnectorsTxGraph } from "./tree/validation";
+import { buildForfeitTx } from "./forfeit";
+export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, OnchainWallet, Ramps, VtxoManager, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, Worker, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, Request, Response, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, ArkNote, networks, WalletRepositoryImpl, ContractRepositoryImpl, Intent, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, };
+export type { Identity, ReadonlyIdentity, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, Recipient, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, IndexerProvider, PageResponse, BatchInfo, 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/intent/index.d.ts

@@ -32,10 +32,27 @@ export declare namespace 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: string, inputs: TransactionInput[], outputs?: TransactionOutput[]): Proof;
+    function create(message: string | Message, inputs: TransactionInput[], outputs?: TransactionOutput[]): Proof;
+    type RegisterMessage = {
+        type: "register";
+        onchain_output_indexes: number[];
+        valid_at: number;
+        expire_at: number;
+        cosigners_public_keys: string[];
+    };
+    type DeleteMessage = {
+        type: "delete";
+        expire_at: number;
+    };
+    type GetPendingTxMessage = {
+        type: "get-pending-tx";
+        expire_at: number;
+    };
+    type Message = RegisterMessage | DeleteMessage | GetPendingTxMessage;
+    function encodeMessage(message: Message): string;
 }

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

@@ -1,6 +1,7 @@
 import { TxTreeNode } from "../tree/txTree";
 import { TreeNonces, TreePartialSigs } from "../tree/signingSession";
 import { Vtxo } from "./indexer";
+import { Intent } from "../intent";
 export type Output = {
     address: string;
     amount: bigint;
@@ -113,9 +114,9 @@ export interface ArkInfo {
     vtxoMaxAmount: bigint;
     vtxoMinAmount: bigint;
 }
-export interface SignedIntent {
+export interface SignedIntent<T extends Intent.Message> {
     proof: string;
-    message: string;
+    message: T;
 }
 export interface TxNotification {
     txid: string;
@@ -135,8 +136,8 @@ export interface ArkProvider {
         signedCheckpointTxs: string[];
     }>;
     finalizeTx(arkTxid: string, finalCheckpointTxs: string[]): Promise<void>;
-    registerIntent(intent: SignedIntent): Promise<string>;
-    deleteIntent(intent: SignedIntent): Promise<void>;
+    registerIntent(intent: SignedIntent<Intent.RegisterMessage>): Promise<string>;
+    deleteIntent(intent: SignedIntent<Intent.DeleteMessage>): Promise<void>;
     confirmRegistration(intentId: string): Promise<void>;
     submitTreeNonces(batchId: string, pubkey: string, nonces: TreeNonces): Promise<void>;
     submitTreeSignatures(batchId: string, pubkey: string, signatures: TreePartialSigs): Promise<void>;
@@ -146,7 +147,7 @@ export interface ArkProvider {
         commitmentTx?: TxNotification;
         arkTx?: TxNotification;
     }>;
-    getPendingTxs(intent: SignedIntent): Promise<PendingTx[]>;
+    getPendingTxs(intent: SignedIntent<Intent.GetPendingTxMessage>): Promise<PendingTx[]>;
 }
 /**
  * REST-based Ark provider implementation.
@@ -167,8 +168,8 @@ export declare class RestArkProvider implements ArkProvider {
         signedCheckpointTxs: string[];
     }>;
     finalizeTx(arkTxid: string, finalCheckpointTxs: string[]): Promise<void>;
-    registerIntent(intent: SignedIntent): Promise<string>;
-    deleteIntent(intent: SignedIntent): Promise<void>;
+    registerIntent(intent: SignedIntent<Intent.RegisterMessage>): Promise<string>;
+    deleteIntent(intent: SignedIntent<Intent.DeleteMessage>): Promise<void>;
     confirmRegistration(intentId: string): Promise<void>;
     submitTreeNonces(batchId: string, pubkey: string, nonces: TreeNonces): Promise<void>;
     submitTreeSignatures(batchId: string, pubkey: string, signatures: TreePartialSigs): Promise<void>;
@@ -178,7 +179,7 @@ export declare class RestArkProvider implements ArkProvider {
         commitmentTx?: TxNotification;
         arkTx?: TxNotification;
     }>;
-    getPendingTxs(intent: SignedIntent): Promise<PendingTx[]>;
+    getPendingTxs(intent: SignedIntent<Intent.GetPendingTxMessage>): Promise<PendingTx[]>;
     protected parseSettlementEvent(data: ProtoTypes.GetEventStreamResponse): SettlementEvent | null;
     protected parseTransactionNotification(data: ProtoTypes.GetTransactionsStreamResponse): {
         commitmentTx?: TxNotification;

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

@@ -20,7 +20,7 @@ export interface PageResponse {
     next: number;
     total: number;
 }
-export interface Batch {
+export interface BatchInfo {
     totalOutputAmount: string;
     totalOutputVtxos: number;
     expiresAt: string;
@@ -36,7 +36,7 @@ export interface CommitmentTx {
     startedAt: string;
     endedAt: string;
     batches: {
-        [key: string]: Batch;
+        [key: string]: BatchInfo;
     };
     totalInputAmount: string;
     totalInputVtxos: number;

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

@@ -0,0 +1,87 @@
+import type { BatchStartedEvent, BatchFinalizedEvent, BatchFailedEvent, TreeTxEvent, TreeSignatureEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchFinalizationEvent, SettlementEvent } from "../providers/ark";
+import { TxTree } from "../tree/txTree";
+/**
+ * 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 declare namespace Batch {
+    interface Handler {
+        /**
+         * Called on BatchStarted event.
+         * @returns { skip: boolean } indicating whether the batch should be skipped or not.
+         */
+        onBatchStarted(event: BatchStartedEvent): Promise<{
+            skip: boolean;
+        }>;
+        /**
+         * Called when tree signing starts.
+         * @param event The tree signing started event.
+         * @param vtxoTree The unsigned VTXO tree, reconstructed from the TreeTxEvent events.
+         * @returns Promise resolving to a boolean indicating whether to continue processing.
+         */
+        onTreeSigningStarted(event: TreeSigningStartedEvent, vtxoTree: TxTree): Promise<{
+            skip: boolean;
+        }>;
+        /**
+         * Called when tree nonces are received.
+         * @param event The tree nonces event.
+         * @returns Promise resolving to a boolean indicating whether signing is complete.
+         */
+        onTreeNonces(event: TreeNoncesEvent): Promise<{
+            fullySigned: boolean;
+        }>;
+        /**
+         * Called during batch finalization.
+         * @param event The batch finalization event.
+         * @param vtxoTree The signed VTXO tree, reconstructed from the TreeTxEvent events.
+         * @param connectorTree The connector transaction tree, reconstructed from the TreeTxEvent events.
+         */
+        onBatchFinalization(event: BatchFinalizationEvent, vtxoTree?: TxTree, connectorTree?: TxTree): Promise<void>;
+        onBatchFinalized?(event: BatchFinalizedEvent): Promise<void>;
+        onBatchFailed?(event: BatchFailedEvent): Promise<void>;
+        onTreeTxEvent?(event: TreeTxEvent): Promise<void>;
+        onTreeSignatureEvent?(event: TreeSignatureEvent): Promise<void>;
+    }
+    /**
+     * Options for the join function.
+     * @param @optional abortController - The abort controller to use to abort the operation.
+     * @param @optional skipVtxoTreeSigning - ignore events related to vtxo tree musig2 signing session.
+     * @param @optional eventCallback - A callback to be called for each event.
+     * @param eventCallback - A callback to be called for each event.
+     */
+    type JoinOptions = Partial<{
+        abortController: AbortController;
+        skipVtxoTreeSigning: boolean;
+        eventCallback: (event: SettlementEvent) => Promise<void>;
+    }>;
+    /**
+     * 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.
+     */
+    function join(eventIterator: AsyncIterableIterator<SettlementEvent>, handler: Handler, options?: JoinOptions): Promise<string>;
+}

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

@@ -1,6 +1,6 @@
 import { Bytes } from "@scure/btc-signer/utils.js";
 import { ArkProvider, Output, SettlementEvent } from "../providers/ark";
-import { Identity } from "../identity";
+import { Identity, ReadonlyIdentity } from "../identity";
 import { RelativeTimelock } from "../script/tapscript";
 import { EncodedVtxoScript, TapLeafScript } from "../script/base";
 import { StorageAdapter } from "../storage";
@@ -8,7 +8,7 @@ import { RenewalConfig } from "./vtxo-manager";
 import { IndexerProvider } from "../providers/indexer";
 import { OnchainProvider } from "../providers/onchain";
 /**
- * Configuration options for wallet initialization.
+ * Base configuration options shared by all wallet types.
  *
  * Supports two configuration modes:
  * 1. URL-based: Provide arkServerUrl, indexerUrl (optional), and esploraUrl
@@ -20,6 +20,54 @@ import { OnchainProvider } from "../providers/onchain";
  * The wallet will use provided URLs to create default providers if custom provider
  * instances are not supplied. If optional parameters are not provided, the wallet
  * will fetch configuration from the Ark server.
+ */
+export interface BaseWalletConfig {
+    arkServerUrl?: string;
+    indexerUrl?: string;
+    esploraUrl?: string;
+    arkServerPublicKey?: string;
+    boardingTimelock?: RelativeTimelock;
+    exitTimelock?: RelativeTimelock;
+    storage?: StorageAdapter;
+    arkProvider?: ArkProvider;
+    indexerProvider?: IndexerProvider;
+    onchainProvider?: OnchainProvider;
+}
+/**
+ * Configuration options for readonly wallet initialization.
+ *
+ * Use this config when you only need to query wallet state (balance, addresses, transactions)
+ * without the ability to send transactions. This is useful for:
+ * - Watch-only wallets
+ * - Monitoring addresses
+ * - Safe sharing of wallet state without private key exposure
+ *
+ * @example
+ * ```typescript
+ * // URL-based configuration
+ * const wallet = await ReadonlyWallet.create({
+ *   identity: ReadonlySingleKey.fromPublicKey(pubkey),
+ *   arkServerUrl: 'https://ark.example.com',
+ *   esploraUrl: 'https://mempool.space/api'
+ * });
+ *
+ * // Provider-based configuration (e.g., for Expo/React Native)
+ * const wallet = await ReadonlyWallet.create({
+ *   identity: ReadonlySingleKey.fromPublicKey(pubkey),
+ *   arkProvider: new ExpoArkProvider('https://ark.example.com'),
+ *   indexerProvider: new ExpoIndexerProvider('https://ark.example.com'),
+ *   onchainProvider: new EsploraProvider('https://mempool.space/api')
+ * });
+ * ```
+ */
+export interface ReadonlyWalletConfig extends BaseWalletConfig {
+    identity: ReadonlyIdentity;
+}
+/**
+ * Configuration options for full wallet initialization.
+ *
+ * This config provides full wallet capabilities including sending transactions,
+ * settling VTXOs, and all readonly operations.
  *
  * @example
  * ```typescript
@@ -37,20 +85,20 @@ import { OnchainProvider } from "../providers/onchain";
  *   indexerProvider: new ExpoIndexerProvider('https://ark.example.com'),
  *   onchainProvider: new EsploraProvider('https://mempool.space/api')
  * });
+ *
+ * // With renewal configuration
+ * const wallet = await Wallet.create({
+ *   identity: SingleKey.fromHex('...'),
+ *   arkServerUrl: 'https://ark.example.com',
+ *   renewalConfig: {
+ *     enabled: true,
+ *     thresholdMs: 86400000, // 24 hours
+ *   }
+ * });
  * ```
  */
-export interface WalletConfig {
+export interface WalletConfig extends ReadonlyWalletConfig {
     identity: Identity;
-    arkServerUrl?: string;
-    indexerUrl?: string;
-    esploraUrl?: string;
-    arkServerPublicKey?: string;
-    boardingTimelock?: RelativeTimelock;
-    exitTimelock?: RelativeTimelock;
-    storage?: StorageAdapter;
-    arkProvider?: ArkProvider;
-    indexerProvider?: IndexerProvider;
-    onchainProvider?: OnchainProvider;
     renewalConfig?: RenewalConfig;
 }
 /**
@@ -142,6 +190,7 @@ export type ExtendedVirtualCoin = TapLeaves & EncodedVtxoScript & VirtualCoin &
 };
 export declare function isSpendable(vtxo: VirtualCoin): boolean;
 export declare function isRecoverable(vtxo: VirtualCoin): boolean;
+export declare function isExpired(vtxo: VirtualCoin): boolean;
 export declare function isSubdust(vtxo: VirtualCoin, dust: bigint): boolean;
 export type GetVtxosFilter = {
     withRecoverable?: boolean;
@@ -154,14 +203,24 @@ export type GetVtxosFilter = {
  * It provides methods for address management, balance checking, virtual UTXO
  * operations, and transaction management including sending, settling, and unrolling.
  */
-export interface IWallet {
+export interface IWallet extends IReadonlyWallet {
     identity: Identity;
+    sendBitcoin(params: SendBitcoinParams): Promise<string>;
+    settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
+}
+/**
+ * Readonly wallet interface for Bitcoin transactions with Ark protocol support.
+ *
+ * This interface defines the contract that all wallet implementations must follow.
+ * It provides methods for address management, balance checking, virtual UTXO
+ * operations, and transaction management including sending, settling, and unrolling.
+ */
+export interface IReadonlyWallet {
+    identity: ReadonlyIdentity;
     getAddress(): Promise<string>;
     getBoardingAddress(): Promise<string>;
     getBalance(): Promise<WalletBalance>;
     getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
     getTransactionHistory(): Promise<ArkTransaction[]>;
-    sendBitcoin(params: SendBitcoinParams): Promise<string>;
-    settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
 }

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

@@ -11,7 +11,11 @@ export declare namespace Request {
     function isBase(message: unknown): message is Base;
     interface InitWallet extends Base {
         type: "INIT_WALLET";
-        privateKey: string;
+        key: {
+            privateKey: string;
+        } | {
+            publicKey: string;
+        };
         arkServerUrl: string;
         arkServerPublicKey?: string;
     }

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

@@ -1,10 +1,11 @@
-import { IWallet, WalletBalance, SendBitcoinParams, SettleParams, ArkTransaction, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter } from "..";
+import { IWallet, WalletBalance, SendBitcoinParams, SettleParams, ArkTransaction, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IReadonlyWallet } from "..";
+import { Request } from "./request";
 import { Response } from "./response";
 import { SettlementEvent } from "../../providers/ark";
-import { Identity } from "../../identity";
+import { Identity, ReadonlyIdentity } from "../../identity";
 import { WalletRepository } from "../../repositories/walletRepository";
 import { ContractRepository } from "../../repositories/contractRepository";
-export type PrivateKeyIdentity = Identity & {
+type PrivateKeyIdentity = Identity & {
     toHex(): string;
 };
 /**
@@ -45,7 +46,7 @@ interface ServiceWorkerWalletOptions {
     esploraUrl?: string;
     dbName?: string;
     dbVersion?: number;
-    identity: PrivateKeyIdentity;
+    identity: ReadonlyIdentity | Identity;
 }
 export type ServiceWorkerWalletCreateOptions = ServiceWorkerWalletOptions & {
     serviceWorker: ServiceWorker;
@@ -53,13 +54,13 @@ export type ServiceWorkerWalletCreateOptions = ServiceWorkerWalletOptions & {
 export type ServiceWorkerWalletSetupOptions = ServiceWorkerWalletOptions & {
     serviceWorkerPath: string;
 };
-export declare class ServiceWorkerWallet implements IWallet {
+export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
     readonly serviceWorker: ServiceWorker;
     readonly walletRepository: WalletRepository;
     readonly contractRepository: ContractRepository;
-    readonly identity: Identity;
-    private constructor();
-    static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerWallet>;
+    readonly identity: ReadonlyIdentity;
+    protected constructor(serviceWorker: ServiceWorker, identity: ReadonlyIdentity, walletRepository: WalletRepository, contractRepository: ContractRepository);
+    static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerReadonlyWallet>;
     /**
      * Simplified setup method that handles service worker registration,
      * identity creation, and wallet initialization automatically.
@@ -67,22 +68,22 @@ export declare class ServiceWorkerWallet implements IWallet {
      * @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
      * });
      * ```
      */
-    static setup(options: ServiceWorkerWalletSetupOptions): Promise<ServiceWorkerWallet>;
-    private sendMessage;
+    static setup(options: ServiceWorkerWalletSetupOptions): Promise<ServiceWorkerReadonlyWallet>;
+    protected sendMessage<T extends Request.Base>(message: T): Promise<Response.Base>;
     clear(): Promise<void>;
     getAddress(): Promise<string>;
     getBoardingAddress(): Promise<string>;
@@ -91,8 +92,38 @@ export declare class ServiceWorkerWallet implements IWallet {
     getStatus(): Promise<Response.WalletStatus["status"]>;
     getTransactionHistory(): Promise<ArkTransaction[]>;
     getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
+    reload(): Promise<boolean>;
+}
+export declare class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet implements IWallet {
+    readonly serviceWorker: ServiceWorker;
+    readonly walletRepository: WalletRepository;
+    readonly contractRepository: ContractRepository;
+    readonly identity: Identity;
+    protected constructor(serviceWorker: ServiceWorker, identity: PrivateKeyIdentity, walletRepository: WalletRepository, contractRepository: ContractRepository);
+    static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerWallet>;
+    /**
+     * 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 setup(options: ServiceWorkerWalletSetupOptions): Promise<ServiceWorkerWallet>;
     sendBitcoin(params: SendBitcoinParams): Promise<string>;
     settle(params?: SettleParams, callback?: (event: SettlementEvent) => void): Promise<string>;
-    reload(): Promise<boolean>;
 }
 export {};

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

@@ -1,12 +1,15 @@
 /**
- * Worker is a class letting to interact with ServiceWorkerWallet from the client
- * it aims to be run in a service worker context
+ * Worker is a class letting to interact with ServiceWorkerWallet and ServiceWorkerReadonlyWallet from
+ * the client; it aims to be run in a service worker context.
+ *
+ * The messages requiring a Wallet rather than a ReadonlyWallet result in no-op
+ * without errors.
  */
 export declare class Worker {
     readonly dbName: string;
     readonly dbVersion: number;
     private readonly messageCallback;
-    private wallet;
+    private handler;
     private arkProvider;
     private indexerProvider;
     private incomingFundsSubscription;

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

@@ -1,3 +1,8 @@
-import type { Coin, ExtendedCoin, ExtendedVirtualCoin, VirtualCoin, Wallet } from "..";
-export declare function extendVirtualCoin(wallet: Wallet, vtxo: VirtualCoin): ExtendedVirtualCoin;
-export declare function extendCoin(wallet: Wallet, utxo: Coin): ExtendedCoin;
+import type { Coin, ExtendedCoin, ExtendedVirtualCoin, VirtualCoin } from "..";
+import { ReadonlyWallet } from "./wallet";
+export declare function extendVirtualCoin(wallet: {
+    offchainTapscript: ReadonlyWallet["offchainTapscript"];
+}, vtxo: VirtualCoin): ExtendedVirtualCoin;
+export declare function extendCoin(wallet: {
+    boardingTapscript: ReadonlyWallet["boardingTapscript"];
+}, utxo: Coin): ExtendedCoin;