@bsv/wallet-toolbox 2.1.25 → 3.0.0-alpha.0

package/out/src/storage/schema/backfill.knex.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnexBackfillDriver = void 0;
+exports.runKnexBackfill = runKnexBackfill;
+const backfill_runner_1 = require("./backfill.runner");
+const STREAM_BATCH = 500;
+/**
+ * Knex driver for the the backfill.
+ *
+ * Reads from the legacy `proven_tx_reqs`, `proven_txs`, and `transactions`
+ * tables, writes into the new `transactions_new` and `actions` tables, and
+ * re-points `tx_labels_map` rows to the new `actionId`.
+ *
+ * All work is performed against the `knex` (or transaction) handle passed in.
+ * The caller is responsible for opening a transaction around the orchestrator
+ * call when atomicity is desired.
+ */
+class KnexBackfillDriver {
+    constructor(knex) {
+        this.knex = knex;
+    }
+    async *streamLegacyReqs() {
+        var _a, _b, _c;
+        let lastId = 0;
+        /* eslint-disable-next-line no-constant-condition */
+        while (true) {
+            const rows = await this.knex('proven_tx_reqs as r')
+                .leftJoin('proven_txs as p', 'r.provenTxId', 'p.provenTxId')
+                .select('r.*', this.knex.ref('p.height').as('p_height'), this.knex.ref('p.index').as('p_index'), this.knex.ref('p.merklePath').as('p_merklePath'), this.knex.ref('p.blockHash').as('p_blockHash'), this.knex.ref('p.merkleRoot').as('p_merkleRoot'), this.knex.ref('p.rawTx').as('p_rawTx'), this.knex.ref('p.created_at').as('p_created_at'), this.knex.ref('p.updated_at').as('p_updated_at'), this.knex.ref('p.txid').as('p_txid'))
+                .where('r.provenTxReqId', '>', lastId)
+                .orderBy('r.provenTxReqId')
+                .limit(STREAM_BATCH);
+            if (rows.length === 0)
+                return;
+            for (const row of rows) {
+                lastId = row.provenTxReqId;
+                const req = {
+                    created_at: row.created_at,
+                    updated_at: row.updated_at,
+                    provenTxReqId: row.provenTxReqId,
+                    provenTxId: row.provenTxId,
+                    status: row.status,
+                    attempts: row.attempts,
+                    notified: row.notified,
+                    txid: row.txid,
+                    batch: row.batch,
+                    history: row.history,
+                    notify: row.notify,
+                    rawTx: (_a = toBytes(row.rawTx)) !== null && _a !== void 0 ? _a : [],
+                    inputBEEF: toBytes(row.inputBEEF),
+                    wasBroadcast: row.wasBroadcast,
+                    rebroadcastAttempts: row.rebroadcastAttempts
+                };
+                let proven;
+                if (row.p_txid != null) {
+                    proven = {
+                        created_at: row.p_created_at,
+                        updated_at: row.p_updated_at,
+                        provenTxId: row.provenTxId,
+                        txid: row.p_txid,
+                        height: row.p_height,
+                        index: row.p_index,
+                        merklePath: (_b = toBytes(row.p_merklePath)) !== null && _b !== void 0 ? _b : [],
+                        rawTx: (_c = toBytes(row.p_rawTx)) !== null && _c !== void 0 ? _c : [],
+                        blockHash: row.p_blockHash,
+                        merkleRoot: row.p_merkleRoot
+                    };
+                }
+                yield { req, proven };
+            }
+        }
+    }
+    async *streamLegacyTransactions() {
+        let lastId = 0;
+        /* eslint-disable-next-line no-constant-condition */
+        while (true) {
+            const rows = await this.knex('transactions')
+                .where('transactionId', '>', lastId)
+                .orderBy('transactionId')
+                .limit(STREAM_BATCH)
+                .select('*');
+            if (rows.length === 0)
+                return;
+            for (const row of rows) {
+                lastId = row.transactionId;
+                yield {
+                    created_at: row.created_at,
+                    updated_at: row.updated_at,
+                    transactionId: row.transactionId,
+                    userId: row.userId,
+                    provenTxId: row.provenTxId,
+                    status: row.status,
+                    reference: row.reference,
+                    isOutgoing: !!row.isOutgoing,
+                    satoshis: row.satoshis,
+                    description: row.description,
+                    version: row.version,
+                    lockTime: row.lockTime,
+                    txid: row.txid,
+                    inputBEEF: toBytes(row.inputBEEF),
+                    rawTx: toBytes(row.rawTx)
+                };
+            }
+        }
+    }
+    async upsertTransactionNew(row) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
+        const existing = await this.knex('transactions_new').where({ txid: row.txid }).first('transactionId');
+        if (existing != null) {
+            await this.knex('transactions_new')
+                .where({ transactionId: existing.transactionId })
+                .update({
+                processing: row.processing,
+                processing_changed_at: row.processingChangedAt,
+                next_action_at: (_a = row.nextActionAt) !== null && _a !== void 0 ? _a : null,
+                attempts: row.attempts,
+                rebroadcast_cycles: row.rebroadcastCycles,
+                was_broadcast: row.wasBroadcast,
+                batch: (_b = row.batch) !== null && _b !== void 0 ? _b : null,
+                raw_tx: toBuf(row.rawTx),
+                input_beef: toBuf(row.inputBeef),
+                height: (_c = row.height) !== null && _c !== void 0 ? _c : null,
+                merkle_index: (_d = row.merkleIndex) !== null && _d !== void 0 ? _d : null,
+                merkle_path: toBuf(row.merklePath),
+                merkle_root: (_e = row.merkleRoot) !== null && _e !== void 0 ? _e : null,
+                block_hash: (_f = row.blockHash) !== null && _f !== void 0 ? _f : null,
+                is_coinbase: row.isCoinbase,
+                updated_at: row.updated_at
+            });
+            return existing.transactionId;
+        }
+        const [insertedId] = await this.knex('transactions_new').insert({
+            txid: row.txid,
+            processing: row.processing,
+            processing_changed_at: row.processingChangedAt,
+            next_action_at: (_g = row.nextActionAt) !== null && _g !== void 0 ? _g : null,
+            attempts: row.attempts,
+            rebroadcast_cycles: row.rebroadcastCycles,
+            was_broadcast: row.wasBroadcast,
+            idempotency_key: (_h = row.idempotencyKey) !== null && _h !== void 0 ? _h : null,
+            batch: (_j = row.batch) !== null && _j !== void 0 ? _j : null,
+            raw_tx: toBuf(row.rawTx),
+            input_beef: toBuf(row.inputBeef),
+            height: (_k = row.height) !== null && _k !== void 0 ? _k : null,
+            merkle_index: (_l = row.merkleIndex) !== null && _l !== void 0 ? _l : null,
+            merkle_path: toBuf(row.merklePath),
+            merkle_root: (_m = row.merkleRoot) !== null && _m !== void 0 ? _m : null,
+            block_hash: (_o = row.blockHash) !== null && _o !== void 0 ? _o : null,
+            is_coinbase: row.isCoinbase,
+            last_provider: (_p = row.lastProvider) !== null && _p !== void 0 ? _p : null,
+            last_provider_status: (_q = row.lastProviderStatus) !== null && _q !== void 0 ? _q : null,
+            frozen_reason: (_r = row.frozenReason) !== null && _r !== void 0 ? _r : null,
+            row_version: row.rowVersion,
+            created_at: row.created_at,
+            updated_at: row.updated_at
+        });
+        if (typeof insertedId === 'number' && insertedId > 0)
+            return insertedId;
+        const row2 = await this.knex('transactions_new').where({ txid: row.txid }).first('transactionId');
+        return row2.transactionId;
+    }
+    async upsertAction(row) {
+        var _a, _b;
+        const existing = await this.knex('actions')
+            .where({ userId: row.userId, transactionId: row.transactionId })
+            .first('actionId');
+        if (existing != null) {
+            await this.knex('actions')
+                .where({ actionId: existing.actionId })
+                .update({
+                reference: row.reference,
+                description: row.description,
+                isOutgoing: row.isOutgoing,
+                satoshis_delta: row.satoshisDelta,
+                user_nosend: row.userNosend,
+                hidden: row.hidden,
+                user_aborted: row.userAborted,
+                notify_json: (_a = row.notifyJson) !== null && _a !== void 0 ? _a : null,
+                updated_at: row.updated_at
+            });
+            return existing.actionId;
+        }
+        const [insertedId] = await this.knex('actions').insert({
+            userId: row.userId,
+            transactionId: row.transactionId,
+            reference: row.reference,
+            description: row.description,
+            isOutgoing: row.isOutgoing,
+            satoshis_delta: row.satoshisDelta,
+            user_nosend: row.userNosend,
+            hidden: row.hidden,
+            user_aborted: row.userAborted,
+            notify_json: (_b = row.notifyJson) !== null && _b !== void 0 ? _b : null,
+            row_version: row.rowVersion,
+            created_at: row.created_at,
+            updated_at: row.updated_at
+        });
+        if (typeof insertedId === 'number' && insertedId > 0)
+            return insertedId;
+        const row2 = await this.knex('actions')
+            .where({ userId: row.userId, transactionId: row.transactionId })
+            .first('actionId');
+        return row2.actionId;
+    }
+    async repointTxLabelMap(legacyTransactionId, actionId) {
+        if (legacyTransactionId === actionId)
+            return;
+        await this.knex('tx_labels_map')
+            .where({ transactionId: legacyTransactionId })
+            .update({ transactionId: actionId });
+    }
+}
+exports.KnexBackfillDriver = KnexBackfillDriver;
+/**
+ * Convenience entry point. Opens a Knex transaction and runs the orchestrator
+ * inside it so that the entire backfill either succeeds or rolls back.
+ */
+async function runKnexBackfill(knex, now = new Date()) {
+    return await knex.transaction(async (trx) => {
+        const driver = new KnexBackfillDriver(trx);
+        return await (0, backfill_runner_1.runBackfill)(driver, now);
+    });
+}
+function toBytes(v) {
+    if (v == null)
+        return undefined;
+    if (Array.isArray(v))
+        return v;
+    if (Buffer.isBuffer(v))
+        return Array.from(v.values());
+    if (v instanceof Uint8Array)
+        return Array.from(v.values());
+    return undefined;
+}
+function toBuf(v) {
+    if (v == null)
+        return null;
+    return Buffer.from(v);
+}
+//# sourceMappingURL=backfill.knex.js.map

