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

package/out/src/storage/StorageKnex.js

@@ -10,17 +10,204 @@ const listOutputsKnex_1 = require("./methods/listOutputsKnex");
 const reviewStatus_1 = require("./methods/reviewStatus");
 const WERR_errors_1 = require("../sdk/WERR_errors");
 const utilityHelpers_1 = require("../utility/utilityHelpers");
+const types_1 = require("../sdk/types");
+const transactionService_1 = require("./schema/transactionService");
 class StorageKnex extends StorageProvider_1.StorageProvider {
     constructor(options) {
         super(options);
+        this._postCutoverCache = undefined;
         this._verifiedReadyForDatabaseAccess = false;
         if (!options.knex)
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('options.knex', 'valid');
         this.knex = options.knex;
     }
+    getTransactionService() {
+        // The new-schema transaction service is only valid post-cutover. Pre-cutover,
+        // the `transactions` table is the legacy schema and queries via this service
+        // would return legacy ids that don't satisfy the `tx_audit.transactionId`
+        // FK (which targets `transactions_new`). Callers gate on `undefined` and
+        // fall back to the legacy storage path.
+        if (this._postCutoverCache !== true)
+            return undefined;
+        return new transactionService_1.TransactionService(this.knex);
+    }
+    /**
+     * Eagerly warm the `_postCutoverCache` so sync query builders such as
+     * `findOutputsQuery` can branch on cutover state without an extra await.
+     * Callers that have invoked `makeAvailable` are guaranteed the cache has
+     * been populated.
+     */
+    async makeAvailable() {
+        const settings = await super.makeAvailable();
+        if (this._postCutoverCache === undefined) {
+            this._postCutoverCache = await this.knex.schema.hasTable('transactions_legacy');
+        }
+        return settings;
+    }
+    /**
+     * Returns true when the database has been through `runSchemaCutover` (i.e.
+     * `transactions_legacy` exists). Result is cached for the lifetime of this
+     * StorageKnex instance.
+     */
+    async isPostCutover() {
+        if (this._postCutoverCache === undefined) {
+            this._postCutoverCache = await this.knex.schema.hasTable('transactions_legacy');
+        }
+        return this._postCutoverCache;
+    }
+    /**
+     * Maps legacy TransactionStatus values to their ProcessingStatus equivalents
+     * for use in `outputs JOIN transactions` WHERE clauses post-cutover.
+     */
+    legacyStatiToProcessing(stati) {
+        const result = new Set();
+        for (const s of stati) {
+            result.add((0, types_1.transactionStatusToProcessing)(s));
+            if (s === 'unproven') {
+                // 'sent','seen','seen_multi','unconfirmed' all map to legacy 'unproven'
+                result.add('sent');
+                result.add('seen');
+                result.add('seen_multi');
+                result.add('unconfirmed');
+            }
+        }
+        return [...result];
+    }
+    /**
+     * Returns the canonical name of the `proven_txs` table — `proven_txs_legacy`
+     * post-cutover, `proven_txs` otherwise.
+     *
+     * Public so that helper modules (reviewStatus, purgeData) can resolve the
+     * correct table name without duplicating the post-cutover detection logic.
+     */
+    async provenTxsTableName() {
+        return (await this.isPostCutover()) ? 'proven_txs_legacy' : 'proven_txs';
+    }
+    /**
+     * Returns the canonical name of the `proven_tx_reqs` table —
+     * `proven_tx_reqs_legacy` post-cutover, `proven_tx_reqs` otherwise.
+     *
+     * Public so that helper modules (reviewStatus, purgeData) can resolve the
+     * correct table name without duplicating the post-cutover detection logic.
+     */
+    async provenTxReqsTableName() {
+        return (await this.isPostCutover()) ? 'proven_tx_reqs_legacy' : 'proven_tx_reqs';
+    }
+    /**
+     * Insert a legacy-shaped transaction row into the correct table:
+     * - Post-cutover: `transactions_legacy` (the renamed legacy schema table)
+     * - Pre-cutover:     `transactions` (the standard table, same behaviour as `insertTransaction`)
+     *
+     * This allows `createAction` to store unsigned rows (txid unknown) without
+     * conflicting with the new `transactions` table's NOT NULL txid constraint.
+     * A new `transactions` row + `actions` row are created later by `processAction`
+     * once the real txid is known.
+     *
+     * On SQLite, foreign key enforcement is temporarily disabled while inserting
+     * into `transactions_legacy` because the referenced `proven_txs` table was
+     * renamed to `proven_txs_legacy` during the the schema cutover. Since `provenTxId`
+     * is always NULL for new unsigned transactions this is semantically safe.
+     */
+    async insertLegacyTransaction(tx, trx) {
+        const e = await this.validateEntityForInsert(tx, trx);
+        if (e.transactionId === 0)
+            delete e.transactionId;
+        const hasLegacyTable = await this.knex.schema.hasTable('transactions_legacy');
+        const tableName = hasLegacyTable ? 'transactions_legacy' : 'transactions';
+        const isSqlite = this.dbtype === 'SQLite';
+        // On SQLite post-cutover the `transactions_legacy` FK to `proven_txs` is dangling
+        // (proven_txs was renamed to proven_txs_legacy). Temporarily disable FK checks for
+        // this insert since provenTxId is always NULL for a brand-new unsigned transaction.
+        if (isSqlite && hasLegacyTable)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            const [id] = await this.toDb(trx)(tableName).insert(e);
+            tx.transactionId = id;
+            return tx.transactionId;
+        }
+        finally {
+            if (isSqlite && hasLegacyTable)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
+    }
+    /**
+     * Insert a `tx_labels_map` row for a legacy transaction that does not yet
+     * have a `actions.actionId`. On post-cutover SQLite, temporarily disables
+     * FK checks so that the legacy transactionId (which is not yet an actionId)
+     * can be written. processAction will repoint it via repointLabelsToActionId.
+     *
+     * Note: bypasses `validateEntityForInsert` (and therefore `verifyReadyForDatabaseAccess`
+     * which would re-enable FK checks) to ensure the PRAGMA=OFF persists across
+     * the insert statement.
+     */
+    async insertLegacyTxLabelMap(labelMap, trx) {
+        const isSqlite = this.dbtype === 'SQLite';
+        const hasLegacyTable = isSqlite ? await this.knex.schema.hasTable('transactions_legacy') : false;
+        if (!isSqlite || !hasLegacyTable) {
+            // Pre-cutover or non-SQLite: standard insert is safe (no dangling FK issue).
+            await this.insertTxLabelMap(labelMap, trx);
+            return;
+        }
+        // Post-cutover SQLite: tx_labels_map.transactionId FK now points to actions.actionId.
+        // We are writing a legacyTransactionId (no corresponding actions row yet).
+        // Temporarily disable FK checks for this single insert.
+        const now = new Date();
+        const e = {
+            created_at: now,
+            updated_at: now,
+            txLabelId: labelMap.txLabelId,
+            transactionId: labelMap.transactionId,
+            isDeleted: labelMap.isDeleted ? 1 : 0
+        };
+        // Use the raw knex handle (not toDb(trx)) to send the PRAGMA on the same connection.
+        await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            await this.knex('tx_labels_map').insert(e);
+        }
+        finally {
+            await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
+    }
     async readSettings() {
         return this.validateEntity((0, utilityHelpers_1.verifyOne)(await this.toDb(undefined)('settings')));
     }
+    /**
+     * Synthesise a `ProvenOrRawTx` from a `TableTransactionNew` row.
+     *
+     * - If the new schema row carries a `merklePath` (i.e. processing is `proven`), build
+     *   a `TableProvenTx`-shaped object so the BEEF assembly code can extract the
+     *   merkle path and merge it into the Beef without hitting the legacy tables.
+     * - If the new schema row only has `rawTx` (broadcast/queued state), return it as the
+     *   raw-tx path.
+     * - Returns `null` when the new schema row has neither rawTx nor merklePath.
+     */
+    newTxToProvenOrRawTx(row, txid) {
+        var _a, _b, _c, _d;
+        // Only use the new-schema row as the primary source when it carries a *non-empty*
+        // merklePath and a rawTx — both are required for `handleProvenTxBranch` to assemble
+        // a valid BEEF.  An empty merklePath (e.g. a backfill race or a req whose proof was
+        // never stored) must fall through to the legacy `proven_txs_legacy` path.
+        // Raw-tx-only rows (no merklePath) are likewise forwarded to the legacy path so
+        // that the legacy `inputBEEF` column is available for recursive BEEF assembly.
+        if (row.merklePath != null && row.merklePath.length > 0 && row.rawTx != null && row.rawTx.length > 0) {
+            // Full proof available — synthesise TableProvenTx shape
+            const proven = {
+                created_at: row.created_at,
+                updated_at: row.updated_at,
+                provenTxId: row.transactionId,
+                txid,
+                height: (_a = row.height) !== null && _a !== void 0 ? _a : 0,
+                index: (_b = row.merkleIndex) !== null && _b !== void 0 ? _b : 0,
+                merklePath: row.merklePath,
+                rawTx: row.rawTx,
+                blockHash: (_c = row.blockHash) !== null && _c !== void 0 ? _c : '',
+                merkleRoot: (_d = row.merkleRoot) !== null && _d !== void 0 ? _d : ''
+            };
+            return { proven, rawTx: undefined, inputBEEF: undefined };
+        }
+        // No complete proof in new-schema row — let the caller fall through to legacy tables.
+        return null;
+    }
     async getProvenOrRawTx(txid, trx) {
         const k = this.toDb(trx);
         const r = {
@@ -28,9 +215,29 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
             rawTx: undefined,
             inputBEEF: undefined
         };
+        // Post-cutover: try new `transactions` table first. The new schema row is the single
+        // source of truth for rawTx and merklePath; legacy tables are read-only
+        // archives after cutover.
+        if (await this.isPostCutover()) {
+            try {
+                const txSvc = this.getTransactionService();
+                if (txSvc != null) {
+                    const newTx = await txSvc.findByTxid(txid);
+                    if (newTx != null) {
+                        const newTxResult = this.newTxToProvenOrRawTx(newTx, txid);
+                        if (newTxResult != null)
+                            return newTxResult;
+                    }
+                }
+            }
+            catch (_a) {
+                // new table lookup failed (e.g. table not yet available) — fall through to legacy
+            }
+        }
         r.proven = (0, utilityHelpers_1.verifyOneOrNone)(await this.findProvenTxs({ partial: { txid } }));
         if (r.proven == null) {
-            const reqRawTx = (0, utilityHelpers_1.verifyOneOrNone)(await k('proven_tx_reqs')
+            const reqTable = await this.provenTxReqsTableName();
+            const reqRawTx = (0, utilityHelpers_1.verifyOneOrNone)(await k(reqTable)
                 .where('txid', txid)
                 .whereIn('status', ['unsent', 'unmined', 'unconfirmed', 'sending', 'nosend', 'completed'])
                 .select('rawTx', 'inputBEEF'));
@@ -52,12 +259,31 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return rs;
     }
     async getRawTxSlice(txid, offset, length, trx) {
+        // Post-cutover: try new transactions table first — the new table is the canonical store
+        // for rawTx after the cutover. Apply the slice in JS to avoid raw SQL
+        // column naming differences between the two schemas.
+        if (await this.isPostCutover()) {
+            try {
+                const txSvc = this.getTransactionService();
+                if (txSvc != null) {
+                    const newTx = await txSvc.findByTxid(txid);
+                    if ((newTx === null || newTx === void 0 ? void 0 : newTx.rawTx) != null) {
+                        return newTx.rawTx.slice(offset, offset + length);
+                    }
+                }
+            }
+            catch (_a) {
+                // new table lookup failed — fall through to legacy tables
+            }
+        }
         const sub = this.dbTypeSubstring('rawTx', offset + 1, length);
-        let rs = await this.toDb(trx).raw(`select ${sub} as rawTx from proven_txs where txid = '${txid}'`);
+        const provenTable = await this.provenTxsTableName();
+        const reqTable = await this.provenTxReqsTableName();
+        let rs = await this.toDb(trx).raw(`select ${sub} as rawTx from ${provenTable} where txid = '${txid}'`);
         const proven = (0, utilityHelpers_1.verifyOneOrNone)(this.normaliseKnexRawResult(rs));
         if ((proven === null || proven === void 0 ? void 0 : proven.rawTx) != null)
             return Array.from(proven.rawTx);
-        rs = await this.toDb(trx).raw(`select ${sub} as rawTx from proven_tx_reqs where txid = '${txid}' and status in ('unsent', 'nosend', 'sending', 'unmined', 'completed', 'unfail')`);
+        rs = await this.toDb(trx).raw(`select ${sub} as rawTx from ${reqTable} where txid = '${txid}' and status in ('unsent', 'nosend', 'sending', 'unmined', 'completed', 'unfail')`);
         const req = (0, utilityHelpers_1.verifyOneOrNone)(this.normaliseKnexRawResult(rs));
         return (req === null || req === void 0 ? void 0 : req.rawTx) != null ? Array.from(req.rawTx) : undefined;
     }
@@ -67,7 +293,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         if (!this.isAvailable())
             await this.makeAvailable();
         if (Number.isInteger(offset) && Number.isInteger(length)) {
-            return this.getRawTxSlice(txid, offset, length, trx);
+            return await this.getRawTxSlice(txid, offset, length, trx);
         }
         const r = await this.getProvenOrRawTx(txid, trx);
         return r.proven != null ? r.proven.rawTx : r.rawTx;
@@ -89,6 +315,25 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return q;
     }
     async getProvenTxsForUser(args) {
+        const postCutover = await this.isPostCutover();
+        if (postCutover) {
+            // Post-cutover: proven_txs → proven_txs_legacy; transactions → transactions_legacy
+            const k = this.toDb(args.trx);
+            let q = k('proven_txs_legacy').where(function () {
+                this.whereExists(k
+                    .select('*')
+                    .from('transactions_legacy')
+                    .whereRaw(`proven_txs_legacy.provenTxId = transactions_legacy.provenTxId and transactions_legacy.userId = ${args.userId}`));
+            });
+            if (args.paged != null) {
+                q = q.limit(args.paged.limit);
+                q = q.offset(args.paged.offset || 0);
+            }
+            if (args.since != null)
+                q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
+            const rs = await q;
+            return this.validateEntities(rs);
+        }
         const q = this.getProvenTxsForUserQuery(args);
         const rs = await q;
         return this.validateEntities(rs);
@@ -110,6 +355,25 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return q;
     }
     async getProvenTxReqsForUser(args) {
+        const postCutover = await this.isPostCutover();
+        if (postCutover) {
+            // Post-cutover: proven_tx_reqs → proven_tx_reqs_legacy; transactions → transactions_legacy
+            const k = this.toDb(args.trx);
+            let q = k('proven_tx_reqs_legacy').where(function () {
+                this.whereExists(k
+                    .select('*')
+                    .from('transactions_legacy')
+                    .whereRaw(`proven_tx_reqs_legacy.txid = transactions_legacy.txid and transactions_legacy.userId = ${args.userId}`));
+            });
+            if (args.paged != null) {
+                q = q.limit(args.paged.limit);
+                q = q.offset(args.paged.offset || 0);
+            }
+            if (args.since != null)
+                q = q.where('updated_at', '>=', this.validateDateForWhere(args.since));
+            const rs = await q;
+            return this.validateEntities(rs, undefined, ['notified']);
+        }
         const q = this.getProvenTxReqsForUserQuery(args);
         const rs = await q;
         return this.validateEntities(rs, undefined, ['notified']);
@@ -166,7 +430,8 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(tx, trx);
         if (e.provenTxId === 0)
             delete e.provenTxId;
-        const [id] = await this.toDb(trx)('proven_txs').insert(e);
+        const tableName = await this.provenTxsTableName();
+        const [id] = await this.toDb(trx)(tableName).insert(e);
         tx.provenTxId = id;
         return tx.provenTxId;
     }
@@ -174,7 +439,10 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(tx, trx);
         if (e.provenTxReqId === 0)
             delete e.provenTxReqId;
-        const [id] = await this.toDb(trx)('proven_tx_reqs').insert(e);
+        // Post-cutover: route to proven_tx_reqs_legacy.
+        // FK bypass is handled by the caller (disableForeignKeys before any transaction).
+        const reqTable = await this.provenTxReqsTableName();
+        const [id] = await this.toDb(trx)(reqTable).insert(e);
         tx.provenTxReqId = id;
         return tx.provenTxReqId;
     }
@@ -228,6 +496,28 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(tx, trx);
         if (e.transactionId === 0)
             delete e.transactionId;
+        // Post-cutover the canonical `transactions` table is the new schema which
+        // does not carry legacy columns (description, status, satoshis, version...).
+        // Legacy-shaped insertions belong in `transactions_legacy`. We route there
+        // automatically so existing callers that still speak the legacy shape keep
+        // working without a code change at every call site. FK enforcement is
+        // bypassed because the renamed legacy table still references the renamed
+        // `proven_txs_legacy` via its original `proven_txs` FK column name.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover) {
+            if (isSqlite)
+                await this.knex.raw('PRAGMA foreign_keys = OFF');
+            try {
+                const [id] = await this.toDb(trx)('transactions_legacy').insert(e);
+                tx.transactionId = id;
+                return tx.transactionId;
+            }
+            finally {
+                if (isSqlite)
+                    await this.knex.raw('PRAGMA foreign_keys = ON');
+            }
+        }
         const [id] = await this.toDb(trx)('transactions').insert(e);
         tx.transactionId = id;
         return tx.transactionId;
