@arkade-os/sdk 0.4.23 → 0.4.25

package/dist/cjs/wallet/unroll.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Unroll = void 0;
+exports.prepareUnrollTransaction = prepareUnrollTransaction;
 const base_1 = require("@scure/base");
 const btc_signer_1 = require("@scure/btc-signer");
-const helpers_1 = require("../contracts/handlers/helpers");
+const timelock_1 = require("../utils/timelock");
 const indexer_1 = require("../providers/indexer");
 const base_2 = require("../script/base");
 const txSizeEstimator_1 = require("../utils/txSizeEstimator");
@@ -129,10 +130,12 @@ 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),
             };
         }
         /**
@@ -164,79 +167,88 @@ 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 = txSizeEstimator_1.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 = base_2.VtxoScript.decode(vtxo.tapTree).findLeaf(base_1.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 = (0, helpers_1.timelockToSequence)(exit.params.timelock);
-            inputs.push({
-                txid: vtxo.txid,
-                index: vtxo.vout,
-                tapLeafScript: [spendingLeaf],
-                sequence,
-                witnessUtxo: {
-                    amount: BigInt(vtxo.value),
-                    script: base_2.VtxoScript.decode(vtxo.tapTree).pkScript,
-                },
-                sighashType: btc_signer_1.SigHash.DEFAULT,
-            });
-            txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, btc_signer_1.TaprootControlBlock.encode(spendingLeaf[0]).length);
-        }
-        const tx = new transaction_1.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_1.Wallet.MIN_FEE_RATE) {
-            feeRate = wallet_1.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(utils_1.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 || (exports.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
+ */
+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 = txSizeEstimator_1.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 = base_2.VtxoScript.decode(vtxo.tapTree).findLeaf(base_1.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 = (0, timelock_1.timelockToSequence)(exit.params.timelock);
+        inputs.push({
+            txid: vtxo.txid,
+            index: vtxo.vout,
+            tapLeafScript: [spendingLeaf],
+            sequence,
+            witnessUtxo: {
+                amount: BigInt(vtxo.value),
+                script: base_2.VtxoScript.decode(vtxo.tapTree).pkScript,
+            },
+            sighashType: btc_signer_1.SigHash.DEFAULT,
+        });
+        txWeightEstimator.addTapscriptInput(64, spendingLeaf[1].length, btc_signer_1.TaprootControlBlock.encode(spendingLeaf[0]).length);
+    }
+    const tx = new transaction_1.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_1.Wallet.MIN_FEE_RATE) {
+        feeRate = wallet_1.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(utils_1.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/cjs/wallet/vtxo-manager.js

@@ -4,6 +4,7 @@ exports.VtxoManager = exports.DEFAULT_SETTLEMENT_CONFIG = exports.DEFAULT_RENEWA
 exports.isVtxoExpiringSoon = isVtxoExpiringSoon;
 exports.getExpiringAndRecoverableVtxos = getExpiringAndRecoverableVtxos;
 const _1 = require(".");
+const errors_1 = require("../providers/errors");
 const arkTransaction_1 = require("../utils/arkTransaction");
 const tapscript_1 = require("../script/tapscript");
 const base_1 = require("@scure/base");
@@ -437,10 +438,22 @@ 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
-                : exports.DEFAULT_RENEWAL_CONFIG.thresholdMs);
+                : exports.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");
             }
@@ -689,9 +702,11 @@ 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;
                             }
                         }
@@ -716,13 +731,20 @@ 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;
         }
@@ -735,7 +757,13 @@ 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);
@@ -746,6 +774,66 @@ 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 = (0, errors_1.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)
@@ -887,6 +975,13 @@ 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.
@@ -978,11 +1073,12 @@ 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/cjs/wallet/wallet.js

@@ -37,8 +37,9 @@ const delegator_1 = require("./delegator");
 const repositories_1 = require("../repositories");
 const contractManager_1 = require("../contracts/contractManager");
 const handlers_1 = require("../contracts/handlers");
-const helpers_1 = require("../contracts/handlers/helpers");
+const timelock_1 = require("../utils/timelock");
 const syncCursors_1 = require("../utils/syncCursors");
+const vtxoOwnership_1 = require("../contracts/vtxoOwnership");
 const getArkadeServerUrl = ({ arkServerUrl, }) => arkServerUrl || _1.DEFAULT_ARKADE_SERVER_URL;
 exports.getArkadeServerUrl = getArkadeServerUrl;
 // Historical unilateral exit delay for mainnet (~7 days in seconds).