package/out/src/storage/schema/backfill.knex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.knex.js","sourceRoot":"","sources":["../../../../src/storage/schema/backfill.knex.ts"],"names":[],"mappings":"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"}

package/out/src/storage/schema/backfill.runner.d.ts

@@ -0,0 +1,63 @@
+import { TableAction, TableProvenTx, TableProvenTxReq, TableTransaction, TableTransactionNew } from './tables';
+/**
+ * Storage-agnostic driver used by the the backfill orchestrator.
+ *
+ * Implementations must be idempotent — calling each method twice with the same
+ * input must not produce duplicate rows. The orchestrator is responsible for
+ * iteration order and chunking; the driver only performs writes.
+ */
+export interface BackfillDriver {
+    /** Stream legacy `proven_tx_reqs` rows joined with their `proven_txs` row when available. */
+    streamLegacyReqs: () => AsyncIterable<{
+        req: TableProvenTxReq;
+        proven?: TableProvenTx;
+    }>;
+    /** Stream legacy `transactions` rows ordered by transactionId ascending. */
+    streamLegacyTransactions: () => AsyncIterable<TableTransaction>;
+    /**
+     * Upsert a new `transactions` row by `txid`. Returns the resolved
+     * `transactionId` (PK of `transactions_new`).
+     */
+    upsertTransactionNew: (row: Omit<TableTransactionNew, 'transactionId'>) => Promise<number>;
+    /**
+     * Upsert a new `actions` row by `(userId, transactionId)`. Returns the
+     * resolved `actionId`.
+     */
+    upsertAction: (row: Omit<TableAction, 'actionId'>) => Promise<number>;
+    /**
+     * Re-point a single legacy `tx_labels_map` row whose `transactionId` refers
+     * to the old `transactions` PK so that it points to the new `actions.actionId`.
+     *
+     * Implementations may choose to rewrite the entire mapping in bulk and treat
+     * this method as a no-op; the orchestrator will still call it once per pair.
+     */
+    repointTxLabelMap: (legacyTransactionId: number, actionId: number) => Promise<void>;
+}
+export interface BackfillStats {
+    reqsBackfilled: number;
+    legacyTxOnlyBackfilled: number;
+    actionsBackfilled: number;
+    labelMapsRepointed: number;
+}
+/**
+ * Orchestrates §3 Steps 2-5 of the spec (PROD_REQ_V7_TS.md).
+ *
+ * Strategy:
+ *  1. Walk every `proven_tx_reqs` row (joined with its proof) and upsert a row
+ *     in `transactions_new`. Build a `txid -> transactionId` map.
+ *  2. Walk every legacy `transactions` row.
+ *     - If the row has a txid AND it is not in the map, upsert a tx-only new-schema
+ *       row (locally-created actions that never reached the broadcast queue).
+ *     - Compute the new-schema `transactionId` for this legacy row. Rows without a
+ *       txid (unsigned, unprocessed) are skipped — they have no canonical new-schema
+ *       representation yet and are surfaced as gaps in the stats.
+ *  3. Upsert an `actions` row per legacy `transactions` row that has a new-schema
+ *     transactionId.
+ *  4. Re-point `tx_labels_map.transactionId` from legacy PK to new `actionId`.
+ *
+ * The driver is invoked one row at a time so that the entire pass can run as
+ * a single Knex transaction or a single IDB readwrite transaction without
+ * holding the full row set in memory.
+ */
+export declare function runBackfill(driver: BackfillDriver, now?: Date): Promise<BackfillStats>;
+//# sourceMappingURL=backfill.runner.d.ts.map

