fix: make getInscriptions to return txid and vout object (#15)

* fix: make getInscriptions to return txid and vout object

Author: jrwbabylonlab

docs/WalletIntegration.md

@@ -56,9 +56,11 @@ export interface UTXO {
   scriptPubKey: string;
 }
 
-export interface Inscription {
-  // output of the inscription in the format of `txid:vout`
-  output: string;
+export interface InscriptionIdentifier {
+  // hash of transaction that holds the ordinals/brc-2-/runes etc in the UTXO
+  txid: string;
+  // index of the output in the transaction
+  vout: number;
 }
 
 // supported networks
@@ -342,25 +344,47 @@ export class OKXWallet extends WalletProvider {
     return await getTipHeight();
   };
 
-  // Inscriptions(Ordinal/Runes/BRC-20 etc)
-  getInscriptions = async (): Promise<Inscription[]> => {
+  getInscriptions = async (): Promise<InscriptionIdentifier[]> => {
     if (!this.okxWalletInfo) {
       throw new Error("OKX Wallet not connected");
     }
-    const inscriptions: Inscription[] = [];
+    // max num of iterations to prevent infinite loop
+    const MAX_ITERATIONS = 100;
+    // Fetch inscriptions in batches of 100
+    const limit = 100;
+    const inscriptionIdentifiers: InscriptionIdentifier[] = [];
     let cursor = 0;
-    while (true) {
-      const { list } = await this.bitcoinNetworkProvider.getInscriptions(
-        cursor,
-        DEFAULT_INSCRIPTION_LIMIT,
-      );
-      inscriptions.push(...list);
-      if (list.length < DEFAULT_INSCRIPTION_LIMIT) {
-        break;
+    let iterations = 0;
+    try {
+      while (iterations < MAX_ITERATIONS) {
+        const { list } = await this.bitcoinNetworkProvider.getInscriptions(
+          cursor,
+          limit,
+        );
+        const identifiers = list.map((i: { output: string }) => {
+          const [txid, vout] = i.output.split(":");
+          return {
+            txid,
+            vout,
+          };
+        });
+        inscriptionIdentifiers.push(...identifiers);
+        if (list.length < limit) {
+          break;
+        }
+        cursor += limit;
+        iterations++;
+        if (iterations >= MAX_ITERATIONS) {
+          throw new Error(
+            "Exceeded maximum iterations when fetching inscriptions",
+          );
+        }
       }
-      cursor += DEFAULT_INSCRIPTION_LIMIT;
+    } catch (error) {
+      throw new Error("Failed to get inscriptions from OKX Wallet");
     }
-    return inscriptions;
+
+    return inscriptionIdentifiers;
   };
 }
 ```

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-staking",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "private": true,
   "scripts": {
     "dev": "next dev",

package.json

@@ -1,6 +1,6 @@
 import { postVerifyUtxoOrdinals, UtxoInfo } from "@/app/api/postFilterOrdinals";
 
-import { Inscription, UTXO } from "../wallet/wallet_provider";
+import { InscriptionIdentifier, UTXO } from "../wallet/wallet_provider";
 
 /**
  * Filters out UTXOs that contain ordinals.
@@ -17,19 +17,25 @@ import { Inscription, UTXO } from "../wallet/wallet_provider";
 export const filterOrdinals = async (
   utxos: UTXO[],
   address: string,
-  getInscriptionsFromWalletCb: () => Promise<Inscription[]>,
+  getInscriptionsFromWalletCb?: () => Promise<InscriptionIdentifier[]>,
 ): Promise<UTXO[]> => {
   if (!utxos.length) {
     return [];
   }
+  // fallback to Babylon API if the wallet does not support getting inscriptions
+  if (!getInscriptionsFromWalletCb) {
+    return filterFromApi(utxos, address);
+  }
   // try to get the ordinals from the wallet first, if the wallet supports it
   // otherwise fallback to the Babylon API
   try {
     const inscriptions = await getInscriptionsFromWalletCb();
     // filter out the utxos that contains ordinals
     return utxos.filter(
       (utxo) =>
-        !inscriptions.find((i) => i.output === `${utxo.txid}:${utxo.vout}`),
+        !inscriptions.find((i) => {
+          return i.txid === utxo.txid && i.vout === utxo.vout;
+        }),
     );
   } catch (error) {
     return filterFromApi(utxos, address);

src/utils/utxo/index.ts

@@ -11,7 +11,7 @@ import {
 } from "../../mempool_api";
 import {
   Fees,
-  Inscription,
+  InscriptionIdentifier,
   Network,
   UTXO,
   WalletProvider,
@@ -210,7 +210,7 @@ export class BitgetWallet extends WalletProvider {
     return await getTipHeight();
   };
 
-  getInscriptions(): Promise<Inscription[]> {
+  getInscriptions(): Promise<InscriptionIdentifier[]> {
     throw new Error("Method not implemented.");
   }
 }

src/utils/wallet/providers/bitget_wallet.ts

@@ -32,7 +32,7 @@ import {
 import { WalletError, WalletErrorType } from "../../errors";
 import {
   Fees,
-  Inscription,
+  InscriptionIdentifier,
   Network,
   UTXO,
   WalletProvider,
@@ -292,7 +292,7 @@ export class KeystoneWallet extends WalletProvider {
     return await getTipHeight();
   };
 
-  getInscriptions(): Promise<Inscription[]> {
+  getInscriptions(): Promise<InscriptionIdentifier[]> {
     throw new Error("Method not implemented.");
   }
 }

src/utils/wallet/providers/keystone/index.ts

@@ -12,9 +12,8 @@ import {
   pushTx,
 } from "../../mempool_api";
 import {
-  DEFAULT_INSCRIPTION_LIMIT,
   Fees,
-  Inscription,
+  InscriptionIdentifier,
   Network,
   UTXO,
   WalletInfo,
@@ -176,23 +175,51 @@ export class OKXWallet extends WalletProvider {
   };
 
   // Inscriptions are only available on OKX Wallet BTC mainnet (i.e okxWallet.bitcoin)
-  getInscriptions = async (): Promise<Inscription[]> => {
+  getInscriptions = async (): Promise<InscriptionIdentifier[]> => {
     if (!this.okxWalletInfo) {
       throw new Error("OKX Wallet not connected");
     }
-    const inscriptions: Inscription[] = [];
-    let cursor = 0;
-    while (true) {
-      const { list } = await this.bitcoinNetworkProvider.getInscriptions(
-        cursor,
-        DEFAULT_INSCRIPTION_LIMIT,
+    if (this.networkEnv !== Network.MAINNET) {
+      throw new Error(
+        "Inscriptions are only available on OKX Wallet BTC mainnet",
       );
-      inscriptions.push(...list);
-      if (list.length < DEFAULT_INSCRIPTION_LIMIT) {
-        break;
+    }
+    // max num of iterations to prevent infinite loop
+    const MAX_ITERATIONS = 100;
+    // Fetch inscriptions in batches of 100
+    const limit = 100;
+    const inscriptionIdentifiers: InscriptionIdentifier[] = [];
+    let cursor = 0;
+    let iterations = 0;
+    try {
+      while (iterations < MAX_ITERATIONS) {
+        const { list } = await this.bitcoinNetworkProvider.getInscriptions(
+          cursor,
+          limit,
+        );
+        const identifiers = list.map((i: { output: string }) => {
+          const [txid, vout] = i.output.split(":");
+          return {
+            txid,
+            vout,
+          };
+        });
+        inscriptionIdentifiers.push(...identifiers);
+        if (list.length < limit) {
+          break;
+        }
+        cursor += limit;
+        iterations++;
+        if (iterations >= MAX_ITERATIONS) {
+          throw new Error(
+            "Exceeded maximum iterations when fetching inscriptions",
+          );
+        }
       }
-      cursor += DEFAULT_INSCRIPTION_LIMIT;
+    } catch (error) {
+      throw new Error("Failed to get inscriptions from OKX Wallet");
     }
-    return inscriptions;
+
+    return inscriptionIdentifiers;
   };
 }

src/utils/wallet/providers/okx_wallet.ts

@@ -7,9 +7,8 @@ import {
   pushTx,
 } from "../../mempool_api";
 import {
-  DEFAULT_INSCRIPTION_LIMIT,
   Fees,
-  Inscription,
+  InscriptionIdentifier,
   Network,
   UTXO,
   WalletInfo,
@@ -165,20 +164,46 @@ export class OneKeyWallet extends WalletProvider {
   }
 
   // Inscriptions are only available on oneKey Wallet BTC mainnet
-  getInscriptions = async (): Promise<Inscription[]> => {
-    const inscriptions: Inscription[] = [];
+  getInscriptions = async (): Promise<InscriptionIdentifier[]> => {
+    if (this.networkEnv !== Network.MAINNET) {
+      throw new Error("Inscriptions are only available on OneKey mainnet");
+    }
+    // max num of iterations to prevent infinite loop
+    const MAX_ITERATIONS = 100;
+    // Fetch inscriptions in batches of 100
+    const limit = 100;
+    const inscriptionIdentifiers: InscriptionIdentifier[] = [];
     let cursor = 0;
-    while (true) {
-      const { list } = await this.bitcoinNetworkProvider.getInscriptions(
-        cursor,
-        DEFAULT_INSCRIPTION_LIMIT,
-      );
-      inscriptions.push(...list);
-      if (list.length < DEFAULT_INSCRIPTION_LIMIT) {
-        break;
+    let iterations = 0;
+    try {
+      while (iterations < MAX_ITERATIONS) {
+        const { list } = await this.bitcoinNetworkProvider.getInscriptions(
+          cursor,
+          limit,
+        );
+        const identifiers = list.map((i: { output: string }) => {
+          const [txid, vout] = i.output.split(":");
+          return {
+            txid,
+            vout,
+          };
+        });
+        inscriptionIdentifiers.push(...identifiers);
+        if (list.length < limit) {
+          break;
+        }
+        cursor += limit;
+        iterations++;
+        if (iterations >= MAX_ITERATIONS) {
+          throw new Error(
+            "Exceeded maximum iterations when fetching inscriptions",
+          );
+        }
       }
-      cursor += DEFAULT_INSCRIPTION_LIMIT;
+    } catch (error) {
+      throw new Error("Failed to get inscriptions from OKX Wallet");
     }
-    return inscriptions;
+
+    return inscriptionIdentifiers;
   };
 }

src/utils/wallet/providers/onekey_wallet.ts

@@ -9,7 +9,7 @@ import {
 
 import {
   Fees,
-  Inscription,
+  InscriptionIdentifier,
   Network,
   UTXO,
   WalletInfo,
@@ -171,7 +171,7 @@ export class TomoWallet extends WalletProvider {
     return await getTipHeight();
   };
 
-  getInscriptions(): Promise<Inscription[]> {
+  getInscriptions(): Promise<InscriptionIdentifier[]> {
     throw new Error("Method not implemented.");
   }
 }

src/utils/wallet/providers/tomo_wallet.ts

@@ -23,11 +23,12 @@ export interface UTXO {
   scriptPubKey: string;
 }
 
-export interface Inscription {
-  // output of the inscription in the format of `txid:vout`
-  output: string;
+export interface InscriptionIdentifier {
+  // hash of transaction that holds the ordinals/brc-2-/runes etc in the UTXO
+  txid: string;
+  // index of the output in the transaction
+  vout: number;
 }
-
 // supported networks
 export enum Network {
   MAINNET = "mainnet",
@@ -41,9 +42,6 @@ export type WalletInfo = {
   address: string;
 };
 
-// Default number of inscriptions to fetch in a single method call
-export const DEFAULT_INSCRIPTION_LIMIT = 100;
-
 /**
  * Abstract class representing a wallet provider.
  * Provides methods for connecting to a wallet, retrieving wallet information, signing transactions, and more.
@@ -153,5 +151,5 @@ export abstract class WalletProvider {
    * Retrieves the inscriptions for the connected wallet.
    * @returns A promise that resolves to an array of inscriptions.
    */
-  abstract getInscriptions(): Promise<Inscription[]>;
+  abstract getInscriptions(): Promise<InscriptionIdentifier[]>;
 }