@arkade-os/sdk 0.4.23 → 0.4.25

package/dist/esm/utils/timelock.js

@@ -0,0 +1,22 @@
+import * as bip68 from "bip68";
+/**
+ * Convert RelativeTimelock to BIP68 sequence number.
+ */
+export function timelockToSequence(timelock) {
+    return bip68.encode(timelock.type === "blocks"
+        ? { blocks: Number(timelock.value) }
+        : { seconds: Number(timelock.value) });
+}
+/**
+ * Convert BIP68 sequence number back to RelativeTimelock.
+ */
+export function sequenceToTimelock(sequence) {
+    const decoded = bip68.decode(sequence);
+    if ("blocks" in decoded && decoded.blocks !== undefined) {
+        return { type: "blocks", value: BigInt(decoded.blocks) };
+    }
+    if ("seconds" in decoded && decoded.seconds !== undefined) {
+        return { type: "seconds", value: BigInt(decoded.seconds) };
+    }
+    throw new Error(`Invalid BIP68 sequence: ${sequence}`);
+}

package/dist/esm/utils/unknownFields.js

@@ -1,6 +1,6 @@
-import * as bip68 from "bip68";
 import { RawWitness, ScriptNum } from "@scure/btc-signer";
 import { hex } from "@scure/base";
+import { sequenceToTimelock } from './timelock.js';
 /**
  * ArkPsbtFieldKey are the available key names for the Arkade PSBT custom fields.
  */