package/out/src/storage/schema/backfill.runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.runner.d.ts","sourceRoot":"","sources":["../../../../src/storage/schema/backfill.runner.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,UAAU,CAAA;AAEjB;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,gBAAgB,EAAE,MAAM,aAAa,CAAC;QAAE,GAAG,EAAE,gBAAgB,CAAC;QAAC,MAAM,CAAC,EAAE,aAAa,CAAA;KAAE,CAAC,CAAA;IACxF,4EAA4E;IAC5E,wBAAwB,EAAE,MAAM,aAAa,CAAC,gBAAgB,CAAC,CAAA;IAC/D;;;OAGG;IACH,oBAAoB,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1F;;;OAGG;IACH,YAAY,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACrE;;;;;;OAMG;IACH,iBAAiB,EAAE,CAAC,mBAAmB,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACpF;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,sBAAsB,EAAE,MAAM,CAAA;IAC9B,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAE,MAAM,EAAE,cAAc,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CA2CzG"}

package/out/src/storage/schema/backfill.runner.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBackfill = runBackfill;
+const backfill_1 = require("./backfill");
+/**
+ * Orchestrates §3 Steps 2-5 of the spec (PROD_REQ_V7_TS.md).
+ *
+ * Strategy:
+ *  1. Walk every `proven_tx_reqs` row (joined with its proof) and upsert a row
+ *     in `transactions_new`. Build a `txid -> transactionId` map.
+ *  2. Walk every legacy `transactions` row.
+ *     - If the row has a txid AND it is not in the map, upsert a tx-only new-schema
+ *       row (locally-created actions that never reached the broadcast queue).
+ *     - Compute the new-schema `transactionId` for this legacy row. Rows without a
+ *       txid (unsigned, unprocessed) are skipped — they have no canonical new-schema
+ *       representation yet and are surfaced as gaps in the stats.
+ *  3. Upsert an `actions` row per legacy `transactions` row that has a new-schema
+ *     transactionId.
+ *  4. Re-point `tx_labels_map.transactionId` from legacy PK to new `actionId`.
+ *
+ * The driver is invoked one row at a time so that the entire pass can run as
+ * a single Knex transaction or a single IDB readwrite transaction without
+ * holding the full row set in memory.
+ */
+async function runBackfill(driver, now = new Date()) {
+    const stats = {
+        reqsBackfilled: 0,
+        legacyTxOnlyBackfilled: 0,
+        actionsBackfilled: 0,
+        labelMapsRepointed: 0
+    };
+    const txidToNewId = new Map();
+    for await (const { req, proven } of driver.streamLegacyReqs()) {
+        const newRow = (0, backfill_1.buildTransactionNewRow)(req, proven, now);
+        const id = await driver.upsertTransactionNew(newRow);
+        txidToNewId.set(newRow.txid, id);
+        stats.reqsBackfilled += 1;
+    }
+    for await (const legacy of driver.streamLegacyTransactions()) {
+        let newId;
+        if (legacy.txid != null) {
+            newId = txidToNewId.get(legacy.txid);
+            if (newId === undefined) {
+                const newRow = (0, backfill_1.buildTransactionNewRowFromLegacyTx)(legacy, now);
+                if (newRow !== undefined) {
+                    newId = await driver.upsertTransactionNew(newRow);
+                    // Use newRow.txid (not legacy.txid) as the map key so that empty-string
+                    // legacy txids each get a unique placeholder key and don't collide.
+                    txidToNewId.set(newRow.txid, newId);
+                    stats.legacyTxOnlyBackfilled += 1;
+                }
+            }
+        }
+        if (newId === undefined)
+            continue;
+        const actionRow = (0, backfill_1.buildActionRow)(legacy, newId, now);
+        const actionId = await driver.upsertAction(actionRow);
+        stats.actionsBackfilled += 1;
+        await driver.repointTxLabelMap(legacy.transactionId, actionId);
+        stats.labelMapsRepointed += 1;
+    }
+    return stats;
+}
+//# sourceMappingURL=backfill.runner.js.map

