@arkade-os/sdk 0.4.23 → 0.4.25

package/README.md

@@ -733,7 +733,7 @@ for await (const step of session) {
       console.log(`Waiting for transaction ${step.txid} to be confirmed`);
       break;
     case Unroll.StepType.UNROLL:
-      console.log(`Broadcasting transaction ${step.tx.id}`);
+      console.log(`Transaction ${step.tx.id} unrolled`);
       break;
     case Unroll.StepType.DONE:
       console.log(`Unrolling complete for virtual output ${step.vtxoTxid}`);
@@ -749,6 +749,26 @@ The unrolling process works by:
 - Waiting for confirmations between steps
 - Using P2A (Pay-to-Anchor) transactions to pay for fees
 
+Optionally, you can use `session.next()` to control the broadcasting process manually.
+
+```typescript
+const step = await session.next();
+switch (step.type) {
+  case Unroll.StepType.WAIT:
+    await step.do(); // wait for the transaction to be confirmed
+    break;
+  case Unroll.StepType.UNROLL:
+    const [parent, child] = step.pkg;
+    console.log(`Parent: ${parent}`)
+    console.log(`Child: ${child}`)
+    await step.do(); // broadcast the 1C1P package
+    break;
+  case Unroll.StepType.DONE:
+    console.log(`Unrolling complete for VTXO ${step.vtxoTxid}`);
+    break;
+  }
+```
+
 #### Step 2: Completing the Exit
 
 Once virtual outputs are fully unrolled and the unilateral exit timelock has expired, you can complete the exit:

package/dist/cjs/contracts/contractManager.js

@@ -6,6 +6,7 @@ const contractWatcher_1 = require("./contractWatcher");
 const handlers_1 = require("./handlers");
 const utils_1 = require("../wallet/utils");
 const syncCursors_1 = require("../utils/syncCursors");
+const vtxoOwnership_1 = require("./vtxoOwnership");
 const DEFAULT_PAGE_SIZE = 500;
 /**
  * Central manager for contract lifecycle and operations.
@@ -357,11 +358,61 @@ 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 (0, vtxoOwnership_1.saveVtxosForContract)(this.config.walletRepository, contract, addressVtxos);
+            }
+            else {
+                await this.config.walletRepository.saveVtxos(address, addressVtxos);
+            }
+        }
+    }
     /**
      * Check if currently watching.
      */
@@ -402,9 +453,9 @@ 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) => (0, vtxoOwnership_1.getVtxosForContract)(this.config.walletRepository, contract).then((vtxos) => vtxos.map((vtxo) => ({
             ...vtxo,
-            contractScript: script,
+            contractScript: contract.script,
         })))));
         return res.flat();
     }
@@ -470,7 +521,14 @@ 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 = (0, vtxoOwnership_1.warnAndFilterVtxosForScript)(contractVtxos, contract.script, "ContractManager.reconcilePendingFrontier");
+            if (filtered.length === 0)
+                continue;
+            await (0, vtxoOwnership_1.saveVtxosForContract)(this.config.walletRepository, contract, filtered);
         }
     }
     async fetchContractVxosFromIndexer(contracts, pageSize, syncWindow) {
@@ -480,7 +538,10 @@ 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 = (0, vtxoOwnership_1.warnAndFilterVtxosForScript)(vtxos, contract.script, "ContractManager.fetchContractVxosFromIndexer");
+                if (filtered.length === 0)
+                    continue;
+                await (0, vtxoOwnership_1.saveVtxosForContract)(this.config.walletRepository, contract, filtered);
             }
         }
         return result;

package/dist/cjs/contracts/contractWatcher.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContractWatcher = void 0;
 const utils_1 = require("../wallet/utils");
 const utils_2 = require("../providers/utils");