@@ -146,11 +146,7 @@ export const VtxoTreeExpiry = {
         const v = ScriptNum(6, true).decode(unknown[1]);
         if (!v)
             return null;
-        const { blocks, seconds } = bip68.decode(Number(v));
-        return {
-            type: blocks ? "blocks" : "seconds",
-            value: BigInt(blocks ?? seconds ?? 0),
-        };
+        return sequenceToTimelock(Number(v));
     }),
 };
 const encodedPsbtFieldKey = Object.fromEntries(Object.values(ArkPsbtFieldKey).map((key) => [

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

@@ -2,6 +2,8 @@ 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");
@@ -311,6 +313,16 @@ export class WalletMessageHandler {
                         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);
@@ -581,11 +593,47 @@ export class WalletMessageHandler {
                     const { newVtxos, spentVtxos } = funds;
                     if (newVtxos.length + spentVtxos.length === 0)
                         return;
-                    // save virtual outputs using unified repository
-                    await this.walletRepository?.saveVtxos(address, [
-                        ...newVtxos,
-                        ...spentVtxos,
-                    ]);
+                    // 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",
@@ -797,17 +845,30 @@ export class WalletMessageHandler {
                 }
             }
         };
-        // Aggregate virtual outputs from all contract addresses
+        // 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) {
-            const vtxos = await this.walletRepository.getVtxos(contract.address);
-            addVtxos(vtxos);
+            addVtxos(await getVtxosForContract(this.walletRepository, contract));
         }
-        // Also check the wallet's primary address
+        // 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(walletVtxos);
+        addVtxos(filterVtxosForScript(walletVtxos, walletScript));
         return allVtxos;
     }
     /**

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

@@ -57,6 +57,7 @@ export const DEFAULT_MESSAGE_TIMEOUTS = {
     UPDATE_CONTRACT: 30000,
     DELETE_CONTRACT: 10000,
     REFRESH_VTXOS: 30000,
+    REFRESH_OUTPOINTS: 30000,
 };
 const DEDUPABLE_REQUEST_TYPES = new Set([
     "GET_ADDRESS",
@@ -821,6 +822,15 @@ export class ServiceWorkerReadonlyWallet {
                 };
                 await sendContractMessage(message);
             },
+            async refreshOutpoints(outpoints) {
+                const message = {
+                    type: "REFRESH_OUTPOINTS",
+                    id: getRandomId(),
+                    tag: messageTag,
+                    payload: { outpoints },
+                };
+                await sendContractMessage(message);
+            },
             async isWatching() {
                 const message = {
                     type: "IS_CONTRACT_MANAGER_WATCHING",

package/dist/esm/wallet/unroll.js

@@ -1,6 +1,6 @@
 import { base64, hex } from "@scure/base";
 import { SigHash, TaprootControlBlock } from "@scure/btc-signer";
-import { timelockToSequence } from '../contracts/handlers/helpers.js';
+import { timelockToSequence } from '../utils/timelock.js';
 import { ChainTxType } from '../providers/indexer.js';
 import { VtxoScript } from '../script/base.js';
 import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
@@ -126,10 +126,12 @@ export var Unroll;
                 // finalize Arkade transaction
                 tx.finalize();
             }
+            const pkg = await this.bumper.bumpP2A(tx);
             return {
                 type: StepType.UNROLL,
                 tx,
-                do: doUnroll(this.bumper, this.explorer, tx),
+                pkg,
+                do: doUnroll(this.explorer, pkg),
             };
         }
         /**
@@ -161,79 +163,88 @@ export var Unroll;
      * @returns the txid of the transaction spending the unrolled funds
      */
     async function completeUnroll(wallet, vtxoTxids, outputAddress) {
-        const chainTip = await wallet.onchainProvider.getChainTip();
-        let vtxos = await wallet.getVtxos({ withUnrolled: true });
-        vtxos = vtxos.filter((vtxo) => vtxoTxids.includes(vtxo.txid));
-        if (vtxos.length === 0) {
-            throw new Error("No vtxos to complete unroll");
-        }
-        const inputs = [];
-        let totalAmount = 0n;
-        const txWeightEstimator = TxWeightEstimator.create();
-        for (const vtxo of vtxos) {
-            if (!vtxo.isUnrolled) {
-                throw new Error(`Vtxo ${vtxo.txid}:${vtxo.vout} is not fully unrolled, use unroll first`);
-            }
-            const txStatus = await wallet.onchainProvider.getTxStatus(vtxo.txid);
-            if (!txStatus.confirmed) {
-                throw new Error(`tx ${vtxo.txid} is not confirmed`);
-            }
-            const exit = availableExitPath({ height: txStatus.blockHeight, time: txStatus.blockTime }, chainTip, vtxo);
-            if (!exit) {
-                throw new Error(`no available exit path found for vtxo ${vtxo.txid}:${vtxo.vout}`);
-            }
-            const spendingLeaf = VtxoScript.decode(vtxo.tapTree).findLeaf(hex.encode(exit.script));
-            if (!spendingLeaf) {
-                throw new Error(`spending leaf not found for vtxo ${vtxo.txid}:${vtxo.vout}`);
-            }
-            totalAmount += BigInt(vtxo.value);
-            const sequence = timelockToSequence(exit.params.timelock);
-            inputs.push({
-                txid: vtxo.txid,
-                index: vtxo.vout,
-                tapLeafScript: [spendingLeaf],
-                sequence,
-                witnessUtxo: {
-                    amount: BigInt(vtxo.value),
-                    script: VtxoScript.decode(vtxo.tapTree).pkScript,
-                },
-                sighashType: SigHash.DEFAULT,
-            });
-            txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, TaprootControlBlock.encode(spendingLeaf[0]).length);
-        }
-        const tx = new Transaction({ version: 2 });
-        for (const input of inputs) {
-            tx.addInput(input);
-        }
-        txWeightEstimator.addOutputAddress(outputAddress, wallet.network);
-        let feeRate = await wallet.onchainProvider.getFeeRate();
-        if (!feeRate || feeRate < Wallet.MIN_FEE_RATE) {
-            feeRate = Wallet.MIN_FEE_RATE;
-        }
-        const feeAmount = txWeightEstimator.vsize().fee(BigInt(feeRate));
-        if (feeAmount > totalAmount) {
-            throw new Error("fee amount is greater than the total amount");
-        }
-        const sendAmount = totalAmount - feeAmount;
-        if (sendAmount < BigInt(DUST_AMOUNT)) {
-            throw new Error("send amount is less than dust amount");
-        }
-        tx.addOutputAddress(outputAddress, sendAmount);
-        const signedTx = await wallet.identity.sign(tx);
-        signedTx.finalize();
+        const signedTx = await prepareUnrollTransaction(wallet, vtxoTxids, outputAddress);
         await wallet.onchainProvider.broadcastTransaction(signedTx.hex);
         return signedTx.id;
     }
     Unroll.completeUnroll = completeUnroll;
 })(Unroll || (Unroll = {}));