package/out/src/storage/schema/backfill.runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.runner.js","sourceRoot":"","sources":["../../../../src/storage/schema/backfill.runner.ts"],"names":[],"mappings":";;AAoEA,kCA2CC;AA/GD,yCAAuG;AAgDvG;;;;;;;;;;;;;;;;;;;GAmBG;AACI,KAAK,UAAU,WAAW,CAAE,MAAsB,EAAE,MAAY,IAAI,IAAI,EAAE;IAC/E,MAAM,KAAK,GAAkB;QAC3B,cAAc,EAAE,CAAC;QACjB,sBAAsB,EAAE,CAAC;QACzB,iBAAiB,EAAE,CAAC;QACpB,kBAAkB,EAAE,CAAC;KACtB,CAAA;IAED,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAA;IAE7C,IAAI,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,MAAM,CAAC,gBAAgB,EAAE,EAAE,CAAC;QAC9D,MAAM,MAAM,GAAG,IAAA,iCAAsB,EAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA;QACvD,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAA;QACpD,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QAChC,KAAK,CAAC,cAAc,IAAI,CAAC,CAAA;IAC3B,CAAC;IAED,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,MAAM,CAAC,wBAAwB,EAAE,EAAE,CAAC;QAC7D,IAAI,KAAyB,CAAA;QAC7B,IAAI,MAAM,CAAC,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACpC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,IAAA,6CAAkC,EAAC,MAAM,EAAE,GAAG,CAAC,CAAA;gBAC9D,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,KAAK,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAA;oBACjD,wEAAwE;oBACxE,oEAAoE;oBACpE,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;oBACnC,KAAK,CAAC,sBAAsB,IAAI,CAAC,CAAA;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAQ;QAEjC,MAAM,SAAS,GAAG,IAAA,yBAAc,EAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAA;QACpD,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,SAAS,CAAC,CAAA;QACrD,KAAK,CAAC,iBAAiB,IAAI,CAAC,CAAA;QAE5B,MAAM,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAA;QAC9D,KAAK,CAAC,kBAAkB,IAAI,CAAC,CAAA;IAC/B,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC"}