+const vtxoOwnership_1 = require("./vtxoOwnership");
 /**
  * Watches multiple contracts for virtual output state changes with resilient connection handling.
  *
@@ -90,7 +91,10 @@ 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 (0, vtxoOwnership_1.getVtxosForContract)(this.config.walletRepository, state.contract);
             for (const vtxo of cached) {
                 if (vtxo.isSpent)
                     continue;
@@ -169,8 +173,10 @@ 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 (0, vtxoOwnership_1.getVtxosForContract)(repo, state.contract);
             if (cached.length > 0) {
                 // Convert to ContractVtxo with contractScript
                 const contractVtxos = cached.map((v) => ({

package/dist/cjs/contracts/handlers/default.js

@@ -4,6 +4,7 @@ exports.DefaultContractHandler = void 0;
 const base_1 = require("@scure/base");
 const default_1 = require("../../script/default");
 const helpers_1 = require("./helpers");
+const timelock_1 = require("../../utils/timelock");
 const descriptor_1 = require("../../identity/descriptor");
 /**
  * Extract pubkey bytes from a descriptor or hex string.
@@ -28,12 +29,12 @@ exports.DefaultContractHandler = {
         return {
             pubKey: base_1.hex.encode(params.pubKey),
             serverPubKey: base_1.hex.encode(params.serverPubKey),
-            csvTimelock: (0, helpers_1.timelockToSequence)(params.csvTimelock).toString(),
+            csvTimelock: (0, timelock_1.timelockToSequence)(params.csvTimelock).toString(),
         };
     },
     deserializeParams(params) {
         const csvTimelock = params.csvTimelock
-            ? (0, helpers_1.sequenceToTimelock)(Number(params.csvTimelock))
+            ? (0, timelock_1.sequenceToTimelock)(Number(params.csvTimelock))
             : default_1.DefaultVtxo.Script.DEFAULT_TIMELOCK;
         return {
             pubKey: extractPubKeyBytes(params.pubKey),

package/dist/cjs/contracts/handlers/delegate.js

@@ -5,6 +5,7 @@ const base_1 = require("@scure/base");
 const delegate_1 = require("../../script/delegate");
 const default_1 = require("../../script/default");
 const helpers_1 = require("./helpers");
+const timelock_1 = require("../../utils/timelock");
 /**
  * Handler for delegate wallet virtual outputs.
  *
@@ -24,12 +25,12 @@ exports.DelegateContractHandler = {
             pubKey: base_1.hex.encode(params.pubKey),
             serverPubKey: base_1.hex.encode(params.serverPubKey),
             delegatePubKey: base_1.hex.encode(params.delegatePubKey),
-            csvTimelock: (0, helpers_1.timelockToSequence)(params.csvTimelock).toString(),
+            csvTimelock: (0, timelock_1.timelockToSequence)(params.csvTimelock).toString(),
         };
     },
     deserializeParams(params) {
         const csvTimelock = params.csvTimelock
-            ? (0, helpers_1.sequenceToTimelock)(Number(params.csvTimelock))
+            ? (0, timelock_1.sequenceToTimelock)(Number(params.csvTimelock))
             : default_1.DefaultVtxo.Script.DEFAULT_TIMELOCK;
         return {
             pubKey: base_1.hex.decode(params.pubKey),

package/dist/cjs/contracts/handlers/helpers.js

@@ -1,44 +1,9 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.timelockToSequence = timelockToSequence;
-exports.sequenceToTimelock = sequenceToTimelock;
 exports.resolveRole = resolveRole;
 exports.isCltvSatisfied = isCltvSatisfied;
 exports.isCsvSpendable = isCsvSpendable;
-const bip68 = __importStar(require("bip68"));
+const timelock_1 = require("../../utils/timelock");
 const descriptor_1 = require("../../identity/descriptor");
 /**
  * Extract raw hex pubkey from a value that may be a descriptor or raw hex.
@@ -56,27 +21,6 @@ function extractRawPubKey(value) {
         return undefined;
     }
 }
-/**
- * Convert RelativeTimelock to BIP68 sequence number.
- */
-function timelockToSequence(timelock) {
-    return bip68.encode(timelock.type === "blocks"
-        ? { blocks: Number(timelock.value) }
-        : { seconds: Number(timelock.value) });
-}
-/**
- * Convert BIP68 sequence number back to RelativeTimelock.
- */
-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}`);
-}
 /**
  * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */
@@ -152,7 +96,7 @@ function isCsvSpendable(context, sequence) {
         return true;
     if (!context.vtxo)
         return false;
-    const timelock = sequenceToTimelock(sequence);
+    const timelock = (0, timelock_1.sequenceToTimelock)(sequence);
     if (timelock.type === "blocks") {
         if (context.blockHeight === undefined ||
             context.vtxo.status.block_height === undefined) {

package/dist/cjs/contracts/handlers/vhtlc.js

@@ -4,6 +4,7 @@ exports.VHTLCContractHandler = void 0;
 const base_1 = require("@scure/base");
 const vhtlc_1 = require("../../script/vhtlc");
 const helpers_1 = require("./helpers");
+const timelock_1 = require("../../utils/timelock");
 /**
  * Handler for Virtual Hash Time Lock Contract (VHTLC).
  *
@@ -32,9 +33,9 @@ exports.VHTLCContractHandler = {
             server: base_1.hex.encode(params.server),
             hash: base_1.hex.encode(params.preimageHash),
             refundLocktime: params.refundLocktime.toString(),
-            claimDelay: (0, helpers_1.timelockToSequence)(params.unilateralClaimDelay).toString(),
-            refundDelay: (0, helpers_1.timelockToSequence)(params.unilateralRefundDelay).toString(),
-            refundNoReceiverDelay: (0, helpers_1.timelockToSequence)(params.unilateralRefundWithoutReceiverDelay).toString(),
+            claimDelay: (0, timelock_1.timelockToSequence)(params.unilateralClaimDelay).toString(),
+            refundDelay: (0, timelock_1.timelockToSequence)(params.unilateralRefundDelay).toString(),
+            refundNoReceiverDelay: (0, timelock_1.timelockToSequence)(params.unilateralRefundWithoutReceiverDelay).toString(),
         };
     },
     deserializeParams(params) {
@@ -44,9 +45,9 @@ exports.VHTLCContractHandler = {
             server: base_1.hex.decode(params.server),
             preimageHash: base_1.hex.decode(params.hash),
             refundLocktime: BigInt(params.refundLocktime),
-            unilateralClaimDelay: (0, helpers_1.sequenceToTimelock)(Number(params.claimDelay)),
-            unilateralRefundDelay: (0, helpers_1.sequenceToTimelock)(Number(params.refundDelay)),
-            unilateralRefundWithoutReceiverDelay: (0, helpers_1.sequenceToTimelock)(Number(params.refundNoReceiverDelay)),
+            unilateralClaimDelay: (0, timelock_1.sequenceToTimelock)(Number(params.claimDelay)),
+            unilateralRefundDelay: (0, timelock_1.sequenceToTimelock)(Number(params.refundDelay)),
+            unilateralRefundWithoutReceiverDelay: (0, timelock_1.sequenceToTimelock)(Number(params.refundNoReceiverDelay)),
         };
     },
     /**

package/dist/cjs/contracts/vtxoOwnership.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vtxoOutpoint = vtxoOutpoint;
+exports.isVtxoForScript = isVtxoForScript;
+exports.filterVtxosForScript = filterVtxosForScript;
+exports.warnAndFilterVtxosForScript = warnAndFilterVtxosForScript;
+exports.validateVtxosForScript = validateVtxosForScript;
+exports.getVtxosForContract = getVtxosForContract;
+exports.saveVtxosForContract = saveVtxosForContract;
+/**
+ * Tier 1 helpers that enforce VTXO ownership at call sites that already know
+ * the intended contract script. Address-keyed repositories may still hand back
+ * legacy duplicate rows under the wrong bucket; these helpers gate reads and
+ * writes so a wrong-script row never wins.
+ *
+ * `script` is the authoritative ownership key. Equality is strict: a missing
+ * or empty `vtxo.script` never matches.
+ */
+function vtxoOutpoint(vtxo) {
+    return `${vtxo.txid}:${vtxo.vout}`;
+}
+function isVtxoForScript(vtxo, script) {
+    return !!vtxo.script && vtxo.script === script;
+}
+function filterVtxosForScript(vtxos, script) {
+    return vtxos.filter((v) => isVtxoForScript(v, script));
+}
+/**
+ * Background/indexer sync flavour: drop wrong-script rows and log enough
+ * context to identify each rejection. Returns only matching rows so the
+ * caller can keep going.
+ */
+function warnAndFilterVtxosForScript(vtxos, script, context) {
+    const matches = [];
+    const rejected = [];
+    for (const v of vtxos) {
+        if (isVtxoForScript(v, script)) {
+            matches.push(v);
+        }
+        else {
+            rejected.push(`${vtxoOutpoint(v)}(script=${v.script ?? ""})`);
+        }
+    }
+    if (rejected.length > 0) {
+        console.warn(`${context}: dropped ${rejected.length} wrong-script VTXO(s) for script ${script}: ${rejected.join(", ")}`);
+    }
+    return matches;
+}
+/**
+ * User-initiated transaction/signing flavour: throw before persisting or
+ * signing inconsistent ownership state. Silently skipping here would hide a
+ * serious bug in the wallet's spend path.
+ */
+function validateVtxosForScript(vtxos, script, context) {
+    const mismatches = vtxos.filter((v) => !isVtxoForScript(v, script));
+    if (mismatches.length === 0)
+        return;
+    const detail = mismatches
+        .map((v) => `${vtxoOutpoint(v)}(script=${v.script ?? ""})`)
+        .join(", ");
+    throw new Error(`${context}: refusing to persist ${mismatches.length} VTXO(s) whose script does not match ${script}: ${detail}`);
+}
+/**
+ * Tier 2 dispatch helpers: route to script-scoped repository methods when
+ * available, falling back to Tier 1 address-based filtering otherwise.
+ */
+async function getVtxosForContract(repo, contract) {
+    return repo.getVtxosForScript
+        ? repo.getVtxosForScript(contract.script)
+        : filterVtxosForScript(await repo.getVtxos(contract.address), contract.script);
+}
+async function saveVtxosForContract(repo, contract, vtxos) {
+    if (repo.saveVtxosForScript) {
+        return repo.saveVtxosForScript({ script: contract.script, address: contract.address }, vtxos);
+    }
+    validateVtxosForScript(vtxos, contract.script, "saveVtxosForContract");
+    return repo.saveVtxos(contract.address, vtxos);
+}

package/dist/cjs/index.js

@@ -183,9 +183,9 @@ Object.defineProperty(exports, "decodeArkContract", { enumerable: true, get: fun
 Object.defineProperty(exports, "contractFromArkContract", { enumerable: true, get: function () { return contracts_1.contractFromArkContract; } });
 Object.defineProperty(exports, "contractFromArkContractWithAddress", { enumerable: true, get: function () { return contracts_1.contractFromArkContractWithAddress; } });
 Object.defineProperty(exports, "isArkContract", { enumerable: true, get: function () { return contracts_1.isArkContract; } });
-const helpers_1 = require("./contracts/handlers/helpers");
-Object.defineProperty(exports, "timelockToSequence", { enumerable: true, get: function () { return helpers_1.timelockToSequence; } });
-Object.defineProperty(exports, "sequenceToTimelock", { enumerable: true, get: function () { return helpers_1.sequenceToTimelock; } });
+const timelock_1 = require("./utils/timelock");
+Object.defineProperty(exports, "timelockToSequence", { enumerable: true, get: function () { return timelock_1.timelockToSequence; } });
+Object.defineProperty(exports, "sequenceToTimelock", { enumerable: true, get: function () { return timelock_1.sequenceToTimelock; } });
 const manager_1 = require("./repositories/indexedDB/manager");
 Object.defineProperty(exports, "closeDatabase", { enumerable: true, get: function () { return manager_1.closeDatabase; } });
 Object.defineProperty(exports, "openDatabase", { enumerable: true, get: function () { return manager_1.openDatabase; } });

package/dist/cjs/repositories/inMemory/walletRepository.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InMemoryWalletRepository = void 0;
+const vtxoOwnership_1 = require("../../contracts/vtxoOwnership");
 /**
  * In-memory implementation of WalletRepository.
  * Data is ephemeral and scoped to the instance.
@@ -24,6 +25,40 @@ class InMemoryWalletRepository {
     async deleteVtxos(address) {
         this.vtxosByAddress.delete(address);
     }
+    async getVtxosForScript(script) {
+        const allMatches = [];
+        for (const bucket of this.vtxosByAddress.values()) {
+            for (const vtxo of bucket) {
+                if ((0, vtxoOwnership_1.isVtxoForScript)(vtxo, script)) {
+                    allMatches.push(vtxo);
+                }
+            }
+        }
+        // Dedup by outpoint (last-write-wins across address buckets)
+        return mergeByKey([], allMatches, (item) => `${item.txid}:${item.vout}`);
+    }
+    async saveVtxosForScript(key, vtxos) {
+        if (!key.address) {
+            throw new Error("InMemoryWalletRepository requires an address");
+        }
+        for (const vtxo of vtxos) {
+            if (!(0, vtxoOwnership_1.isVtxoForScript)(vtxo, key.script)) {
+                throw new Error(`VTXO ${vtxo.txid}:${vtxo.vout} script mismatch: expected ${key.script}, got ${vtxo.script}`);
+            }
+        }
+        return this.saveVtxos(key.address, vtxos);
+    }
+    async deleteVtxosForScript(script) {
+        for (const [address, bucket] of this.vtxosByAddress.entries()) {
+            const next = bucket.filter((v) => !(0, vtxoOwnership_1.isVtxoForScript)(v, script));
+            if (next.length === 0) {
+                this.vtxosByAddress.delete(address);
+            }
+            else {
+                this.vtxosByAddress.set(address, next);
+            }
+        }
+    }
     async getUtxos(address) {
         return this.utxosByAddress.get(address) ?? [];
     }

package/dist/cjs/repositories/indexedDB/walletRepository.js

@@ -6,6 +6,7 @@ const manager_1 = require("./manager");
 const schema_1 = require("./schema");
 const scriptFromAddress_1 = require("../scriptFromAddress");
 const utils_1 = require("../../worker/browser/utils");
+const vtxoOwnership_1 = require("../../contracts/vtxoOwnership");
 /**
  * IndexedDB-based implementation of WalletRepository.
  */
@@ -144,6 +145,85 @@ class IndexedDBWalletRepository {
             throw error;
         }
     }
+    async getVtxosForScript(script) {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction([db_1.STORE_VTXOS], "readonly");
+                const store = transaction.objectStore(db_1.STORE_VTXOS);
+                const index = store.index("script");
+                const request = index.getAll(script);
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => {
+                    const results = request.result || [];
+                    try {
+                        // Defensive filter: only rows whose script matches.
+                        const matching = results.filter((r) => r.script === script);
+                        // Dedup same outpoint rows across address buckets.
+                        // Work on raw rows so the address field is available
+                        // for the canonicality tiebreaker.
+                        const byOutpoint = new Map();
+                        for (const row of matching) {
+                            const outpoint = `${row.txid}:${row.vout}`;
+                            const existing = byOutpoint.get(outpoint);
+                            if (!existing) {
+                                byOutpoint.set(outpoint, row);
+                                continue;
+                            }
+                            if (shouldReplaceVtxo(existing, row)) {
+                                byOutpoint.set(outpoint, row);
+                            }
+                        }
+                        resolve(Array.from(byOutpoint.values()).map(deserializeVtxoWithBackfill));
+                    }
+                    catch (err) {
+                        reject(err);
+                    }
+                };
+            });
+        }
+        catch (error) {
+            console.error(`Failed to get VTXOs for script ${script}:`, error);
+            throw error;
+        }
+    }
+    async saveVtxosForScript(key, vtxos) {
+        if (!key.address) {
+            throw new Error("IndexedDBWalletRepository requires an address");
+        }
+        for (const vtxo of vtxos) {
+            if (!(0, vtxoOwnership_1.isVtxoForScript)(vtxo, key.script)) {
+                throw new Error(`VTXO ${vtxo.txid}:${vtxo.vout} script mismatch: expected ${key.script}, got ${vtxo.script}`);
+            }
+        }
+        return this.saveVtxos(key.address, vtxos);
+    }
+    async deleteVtxosForScript(script) {
+        try {
+            const db = await this.getDB();
+            return new Promise((resolve, reject) => {
+                const transaction = db.transaction([db_1.STORE_VTXOS], "readwrite");
+                const store = transaction.objectStore(db_1.STORE_VTXOS);
+                const index = store.index("script");
+                const request = index.openCursor(IDBKeyRange.only(script));
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => {
+                    const cursor = request.result;
+                    if (cursor) {
+                        cursor.delete();
+                        cursor.continue();
+                    }
+                    else {
+                        resolve();
+                    }
+                };
+            });
+        }
+        catch (error) {
+            console.error(`Failed to clear VTXOs for script ${script}:`, error);
+            throw error;
+        }
+    }
     async getUtxos(address) {
         try {
             const db = await this.getDB();
@@ -355,3 +435,40 @@ function deserializeVtxoWithBackfill(o) {
     }
     return (0, db_1.deserializeVtxo)(o);
 }
+function isCanonicalRow(row) {
+    try {
+        return (0, scriptFromAddress_1.scriptFromArkAddress)(row.address) === row.script;
+    }
+    catch {
+        return false;
+    }
+}
+function shouldReplaceVtxo(existing, incoming) {
+    const existingCanonical = isCanonicalRow(existing);
+    const incomingCanonical = isCanonicalRow(incoming);
+    if (incomingCanonical && !existingCanonical)
+        return true;
+    if (existingCanonical && !incomingCanonical)
+        return false;
+    // Tie on canonicality, check lifecycle completeness
+    const existingWeight = getLifecycleWeight(existing);
+    const incomingWeight = getLifecycleWeight(incoming);
+    if (incomingWeight > existingWeight)
+        return true;
+    if (existingWeight > incomingWeight)
+        return false;
+    // Tie on weight, stable sort by address
+    return incoming.address < existing.address;
+}
+function getLifecycleWeight(v) {
+    let weight = 0;
+    if (v.isSpent !== undefined)
+        weight += 1;
+    if (v.spentBy)
+        weight += 2;
+    if (v.settledBy)
+        weight += 2;
+    if (v.arkTxId)
+        weight += 2;
+    return weight;
+}

package/dist/cjs/repositories/realm/walletRepository.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RealmWalletRepository = void 0;
 const serialization_1 = require("../serialization");
 const scriptFromAddress_1 = require("../scriptFromAddress");
+const vtxoOwnership_1 = require("../../contracts/vtxoOwnership");
 /**
  * Realm-based implementation of WalletRepository.
  *
@@ -88,6 +89,33 @@ class RealmWalletRepository {
             this.realm.delete(toDelete);
         });
     }
+    async getVtxosForScript(script) {
+        await this.ensureInit();
+        const results = this.realm
+            .objects("ArkVtxo")
+            .filtered("script == $0", script);
+        return [...results].map(vtxoObjectToDomain);
+    }
+    async saveVtxosForScript(key, vtxos) {
+        if (!key.address) {
+            throw new Error("RealmWalletRepository requires an address");
+        }
+        for (const vtxo of vtxos) {
+            if (!(0, vtxoOwnership_1.isVtxoForScript)(vtxo, key.script)) {
+                throw new Error(`VTXO ${vtxo.txid}:${vtxo.vout} script mismatch: expected ${key.script}, got ${vtxo.script}`);
+            }
+        }
+        return this.saveVtxos(key.address, vtxos);
+    }
+    async deleteVtxosForScript(script) {
+        await this.ensureInit();
+        this.realm.write(() => {
+            const toDelete = this.realm
+                .objects("ArkVtxo")
+                .filtered("script == $0", script);
+            this.realm.delete(toDelete);
+        });
+    }
     // ── UTXO management ────────────────────────────────────────────────
     async getUtxos(address) {
         await this.ensureInit();