@@ -55,7 +56,7 @@ function dedupeTimelocks(timelocks) {
     const seen = new Set();
     const deduped = [];
     for (const timelock of timelocks) {
-        const sequence = (0, helpers_1.timelockToSequence)(timelock).toString();
+        const sequence = (0, timelock_1.timelockToSequence)(timelock).toString();
         if (seen.has(sequence))
             continue;
         seen.add(sequence);
@@ -648,7 +649,7 @@ class ReadonlyWallet {
             watcherConfig: this.watcherConfig,
         });
         for (const csvTimelock of this.walletContractTimelocks) {
-            const csvTimelockStr = (0, helpers_1.timelockToSequence)(csvTimelock).toString();
+            const csvTimelockStr = (0, timelock_1.timelockToSequence)(csvTimelock).toString();
             const defaultScript = new default_1.DefaultVtxo.Script({
                 pubKey: this.offchainTapscript.options.pubKey,
                 serverPubKey: this.offchainTapscript.options.serverPubKey,
@@ -1830,7 +1831,7 @@ 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;
@@ -1857,8 +1858,37 @@ class Wallet extends ReadonlyWallet {
                     script: base_1.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.
+                (0, vtxoOwnership_1.validateVtxosForScript)(vtxos, script, "Wallet.updateDbAfterOffchainTx");
+                const targetAddr = addrByScript.get(script);
+                if (!targetAddr) {
+                    throw new Error(`Wallet.updateDbAfterOffchainTx: no contract owns script ${script}`);
+                }
+                await (0, vtxoOwnership_1.saveVtxosForContract)(this.walletRepository, { script, address: targetAddr }, vtxos);
+            }
+            // Change is always primary-script by construction.
+            if (changeVtxo) {
+                await (0, vtxoOwnership_1.saveVtxosForContract)(this.walletRepository, { script: changeVtxo.script, address: primaryAddr }, [changeVtxo]);
+            }
+            await this.walletRepository.saveTransactions(primaryAddr, [
                 {
                     key: {
                         boardingTxid: "",
@@ -1874,12 +1904,12 @@ 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();
@@ -1912,7 +1942,32 @@ 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.
+                    (0, vtxoOwnership_1.validateVtxosForScript)(vtxos, script, "Wallet.updateDbAfterSettle");
+                    const targetAddr = addrByScript.get(script);
+                    if (!targetAddr) {
+                        throw new Error(`Wallet.updateDbAfterSettle: no contract owns script ${script}`);
+                    }
+                    await (0, vtxoOwnership_1.saveVtxosForContract)(this.walletRepository, { script, address: targetAddr }, vtxos);
+                }
             }
             if (boardingUtxoToRemove.size > 0) {
                 const currentUtxos = await this.walletRepository.getUtxos(boardingAddress);
@@ -1926,6 +1981,7 @@ class Wallet extends ReadonlyWallet {
         }
         catch (e) {
             console.warn("error updating repository after settle", e);
+            throw e;
         }
     }
 }

package/dist/cjs/worker/expo/processors/contractPollProcessor.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.contractPollProcessor = exports.CONTRACT_POLL_TASK_TYPE = void 0;
+const vtxoOwnership_1 = require("../../../contracts/vtxoOwnership");
 exports.CONTRACT_POLL_TASK_TYPE = "contract-poll";
 /**
  * Polls the indexer for the latest VTXO state of every contract and
@@ -43,8 +44,12 @@ exports.contractPollProcessor = {
                 hasMore = page ? vtxos.length === pageSize : false;
                 pageIndex++;
             }
-            await walletRepository.saveVtxos(contract.address, allVtxos);
-            vtxosSaved += allVtxos.length;
+            // Skip wrong-script rows (legacy duplicates or indexer drift)
+            // before persisting; the loop must keep going for the remaining
+            // contracts even when one row is rejected.
+            const filtered = (0, vtxoOwnership_1.warnAndFilterVtxosForScript)(allVtxos, contract.script, "contractPollProcessor");
+            await (0, vtxoOwnership_1.saveVtxosForContract)(walletRepository, contract, filtered);
+            vtxosSaved += filtered.length;
             contractsProcessed++;
         }
         return {

package/dist/esm/contracts/contractManager.js

@@ -3,6 +3,7 @@ import { ContractWatcher } from './contractWatcher.js';
 import { contractHandlers } from './handlers/index.js';
 import { extendVirtualCoinForContract } from '../wallet/utils.js';
 import { advanceSyncCursor, computeSyncWindow, cursorCutoff, getSyncCursor, } from '../utils/syncCursors.js';
+import { getVtxosForContract, saveVtxosForContract, warnAndFilterVtxosForScript, } from './vtxoOwnership.js';
 const DEFAULT_PAGE_SIZE = 500;
 /**
  * Central manager for contract lifecycle and operations.
@@ -354,11 +355,61 @@ export class ContractManager {
         const contracts = opts?.scripts
             ? await this.getContracts({ script: opts.scripts })
             : undefined;
+        // Only forward an explicit window when the caller supplied one. An
+        // empty `{ after: undefined, before: undefined }` would short-circuit
+        // both the cursor-derived `?after=` query in `syncContracts` (because
+        // `??` doesn't fire on a non-nullish object) AND the cursor-advance
+        // gate (which requires `options.window === undefined`), turning every
+        // `refreshVtxos()` call into an unbounded full re-scan whose cursor
+        // never moves forward.
+        const hasExplicitWindow = opts?.after !== undefined || opts?.before !== undefined;
         await this.syncContracts({
             contracts,
-            window: { after: opts?.after, before: opts?.before },
+            window: hasExplicitWindow
+                ? { after: opts?.after, before: opts?.before }
+                : undefined,
         });
     }
+    async refreshOutpoints(outpoints) {
+        if (outpoints.length === 0)
+            return;
+        const { vtxos } = await this.config.indexerProvider.getVtxos({
+            outpoints,
+        });
+        if (vtxos.length === 0)
+            return;
+        // Filter to outputs whose script we own. Map them to their owning
+        // contract so we can write through to the right per-address entry
+        // in the wallet repository.
+        const scripts = Array.from(new Set(vtxos.map((v) => v.script)));
+        const contracts = await this.config.contractRepository.getContracts({
+            script: scripts,
+        });
+        const scriptToContract = new Map(contracts.map((c) => [c.script, c]));
+        const owned = vtxos.filter((v) => scriptToContract.has(v.script));
+        if (owned.length === 0)
+            return;
+        const annotated = await this.annotateVtxos(owned);
+        const byAddress = new Map();
+        for (const vtxo of annotated) {
+            const contract = scriptToContract.get(vtxo.script);
+            if (!contract)
+                continue;
+            const address = contract.address;
+            const arr = byAddress.get(address) ?? [];
+            arr.push(vtxo);
+            byAddress.set(address, arr);
+        }
+        for (const [address, addressVtxos] of byAddress) {
+            const contract = contracts.find((c) => c.address === address);
+            if (contract) {
+                await saveVtxosForContract(this.config.walletRepository, contract, addressVtxos);
+            }
+            else {
+                await this.config.walletRepository.saveVtxos(address, addressVtxos);
+            }
+        }
+    }
     /**
      * Check if currently watching.
      */
@@ -399,9 +450,9 @@ export class ContractManager {
         this.emitEvent(event);
     }
     async getVtxosForContracts(contracts) {
-        const res = await Promise.all(contracts.map(({ script, address }) => this.config.walletRepository.getVtxos(address).then((vtxos) => vtxos.map((vtxo) => ({
+        const res = await Promise.all(contracts.map((contract) => getVtxosForContract(this.config.walletRepository, contract).then((vtxos) => vtxos.map((vtxo) => ({
             ...vtxo,
-            contractScript: script,
+            contractScript: contract.script,
         })))));
         return res.flat();
     }
@@ -467,7 +518,14 @@ export class ContractManager {
             });
         }
         for (const [addr, contractVtxos] of byContract) {
-            await this.config.walletRepository.saveVtxos(addr, contractVtxos);
+            // The bucket is keyed by contract address, so the script filter
+            // here is the same as the contract's. Skip wrong-script rows
+            // rather than crash the reconcile loop.
+            const contract = contracts.find((c) => c.address === addr);
+            const filtered = warnAndFilterVtxosForScript(contractVtxos, contract.script, "ContractManager.reconcilePendingFrontier");
+            if (filtered.length === 0)
+                continue;
+            await saveVtxosForContract(this.config.walletRepository, contract, filtered);
         }
     }
     async fetchContractVxosFromIndexer(contracts, pageSize, syncWindow) {
@@ -477,7 +535,10 @@ export class ContractManager {
             result.set(contractScript, vtxos);
             const contract = contracts.find((c) => c.script === contractScript);
             if (contract) {
-                await this.config.walletRepository.saveVtxos(contract.address, vtxos);
+                const filtered = warnAndFilterVtxosForScript(vtxos, contract.script, "ContractManager.fetchContractVxosFromIndexer");
+                if (filtered.length === 0)
+                    continue;
+                await saveVtxosForContract(this.config.walletRepository, contract, filtered);
             }
         }
         return result;

package/dist/esm/contracts/contractWatcher.js

@@ -1,5 +1,6 @@
 import { extendVirtualCoinForContract } from '../wallet/utils.js';
 import { isEventSourceError } from '../providers/utils.js';
+import { getVtxosForContract } from './vtxoOwnership.js';
 /**
  * Watches multiple contracts for virtual output state changes with resilient connection handling.
  *
@@ -87,7 +88,10 @@ export class ContractWatcher {
      */
     async seedLastKnownVtxos(state) {
         try {
-            const cached = await this.config.walletRepository.getVtxos(state.contract.address);
+            // Apply the same script gate used by getContractVtxos so a legacy
+            // wrong-script row in the address bucket can't seed the baseline
+            // and then look "spent" on the first poll.
+            const cached = await getVtxosForContract(this.config.walletRepository, state.contract);
             for (const vtxo of cached) {
                 if (vtxo.isSpent)
                     continue;
@@ -166,8 +170,10 @@ export class ContractWatcher {
             return true;
         })
             .map(async (state) => {
-            // Use contract address as cache key
-            const cached = await repo.getVtxos(state.contract.address);
+            // Use contract address as cache key. Legacy address buckets
+            // can contain rows from other contracts; gate by script before
+            // converting so a wrong-script row never reaches the watcher.
+            const cached = await getVtxosForContract(repo, state.contract);
             if (cached.length > 0) {
                 // Convert to ContractVtxo with contractScript
                 const contractVtxos = cached.map((v) => ({