package/out/src/storage/schema/coinbaseMaturityBackfill.d.ts

@@ -0,0 +1,25 @@
+import { Knex } from 'knex';
+export interface BackfillCoinbaseMaturityArgs {
+    /** Maximum number of rows examined per batch. Default 500. */
+    batchSize?: number;
+    /** Override clock for `updated_at` writes. Default `new Date()`. */
+    now?: Date;
+}
+export interface BackfillCoinbaseMaturityStats {
+    /** Rows visited by the scan, including any that could not be updated. */
+    examined: number;
+    /** Rows whose `matures_at_height` was written by this run. */
+    updated: number;
+}
+/**
+ * Stream every output joined with `transactions` where the owning transaction
+ * is a coinbase, `outputs.matures_at_height` is NULL, and the transaction has
+ * a non-null block height. For each candidate compute
+ * `maturesAtHeight = height + 100` and write it back in a batched UPDATE.
+ *
+ * Returns `{ examined, updated }` for telemetry. The two counts diverge only
+ * when concurrent writers update the same rows mid-scan; in steady state on
+ * a quiescent DB they are equal.
+ */
+export declare function backfillCoinbaseMaturity(knex: Knex, args?: BackfillCoinbaseMaturityArgs): Promise<BackfillCoinbaseMaturityStats>;
+//# sourceMappingURL=coinbaseMaturityBackfill.d.ts.map