@@ -236,21 +526,42 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         const e = await this.validateEntityForInsert(commission, trx);
         if (e.commissionId === 0)
             delete e.commissionId;
-        const [id] = await this.toDb(trx)('commissions').insert(e);
-        commission.commissionId = id;
-        return commission.commissionId;
+        // Post-cutover bridge-period: commissions.transactionId FKs new transactions.
+        // During createAction the transactionId references transactions_legacy, so bypass FK.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            const [id] = await this.toDb(trx)('commissions').insert(e);
+            commission.commissionId = id;
+            return commission.commissionId;
+        }
+        finally {
+            if (postCutover)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
     }
     async insertOutput(output, trx) {
+        const e = await this.validateEntityForInsert(output, trx);
+        if (e.outputId === 0)
+            delete e.outputId;
+        // Post-cutover bridge-period: outputs.transactionId FKs new transactions,
+        // but new unsigned outputs reference transactions_legacy (bridge-period rows).
+        // Temporarily disable FK checks on SQLite. Safe because once processAction
+        // runs, spentBy and transactionId are remapped to real new-schema IDs.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
         try {
-            const e = await this.validateEntityForInsert(output, trx);
-            if (e.outputId === 0)
-                delete e.outputId;
             const [id] = await this.toDb(trx)('outputs').insert(e);
             output.outputId = id;
             return output.outputId;
         }
-        catch (e) {
-            throw e;
+        finally {
+            if (postCutover)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
         }
     }
     async insertOutputTag(tag, trx) {
@@ -275,6 +586,22 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async insertTxLabelMap(labelMap, trx) {
         const e = await this.validateEntityForInsert(labelMap, trx, undefined, ['isDeleted']);
+        // Post-cutover SQLite: tx_labels_map.transactionId references actions.actionId
+        // (rebuilt during schema cutover). Sync paths that import legacy rows still
+        // carry the legacy transactionId until repointLabelsToActionId remaps them.
+        // Temporarily disable FK checks so the import does not fail.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover) {
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+            try {
+                await this.toDb(trx)('tx_labels_map').insert(e);
+            }
+            finally {
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+            }
+            return;
+        }
         await this.toDb(trx)('tx_labels_map').insert(e);
     }
     async insertMonitorEvent(event, trx) {
@@ -307,9 +634,22 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateCommission(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
-        return await this.toDb(trx)('commissions')
-            .where({ commissionId: id })
-            .update(this.validatePartialForUpdate(update));
+        // Post-cutover SQLite: commissions.transactionId FK references the new
+        // schema `transactions` table. Legacy callers carry transactionId values
+        // that still point at transactions_legacy. Bypass FK so the update lands.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        if (postCutover)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            return await this.toDb(trx)('commissions')
+                .where({ commissionId: id })
+                .update(this.validatePartialForUpdate(update));
+        }
+        finally {
+            if (postCutover)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
     }
     async updateOutputBasket(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
@@ -337,14 +677,15 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateProvenTxReq(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
+        const reqTable = await this.provenTxReqsTableName();
         let r;
         if (Array.isArray(id)) {
-            r = await this.toDb(trx)('proven_tx_reqs')
+            r = await this.toDb(trx)(reqTable)
                 .whereIn('provenTxReqId', id)
                 .update(this.validatePartialForUpdate(update));
         }
         else if (Number.isInteger(id)) {
-            r = await this.toDb(trx)('proven_tx_reqs')
+            r = await this.toDb(trx)(reqTable)
                 .where({ provenTxReqId: id })
                 .update(this.validatePartialForUpdate(update));
         }
@@ -355,7 +696,8 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateProvenTx(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
-        return await this.toDb(trx)('proven_txs')
+        const tableName = await this.provenTxsTableName();
+        return await this.toDb(trx)(tableName)
             .where({ provenTxId: id })
             .update(this.validatePartialForUpdate(update));
     }
@@ -367,21 +709,36 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     }
     async updateTransaction(id, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
-        let r;
-        if (Array.isArray(id)) {
-            r = await this.toDb(trx)('transactions')
-                .whereIn('transactionId', id)
-                .update(this.validatePartialForUpdate(update));
-        }
-        else if (Number.isInteger(id)) {
-            r = await this.toDb(trx)('transactions')
-                .where({ transactionId: id })
-                .update(this.validatePartialForUpdate(update));
+        // Post-cutover the canonical `transactions` table is the new schema which
+        // lacks legacy columns (userId, status, description, satoshis, version, ...).
+        // Legacy-shaped updates belong in `transactions_legacy`, matching the
+        // routing performed by `insertTransaction`.
+        const isSqlite = this.dbtype === 'SQLite';
+        const postCutover = isSqlite ? await this.isPostCutover() : false;
+        const tableName = postCutover ? 'transactions_legacy' : 'transactions';
+        if (postCutover && isSqlite)
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        try {
+            let r;
+            if (Array.isArray(id)) {
+                r = await this.toDb(trx)(tableName)
+                    .whereIn('transactionId', id)
+                    .update(this.validatePartialForUpdate(update));
+            }
+            else if (Number.isInteger(id)) {
+                r = await this.toDb(trx)(tableName)
+                    .where({ transactionId: id })
+                    .update(this.validatePartialForUpdate(update));
+            }
+            else {
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER('id', 'transactionId or array of transactionId');
+            }
+            return r;
         }
-        else {
-            throw new WERR_errors_1.WERR_INVALID_PARAMETER('id', 'transactionId or array of transactionId');
+        finally {
+            if (postCutover && isSqlite)
+                await this.knex.raw('PRAGMA foreign_keys = ON');
         }
-        return r;
     }
     async updateTxLabelMap(transactionId, txLabelId, update, trx) {
         await this.verifyReadyForDatabaseAccess(trx);
@@ -430,15 +787,18 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
                     sortColumn = 'outputTagId';
                     break;
                 case 'proven_tx_reqs':
+                case 'proven_tx_reqs_legacy':
                     sortColumn = 'provenTxReqId';
                     break;
                 case 'proven_txs':
+                case 'proven_txs_legacy':
                     sortColumn = 'provenTxId';
                     break;
                 case 'sync_states':
                     sortColumn = 'syncStateId';
                     break;
                 case 'transactions':
+                case 'transactions_legacy':
                     sortColumn = 'transactionId';
                     break;
                 case 'tx_labels':
@@ -489,7 +849,19 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         }
         const q = this.setupQuery('outputs', args);
         if ((args.txStatus != null) && args.txStatus.length > 0) {
-            q.whereRaw(`(select status from transactions where transactions.transactionId = outputs.transactionId) in (${args.txStatus.map(s => "'" + s + "'").join(',')})`);
+            // Post-cutover the `transactions` table carries `processing`
+            // (ProcessingStatus), not the legacy `status` column. We translate
+            // the requested legacy status set to its ProcessingStatus equivalents
+            // when the cutover has been applied; pre-cutover the original `status`
+            // column lookup remains correct.
+            if (this._postCutoverCache === true) {
+                const processingFilter = this.legacyStatiToProcessing(args.txStatus);
+                const filterList = processingFilter.map(s => "'" + s + "'").join(',');
+                q.whereRaw(`(select processing from transactions where transactions.transactionId = outputs.transactionId) in (${filterList})`);
+            }
+            else {
+                q.whereRaw(`(select status from transactions where transactions.transactionId = outputs.transactionId) in (${args.txStatus.map(s => "'" + s + "'").join(',')})`);
+            }
         }
         if (args.noScript && !count) {
             const columns = tables_1.outputColumnsWithoutLockingScript.map(c => `outputs.${c}`);
@@ -506,14 +878,14 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
     findOutputTagsQuery(args) {
         return this.setupQuery('output_tags', args);
     }
-    findProvenTxReqsQuery(args) {
+    findProvenTxReqsQuery(args, tableName = 'proven_tx_reqs') {
         if (args.partial.rawTx != null) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', 'undefined. ProvenTxReqs may not be found by rawTx value.');
         }
         if (args.partial.inputBEEF != null) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.inputBEEF', 'undefined. ProvenTxReqs may not be found by inputBEEF value.');
         }
-        const q = this.setupQuery('proven_tx_reqs', args);
+        const q = this.setupQuery(tableName, args);
         if ((args.status != null) && args.status.length > 0)
             q.whereIn('status', args.status);
         if (args.txids != null) {
@@ -523,17 +895,17 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         }
         return q;
     }
-    findProvenTxsQuery(args) {
+    findProvenTxsQuery(args, tableName = 'proven_txs') {
         if (args.partial.rawTx != null) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.rawTx', 'undefined. ProvenTxs may not be found by rawTx value.');
         }
         if (args.partial.merklePath != null) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.merklePath', 'undefined. ProvenTxs may not be found by merklePath value.');
         }
-        return this.setupQuery('proven_txs', args);
+        return this.setupQuery(tableName, args);
     }
-    findStaleMerkleRootsQuery(args) {
-        const q = this.toDb(args.trx)('proven_txs');
+    findStaleMerkleRootsQuery(args, tableName = 'proven_txs') {
+        const q = this.toDb(args.trx)(tableName);
         q.where('height', '=', args.height);
         q.where('merkleRoot', '!=', args.merkleRoot);
         q.select('merkleRoot');
@@ -550,7 +922,16 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         if (args.partial.inputBEEF != null) {
             throw new WERR_errors_1.WERR_INVALID_PARAMETER('args.partial.inputBEEF', 'undefined. Transactions may not be found by inputBEEF value.');
         }
-        const q = this.setupQuery('transactions', args);
+        // Post-cutover the original per-user `transactions` table has been
+        // renamed to `transactions_legacy`. `findTransactions` returns the
+        // legacy shape (status / userId / satoshis / description / etc.) so it
+        // must route at the renamed table to preserve the legacy read surface
+        // through the bridge period. New-canonical per-txid reads go through
+        // TransactionService.
+        const tableName = this._postCutoverCache === true
+            ? 'transactions_legacy'
+            : 'transactions';
+        const q = this.setupQuery(tableName, args);
         if ((args.status != null) && args.status.length > 0)
             q.whereIn('status', args.status);
         if (args.from != null)
@@ -558,7 +939,7 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         if (args.to != null)
             q.where('created_at', '<', this.validateDateForWhere(args.to));
         if (args.noRawTx && !count) {
-            const columns = tables_1.transactionColumnsWithoutRawTx.map(c => `transactions.${c}`);
+            const columns = tables_1.transactionColumnsWithoutRawTx.map(c => `${tableName}.${c}`);
             q.select(columns);
         }
         return q;
@@ -644,17 +1025,20 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return this.validateEntities(r, undefined, ['isDeleted']);
     }
     async findProvenTxReqs(args) {
-        const q = this.findProvenTxReqsQuery(args);
+        const reqTable = await this.provenTxReqsTableName();
+        const q = this.findProvenTxReqsQuery(args, reqTable);
         const r = await q;
         return this.validateEntities(r, undefined, ['notified', 'wasBroadcast']);
     }
     async findProvenTxs(args) {
-        const q = this.findProvenTxsQuery(args);
+        const tableName = await this.provenTxsTableName();
+        const q = this.findProvenTxsQuery(args, tableName);
         const r = await q;
         return this.validateEntities(r);
     }
     async findStaleMerkleRoots(args) {
-        const q = this.findStaleMerkleRootsQuery(args);
+        const tableName = await this.provenTxsTableName();
+        const q = this.findStaleMerkleRootsQuery(args, tableName);
         const r = await q;
         return r.map((row) => row.merkleRoot);
     }
@@ -673,6 +1057,172 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         }
         return this.validateEntities(r, undefined, ['isOutgoing']);
     }
+    /**
+     * Post-cutover: queries `transactions_legacy` for unsigned/pending rows
+     * created by `createAction` (which have no real txid yet and therefore have no
+     * new-schema counterpart).  Falls back to the standard `findTransactions` pre-cutover.
+     *
+     * Used by `processAction.validateCommitNewTxToStorageArgs` to locate the
+     * unsigned transaction row by `{userId, reference}`.
+     *
+     * Mapping §2: legacy `unsigned` / `unprocessed` → these rows only exist in
+     * `transactions_legacy` post-cutover; new `transactions` has `processing` not
+     * `status` and no unsigned-state rows.
+     */
+    async findLegacyTransactions(args) {
+        const postCutover = await this.isPostCutover();
+        if (!postCutover) {
+            // Pre-cutover: standard transactions table
+            return await this.findTransactions(args);
+        }
+        // Post-cutover: unsigned/unprocessed rows live in transactions_legacy
+        const q = this.setupQuery('transactions_legacy', args);
+        if ((args.status != null) && args.status.length > 0)
+            q.whereIn('status', args.status);
+        if (args.from != null)
+            q.where('created_at', '>=', this.validateDateForWhere(args.from));
+        if (args.to != null)
+            q.where('created_at', '<', this.validateDateForWhere(args.to));
+        if (args.noRawTx) {
+            const columns = tables_1.transactionColumnsWithoutRawTx.map(c => `transactions_legacy.${c}`);
+            q.select(columns);
+        }
+        const r = await q;
+        if (!args.noRawTx) {
+            for (const t of r) {
+                await this.validateRawTransaction(t, args.trx);
+            }
+        }
+        return this.validateEntities(r, undefined, ['isOutgoing']);
+    }
+    /**
+     * Post-cutover: updates `transactions_legacy` (where unsigned rows live).
+     * Pre-cutover: delegates to `updateTransaction`.
+     *
+     * Used by `processAction.commitNewTxToStorage` to write back the real txid
+     * and status to the legacy row that was created by `createAction`.
+     *
+     * Mapping §2: legacy `unsigned` → `unprocessed` transition and txid write-back
+     * must go to `transactions_legacy` post-cutover, not new `transactions`.
+     */
+    async updateLegacyTransaction(id, update, trx) {
+        const postCutover = await this.isPostCutover();
+        if (!postCutover) {
+            return await this.updateTransaction(id, update, trx);
+        }
+        // Post-cutover: unsigned rows are in transactions_legacy
+        await this.verifyReadyForDatabaseAccess(trx);
+        let r;
+        if (Array.isArray(id)) {
+            r = await this.toDb(trx)('transactions_legacy')
+                .whereIn('transactionId', id)
+                .update(this.validatePartialForUpdate(update));
+        }
+        else if (Number.isInteger(id)) {
+            r = await this.toDb(trx)('transactions_legacy')
+                .where({ transactionId: id })
+                .update(this.validatePartialForUpdate(update));
+        }
+        else {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('id', 'transactionId or array of transactionId');
+        }
+        return r;
+    }
+    /**
+     * Post-cutover SQLite: temporarily disable FK enforcement around the
+     * `outputs.spentBy = legacyTransactionId` UPDATE. The `outputs.spentBy` FK
+     * references `transactions.transactionId` after cutover, but unsigned
+     * transactions from `createAction` live in `transactions_legacy` (their new-schema
+     * counterpart is created later by `processAction`).
+     *
+     * IMPORTANT: We bypass `updateOutput` (and therefore `verifyReadyForDatabaseAccess`)
+     * because `verifyReadyForDatabaseAccess` always re-enables FK with
+     * `PRAGMA foreign_keys = ON`, which would undo our bypass. Instead we
+     * directly run the UPDATE via the raw knex handle.
+     *
+     * Pre-cutover or MySQL: delegates to `updateOutput` unchanged.
+     *
+     * Mapping §2: bridge-period spentBy references transactions_legacy during
+     * createAction; FK bypass covers this until processAction wires the new-schema.
+     */
+    async markOutputAsSpentBy(outputId, update, trx) {
+        const postCutover = await this.isPostCutover();
+        const isSqlite = this.dbtype === 'SQLite';
+        if (postCutover && isSqlite) {
+            // Build the UPDATE payload the same way validatePartialForUpdate does,
+            // but WITHOUT calling verifyReadyForDatabaseAccess (which always issues
+            // PRAGMA foreign_keys = ON, undoing our bypass).
+            const now = new Date().toISOString();
+            const payload = { updated_at: now };
+            for (const [k, v] of Object.entries(update)) {
+                if (v === undefined) {
+                    payload[k] = null;
+                }
+                else if (Array.isArray(v) && (v.length === 0 || typeof v[0] === 'number')) {
+                    payload[k] = Buffer.from(v);
+                }
+                else {
+                    payload[k] = v;
+                }
+            }
+            // Strategy: FK is a connection-level setting in SQLite. PRAGMA changes
+            // inside a Knex transaction are no-ops (SQLite restriction), but PRAGMA
+            // changes OUTSIDE a transaction persist.
+            //
+            // When called with trx (inside a transaction): the caller is expected to have
+            // already disabled FK before opening the transaction. We run the UPDATE via
+            // the transaction handle (no PRAGMA calls needed here — they'd be no-ops or
+            // pool-exhausting anyway).
+            //
+            // When called without trx (outside a transaction): disable FK, run UPDATE,
+            // re-enable FK.
+            if (trx != null) {
+                // Inside caller's transaction — FK was disabled before the transaction.
+                // Just run the UPDATE; do NOT try to PRAGMA here (no-op or timeout).
+                this.whenLastAccess = new Date();
+                await (this.toDb(trx))('outputs')
+                    .where({ outputId })
+                    .update(payload);
+            }
+            else {
+                // Outside any transaction — we can safely toggle FK on the bare connection.
+                await this.knex.raw('PRAGMA foreign_keys = OFF');
+                try {
+                    this.whenLastAccess = new Date();
+                    await this.knex('outputs').where({ outputId }).update(payload);
+                }
+                finally {
+                    await this.knex.raw('PRAGMA foreign_keys = ON');
+                }
+            }
+        }
+        else {
+            await this.updateOutput(outputId, update, trx);
+        }
+    }
+    /**
+     * Post-cutover SQLite: disable FK on the bare connection BEFORE opening a
+     * transaction. PRAGMA foreign_keys changes inside SQLite transactions are no-ops,
+     * so this MUST be called before `this.knex.transaction()`.
+     *
+     * Only acts when post-cutover AND SQLite. Pre-cutover or MySQL: no-op.
+     */
+    async disableForeignKeys() {
+        const postCutover = await this.isPostCutover();
+        if (postCutover && this.dbtype === 'SQLite') {
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        }
+    }
+    /**
+     * Re-enable FK after the transaction opened via `disableForeignKeys()` completes.
+     * Only acts when post-cutover AND SQLite.
+     */
+    async enableForeignKeys() {
+        const postCutover = await this.isPostCutover();
+        if (postCutover && this.dbtype === 'SQLite') {
+            await this.knex.raw('PRAGMA foreign_keys = ON');
+        }
+    }
     async findTxLabelMaps(args) {
         const q = this.findTxLabelMapsQuery(args);
         const r = await q;
@@ -734,10 +1284,12 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return await this.getCount(this.findOutputTagsQuery(args));
     }
     async countProvenTxReqs(args) {
-        return await this.getCount(this.findProvenTxReqsQuery(args));
+        const reqTable = await this.provenTxReqsTableName();
+        return await this.getCount(this.findProvenTxReqsQuery(args, reqTable));
     }
     async countProvenTxs(args) {
-        return await this.getCount(this.findProvenTxsQuery(args));
+        const tableName = await this.provenTxsTableName();
+        return await this.getCount(this.findProvenTxsQuery(args, tableName));
     }
     async countSyncStates(args) {
         return await this.getCount(this.findSyncStatesQuery(args));
@@ -985,13 +1537,19 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
      * - sending (if excludeSending is false)
      */
     async countChangeInputs(userId, basketId, excludeSending) {
-        const status = ['completed', 'unproven'];
+        const legacyStatus = ['completed', 'unproven'];
         if (!excludeSending)
-            status.push('sending');
+            legacyStatus.push('sending');
+        const postCutover = await this.isPostCutover();
         const q = this.knex('outputs as o')
             .join('transactions as t', 'o.transactionId', 't.transactionId')
-            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId })
-            .whereIn('t.status', status);
+            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId });
+        if (postCutover) {
+            q.whereIn('t.processing', this.legacyStatiToProcessing(legacyStatus));
+        }
+        else {
+            q.whereIn('t.status', legacyStatus);
+        }
         const count = await this.getCount(q);
         return count;
     }
