@arkade-os/sdk 0.4.17 → 0.4.18

package/dist/esm/repositories/sqlite/walletRepository.js

@@ -1,4 +1,5 @@
 import { serializeVtxo, serializeUtxo, deserializeVtxo, deserializeUtxo, } from '../serialization.js';
+import { scriptFromArkAddress } from '../scriptFromAddress.js';
 /**
  * SQLite-based implementation of WalletRepository.
  *
@@ -29,30 +30,7 @@ export class SQLiteWalletRepository {
         return this.initPromise;
     }
     async init() {
-        await this.db.run(`
-            CREATE TABLE IF NOT EXISTS ${this.tables.vtxos} (
-                txid TEXT NOT NULL,
-                vout INTEGER NOT NULL,
-                value INTEGER NOT NULL,
-                address TEXT NOT NULL,
-                tap_tree TEXT NOT NULL,
-                forfeit_cb TEXT NOT NULL,
-                forfeit_s TEXT NOT NULL,
-                intent_cb TEXT NOT NULL,
-                intent_s TEXT NOT NULL,
-                status_json TEXT NOT NULL,
-                virtual_status_json TEXT NOT NULL,
-                created_at TEXT NOT NULL,
-                is_unrolled INTEGER NOT NULL DEFAULT 0,
-                is_spent INTEGER,
-                spent_by TEXT,
-                settled_by TEXT,
-                ark_tx_id TEXT,
-                extra_witness_json TEXT,
-                assets_json TEXT,
-                PRIMARY KEY (txid, vout)
-            )
-        `);
+        await this.migrateVtxosTable();
         await this.db.run(`
             CREATE TABLE IF NOT EXISTS ${this.tables.utxos} (
                 txid TEXT NOT NULL,
@@ -86,14 +64,121 @@ export class SQLiteWalletRepository {
         await this.db.run(`
             CREATE TABLE IF NOT EXISTS ${this.tables.walletState} (
                 key TEXT PRIMARY KEY,
-                last_sync_time INTEGER,
-                settings_json TEXT
+                settings_json TEXT,
+                last_sync_time INTEGER
             )
         `);
         await this.db.run(`CREATE INDEX IF NOT EXISTS idx_${this.prefix}vtxos_address ON ${this.tables.vtxos} (address)`);
+        await this.db.run(`CREATE INDEX IF NOT EXISTS idx_${this.prefix}vtxos_script ON ${this.tables.vtxos} (script)`);
         await this.db.run(`CREATE INDEX IF NOT EXISTS idx_${this.prefix}utxos_address ON ${this.tables.utxos} (address)`);
         await this.db.run(`CREATE INDEX IF NOT EXISTS idx_${this.prefix}transactions_address ON ${this.tables.transactions} (address)`);
     }
+    /**
+     * Bring the `vtxos` table to the current schema (v1 = `script` NOT NULL).
+     *
+     * Three cases:
+     *   - Fresh install: create the v1 schema directly.
+     *   - Legacy install without a `script` column: add it, backfill from
+     *     `address`, then rebuild the table with NOT NULL (SQLite cannot add
+     *     the NOT NULL constraint in place).
+     *   - Legacy install with a nullable `script` column: backfill the NULLs
+     *     and rebuild.
+     *
+     * The backfill derives `script` from the Ark address, matching what the
+     * indexer would have returned — new rows from the indexer always carry a
+     * populated `script`, so the migration is idempotent.
+     *
+     * The rebuild path is wrapped in a transaction: without it, a crash
+     * between the `DROP TABLE vtxos` and the `RENAME tmp → vtxos` commits
+     * would leave the next startup seeing no `vtxos` table and create a
+     * fresh empty one, silently orphaning every row in the temp table.
+     */
+    async migrateVtxosTable() {
+        const tableExists = await this.db.get(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`, [this.tables.vtxos]);
+        if (!tableExists) {
+            await this.db.run(this.vtxosCreateSql(this.tables.vtxos));
+            return;
+        }
+        const cols = await this.db.all(`PRAGMA table_info(${this.tables.vtxos})`);
+        const scriptCol = cols.find((c) => c.name === "script");
+        if (scriptCol && scriptCol.notnull === 1) {
+            // Already on v1 schema.
+            return;
+        }
+        await this.db.run("BEGIN IMMEDIATE");
+        try {
+            if (!scriptCol) {
+                await this.db.run(`ALTER TABLE ${this.tables.vtxos} ADD COLUMN script TEXT`);
+            }
+            // Backfill any NULL scripts from the owning address. Derivation
+            // is deterministic, so re-running after a rolled-back attempt
+            // produces the same values.
+            const nullRows = await this.db.all(`SELECT txid, vout, address FROM ${this.tables.vtxos} WHERE script IS NULL`);
+            for (const row of nullRows) {
+                await this.db.run(`UPDATE ${this.tables.vtxos} SET script = ? WHERE txid = ? AND vout = ?`, [scriptFromArkAddress(row.address), row.txid, row.vout]);
+            }
+            // SQLite can't turn a nullable column into NOT NULL in place —
+            // do the canonical 12-step table rebuild. Drop any stale temp
+            // table from a prior aborted attempt first.
+            const tempName = `${this.tables.vtxos}__migrate_tmp`;
+            await this.db.run(`DROP TABLE IF EXISTS ${tempName}`);
+            await this.db.run(this.vtxosCreateSql(tempName));
+            await this.db.run(`
+                INSERT INTO ${tempName}
+                    (txid, vout, value, address, tap_tree,
+                     forfeit_cb, forfeit_s, intent_cb, intent_s,
+                     status_json, virtual_status_json, created_at,
+                     is_unrolled, is_spent, spent_by, settled_by, ark_tx_id,
+                     extra_witness_json, assets_json, script)
+                SELECT txid, vout, value, address, tap_tree,
+                       forfeit_cb, forfeit_s, intent_cb, intent_s,
+                       status_json, virtual_status_json, created_at,
+                       is_unrolled, is_spent, spent_by, settled_by, ark_tx_id,
+                       extra_witness_json, assets_json, script
+                FROM ${this.tables.vtxos}
+            `);
+            await this.db.run(`DROP TABLE ${this.tables.vtxos}`);
+            await this.db.run(`ALTER TABLE ${tempName} RENAME TO ${this.tables.vtxos}`);
+            await this.db.run("COMMIT");
+        }
+        catch (e) {
+            // A failed COMMIT auto-rolls-back in SQLite, which makes a
+            // follow-up ROLLBACK throw "no transaction is active". Swallow
+            // that secondary error so the original cause surfaces.
+            try {
+                await this.db.run("ROLLBACK");
+            }
+            catch {
+                // already rolled back
+            }
+            throw e;
+        }
+    }
+    vtxosCreateSql(tableName) {
+        return `CREATE TABLE ${tableName} (
+            txid TEXT NOT NULL,
+            vout INTEGER NOT NULL,
+            value INTEGER NOT NULL,
+            address TEXT NOT NULL,
+            tap_tree TEXT NOT NULL,
+            forfeit_cb TEXT NOT NULL,
+            forfeit_s TEXT NOT NULL,
+            intent_cb TEXT NOT NULL,
+            intent_s TEXT NOT NULL,
+            status_json TEXT NOT NULL,
+            virtual_status_json TEXT NOT NULL,
+            created_at TEXT NOT NULL,
+            is_unrolled INTEGER NOT NULL DEFAULT 0,
+            is_spent INTEGER,
+            spent_by TEXT,
+            settled_by TEXT,
+            ark_tx_id TEXT,
+            extra_witness_json TEXT,
+            assets_json TEXT,
+            script TEXT NOT NULL,
+            PRIMARY KEY (txid, vout)
+        )`;
+    }
     async [Symbol.asyncDispose]() {
         // no-op — consumer owns the SQLExecutor lifecycle
     }
@@ -120,12 +205,12 @@ export class SQLiteWalletRepository {
                      tap_tree, forfeit_cb, forfeit_s, intent_cb, intent_s,
                      status_json, virtual_status_json, created_at,
                      is_unrolled, is_spent, spent_by, settled_by, ark_tx_id,
-                     extra_witness_json, assets_json)
+                     extra_witness_json, assets_json, script)
                  VALUES (?, ?, ?, ?,
                          ?, ?, ?, ?, ?,
                          ?, ?, ?,
                          ?, ?, ?, ?, ?,
-                         ?, ?)`, [
+                         ?, ?, ?)`, [
                 s.txid,
                 s.vout,
                 s.value,
@@ -149,6 +234,7 @@ export class SQLiteWalletRepository {
                 s.arkTxId ?? null,
                 s.extraWitness ? JSON.stringify(s.extraWitness) : null,
                 s.assets ? JSON.stringify(s.assets) : null,
+                s.script ?? null,
             ]);
         }
     }
@@ -228,22 +314,20 @@ export class SQLiteWalletRepository {
         if (!row)
             return null;
         const state = {};
-        if (row.last_sync_time !== null && row.last_sync_time !== undefined) {
-            state.lastSyncTime = row.last_sync_time;
-        }
         if (row.settings_json) {
             state.settings = JSON.parse(row.settings_json);
         }
+        state.lastSyncTime = row.last_sync_time ?? undefined;
         return state;
     }
     async saveWalletState(state) {
         await this.ensureInit();
         await this.db.run(`INSERT OR REPLACE INTO ${this.tables.walletState}
-                (key, last_sync_time, settings_json)
+                (key, settings_json, last_sync_time)
              VALUES (?, ?, ?)`, [
             "state",
-            state.lastSyncTime ?? null,
             state.settings ? JSON.stringify(state.settings) : null,
+            state.lastSyncTime ?? null,
         ]);
     }
 }
@@ -281,6 +365,10 @@ function vtxoRowToDomain(row) {
             ? JSON.parse(row.extra_witness_json)
             : undefined,
         assets: row.assets_json ? JSON.parse(row.assets_json) : undefined,
+        // Post-migration every row has `script`, but the backfill is
+        // idempotent: derive from `address` if the legacy column is still
+        // null (e.g. the migration hasn't run yet on this handle).
+        script: row.script ?? scriptFromArkAddress(row.address),
     };
     return deserializeVtxo(serialized);
 }

package/dist/esm/utils/syncCursors.js

@@ -1,11 +1,10 @@
 /** Lag behind real-time to avoid racing with indexer writes. */
 export const SAFETY_LAG_MS = 30000;
 /** Overlap window so boundary virtual outputs are never missed. */
-export const OVERLAP_MS = 60000;
+export const OVERLAP_MS = 24 * 60 * 60 * 1000;
 /**
  * Per-repository mutex that serializes wallet-state mutations so that
- * concurrent read-modify-write cycles (e.g. advanceSyncCursors racing
- * with clearSyncCursors or setPendingTxFlag) never silently overwrite
+ * concurrent read-modify-write cycles never silently overwrite
  * each other's changes.
  */
 const walletStateLocks = new WeakMap();
@@ -25,88 +24,83 @@ export async function updateWalletState(repo, updater) {
     return op;
 }
 /**
- * Read the high-water mark for a single script.
- * Returns `undefined` when the script has never been synced (bootstrap case).
+ * Settings key that gates interpretation of the `lastSyncTime` field.
+ *
+ * The `lastSyncTime` column existed pre-PR with a different semantic
+ * (wall-clock at sync completion, written by the buggy sync loop this
+ * PR fixes). On upgrade we cannot trust any pre-existing value, so the
+ * cursor is only honoured after the first successful post-upgrade
+ * advance writes this marker into the `settings` JSON blob. Reusing
+ * `settings` avoids any schema migration.
  */
-export async function getSyncCursor(repo, script) {
-    const state = await repo.getWalletState();
-    return state?.settings?.vtxoSyncCursors?.[script];
+const CURSOR_MIGRATED_KEY = "vtxoCursorMigrated";
+function hasMigrationMarker(state) {
+    return state?.settings?.[CURSOR_MIGRATED_KEY] === true;
 }
 /**
- * Read cursors for every previously-synced script.
+ * Read the global high-water mark for VTXO indexer syncs.
+ *
+ * Returns `0` when:
+ *  - the wallet has never been synced (bootstrap case), or
+ *  - the stored `lastSyncTime` was written by pre-PR code and is not
+ *    safe to reuse under the new semantics (see {@link CURSOR_MIGRATED_KEY}).
  */
-export async function getAllSyncCursors(repo) {
+export async function getSyncCursor(repo) {
     const state = await repo.getWalletState();
-    return state?.settings?.vtxoSyncCursors ?? {};
+    if (!hasMigrationMarker(state))
+        return 0;
+    return state?.lastSyncTime ?? 0;
 }
 /**
- * Advance the cursor for one script after a successful delta sync.
- * `cursor` should be the `before` cutoff used in the request.
- */
-export async function advanceSyncCursor(repo, script, cursor) {
-    await updateWalletState(repo, (state) => {
-        const existing = state.settings?.vtxoSyncCursors ?? {};
-        return {
-            ...state,
-            settings: {
-                ...state.settings,
-                vtxoSyncCursors: { ...existing, [script]: cursor },
-            },
-        };
-    });
-}
-/**
- * Advance cursors for multiple scripts in a single write.
+ * Advance the global cursor after a successful full-scope delta sync.
+ *
+ * Clamped with `Math.max` against the current value so concurrent syncs
+ * that finish out of order can't rewind the cursor: `lastUpdatedAt` is
+ * captured before each sync enters the `updateWalletState` mutex, and
+ * the later-started sync would otherwise overwrite the earlier-captured
+ * one with a smaller value. The legacy value is discarded on the first
+ * advance if the migration marker is absent so pre-PR data doesn't
+ * survive the upgrade.
  */
-export async function advanceSyncCursors(repo, updates) {
+export async function advanceSyncCursor(repo, lastUpdatedAt) {
     await updateWalletState(repo, (state) => {
-        const existing = state.settings?.vtxoSyncCursors ?? {};
+        const current = hasMigrationMarker(state)
+            ? (state.lastSyncTime ?? 0)
+            : 0;
         return {
             ...state,
+            lastSyncTime: Math.max(current, lastUpdatedAt),
             settings: {
-                ...state.settings,
-                vtxoSyncCursors: { ...existing, ...updates },
+                ...(state.settings ?? {}),
+                [CURSOR_MIGRATED_KEY]: true,
             },
         };
     });
 }
 /**
- * Remove sync cursors, forcing a full re-bootstrap on next sync.
- * When `scripts` is provided, only those cursors are cleared.
+ * Remove the sync cursor, forcing a full re-bootstrap on next sync.
+ *
+ * Also clears the migration marker so any stored `lastSyncTime` is
+ * treated as untrusted on the next read.
  */
-export async function clearSyncCursors(repo, scripts) {
+export async function clearSyncCursor(repo) {
     await updateWalletState(repo, (state) => {
-        if (!scripts) {
-            const { vtxoSyncCursors: _, ...restSettings } = state.settings ?? {};
-            return {
-                ...state,
-                settings: restSettings,
-            };
-        }
-        const existing = state.settings?.vtxoSyncCursors ?? {};
-        const filtered = { ...existing };
-        for (const s of scripts)
-            delete filtered[s];
+        const { [CURSOR_MIGRATED_KEY]: _, ...restSettings } = state.settings ?? {};
         return {
             ...state,
-            settings: {
-                ...state.settings,
-                vtxoSyncCursors: filtered,
-            },
+            lastSyncTime: undefined,
+            settings: restSettings,
         };
     });
 }
 /**
  * Compute the `after` lower-bound for a delta sync query.
- * Returns `undefined` when the script has no cursor (bootstrap needed).
  *
  * No upper bound (`before`) is applied to the query so that freshly
  * created virtual outputs are never excluded. The safety lag is applied only
  * when advancing the cursor (see @see cursorCutoff).
  */
 export function computeSyncWindow(cursor) {
-    if (cursor === undefined)
-        return undefined;
     const after = Math.max(0, cursor - OVERLAP_MS);
     return { after };
 }

package/dist/esm/wallet/expo/background.js

@@ -1,7 +1,5 @@
-import { hex } from "@scure/base";
 import { runTasks, createTaskDependencies } from '../../worker/expo/taskRunner.js';
 import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from '../../worker/expo/processors/index.js';
-import { DefaultVtxo } from '../../script/default.js';
 import { ExpoArkProvider } from '../../providers/expoArk.js';
 import { ExpoIndexerProvider } from '../../providers/expoIndexer.js';
 import { getRandomId } from '../utils.js';
@@ -59,22 +57,11 @@ export function defineExpoBackgroundTask(taskName, options) {
             // Reconstruct providers
             const indexerProvider = new ExpoIndexerProvider(config.arkServerUrl);
             const arkProvider = new ExpoArkProvider(config.arkServerUrl);
-            // Reconstruct default offchainTapscript as fallback
-            // for virtual outputs not associated with a contract.
-            const offchainTapscript = new DefaultVtxo.Script({
-                pubKey: hex.decode(config.pubkeyHex),
-                serverPubKey: hex.decode(config.serverPubKeyHex),
-                csvTimelock: {
-                    value: BigInt(config.exitTimelockValue),
-                    type: config.exitTimelockType,
-                },
-            });
             const deps = createTaskDependencies({
                 walletRepository,
                 contractRepository,
                 indexerProvider,
                 arkProvider,
-                offchainTapscript,
             });
             await runTasks(taskQueue, processors, deps);
             // Acknowledge outbox results (no foreground to consume them)

package/dist/esm/wallet/expo/wallet.js

@@ -3,7 +3,7 @@ import { Wallet } from '../wallet.js';
 import { RestArkProvider } from '../../providers/ark.js';
 import { runTasks } from '../../worker/expo/taskRunner.js';
 import { contractPollProcessor, CONTRACT_POLL_TASK_TYPE, } from '../../worker/expo/processors/index.js';
-import { extendVirtualCoin, extendVtxoFromContract, getRandomId, } from '../utils.js';
+import { extendVirtualCoinForContract, getRandomId } from '../utils.js';
 import { DefaultVtxo } from '../../script/default.js';
 /**
  * Expo/React Native wallet with built-in background task processing.
@@ -67,12 +67,7 @@ export class ExpoWallet {
             contractRepository: wallet.contractRepository,
             indexerProvider: wallet.indexerProvider,
             arkProvider: wallet.arkProvider,
-            extendVtxo: (vtxo, contract) => {
-                if (contract) {
-                    return extendVtxoFromContract(vtxo, contract);
-                }
-                return extendVirtualCoin(wallet, vtxo);
-            },
+            extendVtxo: (vtxo, contract) => extendVirtualCoinForContract(vtxo, contract),
         };
         const { taskQueue } = config.background;
         // Persist wallet params so the background handler can rehydrate

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

@@ -1,6 +1,6 @@
 import { RestIndexerProvider } from '../../providers/indexer.js';
 import { isExpired, isRecoverable, isSpendable, isSubdust, } from '../index.js';
-import { extendCoin, extendVirtualCoin } from '../utils.js';
+import { extendCoin } from '../utils.js';
 import { buildTransactionHistory } from '../../utils/transactionHistory.js';
 export class WalletNotInitializedError extends Error {
     constructor() {
@@ -239,6 +239,15 @@ export class WalletMessageHandler {
                         payload: { contracts },
                     });
                 }
+                case "ANNOTATE_VTXOS": {
+                    const manager = await this.readonlyWallet.getContractManager();
+                    const annotated = await manager.annotateVtxos(message.payload.vtxos);
+                    return this.tagged({
+                        id,
+                        type: "ANNOTATED_VTXOS",
+                        payload: { vtxos: annotated },
+                    });
+                }
                 case "UPDATE_CONTRACT": {
                     const manager = await this.readonlyWallet.getContractManager();
                     const contract = await manager.updateContract(message.payload.script, message.payload.updates);
@@ -554,13 +563,13 @@ export class WalletMessageHandler {
         this.incomingFundsSubscription =
             await this.readonlyWallet.notifyIncomingFunds(async (funds) => {
                 if (funds.type === "vtxo") {
-                    const newVtxos = funds.newVtxos.length > 0
-                        ? funds.newVtxos.map((vtxo) => extendVirtualCoin(this.readonlyWallet, vtxo))
-                        : [];
-                    const spentVtxos = funds.spentVtxos.length > 0
-                        ? funds.spentVtxos.map((vtxo) => extendVirtualCoin(this.readonlyWallet, vtxo))
-                        : [];
-                    if ([...newVtxos, ...spentVtxos].length === 0)
+                    // `funds.newVtxos` / `funds.spentVtxos` are already
+                    // ExtendedVirtualCoin — annotation happened inside the
+                    // underlying Wallet's subscription handler before this
+                    // callback fired. Re-annotating here would only duplicate
+                    // work and re-expose us to `annotateVtxos` throws.
+                    const { newVtxos, spentVtxos } = funds;
+                    if (newVtxos.length + spentVtxos.length === 0)
                         return;
                     // save virtual outputs using unified repository
                     await this.walletRepository?.saveVtxos(address, [

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

@@ -25,6 +25,7 @@ export const DEFAULT_MESSAGE_TIMEOUTS = {
     GET_TRANSACTION_HISTORY: 20000,
     GET_CONTRACTS: 20000,
     GET_CONTRACTS_WITH_VTXOS: 20000,
+    ANNOTATE_VTXOS: 20000,
     GET_SPENDABLE_PATHS: 20000,
     GET_ALL_SPENDING_PATHS: 20000,
     GET_ASSET_DETAILS: 20000,
@@ -66,6 +67,7 @@ const DEDUPABLE_REQUEST_TYPES = new Set([
     "GET_VTXOS",
     "GET_CONTRACTS",
     "GET_CONTRACTS_WITH_VTXOS",
+    "ANNOTATE_VTXOS",
     "GET_SPENDABLE_PATHS",
     "GET_ALL_SPENDING_PATHS",
     "GET_ASSET_DETAILS",
@@ -653,6 +655,23 @@ export class ServiceWorkerReadonlyWallet {
                     throw new Error("Failed to get contracts with vtxos");
                 }
             },
+            async annotateVtxos(vtxos) {
+                if (vtxos.length === 0)
+                    return [];
+                const message = {
+                    type: "ANNOTATE_VTXOS",
+                    id: getRandomId(),
+                    tag: messageTag,
+                    payload: { vtxos },
+                };
+                try {
+                    const response = await sendContractMessage(message);
+                    return response.payload.vtxos;
+                }
+                catch (e) {
+                    throw new Error("Failed to annotate vtxos");
+                }
+            },
             async updateContract(script, updates) {
                 const message = {
                     type: "UPDATE_CONTRACT",

package/dist/esm/wallet/utils.js

@@ -2,14 +2,6 @@ import { ArkAddress, } from '../index.js';
 import { contractHandlers } from '../contracts/handlers/index.js';
 import { hex } from "@scure/base";
 export const DUST_AMOUNT = 546; // sats
-export function extendVirtualCoin(wallet, vtxo) {
-    return {
-        ...vtxo,
-        forfeitTapLeafScript: wallet.offchainTapscript.forfeit(),
-        intentTapLeafScript: wallet.offchainTapscript.forfeit(),
-        tapTree: wallet.offchainTapscript.encode(),
-    };
-}
 export function extendCoin(wallet, utxo) {
     return {
         ...utxo,
@@ -18,7 +10,7 @@ export function extendCoin(wallet, utxo) {
         tapTree: wallet.boardingTapscript.encode(),
     };
 }
-export function extendVtxoFromContract(vtxo, contract) {
+function extendVtxoFromContract(vtxo, contract) {
     const handler = contractHandlers.get(contract.type);
     if (!handler) {
         throw new Error(`No handler for contract type '${contract.type}'`);
@@ -31,6 +23,46 @@ export function extendVtxoFromContract(vtxo, contract) {
         tapTree: script.encode(),
     };
 }
+/**
+ * Extend a VirtualCoin with the tap scripts of whichever contract locks it.
+ *
+ * The second argument accepts either form, so each callsite passes what it
+ * already has:
+ * - a single `Contract` (when the caller already knows the owning contract,
+ *   e.g. the contract manager iterating its own `scriptToContract` map), or
+ * - a `ReadonlyMap<script, Contract>` (when the caller resolves by
+ *   `vtxo.script`, populated by the indexer).
+ *
+ * Throws when no contract can be resolved — there is intentionally no
+ * default-tapscript fallback. When the wallet owns multiple contracts
+ * (default + delegate, several active vHTLCs, etc.) a default-tapscript path
+ * silently stamps every VTXO with the same forfeit/intent data, overwriting
+ * the correct data for any VTXO locked to a non-default contract. Callers
+ * must feed a Contract or a populated script→Contract map; otherwise the
+ * caller (typically `ContractManager.annotateVtxos`) should fetch the owning
+ * contract first.
+ */
+export function extendVirtualCoinForContract(vtxo, contractOrMap) {
+    const contract = resolveContract(vtxo, contractOrMap);
+    if (!contract) {
+        throw new Error("extendVirtualCoinForContract: no contract matched vtxo.script — callers must resolve the owning contract before annotating");
+    }
+    return extendVtxoFromContract(vtxo, contract);
+}
+function isContractMap(value) {
+    // A `Contract` is a plain object with a string `type`. `ReadonlyMap` is
+    // an interface so `instanceof Map` is not enough to narrow it — but a
+    // contract has no `get` method, so duck-typing on that is unambiguous.
+    return typeof value.get === "function";
+}
+function resolveContract(vtxo, contractOrMap) {
+    if (!contractOrMap)
+        return undefined;
+    if (isContractMap(contractOrMap)) {
+        return contractOrMap.get(vtxo.script);
+    }
+    return contractOrMap;
+}
 export function getRandomId() {
     const randomValue = crypto.getRandomValues(new Uint8Array(16));
     return hex.encode(randomValue);