package/out/src/storage/schema/coinbaseMaturityBackfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coinbaseMaturityBackfill.d.ts","sourceRoot":"","sources":["../../../../src/storage/schema/coinbaseMaturityBackfill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAiC3B,MAAM,WAAW,4BAA4B;IAC3C,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oEAAoE;IACpE,GAAG,CAAC,EAAE,IAAI,CAAA;CACX;AAED,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,4BAAiC,GACtC,OAAO,CAAC,6BAA6B,CAAC,CAkCxC"}

package/out/src/storage/schema/coinbaseMaturityBackfill.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillCoinbaseMaturity = backfillCoinbaseMaturity;
+/**
+ * §4 spendability backfill — populate `outputs.matures_at_height` for
+ * legacy coinbase outputs that were inserted before the new-schema column existed
+ * (migration `2026-05-13-001`).
+ *
+ * The §4 rule treats coinbase outputs whose `matures_at_height` is NULL as
+ * not-yet-mature, so any coinbase output inserted prior to the migration is
+ * permanently un-spendable until backfilled. This helper computes the BSV
+ * coinbase maturity height as `transactions.height + 100` and writes it via
+ * batched UPDATEs.
+ *
+ * Only rows where:
+ *   - `transactions.is_coinbase = true`
+ *   - `outputs.matures_at_height IS NULL`
+ *   - `transactions.height IS NOT NULL`
+ * are touched. Non-coinbase outputs and outputs whose owning transaction has
+ * no recorded block height are left alone.
+ *
+ * Idempotent: re-running after a successful backfill examines the same set
+ * of rows from a fresh scan and finds none with a NULL maturity, so the
+ * second invocation reports `updated: 0`.
+ *
+ * Note on column naming: the database column is snake_case
+ * (`outputs.matures_at_height`) but is exposed in API surfaces as
+ * `maturesAtHeight`. This module references the DB column name directly
+ * because Knex passes column literals straight through to SQL.
+ */
+const DEFAULT_BATCH_SIZE = 500;
+const BSV_COINBASE_MATURITY = 100;
+/**
+ * Stream every output joined with `transactions` where the owning transaction
+ * is a coinbase, `outputs.matures_at_height` is NULL, and the transaction has
+ * a non-null block height. For each candidate compute
+ * `maturesAtHeight = height + 100` and write it back in a batched UPDATE.
+ *
+ * Returns `{ examined, updated }` for telemetry. The two counts diverge only
+ * when concurrent writers update the same rows mid-scan; in steady state on
+ * a quiescent DB they are equal.
+ */
+async function backfillCoinbaseMaturity(knex, args = {}) {
+    var _a, _b;
+    const batchSize = (_a = args.batchSize) !== null && _a !== void 0 ? _a : DEFAULT_BATCH_SIZE;
+    const now = (_b = args.now) !== null && _b !== void 0 ? _b : new Date();
+    const stats = { examined: 0, updated: 0 };
+    let lastOutputId = 0;
+    /* eslint-disable-next-line no-constant-condition */
+    while (true) {
+        const rows = await knex('outputs as o')
+            .join('transactions as t', 't.transactionId', 'o.transactionId')
+            .where('t.is_coinbase', true)
+            .whereNull('o.matures_at_height')
+            .whereNotNull('t.height')
+            .andWhere('o.outputId', '>', lastOutputId)
+            .orderBy('o.outputId')
+            .limit(batchSize)
+            .select(knex.ref('o.outputId').as('outputId'), knex.ref('t.height').as('height'));
+        if (rows.length === 0)
+            return stats;
+        for (const row of rows) {
+            lastOutputId = row.outputId;
+            stats.examined += 1;
+            const maturesAtHeight = row.height + BSV_COINBASE_MATURITY;
+            const written = await knex('outputs')
+                .where({ outputId: row.outputId })
+                .whereNull('matures_at_height')
+                .update({ matures_at_height: maturesAtHeight, updated_at: now });
+            if (written > 0)
+                stats.updated += 1;
+        }
+    }
+}
+//# sourceMappingURL=coinbaseMaturityBackfill.js.map

