refactor(btcindexer): rename types and API to more logical one

types:
- BtcTxStatus -> MintTxStatus
- TxStatusResp -> NbtcTxResp

RPC (and similar in the Indexer):
- statusByTxid -> nbtcMintTx
- statusBySuiAddress -> nbtcMintTxsBySuiAddr

Signed-off-by: Robert Zaremba <robert@zaremba.ch>

Author: robert-zaremba

packages/btcindexer/src/btcindexer.ts

@@ -10,8 +10,9 @@ import type {
 	MintBatchArg,
 	GroupedFinalizedTx,
 	NbtcAddress,
+	NbtcTxRow,
 } from "./models";
-import { BlockStatus, BtcTxStatus } from "./models";
+import { BlockStatus, MintTxStatus } from "./models";
 import { toSerializableError } from "./errutils";
 import type { Electrs } from "./electrs";
 import { ElectrsService } from "./electrs";
@@ -213,7 +214,7 @@ export class Indexer {
 			await this.storage.insertOrUpdateNbtcTxs(nbtcTxs);
 		}
 		if (senders.length > 0) {
-			await this.storage.insertSenderDeposits(senders);
+			await this.storage.insertBtcDeposit(senders);
 		}
 
 		if (nbtcTxs.length === 0) {
@@ -281,7 +282,7 @@ export class Indexer {
 	}
 
 	async processFinalizedTransactions(): Promise<void> {
-		const finalizedTxs = await this.storage.getFinalizedTxs(this.maxNbtcMintTxRetries);
+		const finalizedTxs = await this.storage.getNbtcFinalizedTxs(this.maxNbtcMintTxRetries);
 
 		if (!finalizedTxs || finalizedTxs.length === 0) {
 			return;
@@ -351,7 +352,7 @@ export class Indexer {
 					});
 					try {
 						// TODO: need to distniguish FINALIZED_REORG and MINTED_REORG
-						await this.storage.updateTxsStatus([txId], BtcTxStatus.FinalizedReorg);
+						await this.storage.updateNbtcTxsStatus([txId], MintTxStatus.FinalizedReorg);
 					} catch (e) {
 						console.error({
 							msg: "Minting: Failed to update status to 'finalized-reorg'",
@@ -467,7 +468,7 @@ export class Indexer {
 						processedPrimaryKeys.map((p) => ({
 							tx_id: p.tx_id,
 							vout: p.vout,
-							status: BtcTxStatus.Minted,
+							status: MintTxStatus.Minted,
 							suiTxDigest,
 						})),
 					);
@@ -477,7 +478,7 @@ export class Indexer {
 						processedPrimaryKeys.map((p) => ({
 							tx_id: p.tx_id,
 							vout: p.vout,
-							status: BtcTxStatus.MintFailed,
+							status: MintTxStatus.MintFailed,
 						})),
 					);
 				}
@@ -575,7 +576,7 @@ export class Indexer {
 			});
 			// This requires a new method in the Storage interface like:
 			// updateTxsStatus(txIds: string[], status: TxStatus): Promise<void>
-			await this.storage.updateTxsStatus(reorgedTxIds, BtcTxStatus.Reorg);
+			await this.storage.updateNbtcTxsStatus(reorgedTxIds, MintTxStatus.Reorg);
 		}
 
 		// TODO: add a unit test for it so we make sure we do not finalize reorrged tx.
@@ -587,7 +588,7 @@ export class Indexer {
 				msg: "Finalization: Applying status updates to D1",
 				finalizedCount: finalizationTxIds.length,
 			});
-			await this.storage.finalizeTxs(finalizationTxIds);
+			await this.storage.finalizeNbtcTxs(finalizationTxIds);
 		}
 	}
 
@@ -631,37 +632,27 @@ export class Indexer {
 		return txIds;
 	}
 