@@ -1072,15 +1630,20 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
         return byTag;
     }
     async sumSpendableSatoshisInBasket(userId, basketId, excludeSending, trx) {
-        const status = ['completed', 'unproven'];
+        const legacyStatus = ['completed', 'unproven'];
         if (!excludeSending)
-            status.push('sending');
-        const row = await this.toDb(trx)('outputs as o')
+            legacyStatus.push('sending');
+        const postCutover = await this.isPostCutover();
+        const q = this.toDb(trx)('outputs as o')
             .join('transactions as t', 'o.transactionId', 't.transactionId')
-            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId })
-            .whereIn('t.status', status)
-            .sum({ totalSatoshis: 'o.satoshis' })
-            .first();
+            .where({ 'o.userId': userId, 'o.spendable': true, 'o.basketId': basketId });
+        if (postCutover) {
+            q.whereIn('t.processing', this.legacyStatiToProcessing(legacyStatus));
+        }
+        else {
+            q.whereIn('t.status', legacyStatus);
+        }
+        const row = await q.sum({ totalSatoshis: 'o.satoshis' }).first();
         return Number(((row != null) && row.totalSatoshis) || 0);
     }
     /**
@@ -1089,44 +1652,78 @@ class StorageKnex extends StorageProvider_1.StorageProvider {
      * Transactionally allocate the output such that
      */
     async allocateChangeInput(userId, basketId, targetSatoshis, exactSatoshis, excludeSending, transactionId) {
-        const status = ['completed', 'unproven'];
+        const legacyStatus = ['completed', 'unproven'];
         if (!excludeSending)
-            status.push('sending');
-        const r = await this.knex.transaction(async (trx) => {
-            const baseQuery = () => trx('outputs as o')
-                .join('transactions as t', 'o.transactionId', 't.transactionId')
-                .where('o.userId', userId)
-                .where('o.spendable', true)
-                .where('o.basketId', basketId)
-                .whereIn('t.status', status)
-                .select('o.*');
-            let output;
-            if (exactSatoshis !== undefined) {
-                output = await baseQuery().where('o.satoshis', exactSatoshis).orderBy('o.outputId', 'asc').first();
+            legacyStatus.push('sending');
+        const postCutover = await this.isPostCutover();
+        const processingFilter = postCutover ? this.legacyStatiToProcessing(legacyStatus) : undefined;
+        // Post-cutover bridge-period: `transactionId` here is a legacy row in
+        // `transactions_legacy` (new unsigned tx created by createAction). The
+        // `outputs.spentBy` FK now references `transactions.transactionId`, so
+        // setting spentBy to a transactions_legacy ID would violate the constraint.
+        // PRAGMA foreign_keys is silently ignored inside SQLite transactions, so
+        // we toggle FK enforcement on the bare connection BEFORE opening the
+        // transaction. processAction will remap spentBy to the real new transactionId
+        // once the txid is known and the new schema row is created.
+        const isSqlite = this.dbtype === 'SQLite';
+        if (postCutover && isSqlite) {
+            await this.knex.raw('PRAGMA foreign_keys = OFF');
+        }
+        let r;
+        try {
+            r = await this.knex.transaction(async (trx) => {
+                const baseQuery = () => {
+                    const q = trx('outputs as o')
+                        .join('transactions as t', 'o.transactionId', 't.transactionId')
+                        .where('o.userId', userId)
+                        .where('o.spendable', true)
+                        .where('o.basketId', basketId)
+                        .select('o.*');
+                    if (processingFilter != null) {
+                        q.whereIn('t.processing', processingFilter);
+                    }
+                    else {
+                        q.whereIn('t.status', legacyStatus);
+                    }
+                    return q;
+                };
+                let output;
+                if (exactSatoshis !== undefined) {
+                    output = await baseQuery().where('o.satoshis', exactSatoshis).orderBy('o.outputId', 'asc').first();
+                }
+                output !== null && output !== void 0 ? output : (output = await baseQuery()
+                    .where('o.satoshis', '>=', targetSatoshis)
+                    .orderBy('o.satoshis', 'asc')
+                    .orderBy('o.outputId', 'asc')
+                    .first());
+                output !== null && output !== void 0 ? output : (output = await baseQuery()
+                    .where('o.satoshis', '<', targetSatoshis)
+                    .orderBy('o.satoshis', 'desc')
+                    .orderBy('o.outputId', 'desc')
+                    .first());
+                if (output == null)
+                    return undefined;
+                // Post-cutover: transactionId is in transactions_legacy; FK would fail.
+                // markOutputAsSpentBy disables FK via raw knex handle, bypassing
+                // verifyReadyForDatabaseAccess that would re-enable it.
+                // Mapping §2: bridge-period spentBy → transactions_legacy during createAction.
+                await this.markOutputAsSpentBy(output.outputId, {
+                    spendable: false,
+                    spentBy: transactionId
+                }, trx);
+                // Keep behavior identical to the pre-optimization path: ensure lockingScript
+                // is present even when it was offloaded from outputs into rawTx storage.
+                await this.validateOutputScript(output, trx);
+                output.spendable = false;
+                output.spentBy = transactionId;
+                return output;
+            });
+        }
+        finally {
+            if (postCutover && isSqlite) {
+                await this.knex.raw('PRAGMA foreign_keys = ON');
             }
-            output !== null && output !== void 0 ? output : (output = await baseQuery()
-                .where('o.satoshis', '>=', targetSatoshis)
-                .orderBy('o.satoshis', 'asc')
-                .orderBy('o.outputId', 'asc')
-                .first());
-            output !== null && output !== void 0 ? output : (output = await baseQuery()
-                .where('o.satoshis', '<', targetSatoshis)
-                .orderBy('o.satoshis', 'desc')
-                .orderBy('o.outputId', 'desc')
-                .first());
-            if (output == null)
-                return undefined;
-            await this.updateOutput(output.outputId, {
-                spendable: false,
-                spentBy: transactionId
-            }, trx);
-            // Keep behavior identical to the pre-optimization path: ensure lockingScript
-            // is present even when it was offloaded from outputs into rawTx storage.
-            await this.validateOutputScript(output, trx);
-            output.spendable = false;
-            output.spentBy = transactionId;
-            return output;
-        });
+        }
         return r;
     }
     /** Convert null→undefined and Buffer→number[] on a retrieved entity in-place. */