package/out/src/storage/schema/coinbaseMaturityBackfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coinbaseMaturityBackfill.js","sourceRoot":"","sources":["../../../../src/storage/schema/coinbaseMaturityBackfill.ts"],"names":[],"mappings":";;AAyDA,4DAqCC;AA5FD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAC9B,MAAM,qBAAqB,GAAG,GAAG,CAAA;AAgBjC;;;;;;;;;GASG;AACI,KAAK,UAAU,wBAAwB,CAC5C,IAAU,EACV,OAAqC,EAAE;;IAEvC,MAAM,SAAS,GAAG,MAAA,IAAI,CAAC,SAAS,mCAAI,kBAAkB,CAAA;IACtD,MAAM,GAAG,GAAG,MAAA,IAAI,CAAC,GAAG,mCAAI,IAAI,IAAI,EAAE,CAAA;IAClC,MAAM,KAAK,GAAkC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAA;IAExE,IAAI,YAAY,GAAG,CAAC,CAAA;IACpB,oDAAoD;IACpD,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,IAAI,GAAgD,MAAM,IAAI,CAAC,cAAc,CAAC;aACjF,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,EAAE,iBAAiB,CAAC;aAC/D,KAAK,CAAC,eAAe,EAAE,IAAI,CAAC;aAC5B,SAAS,CAAC,qBAAqB,CAAC;aAChC,YAAY,CAAC,UAAU,CAAC;aACxB,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC;aACzC,OAAO,CAAC,YAAY,CAAC;aACrB,KAAK,CAAC,SAAS,CAAC;aAChB,MAAM,CACL,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,EACrC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,CAClC,CAAA;QAEH,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;QAEnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,YAAY,GAAG,GAAG,CAAC,QAAQ,CAAA;YAC3B,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAA;YACnB,MAAM,eAAe,GAAG,GAAG,CAAC,MAAM,GAAG,qBAAqB,CAAA;YAC1D,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC;iBAClC,KAAK,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;iBACjC,SAAS,CAAC,mBAAmB,CAAC;iBAC9B,MAAM,CAAC,EAAE,iBAAiB,EAAE,eAAe,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAA;YAClE,IAAI,OAAO,GAAG,CAAC;gBAAE,KAAK,CAAC,OAAO,IAAI,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;AACH,CAAC"}

