@arkade-os/sdk 0.4.26 → 0.4.28

package/dist/esm/wallet/serviceWorker/wallet-message-handler.js

@@ -1,946 +0,0 @@
-import { RestIndexerProvider } from "../../providers/indexer.js";
-import { isExpired, isRecoverable, isSpendable, isSubdust, } from "../index.js";
-import { extendCoin } from "../utils.js";
-import { buildTransactionHistory } from "../../utils/transactionHistory.js";
-import { filterVtxosForScript, getVtxosForContract, saveVtxosForContract, warnAndFilterVtxosForScript, } from "../../contracts/vtxoOwnership.js";
-import { scriptFromArkAddress } from "../../repositories/scriptFromAddress.js";
-export class WalletNotInitializedError extends Error {
-    constructor() {
-        super("Wallet handler not initialized");
-        this.name = "WalletNotInitializedError";
-    }
-}
-export class ReadonlyWalletError extends Error {
-    constructor() {
-        super("Read-only wallet: operation requires signing");
-        this.name = "ReadonlyWalletError";
-    }
-}
-export class DelegatorNotConfiguredError extends Error {
-    constructor() {
-        super("Delegator not configured");
-        this.name = "DelegatorNotConfiguredError";
-    }
-}
-export const DEFAULT_MESSAGE_TAG = "WALLET_UPDATER";
-export class WalletMessageHandler {
-    /**
-     * Instantiate a new WalletUpdater.
-     * Can override the default `messageTag` allowing more than one updater to run in parallel.
-     * Note that the default ServiceWorkerWallet sends messages to the default WalletUpdater tag.
-     */
-    constructor(options) {
-        this.onNextTick = [];
-        this.messageTag = options?.messageTag ?? DEFAULT_MESSAGE_TAG;
-    }
-    // lifecycle methods
-    async start(...params) {
-        const [services, repositories] = params;
-        this.readonlyWallet = services.readonlyWallet;
-        this.wallet = services.wallet;
-        this.arkProvider = services.arkProvider;
-        this.walletRepository = repositories.walletRepository;
-    }
-    async stop() {
-        if (this.incomingFundsSubscription) {
-            this.incomingFundsSubscription();
-            this.incomingFundsSubscription = undefined;
-        }
-        if (this.contractEventsSubscription) {
-            this.contractEventsSubscription();
-            this.contractEventsSubscription = undefined;
-        }
-        // Dispose the wallet to stop VtxoManager background tasks
-        // (auto-renewal, boarding input polling) and ContractWatcher.
-        try {
-            if (this.wallet) {
-                await this.wallet.dispose();
-            }
-            else if (this.readonlyWallet) {
-                await this.readonlyWallet.dispose();
-            }
-        }
-        catch (_) {
-            // best-effort teardown
-        }
-        this.wallet = undefined;
-        this.readonlyWallet = undefined;
-        this.arkProvider = undefined;
-        this.indexerProvider = undefined;
-    }
-    async tick(_now) {
-        const results = await Promise.allSettled(this.onNextTick.map((fn) => fn()));
-        this.onNextTick = [];
-        return results
-            .map((result) => {
-            if (result.status === "fulfilled") {
-                return result.value;
-            }
-            else {
-                console.error(`[${this.messageTag}] tick failed`, result.reason);
-                // TODO: how to deliver errors down the stream? a broadcast?
-                return null;
-            }
-        })
-            .filter((response) => response !== null);
-    }
-    scheduleForNextTick(callback) {
-        this.onNextTick.push(callback);
-    }
-    requireWallet() {
-        if (!this.wallet) {
-            throw new ReadonlyWalletError();
-        }
-        return this.wallet;
-    }
-    tagged(res) {
-        return {
-            ...res,
-            tag: this.messageTag,
-        };
-    }
-    // Flows that surrender control to the Ark server and the other participants
-    // in a batch round: quiet gaps between protocol events can easily exceed
-    // the bus-level messageTimeoutMs. Liveness is covered out-of-band by the
-    // page-side PING / MESSAGE_BUS_NOT_INITIALIZED path triggered by concurrent
-    // short requests (GET_STATUS, GET_BALANCE, ...).
-    isLongRunning(message) {
-        return (message.type === "SETTLE" ||
-            message.type === "RECOVER_VTXOS" ||
-            message.type === "RENEW_VTXOS");
-    }
-    async handleMessage(message) {
-        const id = message.id;
-        if (message.type === "INIT_WALLET") {
-            await this.handleInitWallet(message);
-            return this.tagged({
-                id,
-                type: "WALLET_INITIALIZED",
-            });
-        }
-        if (!this.readonlyWallet) {
-            return this.tagged({
-                id,
-                error: new WalletNotInitializedError(),
-            });
-        }
-        try {
-            switch (message.type) {
-                case "SETTLE": {
-                    const response = await this.handleSettle(message);
-                    return this.tagged({
-                        id,
-                        ...response,
-                    });
-                }
-                case "SEND_BITCOIN": {
-                    const response = await this.handleSendBitcoin(message);
-                    return this.tagged({
-                        id,
-                        ...response,
-                    });
-                }
-                case "GET_ADDRESS": {
-                    const address = await this.readonlyWallet.getAddress();
-                    return this.tagged({
-                        id,
-                        type: "ADDRESS",
-                        payload: { address },
-                    });
-                }
-                case "GET_BOARDING_ADDRESS": {
-                    const address = await this.readonlyWallet.getBoardingAddress();
-                    return this.tagged({
-                        id,
-                        type: "BOARDING_ADDRESS",
-                        payload: { address },
-                    });
-                }
-                case "GET_BALANCE": {
-                    const balance = await this.handleGetBalance();
-                    return this.tagged({
-                        id,
-                        type: "BALANCE",
-                        payload: balance,
-                    });
-                }
-                case "GET_VTXOS": {
-                    const vtxos = await this.handleGetVtxos(message);
-                    return {
-                        tag: this.messageTag,
-                        id,
-                        type: "VTXOS",
-                        payload: { vtxos },
-                    };
-                }
-                case "GET_BOARDING_UTXOS": {
-                    const utxos = await this.getAllBoardingUtxos();
-                    return this.tagged({
-                        id,
-                        type: "BOARDING_UTXOS",
-                        payload: { utxos },
-                    });
-                }
-                case "GET_TRANSACTION_HISTORY": {
-                    const allVtxos = await this.getVtxosFromRepo();
-                    const transactions = (await this.buildTransactionHistoryFromCache(allVtxos)) ?? [];
-                    return this.tagged({
-                        id,
-                        type: "TRANSACTION_HISTORY",
-                        payload: { transactions },
-                    });
-                }
-                case "GET_STATUS": {
-                    const pubKey = await this.readonlyWallet.identity.xOnlyPublicKey();
-                    return this.tagged({
-                        id,
-                        type: "WALLET_STATUS",
-                        payload: {
-                            walletInitialized: true,
-                            xOnlyPublicKey: pubKey,
-                        },
-                    });
-                }
-                case "CLEAR": {
-                    await this.clear();
-                    return this.tagged({
-                        id,
-                        type: "CLEAR_SUCCESS",
-                        payload: { cleared: true },
-                    });
-                }
-                case "RELOAD_WALLET": {
-                    await this.reloadWallet();
-                    return this.tagged({
-                        id,
-                        type: "RELOAD_SUCCESS",
-                        payload: { reloaded: true },
-                    });
-                }
-                case "SIGN_TRANSACTION": {
-                    const response = await this.handleSignTransaction(message);
-                    return this.tagged({
-                        id,
-                        ...response,
-                    });
-                }
-                case "CREATE_CONTRACT": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const contract = await manager.createContract(message.payload);
-                    return this.tagged({
-                        id,
-                        type: "CONTRACT_CREATED",
-                        payload: { contract },
-                    });
-                }
-                case "GET_CONTRACTS": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const contracts = await manager.getContracts(message.payload.filter);
-                    return this.tagged({
-                        id,
-                        type: "CONTRACTS",
-                        payload: { contracts },
-                    });
-                }
-                case "GET_CONTRACTS_WITH_VTXOS": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const contracts = await manager.getContractsWithVtxos(message.payload.filter);
-                    return this.tagged({
-                        id,
-                        type: "CONTRACTS_WITH_VTXOS",
-                        payload: { contracts },
-                    });
-                }
-                case "ANNOTATE_VTXOS": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const annotated = await manager.annotateVtxos(message.payload.vtxos);
-                    return this.tagged({
-                        id,
-                        type: "ANNOTATED_VTXOS",
-                        payload: { vtxos: annotated },
-                    });
-                }
-                case "UPDATE_CONTRACT": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const contract = await manager.updateContract(message.payload.script, message.payload.updates);
-                    return this.tagged({
-                        id,
-                        type: "CONTRACT_UPDATED",
-                        payload: { contract },
-                    });
-                }
-                case "DELETE_CONTRACT": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    await manager.deleteContract(message.payload.script);
-                    return this.tagged({
-                        id,
-                        type: "CONTRACT_DELETED",
-                        payload: { deleted: true },
-                    });
-                }
-                case "GET_SPENDABLE_PATHS": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const paths = await manager.getSpendablePaths(message.payload.options);
-                    return this.tagged({
-                        id,
-                        type: "SPENDABLE_PATHS",
-                        payload: { paths },
-                    });
-                }
-                case "GET_ALL_SPENDING_PATHS": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const paths = await manager.getAllSpendingPaths(message.payload.options);
-                    return this.tagged({
-                        id,
-                        type: "ALL_SPENDING_PATHS",
-                        payload: { paths },
-                    });
-                }
-                case "IS_CONTRACT_MANAGER_WATCHING": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const isWatching = await manager.isWatching();
-                    return this.tagged({
-                        id,
-                        type: "CONTRACT_WATCHING",
-                        payload: { isWatching },
-                    });
-                }
-                case "REFRESH_VTXOS": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    await manager.refreshVtxos(message.payload);
-                    return this.tagged({
-                        id,
-                        type: "REFRESH_VTXOS_SUCCESS",
-                    });
-                }
-                case "REFRESH_OUTPOINTS": {
-                    const manager = await this.readonlyWallet.getContractManager();
-                    const { outpoints } = message
-                        .payload;
-                    await manager.refreshOutpoints(outpoints);
-                    return this.tagged({
-                        id,
-                        type: "REFRESH_OUTPOINTS_SUCCESS",
-                    });
-                }
-                case "SEND": {
-                    const { recipients } = message.payload;
-                    const txid = await this.wallet.send(...recipients);
-                    return this.tagged({
-                        id,
-                        type: "SEND_SUCCESS",
-                        payload: { txid },
-                    });
-                }
-                case "GET_ASSET_DETAILS": {
-                    const { assetId } = message
-                        .payload;
-                    const assetDetails = await this.readonlyWallet.assetManager.getAssetDetails(assetId);
-                    return this.tagged({
-                        id,
-                        type: "ASSET_DETAILS",
-                        payload: { assetDetails },
-                    });
-                }
-                case "ISSUE": {
-                    const { params } = message.payload;
-                    const result = await this.wallet.assetManager.issue(params);
-                    return this.tagged({
-                        id,
-                        type: "ISSUE_SUCCESS",
-                        payload: { result },
-                    });
-                }
-                case "REISSUE": {
-                    const { params } = message.payload;
-                    const txid = await this.wallet.assetManager.reissue(params);
-                    return this.tagged({
-                        id,
-                        type: "REISSUE_SUCCESS",
-                        payload: { txid },
-                    });
-                }
-                case "BURN": {
-                    const { params } = message.payload;
-                    const txid = await this.wallet.assetManager.burn(params);
-                    return this.tagged({
-                        id,
-                        type: "BURN_SUCCESS",
-                        payload: { txid },
-                    });
-                }
-                case "DELEGATE": {
-                    const response = await this.handleDelegate(message);
-                    return this.tagged({ id, ...response });
-                }
-                case "GET_DELEGATE_INFO": {
-                    const wallet = this.requireWallet();
-                    const delegatorManager = await wallet.getDelegatorManager();
-                    if (!delegatorManager) {
-                        throw new DelegatorNotConfiguredError();
-                    }
-                    const info = await delegatorManager.getDelegateInfo();
-                    return this.tagged({
-                        id,
-                        type: "DELEGATE_INFO",
-                        payload: { info },
-                    });
-                }
-                case "RECOVER_VTXOS": {
-                    const wallet = this.requireWallet();
-                    const vtxoManager = await wallet.getVtxoManager();
-                    const txid = await vtxoManager.recoverVtxos((e) => {
-                        this.scheduleForNextTick(() => this.tagged({
-                            id,
-                            type: "RECOVER_VTXOS_EVENT",
-                            payload: e,
-                        }));
-                    });
-                    return this.tagged({
-                        id,
-                        type: "RECOVER_VTXOS_SUCCESS",
-                        payload: { txid },
-                    });
-                }
-                case "GET_RECOVERABLE_BALANCE": {
-                    const wallet = this.requireWallet();
-                    const vtxoManager = await wallet.getVtxoManager();
-                    const balance = await vtxoManager.getRecoverableBalance();
-                    return this.tagged({
-                        id,
-                        type: "RECOVERABLE_BALANCE",
-                        payload: {
-                            recoverable: balance.recoverable.toString(),
-                            subdust: balance.subdust.toString(),
-                            includesSubdust: balance.includesSubdust,
-                            vtxoCount: balance.vtxoCount,
-                        },
-                    });
-                }
-                case "GET_EXPIRING_VTXOS": {
-                    const wallet = this.requireWallet();
-                    const vtxoManager = await wallet.getVtxoManager();
-                    const vtxos = await vtxoManager.getExpiringVtxos(message.payload.thresholdMs);
-                    return this.tagged({
-                        id,
-                        type: "EXPIRING_VTXOS",
-                        payload: { vtxos },
-                    });
-                }
-                case "RENEW_VTXOS": {
-                    const wallet = this.requireWallet();
-                    const vtxoManager = await wallet.getVtxoManager();
-                    const txid = await vtxoManager.renewVtxos((e) => {
-                        this.scheduleForNextTick(() => this.tagged({
-                            id,
-                            type: "RENEW_VTXOS_EVENT",
-                            payload: e,
-                        }));
-                    });
-                    return this.tagged({
-                        id,
-                        type: "RENEW_VTXOS_SUCCESS",
-                        payload: { txid },
-                    });
-                }
-                case "GET_EXPIRED_BOARDING_UTXOS": {
-                    const wallet = this.requireWallet();
-                    const vtxoManager = await wallet.getVtxoManager();
-                    const utxos = await vtxoManager.getExpiredBoardingUtxos();
-                    return this.tagged({
-                        id,
-                        type: "EXPIRED_BOARDING_UTXOS",
-                        payload: { utxos },
-                    });
-                }
-                case "SWEEP_EXPIRED_BOARDING_UTXOS": {
-                    const wallet = this.requireWallet();
-                    const vtxoManager = await wallet.getVtxoManager();
-                    const txid = await vtxoManager.sweepExpiredBoardingUtxos();
-                    return this.tagged({
-                        id,
-                        type: "SWEEP_EXPIRED_BOARDING_UTXOS_SUCCESS",
-                        payload: { txid },
-                    });
-                }
-                default:
-                    console.error("Unknown message type", message);
-                    throw new Error("Unknown message");
-            }
-        }
-        catch (error) {
-            return this.tagged({ id, error: error });
-        }
-    }
-    // Wallet methods
-    async handleInitWallet({ payload }) {
-        const { arkServerUrl } = payload;
-        this.indexerProvider = new RestIndexerProvider(arkServerUrl);
-        await this.onWalletInitialized();
-    }
-    async handleGetBalance() {
-        const [boardingUtxos, allVtxos] = await Promise.all([
-            this.getAllBoardingUtxos(),
-            this.getVtxosFromRepo(),
-        ]);
-        // boarding
-        let confirmed = 0;
-        let unconfirmed = 0;
-        for (const utxo of boardingUtxos) {
-            if (utxo.status.confirmed) {
-                confirmed += utxo.value;
-            }
-            else {
-                unconfirmed += utxo.value;
-            }
-        }
-        // offchain — split spendable vs swept from single repo read
-        const spendableVtxos = allVtxos.filter(isSpendable);
-        const sweptVtxos = allVtxos.filter((vtxo) => vtxo.virtualStatus.state === "swept");
-        let settled = 0;
-        let preconfirmed = 0;
-        let recoverable = 0;
-        for (const vtxo of spendableVtxos) {
-            if (vtxo.virtualStatus.state === "settled") {
-                settled += vtxo.value;
-            }
-            else if (vtxo.virtualStatus.state === "preconfirmed") {
-                preconfirmed += vtxo.value;
-            }
-        }
-        for (const vtxo of sweptVtxos) {
-            if (isSpendable(vtxo)) {
-                recoverable += vtxo.value;
-            }
-        }
-        const totalBoarding = confirmed + unconfirmed;
-        const totalOffchain = settled + preconfirmed + recoverable;
-        // aggregate asset balances from spendable virtual outputs
-        const assetBalances = new Map();
-        for (const vtxo of spendableVtxos) {
-            if (vtxo.assets) {
-                for (const a of vtxo.assets) {
-                    const current = assetBalances.get(a.assetId) ?? 0n;
-                    assetBalances.set(a.assetId, current + a.amount);
-                }
-            }
-        }
-        const assets = Array.from(assetBalances.entries()).map(([assetId, amount]) => ({ assetId, amount }));
-        return {
-            boarding: {
-                confirmed,
-                unconfirmed,
-                total: totalBoarding,
-            },
-            settled,
-            preconfirmed,
-            available: settled + preconfirmed,
-            recoverable,
-            total: totalBoarding + totalOffchain,
-            assets,
-        };
-    }
-    async getAllBoardingUtxos() {
-        if (!this.readonlyWallet)
-            return [];
-        return this.readonlyWallet.getBoardingUtxos();
-    }
-    /**
-     * Get spendable vtxos from the repository
-     */
-    async getSpendableVtxos() {
-        const vtxos = await this.getVtxosFromRepo();
-        return vtxos.filter(isSpendable);
-    }
-    async onWalletInitialized() {
-        if (!this.readonlyWallet ||
-            !this.arkProvider ||
-            !this.indexerProvider ||
-            !this.walletRepository) {
-            return;
-        }
-        // Initialize contract manager FIRST — this populates the repository
-        // with full virtual output history for all contracts (one indexer call per contract)
-        await this.ensureContractEventBroadcasting();
-        // Refresh cached data (virtual outputs, boarding inputs, tx history)
-        await this.refreshCachedData();
-        // Recover pending transactions (init-only, not on reload).
-        // Pending txs only exist if a send was interrupted mid-finalization.
-        if (this.wallet) {
-            try {
-                const vtxos = await this.getVtxosFromRepo();
-                const { pending, finalized } = await this.wallet.finalizePendingTxs(vtxos.filter((vtxo) => vtxo.virtualStatus.state !== "swept" &&
-                    vtxo.virtualStatus.state !== "settled"));
-                console.info(`Recovered ${finalized.length}/${pending.length} pending transactions: ${finalized.join(", ")}`);
-            }
-            catch (error) {
-                console.error("Error recovering pending transactions:", error);
-            }
-        }
-        // unsubscribe previous subscription if any
-        if (this.incomingFundsSubscription)
-            this.incomingFundsSubscription();
-        const address = await this.readonlyWallet.getAddress();
-        // subscribe for incoming funds and notify all clients when new funds arrive
-        this.incomingFundsSubscription =
-            await this.readonlyWallet.notifyIncomingFunds(async (funds) => {
-                if (funds.type === "vtxo") {
-                    // `funds.newVtxos` / `funds.spentVtxos` are already
-                    // ExtendedVirtualCoin — annotation happened inside the
-                    // underlying Wallet's subscription handler before this
-                    // callback fired. Re-annotating here would only duplicate
-                    // work and re-expose us to `annotateVtxos` throws.
-                    const { newVtxos, spentVtxos } = funds;
-                    if (newVtxos.length + spentVtxos.length === 0)
-                        return;
-                    // Save virtual outputs using unified repository. The
-                    // event may carry rows for several scripts (other
-                    // contracts the wallet watches), so split by script and
-                    // save each bucket under its own contract address rather
-                    // than saving a mixed-script array under one address.
-                    const byScript = new Map();
-                    for (const v of [...newVtxos, ...spentVtxos]) {
-                        if (!v.script) {
-                            // Without a script we can't route the row to the
-                            // right contract bucket; surface the drop instead
-                            // of silently losing the VTXO.
-                            console.warn(`WalletMessageHandler.notifyIncomingFunds: dropping VTXO without script ${v.txid}:${v.vout}`);
-                            continue;
-                        }
-                        const arr = byScript.get(v.script) ?? [];
-                        arr.push(v);
-                        byScript.set(v.script, arr);
-                    }
-                    let walletScript;
-                    try {
-                        walletScript = scriptFromArkAddress(address);
-                    }
-                    catch {
-                        walletScript = undefined;
-                    }
-                    const cm = await this.readonlyWallet.getContractManager();
-                    const contracts = await cm.getContracts();
-                    const addrByScript = new Map(contracts.map((c) => [c.script, c.address]));
-                    for (const [script, vtxos] of byScript) {
-                        const filtered = warnAndFilterVtxosForScript(vtxos, script, "WalletMessageHandler.notifyIncomingFunds");
-                        if (filtered.length === 0)
-                            continue;
-                        const targetAddress = script === walletScript
-                            ? address
-                            : addrByScript.get(script);
-                        if (!targetAddress)
-                            continue;
-                        if (this.walletRepository) {
-                            await saveVtxosForContract(this.walletRepository, { script, address: targetAddress }, filtered);
-                        }
-                    }
-                    // notify all clients about the virtual output state update
-                    this.scheduleForNextTick(() => this.tagged({
-                        type: "VTXO_UPDATE",
-                        broadcast: true,
-                        payload: { newVtxos, spentVtxos },
-                    }));
-                }
-                if (funds.type === "utxo") {
-                    const utxos = funds.coins.map((utxo) => extendCoin(this.readonlyWallet, utxo));
-                    const boardingAddress = await this.readonlyWallet.getBoardingAddress();
-                    // save boarding inputs using unified repository
-                    // TODO: remove UTXOs by address
-                    //  await this.walletRepository.clearUtxos(boardingAddress);
-                    await this.walletRepository?.saveUtxos(boardingAddress, utxos);
-                    // notify all clients about the boarding input state update
-                    this.scheduleForNextTick(() => this.tagged({
-                        type: "UTXO_UPDATE",
-                        broadcast: true,
-                        payload: { coins: utxos },
-                    }));
-                }
-            });
-        // Eagerly start the VtxoManager so its background tasks (auto-renewal,
-        // boarding input polling/sweep) run inside the service worker without
-        // waiting for a client to send a VtxoManager message first.
-        if (this.wallet) {
-            try {
-                await this.wallet.getVtxoManager();
-            }
-            catch (error) {
-                console.error("Error starting VtxoManager:", error);
-            }
-        }
-    }
-    /**
-     * Refresh virtual outputs, boarding inputs, and transaction history from cache.
-     * Shared by onWalletInitialized (full bootstrap) and reloadWallet
-     * (post-refresh), avoiding duplicate subscriptions and VtxoManager restarts.
-     */
-    async refreshCachedData() {
-        if (!this.readonlyWallet || !this.walletRepository) {
-            return;
-        }
-        // Read virtual outputs from repository (now populated by contract manager)
-        const vtxos = await this.getVtxosFromRepo();
-        // Fetch boarding inputs and save using unified repository
-        const boardingAddress = await this.readonlyWallet.getBoardingAddress();
-        const coins = await this.readonlyWallet.onchainProvider.getCoins(boardingAddress);
-        await this.walletRepository.deleteUtxos(boardingAddress);
-        await this.walletRepository.saveUtxos(boardingAddress, coins.map((utxo) => extendCoin(this.readonlyWallet, utxo)));
-        // Build transaction history from cached virtual outputs (no indexer call)
-        const address = await this.readonlyWallet.getAddress();
-        const txs = await this.buildTransactionHistoryFromCache(vtxos);
-        if (txs)
-            await this.walletRepository.saveTransactions(address, txs);
-    }
-    /**
-     * Force a full VTXO refresh from the indexer, then refresh cached data.
-     * Used by RELOAD_WALLET to ensure fresh data without re-subscribing
-     * to incoming funds or restarting the VtxoManager.
-     */
-    async reloadWallet() {
-        if (!this.readonlyWallet)
-            return;
-        const manager = await this.readonlyWallet.getContractManager();
-        await manager.refreshVtxos();
-        await this.refreshCachedData();
-    }
-    async handleSettle(message) {
-        const wallet = this.requireWallet();
-        const txid = await wallet.settle(message.payload.params, (e) => {
-            this.scheduleForNextTick(() => this.tagged({
-                id: message.id,
-                type: "SETTLE_EVENT",
-                payload: e,
-            }));
-        });
-        if (!txid) {
-            throw new Error("Settlement failed");
-        }
-        return { type: "SETTLE_SUCCESS", payload: { txid } };
-    }
-    async handleSendBitcoin(message) {
-        const wallet = this.requireWallet();
-        const txid = await wallet.sendBitcoin(message.payload);
-        if (!txid) {
-            throw new Error("Send bitcoin failed");
-        }
-        return {
-            type: "SEND_BITCOIN_SUCCESS",
-            payload: { txid },
-        };
-    }
-    async handleSignTransaction(message) {
-        const wallet = this.requireWallet();
-        const { tx, inputIndexes } = message.payload;
-        const signature = await wallet.identity.sign(tx, inputIndexes);
-        if (!signature) {
-            throw new Error("Sign transaction failed");
-        }
-        return {
-            type: "SIGN_TRANSACTION",
-            payload: { tx: signature },
-        };
-    }
-    async handleDelegate(message) {
-        const wallet = this.requireWallet();
-        const delegatorManager = await wallet.getDelegatorManager();
-        if (!delegatorManager) {
-            throw new DelegatorNotConfiguredError();
-        }
-        const { vtxoOutpoints, destination, delegateAt } = message.payload;
-        const allVtxos = await wallet.getVtxos();
-        const outpointSet = new Set(vtxoOutpoints.map((o) => `${o.txid}:${o.vout}`));
-        const filtered = allVtxos
-            .filter((v) => outpointSet.has(`${v.txid}:${v.vout}`))
-            .map((v) => ({ ...v, contractScript: v.script }));
-        const result = await delegatorManager.delegate(filtered, destination, delegateAt !== undefined ? new Date(delegateAt) : undefined);
-        return {
-            tag: this.messageTag,
-            type: "DELEGATE_SUCCESS",
-            payload: {
-                delegated: result.delegated.map((o) => ({
-                    txid: o.txid,
-                    vout: o.vout,
-                })),
-                failed: result.failed.map((f) => ({
-                    outpoints: f.outpoints.map((o) => ({
-                        txid: o.txid,
-                        vout: o.vout,
-                    })),
-                    error: String(f.error),
-                })),
-            },
-        };
-    }
-    async handleGetVtxos(message) {
-        if (!this.readonlyWallet) {
-            throw new WalletNotInitializedError();
-        }
-        const vtxos = await this.getSpendableVtxos();
-        const dustAmount = this.readonlyWallet.dustAmount;
-        const includeRecoverable = message.payload.filter?.withRecoverable ?? false;
-        const filteredVtxos = includeRecoverable
-            ? vtxos
-            : vtxos.filter((v) => {
-                if (dustAmount != null && isSubdust(v, dustAmount)) {
-                    return false;
-                }
-                if (isRecoverable(v)) {
-                    return false;
-                }
-                if (isExpired(v)) {
-                    return false;
-                }
-                return true;
-            });
-        return filteredVtxos;
-    }
-    async clear() {
-        if (!this.readonlyWallet)
-            return;
-        if (this.incomingFundsSubscription)
-            this.incomingFundsSubscription();
-        if (this.contractEventsSubscription) {
-            this.contractEventsSubscription();
-            this.contractEventsSubscription = undefined;
-        }
-        // Dispose the wallet to stop the ContractWatcher (and its polling
-        // intervals) before clearing the repositories, otherwise the poller
-        // will hit a closing IndexedDB connection.
-        try {
-            if (this.wallet) {
-                await this.wallet.dispose();
-            }
-            else {
-                await this.readonlyWallet.dispose();
-            }
-        }
-        catch (_) {
-            // best-effort teardown
-        }
-        try {
-            await this.walletRepository?.clear();
-        }
-        catch (_) {
-            console.warn("Failed to clear vtxos from wallet repository");
-        }
-        this.wallet = undefined;
-        this.readonlyWallet = undefined;
-        this.arkProvider = undefined;
-        this.indexerProvider = undefined;
-    }
-    /**
-     * Read all virtual outputs from the repository, aggregated across all contract
-     * addresses and the wallet's primary address, with deduplication.
-     */
-    async getVtxosFromRepo() {
-        if (!this.walletRepository || !this.readonlyWallet)
-            return [];
-        const seen = new Set();
-        const allVtxos = [];
-        const addVtxos = (vtxos) => {
-            for (const vtxo of vtxos) {
-                const key = `${vtxo.txid}:${vtxo.vout}`;
-                if (!seen.has(key)) {
-                    seen.add(key);
-                    allVtxos.push(vtxo);
-                }
-            }
-        };
-        // Aggregate virtual outputs from all contract addresses. Address
-        // buckets may carry legacy duplicate rows from other contracts; gate
-        // each bucket by its owning contract script before deduplication so a
-        // wrong-script row never wins the txid:vout race.
-        const manager = await this.readonlyWallet.getContractManager();
-        const contracts = await manager.getContracts();
-        for (const contract of contracts) {
-            addVtxos(await getVtxosForContract(this.walletRepository, contract));
-        }
-        // Also check the wallet's primary address. Decode it to its script
-        // and apply the same script gate. Failing to decode the wallet's own
-        // address is a structural bug — surfacing the error is safer than
-        // silently dropping the primary bucket and zeroing the user's
-        // visible balance.
-        const walletAddress = await this.readonlyWallet.getAddress();
-        let walletScript;
-        try {
-            walletScript = scriptFromArkAddress(walletAddress);
-        }
-        catch (e) {
-            throw new Error(`WalletMessageHandler.getVtxosFromRepo: failed to derive script from wallet address ${walletAddress}: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        const walletVtxos = await this.walletRepository.getVtxos(walletAddress);
-        addVtxos(filterVtxosForScript(walletVtxos, walletScript));
-        return allVtxos;
-    }
-    /**
-     * Build transaction history from cached virtual outputs without hitting the indexer.
-     * Falls back to indexer only for uncached transaction timestamps.
-     */
-    async buildTransactionHistoryFromCache(vtxos) {
-        if (!this.readonlyWallet)
-            return null;
-        const { boardingTxs, commitmentsToIgnore } = await this.readonlyWallet.getBoardingTxs();
-        // Build a lookup for cached virtual output timestamps, keyed by txid.
-        // Multiple virtual outputs can share a txid (different vouts) — we keep the
-        // earliest createdAt so the history ordering is stable.
-        const vtxoCreatedAt = new Map();
-        for (const vtxo of vtxos) {
-            const existing = vtxoCreatedAt.get(vtxo.txid);
-            const ts = vtxo.createdAt.getTime();
-            if (existing === undefined || ts < existing) {
-                vtxoCreatedAt.set(vtxo.txid, ts);
-            }
-        }
-        // Pre-fetch uncached timestamps in a single batched indexer call.
-        // buildTransactionHistory needs these for spent-offchain virtual outputs with
-        // no change outputs (i.e. arkTxId is set but no virtual output has txid === arkTxId).
-        if (this.indexerProvider) {
-            const uncachedTxids = new Set();
-            for (const vtxo of vtxos) {
-                if (vtxo.isSpent &&
-                    vtxo.arkTxId &&
-                    !vtxoCreatedAt.has(vtxo.arkTxId) &&
-                    !vtxos.some((v) => v.txid === vtxo.arkTxId)) {
-                    uncachedTxids.add(vtxo.arkTxId);
-                }
-            }
-            if (uncachedTxids.size > 0) {
-                const outpoints = [...uncachedTxids].map((txid) => ({
-                    txid,
-                    vout: 0,
-                }));
-                const BATCH_SIZE = 100;
-                for (let i = 0; i < outpoints.length; i += BATCH_SIZE) {
-                    const res = await this.indexerProvider.getVtxos({
-                        outpoints: outpoints.slice(i, i + BATCH_SIZE),
-                    });
-                    for (const v of res.vtxos) {
-                        vtxoCreatedAt.set(v.txid, v.createdAt.getTime());
-                    }
-                }
-            }
-        }
-        const getTxCreatedAt = async (txid) => {
-            return vtxoCreatedAt.get(txid);
-        };
-        return buildTransactionHistory(vtxos, boardingTxs, commitmentsToIgnore, getTxCreatedAt);
-    }
-    async ensureContractEventBroadcasting() {
-        if (!this.readonlyWallet)
-            return;
-        if (this.contractEventsSubscription)
-            return;
-        try {
-            const manager = await this.readonlyWallet.getContractManager();
-            this.contractEventsSubscription = manager.onContractEvent((event) => {
-                this.scheduleForNextTick(() => this.tagged({
-                    type: "CONTRACT_EVENT",
-                    broadcast: true,
-                    payload: { event },
-                }));
-            });
-        }
-        catch (error) {
-            console.error("Error subscribing to contract events:", error);
-        }
-    }
-}