+/**
+ * Prepares the transaction that spends the CSV path to complete unrolling a VTXO.
+ * @param wallet the wallet owning the VTXO(s)
+ * @param vtxoTxIds the txids of the VTXO(s) to complete unroll
+ * @param outputAddress the address to send the unrolled funds to
+ * @throws if the VTXO(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
+ * @returns the transaction spending the unrolled funds
+ */
+export async function prepareUnrollTransaction(wallet, vtxoTxIds, outputAddress) {
+    const chainTip = await wallet.onchainProvider.getChainTip();
+    let vtxos = await wallet.getVtxos({ withUnrolled: true });
+    vtxos = vtxos.filter((vtxo) => vtxoTxIds.includes(vtxo.txid));
+    if (vtxos.length === 0) {
+        throw new Error("No vtxos to complete unroll");
+    }
+    const inputs = [];
+    let totalAmount = 0n;
+    const txWeightEstimator = TxWeightEstimator.create();
+    for (const vtxo of vtxos) {
+        if (!vtxo.isUnrolled) {
+            throw new Error(`Vtxo ${vtxo.txid}:${vtxo.vout} is not fully unrolled, use unroll first`);
+        }
+        const txStatus = await wallet.onchainProvider.getTxStatus(vtxo.txid);
+        if (!txStatus.confirmed) {
+            throw new Error(`tx ${vtxo.txid} is not confirmed`);
+        }
+        const exit = availableExitPath({ height: txStatus.blockHeight, time: txStatus.blockTime }, chainTip, vtxo);
+        if (!exit) {
+            throw new Error(`no available exit path found for vtxo ${vtxo.txid}:${vtxo.vout}`);
+        }
+        const spendingLeaf = VtxoScript.decode(vtxo.tapTree).findLeaf(hex.encode(exit.script));
+        if (!spendingLeaf) {
+            throw new Error(`spending leaf not found for vtxo ${vtxo.txid}:${vtxo.vout}`);
+        }
+        totalAmount += BigInt(vtxo.value);
+        const sequence = timelockToSequence(exit.params.timelock);
+        inputs.push({
+            txid: vtxo.txid,
+            index: vtxo.vout,
+            tapLeafScript: [spendingLeaf],
+            sequence,
+            witnessUtxo: {
+                amount: BigInt(vtxo.value),
+                script: VtxoScript.decode(vtxo.tapTree).pkScript,
+            },
+            sighashType: SigHash.DEFAULT,
+        });
+        txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, TaprootControlBlock.encode(spendingLeaf[0]).length);
+    }
+    const tx = new Transaction({ version: 2 });
+    for (const input of inputs) {
+        tx.addInput(input);
+    }
+    txWeightEstimator.addOutputAddress(outputAddress, wallet.network);
+    let feeRate = await wallet.onchainProvider.getFeeRate();
+    if (!feeRate || feeRate < Wallet.MIN_FEE_RATE) {
+        feeRate = Wallet.MIN_FEE_RATE;
+    }
+    const feeAmount = txWeightEstimator.vsize().fee(BigInt(feeRate));
+    if (feeAmount > totalAmount) {
+        throw new Error("fee amount is greater than the total amount");
+    }
+    const sendAmount = totalAmount - feeAmount;
+    if (sendAmount < BigInt(DUST_AMOUNT)) {
+        throw new Error("send amount is less than dust amount");
+    }
+    tx.addOutputAddress(outputAddress, sendAmount, wallet.network);
+    const signedTx = await wallet.identity.sign(tx);
+    signedTx.finalize();
+    return signedTx;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-function doUnroll(bumper, onchainProvider, tx) {
-    return async () => {
-        const [parent, child] = await bumper.bumpP2A(tx);
-        await onchainProvider.broadcastTransaction(parent, child);
-    };
+function doUnroll(onchainProvider, pkg) {
+    return () => onchainProvider.broadcastTransaction(...pkg).then(() => undefined);
 }
 function doWait(onchainProvider, txid) {
     return () => {

package/dist/esm/wallet/vtxo-manager.js

@@ -1,4 +1,5 @@
 import { isExpired, isRecoverable, isSpendable, isSubdust, } from './index.js';
+import { maybeArkError } from '../providers/errors.js';
 import { hasBoardingTxExpired } from '../utils/arkTransaction.js';
 import { CSVMultisigTapscript } from '../script/tapscript.js';
 import { hex } from "@scure/base";
@@ -432,10 +433,22 @@ export class VtxoManager {
         try {
             // Get all virtual outputs (including recoverable ones)
             // Use default threshold to bypass settlementConfig gate (manual API should always work)
-            const vtxos = await this.getExpiringVtxos(this.settlementConfig !== false &&
+            const threshold = this.settlementConfig !== false &&
                 this.settlementConfig?.vtxoThreshold !== undefined
                 ? this.settlementConfig.vtxoThreshold * 1000
-                : DEFAULT_RENEWAL_CONFIG.thresholdMs);
+                : DEFAULT_RENEWAL_CONFIG.thresholdMs;
+            let vtxos = await this.getExpiringVtxos(threshold);
+            if (vtxos.length === 0) {
+                throw new Error("No VTXOs available to renew");
+            }
+            // Pre-flight: validate the chosen inputs against the indexer's
+            // authoritative state before submitting. The cursor-derived
+            // delta sync filters by `created_at`, so a VTXO created
+            // before the cursor and spent recently can sit in the local
+            // cache forever; settling against it yields a guaranteed
+            // VTXO_ALREADY_SPENT 400. Refreshing the candidates here
+            // catches that BEFORE the network round-trip.
+            vtxos = await this.revalidateBeforeSettle(vtxos, threshold);
             if (vtxos.length === 0) {
                 throw new Error("No VTXOs available to renew");
             }
@@ -684,9 +697,11 @@ export class VtxoManager {
                             if (e.message.includes("VTXO_ALREADY_SPENT")) {
                                 // Our local VTXO cache is stale vs. the
                                 // server's authoritative view. Trigger a
-                                // throttled refresh to reconcile, then skip
-                                // — the next cycle will see fresh data.
-                                void this.maybeRefreshAfterVtxoSpent();
+                                // throttled, targeted refresh on the
+                                // offending outpoint (if the server told
+                                // us which one), then skip — the next
+                                // cycle will see fresh data.
+                                void this.maybeRefreshAfterVtxoSpent(this.extractSpentOutpoint(e));
                                 return;
                             }
                         }
@@ -711,13 +726,20 @@ export class VtxoManager {
     /**
      * VTXO_ALREADY_SPENT means the server's authoritative view of VTXO state
      * is ahead of ours — cross-instance race, pre-lock snapshot drift, or an
-     * SSE gap left stale data in the local cache. Silent-swallowing guarantees
-     * the same error on the next cycle because nothing reconciles the cache,
-     * so instead we trigger a full refreshVtxos() to advance the global sync
-     * cursor. Throttled to prevent a buggy indexer from causing a refresh
-     * storm.
+     * SSE gap left stale data in the local cache. Silent-swallowing
+     * guarantees the same error on the next cycle because nothing
+     * reconciles the cache.
+     *
+     * The cursor-derived delta sync filters by `created_at`, so a VTXO that
+     * was created before the cursor but spent recently can never be
+     * reconciled by `refreshVtxos()`. Use `refreshOutpoints` for surgical
+     * recovery: query the indexer for the specific stale outpoint and
+     * upsert its authoritative state into the wallet repository.
+     *
+     * Throttled because the same VTXO can fire repeatedly before the
+     * upsert observably propagates through the renewal selector.
      */
-    maybeRefreshAfterVtxoSpent() {
+    maybeRefreshAfterVtxoSpent(spentOutpoint) {
         if (this.vtxoSpentRefreshPromise) {
             return this.vtxoSpentRefreshPromise;
         }
@@ -730,7 +752,13 @@ export class VtxoManager {
         this.vtxoSpentRefreshPromise = (async () => {
             try {
                 const contractManager = await this.wallet.getContractManager();
-                await contractManager.refreshVtxos();
+                if (spentOutpoint) {
+                    await contractManager.refreshOutpoints([spentOutpoint]);
+                }
+                else {
+                    // No outpoint metadata — fall back to the broader refresh.
+                    await contractManager.refreshVtxos();
+                }
             }
             catch (e) {
                 console.error("Error refreshing VTXOs after VTXO_ALREADY_SPENT:", e);
@@ -741,6 +769,66 @@ export class VtxoManager {
         })();
         return this.vtxoSpentRefreshPromise;
     }
+    /**
+     * Extract the offending VTXO outpoint from a `VTXO_ALREADY_SPENT` error,
+     * if the server attached one in `metadata.vtxo_outpoint`. Returns
+     * `undefined` when the error isn't a parsed ArkError, isn't this code,
+     * or doesn't carry the metadata.
+     */
+    extractSpentOutpoint(error) {
+        const ark = maybeArkError(error);
+        if (!ark || ark.name !== "VTXO_ALREADY_SPENT")
+            return undefined;
+        const raw = ark.metadata?.vtxo_outpoint;
+        if (typeof raw !== "string")
+            return undefined;
+        const [txid, voutStr] = raw.split(":");
+        if (!txid || !voutStr)
+            return undefined;
+        const vout = Number(voutStr);
+        if (!Number.isInteger(vout) || vout < 0)
+            return undefined;
+        return { txid, vout };
+    }
+    /**
+     * Reconcile the chosen VTXOs with the indexer's authoritative state
+     * before submitting a settle intent. Pulls the canonical record for
+     * each candidate outpoint via {@link IContractManager.refreshOutpoints}
+     * (which upserts the result into the wallet repository), then
+     * re-selects through the standard expiring-vtxo filter so anything
+     * the refresh flagged as spent is dropped.
+     *
+     * Best-effort: a failed refresh just falls back to the original
+     * candidates and lets the post-submit `VTXO_ALREADY_SPENT` recovery
+     * handle whatever slipped through.
+     */
+    async revalidateBeforeSettle(candidates, thresholdMs) {
+        if (candidates.length === 0)
+            return candidates;
+        try {
+            const cm = await this.wallet.getContractManager();
+            await cm.refreshOutpoints(candidates.map((v) => ({ txid: v.txid, vout: v.vout })));
+        }
+        catch (e) {
+            console.error("Error pre-validating VTXOs before settle:", e);
+            return candidates;
+        }
+        // Re-select from the now-fresh local cache. Anything previously
+        // selected but spent gets filtered out by the standard
+        // `isSpendable`/`isSpent` checks inside getVtxos / getExpiringVtxos.
+        try {
+            const refreshed = await this.getExpiringVtxos(thresholdMs);
+            const candidateKeys = new Set(candidates.map((v) => `${v.txid}:${v.vout}`));
+            // Restrict to vtxos that were also in the original candidate set
+            // — `getExpiringVtxos` may surface NEW vtxos and we don't want
+            // pre-flight to silently expand the input set.
+            return refreshed.filter((v) => candidateKeys.has(`${v.txid}:${v.vout}`));
+        }
+        catch (e) {
+            console.error("Error re-selecting VTXOs after pre-validate:", e);
+            return candidates;
+        }
+    }
     /** Computes the next poll delay, applying exponential backoff on failures. */
     getNextPollDelay() {
         if (this.settlementConfig === false)
@@ -882,6 +970,13 @@ export class VtxoManager {
         if (!this.renewalInProgress) {
             try {
                 expiringVtxos = await this.getExpiringVtxos();
+                // Pre-flight validation: see comment in `renewVtxos`. The
+                // local cache may carry vtxos that the indexer already
+                // marks spent because the cursor-derived delta sync only
+                // catches `created_at`-recent updates, not status changes
+                // for older VTXOs.
+                expiringVtxos =
+                    await this.revalidateBeforeSettle(expiringVtxos);
             }
             catch (e) {
                 // Non-fatal: fall back to boarding-only settle.
@@ -973,11 +1068,12 @@ export class VtxoManager {
                     e.message.includes("VTXO_ALREADY_SPENT")) {
                     // Local VTXO cache is stale vs. the server's
                     // authoritative view — not a transient failure.
-                    // Trigger a throttled refresh and skip this cycle
-                    // without bumping the failure counter, so the next
-                    // poll can retry once the cache reconciles.
+                    // Trigger a throttled, targeted refresh on the
+                    // offending outpoint and skip this cycle without
+                    // bumping the failure counter, so the next poll
+                    // can retry once the cache reconciles.
                     staleCacheSkip = true;
-                    void this.maybeRefreshAfterVtxoSpent();
+                    void this.maybeRefreshAfterVtxoSpent(this.extractSpentOutpoint(e));
                 }
                 else {
                     throw e;

package/dist/esm/wallet/wallet.js

@@ -32,8 +32,9 @@ import { DelegatorManagerImpl, findDestinationOutputIndex, } from './delegator.j
 import { IndexedDBContractRepository, IndexedDBWalletRepository, } from '../repositories/index.js';
 import { ContractManager } from '../contracts/contractManager.js';
 import { contractHandlers } from '../contracts/handlers/index.js';
-import { timelockToSequence } from '../contracts/handlers/helpers.js';
+import { timelockToSequence } from '../utils/timelock.js';
 import { clearSyncCursor, updateWalletState } from '../utils/syncCursors.js';
+import { validateVtxosForScript, saveVtxosForContract, } from '../contracts/vtxoOwnership.js';
 export const getArkadeServerUrl = ({ arkServerUrl, }) => arkServerUrl || DEFAULT_ARKADE_SERVER_URL;
 // Historical unilateral exit delay for mainnet (~7 days in seconds).
 // Kept so existing wallets can still discover and spend VTXOs sent to the
@@ -1823,7 +1824,7 @@ export class Wallet extends ReadonlyWallet {
                 }
             }
             const createdAt = Date.now();
-            const addr = this.arkAddress.encode();
+            const primaryAddr = this.arkAddress.encode();
             // Only save a change virtual output for preconfirmed coins (those with a batchExpiry).
             // Inputs without a batchExpiry are already settled/unrolled and don't need tracking.
             let changeVtxo;
@@ -1850,8 +1851,37 @@ export class Wallet extends ReadonlyWallet {
                     script: hex.encode(this.offchainTapscript.pkScript),
                 };
             }
-            await this.walletRepository.saveVtxos(addr, changeVtxo ? [...spentVtxos, changeVtxo] : spentVtxos);
-            await this.walletRepository.saveTransactions(addr, [
+            // Route spent rows to their owning contract bucket. The wallet's
+            // primary contract is registered with the manager at boot, so
+            // `addrByScript` already includes it; in a multi-contract spend
+            // each input may belong to a different contract.
+            const contracts = await cm.getContracts();
+            const addrByScript = new Map(contracts.map((c) => [c.script, c.address]));
+            const spentByScript = new Map();
+            for (const v of spentVtxos) {
+                if (!v.script) {
+                    throw new Error(`Wallet.updateDbAfterOffchainTx: spent VTXO ${v.txid}:${v.vout} has no script`);
+                }
+                const arr = spentByScript.get(v.script) ?? [];
+                arr.push(v);
+                spentByScript.set(v.script, arr);
+            }
+            for (const [script, vtxos] of spentByScript) {
+                // User-initiated send path: a wrong-script row here means the
+                // wallet is about to record ownership against the wrong
+                // contract — fail loudly rather than persist inconsistent state.
+                validateVtxosForScript(vtxos, script, "Wallet.updateDbAfterOffchainTx");
+                const targetAddr = addrByScript.get(script);
+                if (!targetAddr) {
+                    throw new Error(`Wallet.updateDbAfterOffchainTx: no contract owns script ${script}`);
+                }
+                await saveVtxosForContract(this.walletRepository, { script, address: targetAddr }, vtxos);
+            }
+            // Change is always primary-script by construction.
+            if (changeVtxo) {
+                await saveVtxosForContract(this.walletRepository, { script: changeVtxo.script, address: primaryAddr }, [changeVtxo]);
+            }
+            await this.walletRepository.saveTransactions(primaryAddr, [
                 {
                     key: {
                         boardingTxid: "",
@@ -1867,12 +1897,12 @@ export class Wallet extends ReadonlyWallet {
         }
         catch (e) {
             console.warn("error saving offchain tx to repository", e);
+            throw e;
         }
     }
     // mark virtual outputs as spent/settled, remove boarding inputs
     async updateDbAfterSettle(inputs, commitmentTxid) {
         try {
-            const addr = this.arkAddress.encode();
             const boardingAddress = await this.getBoardingAddress();
             const spentVtxos = [];
             const inputArkTxIds = new Set();
@@ -1905,7 +1935,32 @@ export class Wallet extends ReadonlyWallet {
                 }
             }
             if (spentVtxos.length > 0) {
-                await this.walletRepository.saveVtxos(addr, spentVtxos);
+                // Route settled rows to their owning contract bucket. In a
+                // multi-contract settle the inputs may belong to several
+                // contracts; the wallet's primary contract is registered with
+                // the manager at boot, so its address is in `addrByScript`
+                // alongside the rest.
+                const contracts = await cm.getContracts();
+                const addrByScript = new Map(contracts.map((c) => [c.script, c.address]));
+                const byScript = new Map();
+                for (const v of spentVtxos) {
+                    if (!v.script) {
+                        throw new Error(`Wallet.updateDbAfterSettle: spent VTXO ${v.txid}:${v.vout} has no script`);
+                    }
+                    const arr = byScript.get(v.script) ?? [];
+                    arr.push(v);
+                    byScript.set(v.script, arr);
+                }
+                for (const [script, vtxos] of byScript) {
+                    // User-initiated settle path: refuse to record a settle
+                    // against the wrong script.
+                    validateVtxosForScript(vtxos, script, "Wallet.updateDbAfterSettle");
+                    const targetAddr = addrByScript.get(script);
+                    if (!targetAddr) {
+                        throw new Error(`Wallet.updateDbAfterSettle: no contract owns script ${script}`);
+                    }
+                    await saveVtxosForContract(this.walletRepository, { script, address: targetAddr }, vtxos);
+                }
             }
             if (boardingUtxoToRemove.size > 0) {
                 const currentUtxos = await this.walletRepository.getUtxos(boardingAddress);
@@ -1919,6 +1974,7 @@ export class Wallet extends ReadonlyWallet {
         }
         catch (e) {
             console.warn("error updating repository after settle", e);
+            throw e;
         }
     }
 }