package/out/src/storage/schema/monitorLease.d.ts

@@ -0,0 +1,57 @@
+import { Knex } from 'knex';
+import { TableMonitorLease } from './tables';
+/**
+ * monitor lease primitive.
+ *
+ * A `monitor_lease` row records the owner that may currently execute a named
+ * task. Acquisition is opportunistic: a Monitor calls `tryClaimLease()` to
+ * insert or take over a stale row; if it succeeds it owns the task until
+ * `expiresAt`. While running it calls `renewLease()` to extend the deadline.
+ * On clean shutdown it calls `releaseLease()`.
+ *
+ * The Knex driver expresses claim + takeover as a single conditional UPDATE
+ * so that two contending Monitors cannot both believe they own the task — at
+ * most one row write will succeed per (task, expiry) pair.
+ */
+export interface MonitorLeaseClaim {
+    taskName: string;
+    ownerId: string;
+    ttlMs: number;
+    note?: string;
+}
+export interface MonitorLeaseRenew {
+    taskName: string;
+    ownerId: string;
+    ttlMs: number;
+    note?: string;
+}
+export interface MonitorLeaseRelease {
+    taskName: string;
+    ownerId: string;
+}
+export interface MonitorLeaseResult {
+    acquired: boolean;
+    lease?: TableMonitorLease;
+}
+/**
+ * Try to claim a lease on `taskName`. Succeeds iff:
+ *   - no row exists for the task, OR
+ *   - the existing row has `expiresAt <= now`, OR
+ *   - the existing row's `ownerId` already equals the requested owner.
+ *
+ * On success the row is upserted with `expiresAt = now + ttlMs` and
+ * `renewCount = renewCount + 1` (0 for fresh rows).
+ */
+export declare function tryClaimLease(knex: Knex, claim: MonitorLeaseClaim, now?: Date): Promise<MonitorLeaseResult>;
+/**
+ * Extend the current owner's lease. Fails (returns `acquired: false`) when the
+ * row does not exist, is owned by someone else, or has already expired.
+ */
+export declare function renewLease(knex: Knex, renew: MonitorLeaseRenew, now?: Date): Promise<MonitorLeaseResult>;
+/**
+ * Release the lease (no-op when not owned by the caller).
+ * The row is deleted so subsequent claimants do not see an inherited
+ * `renew_count`.
+ */
+export declare function releaseLease(knex: Knex, release: MonitorLeaseRelease): Promise<boolean>;
+//# sourceMappingURL=monitorLease.d.ts.map

package/out/src/storage/schema/monitorLease.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitorLease.d.ts","sourceRoot":"","sources":["../../../../src/storage/schema/monitorLease.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAE5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,iBAAiB,CAAA;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,iBAAiB,EACxB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAmC7B;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,iBAAiB,EACxB,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAkB7B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAK9F"}