-	async getStatusByTxid(txid: string): Promise<NbtcTxResp | null> {
-		const latestHeight = await this.storage.getChainTip();
-		const tx = await this.storage.getStatusByTxid(txid);
-
-		if (!tx) {
-			return null;
-		}
+	// queries NbtcTxResp by BTC Tx ID
+	async getNbtcMintTx(txid: string): Promise<NbtcTxResp | null> {
+		const nbtMintRow = await this.storage.getNbtcMintTx(txid);
+		if (!nbtMintRow) return null;
 
-		const blockHeight = tx.block_height as number;
-		const confirmations = blockHeight && latestHeight ? latestHeight - blockHeight + 1 : 0;
+		const latestHeight = await this.storage.getChainTip();
 
-		return {
-			...tx,
-			btc_tx_id: tx.tx_id,
-			status: tx.status as BtcTxStatus,
-			block_height: blockHeight,
-			confirmations: confirmations > 0 ? confirmations : 0,
-		};
+		return nbtcRowToResp(nbtMintRow, latestHeight);
 	}
 
-	async getStatusBySuiAddress(suiAddress: string): Promise<NbtcTxResp[]> {
+	async getNbtcMintTxsBySuiAddr(suiAddress: string): Promise<NbtcTxResp[]> {
 		const latestHeight = await this.storage.getChainTip();
-		const dbResult = await this.storage.getStatusBySuiAddress(suiAddress);
+		const dbResult = await this.storage.getNbtcMintTxsBySuiAddr(suiAddress);
 
 		return dbResult.map((tx): NbtcTxResp => {
 			const blockHeight = tx.block_height as number;
 			const confirmations = blockHeight && latestHeight ? latestHeight - blockHeight + 1 : 0;
 			return {
 				...tx,
 				btc_tx_id: tx.tx_id,
-				status: tx.status as BtcTxStatus,
+				status: tx.status as MintTxStatus,
 				block_height: blockHeight,
 				confirmations: confirmations > 0 ? confirmations : 0,
 			};
@@ -696,22 +687,10 @@ export class Indexer {
 	}
 
 	async getDepositsBySender(btcAddress: string): Promise<NbtcTxResp[]> {
-		const dbResult = await this.storage.getDepositsBySender(btcAddress);
+		const nbtcMintRows = await this.storage.getNbtcMintTxsByBtcSender(btcAddress);
 		const latestHeight = await this.storage.getChainTip();
 
-		return dbResult.map((tx): NbtcTxResp => {
-			const bh = tx.block_height;
-			const confirmations = bh && latestHeight ? latestHeight - bh + 1 : 0;
-			const btc_tx_id = tx.tx_id;
-			// @ts-expect-error The operand of a 'delete' operator must be optional
-			delete tx.tx_id;
-
-			return {
-				btc_tx_id,
-				confirmations: confirmations > 0 ? confirmations : 0,
-				...tx,
-			};
-		});
+		return nbtcMintRows.map((r) => nbtcRowToResp(r, latestHeight));
 	}
 
 	private async getSenderAddresses(tx: Transaction): Promise<string[]> {
@@ -764,3 +743,17 @@ function parseSuiRecipientFromOpReturn(script: Buffer): string | null {
 	// for now we cannot determine the recipient
 	return null;
 }
+
+function nbtcRowToResp(r: NbtcTxRow, latestHeight: number | null): NbtcTxResp {
+	const bh = r.block_height;
+	const confirmations = bh && latestHeight ? latestHeight - bh + 1 : 0;
+	const btc_tx_id = r.tx_id;
+	// @ts-expect-error The operand of a 'delete' operator must be optional
+	delete r.tx_id;
+
+	return {
+		btc_tx_id,
+		confirmations: confirmations > 0 ? confirmations : 0,
+		...r,
+	};
+}

packages/btcindexer/src/cf-storage.ts

@@ -1,7 +1,7 @@
 import { Block } from "bitcoinjs-lib";
 import { toSerializableError } from "./errutils";
 import type { BlockInfo, FinalizedTxRow, NbtcTxRow, PendingTx } from "./models";
-import { BlockStatus, BtcTxStatus } from "./models";
+import { BlockStatus, MintTxStatus } from "./models";
 import type { Storage } from "./storage";
 
 export class CFStorage implements Storage {
@@ -146,11 +146,11 @@ export class CFStorage implements Storage {
 		const now = Date.now();
 		const insertOrUpdateNbtcTxStmt = this.d1.prepare(
 			`INSERT INTO nbtc_minting (tx_id, vout, block_hash, block_height, sui_recipient, amount_sats, status, created_at, updated_at)
-             VALUES (?, ?, ?, ?, ?, ?, '${BtcTxStatus.Confirming}', ?, ?)
+             VALUES (?, ?, ?, ?, ?, ?, '${MintTxStatus.Confirming}', ?, ?)
              ON CONFLICT(tx_id, vout) DO UPDATE SET
                 block_hash = excluded.block_hash,
                 block_height = excluded.block_height,
-                status = '${BtcTxStatus.Confirming}',
+                status = '${MintTxStatus.Confirming}',
                 updated_at = excluded.updated_at`,
 		);
 		const statements = txs.map((tx) =>
@@ -176,17 +176,17 @@ export class CFStorage implements Storage {
 		}
 	}
 
-	async getFinalizedTxs(maxRetries: number): Promise<FinalizedTxRow[]> {
+	async getNbtcFinalizedTxs(maxRetries: number): Promise<FinalizedTxRow[]> {
 		const finalizedTxs = await this.d1
 			.prepare(
-				`SELECT tx_id, vout, block_hash, block_height, retry_count, nbtc_pkg, sui_network FROM nbtc_minting WHERE (status = '${BtcTxStatus.Finalized}' OR (status = '${BtcTxStatus.MintFailed}' AND retry_count <= ?)) AND status != '${BtcTxStatus.FinalizedReorg}'`,
+				`SELECT tx_id, vout, block_hash, block_height, retry_count, nbtc_pkg, sui_network FROM nbtc_minting WHERE (status = '${MintTxStatus.Finalized}' OR (status = '${MintTxStatus.MintFailed}' AND retry_count <= ?)) AND status != '${MintTxStatus.FinalizedReorg}'`,
 			)
 			.bind(maxRetries)
 			.all<FinalizedTxRow>();
 		return finalizedTxs.results ?? [];
 	}
 
-	async updateTxsStatus(txIds: string[], status: BtcTxStatus): Promise<void> {
+	async updateNbtcTxsStatus(txIds: string[], status: MintTxStatus): Promise<void> {
 		if (txIds.length === 0) {
 			return;
 		}
@@ -201,7 +201,7 @@ export class CFStorage implements Storage {
 	}
 
 	async batchUpdateNbtcTxs(
-		updates: { tx_id: string; vout: number; status: BtcTxStatus; suiTxDigest?: string }[],
+		updates: { tx_id: string; vout: number; status: MintTxStatus; suiTxDigest?: string }[],
 	): Promise<void> {
 		const now = Date.now();
 		const setMintedStmt = this.d1.prepare(
@@ -212,10 +212,10 @@ export class CFStorage implements Storage {
 		);
 
 		const statements = updates.map((p) => {
-			if (p.status === BtcTxStatus.Minted) {
-				return setMintedStmt.bind(BtcTxStatus.Minted, p.suiTxDigest, now, p.tx_id, p.vout);
+			if (p.status === MintTxStatus.Minted) {
+				return setMintedStmt.bind(MintTxStatus.Minted, p.suiTxDigest, now, p.tx_id, p.vout);
 			} else {
-				return setFailedStmt.bind(BtcTxStatus.MintFailed, now, p.tx_id, p.vout);
+				return setFailedStmt.bind(MintTxStatus.MintFailed, now, p.tx_id, p.vout);
 			}
 		});
 		try {
@@ -236,7 +236,7 @@ export class CFStorage implements Storage {
 		// This ensures we only try to verify blocks we know about.
 		const blocksToVerify = await this.d1
 			.prepare(
-				`SELECT DISTINCT block_hash FROM nbtc_minting WHERE status = '${BtcTxStatus.Confirming}' AND block_hash IS NOT NULL`,
+				`SELECT DISTINCT block_hash FROM nbtc_minting WHERE status = '${MintTxStatus.Confirming}' AND block_hash IS NOT NULL`,
 			)
 			.all<{ block_hash: string }>();
 		return blocksToVerify.results ?? [];
@@ -247,7 +247,7 @@ export class CFStorage implements Storage {
 		const placeholders = blockHashes.map(() => "?").join(",");
 		const updateStmt = this.d1
 			.prepare(
-				`UPDATE nbtc_minting SET status = '${BtcTxStatus.Reorg}', updated_at = ? WHERE block_hash IN (${placeholders})`,
+				`UPDATE nbtc_minting SET status = '${MintTxStatus.Reorg}', updated_at = ? WHERE block_hash IN (${placeholders})`,
 			)
 			.bind(now, ...blockHashes);
 		await updateStmt.run();
@@ -256,33 +256,32 @@ export class CFStorage implements Storage {
 	async getConfirmingTxs(): Promise<PendingTx[]> {
 		const pendingTxs = await this.d1
 			.prepare(
-				`SELECT tx_id, block_hash, block_height FROM nbtc_minting WHERE status = '${BtcTxStatus.Confirming}'`,
+				`SELECT tx_id, block_hash, block_height FROM nbtc_minting WHERE status = '${MintTxStatus.Confirming}'`,
 			)
 			.all<PendingTx>();
 		return pendingTxs.results ?? [];
 	}
 
-	async finalizeTxs(txIds: string[]): Promise<void> {
+	async finalizeNbtcTxs(txIds: string[]): Promise<void> {
 		if (txIds.length === 0) {
 			return;
 		}
 		const now = Date.now();
 		const finalizeStmt = this.d1.prepare(
-			`UPDATE nbtc_minting SET status = '${BtcTxStatus.Finalized}', updated_at = ${now} WHERE tx_id = ?`,
+			`UPDATE nbtc_minting SET status = '${MintTxStatus.Finalized}', updated_at = ${now} WHERE tx_id = ?`,
 		);
 		const statements = txIds.map((txId) => finalizeStmt.bind(txId));
 		await this.d1.batch(statements);
 	}
 
-	// TODO: rename to getNbtcMineTx
-	async getStatusByTxid(txid: string): Promise<NbtcTxRow | null> {
+	async getNbtcMintTx(txId: string): Promise<NbtcTxRow | null> {
 		return this.d1
 			.prepare("SELECT * FROM nbtc_minting WHERE tx_id = ?")
-			.bind(txid)
+			.bind(txId)
 			.first<NbtcTxRow>();
 	}
 
-	async getStatusBySuiAddress(suiAddress: string): Promise<NbtcTxRow[]> {
+	async getNbtcMintTxsBySuiAddr(suiAddress: string): Promise<NbtcTxRow[]> {
 		const dbResult = await this.d1
 			.prepare("SELECT * FROM nbtc_minting WHERE sui_recipient = ? ORDER BY created_at DESC")
 			.bind(suiAddress)
@@ -296,7 +295,7 @@ export class CFStorage implements Storage {
 		const now = Date.now();
 		const insertStmt = this.d1.prepare(
 			`INSERT OR IGNORE INTO nbtc_minting (tx_id, vout, sui_recipient, amount_sats, status, created_at, updated_at)
-         VALUES (?, ?, ?, ?, '${BtcTxStatus.Broadcasting}', ?, ?)`,
+         VALUES (?, ?, ?, ?, '${MintTxStatus.Broadcasting}', ?, ?)`,
 		);
 
 		const statements = deposits.map((deposit) =>
@@ -312,7 +311,7 @@ export class CFStorage implements Storage {
 		await this.d1.batch(statements);
 	}
 
-	async getDepositsBySender(btcAddress: string): Promise<NbtcTxRow[]> {
+	async getNbtcMintTxsByBtcSender(btcAddress: string): Promise<NbtcTxRow[]> {
 		const query = this.d1.prepare(`
             SELECT m.* FROM nbtc_minting m
             JOIN nbtc_sender_deposits s ON m.tx_id = s.tx_id
@@ -323,7 +322,7 @@ export class CFStorage implements Storage {
 		return dbResult.results ?? [];
 	}
 
-	async insertSenderDeposits(senders: { txId: string; sender: string }[]): Promise<void> {
+	async insertBtcDeposit(senders: { txId: string; sender: string }[]): Promise<void> {
 		if (senders.length === 0) {
 			return;
 		}

packages/btcindexer/src/models.ts

@@ -58,7 +58,7 @@ export interface GroupedFinalizedTx {
  * - **reorg**: A blockchain reorg detected while the tx was in the 'confirming' state. The tx block is no longer part of the canonical chain.
  * - **finalized-reorg**: An edge-case status indicating that a tx was marked 'finalized', but was later discovered to be on an orphaned (re-org deeper than the confirmation depth).
  */
-export const enum BtcTxStatus {
+export const enum MintTxStatus {
 	Broadcasting = "broadcasting",
 	Confirming = "confirming",
 	Finalized = "finalized",
@@ -75,7 +75,7 @@ export const enum BlockStatus {
 
 export interface NbtcTxResp extends Omit<NbtcTxRow, "tx_id"> {
 	btc_tx_id: string;
-	status: BtcTxStatus;
+	status: MintTxStatus;
 	confirmations: number;
 }
 
@@ -88,7 +88,7 @@ export interface NbtcTxRow {
 	block_height: number | null;
 	sui_recipient: string;
 	amount_sats: number;
-	status: BtcTxStatus;
+	status: MintTxStatus;
 	// epoch time in ms
 	created_at: number;
 	// epoch time in ms

packages/btcindexer/src/router.ts

@@ -32,8 +32,8 @@ export default class HttpRouter {
 
 		r.post(RestPath.nbtcTx, this.postNbtcTx);
 		// ?sui_recipient="0x..."  - query by sui address
-		r.get(RestPath.nbtcTx, this.getStatusBySuiAddress);
-		r.get(RestPath.nbtcTx + "/:txid", this.getStatusByTxid); // query by bitcoin_tx_id
+		r.get(RestPath.nbtcTx, this.getNbtcMintTxsBySuiAddr);
+		r.get(RestPath.nbtcTx + "/:txid", this.getNbtcMintTx); // query by bitcoin_tx_id
 		r.get(RestPath.depositsBySender, this.getDepositsBySender);
 
 		//
@@ -133,7 +133,7 @@ export default class HttpRouter {
 		return kv.get(key);
 	};
 
-	getStatusByTxid = async (req: IRequest) => {
+	getNbtcMintTx = async (req: IRequest) => {
 		const params = req.params;
 		if (!params) {
 			return error(400, "Missing parameters");
@@ -142,23 +142,23 @@ export default class HttpRouter {
 		if (!txid) {
 			return error(400, "Missing txid parameter");
 		}
-		const result = await this.indexer().getStatusByTxid(txid);
+		const result = await this.indexer().getNbtcMintTx(txid);
 
 		if (result === null) {
 			return error(404, "Transaction not found.");
 		}
 		return result;
 	};
 
-	getStatusBySuiAddress = async (req: IRequest) => {
+	getNbtcMintTxsBySuiAddr = async (req: IRequest) => {
 		const suiRecipient = req.query.sui_recipient;
 		if (!suiRecipient || typeof suiRecipient !== "string") {
 			return error(400, "Missing or invalid sui_recipient query parameter.");
 		}
 		if (!isValidSuiAddress(suiRecipient)) {
 			return error(400, "Invalid SUI address format.");
 		}
-		return this.indexer().getStatusBySuiAddress(suiRecipient);
+		return this.indexer().getNbtcMintTxsBySuiAddr(suiRecipient);
 	};
 
 	getLatestHeight = () => {

packages/btcindexer/src/rpc-interface.ts

@@ -8,7 +8,7 @@ export interface BtcIndexerRpcI {
 	putBlocks(blocks: PutBlocks[]): Promise<number>;
 	latestHeight(): Promise<{ height: number | null }>;
 	putNbtcTx(txHex: string): Promise<{ tx_id: string; registered_deposits: number }>;
-	statusByTxid(txid: string): Promise<NbtcTxResp | null>;
-	statusBySuiAddress(suiAddress: string): Promise<NbtcTxResp[]>;
+	nbtcMintTx(txId: string): Promise<NbtcTxResp | null>;
+	nbtcMintTxsBySuiAddr(suiAddress: string): Promise<NbtcTxResp[]>;
 	depositsBySender(address: string): Promise<NbtcTxResp[]>;
 }