Improve find wallet for redemption logic

typescript/src/bitcoin.ts

@@ -333,6 +333,18 @@ export interface Client {
     address: string
   ): Promise<UnspentTransactionOutput[]>
 
+  /**
+   * Gets the history of confirmed transactions for given Bitcoin address.
+   * Returned transactions are sorted from oldest to newest. The returned
+   * result does not contain unconfirmed transactions living in the mempool
+   * at the moment of request.
+   * @param address - Bitcoin address transaction history should be determined for.
+   * @param limit - Optional parameter that can limit the resulting list to
+   *        a specific number of last transaction. For example, limit = 5 will
+   *        return only the last 5 transactions for the given address.
+   */
+  getTransactionHistory(address: string, limit?: number): Promise<Transaction[]>
+
   /**
    * Gets the full transaction object for given transaction hash.
    * @param transactionHash - Hash of the transaction.

typescript/src/electrum.ts

@@ -253,6 +253,58 @@ export class Client implements BitcoinClient {
     )
   }
 
+  // eslint-disable-next-line valid-jsdoc
+  /**
+   * @see {BitcoinClient#getTransactionHistory}
+   */
+  getTransactionHistory(
+    address: string,
+    limit?: number
+  ): Promise<Transaction[]> {
+    return this.withElectrum<Transaction[]>(async (electrum: Electrum) => {
+      const script = bcoin.Script.fromAddress(address).toRaw().toString("hex")
+
+      // eslint-disable-next-line camelcase
+      type HistoryItem = { height: number; tx_hash: string }
+
+      let historyItems: HistoryItem[] = await this.withBackoffRetrier<
+        HistoryItem[]
+      >()(async () => {
+        return await electrum.blockchain_scripthash_getHistory(
+          computeScriptHash(script)
+        )
+      })
+
+      // According to https://electrumx.readthedocs.io/en/latest/protocol-methods.html#blockchain-scripthash-get-history
+      // unconfirmed items living in the mempool are appended at the end of the
+      // returned list and their height value is either -1 or 0. That means
+      // we need to take all items with height >0 to obtain a confirmed txs
+      // history.
+      historyItems = historyItems.filter((item) => item.height > 0)
+
+      // The list returned from blockchain.scripthash.get_history is sorted by
+      // the block height in the ascending order though we are sorting it
+      // again just in case (e.g. API contract changes).
+      historyItems = historyItems.sort(
+        (item1, item2) => item1.height - item2.height
+      )
+
+      if (
+        typeof limit !== "undefined" &&
+        limit > 0 &&
+        historyItems.length > limit
+      ) {
+        historyItems = historyItems.slice(-limit)
+      }
+
+      const transactions = historyItems.map((item) =>
+        this.getTransaction(TransactionHash.from(item.tx_hash))
+      )
+
+      return Promise.all(transactions)
+    })
+  }
+
   // eslint-disable-next-line valid-jsdoc
   /**
    * @see {BitcoinClient#getTransaction}

typescript/src/redemption.ts

@@ -7,11 +7,10 @@ import {
   UnspentTransactionOutput,
   Client as BitcoinClient,
   TransactionHash,
-  encodeToBitcoinAddress,
 } from "./bitcoin"
 import { Bridge, Identifier, TBTCToken } from "./chain"
 import { assembleTransactionProof } from "./proof"
-import { WalletState } from "./wallet"
+import { determineWalletMainUtxo, WalletState } from "./wallet"
 import { BitcoinNetwork } from "./bitcoin-network"
 import { Hex } from "./hex"
 
@@ -445,7 +444,7 @@ export async function findWalletForRedemption(
 
   for (const wallet of wallets) {
     const { walletPublicKeyHash } = wallet
-    const { state, mainUtxoHash, walletPublicKey, pendingRedemptionsValue } =
+    const { state, walletPublicKey, pendingRedemptionsValue } =
       await bridge.wallets(walletPublicKeyHash)
 
     // Wallet must be in Live state.
@@ -458,18 +457,20 @@ export async function findWalletForRedemption(
       continue
     }
 
-    if (
-      mainUtxoHash.equals(
-        Hex.from(
-          "0x0000000000000000000000000000000000000000000000000000000000000000"
-        )
-      )
-    ) {
+    // Wallet must have a main UTXO that can be determined.
+    const mainUtxo = await determineWalletMainUtxo(
+      walletPublicKeyHash,
+      bridge,
+      bitcoinClient,
+      bitcoinNetwork
+    )
+    if (!mainUtxo) {
       console.debug(
-        `Main utxo not set for wallet public ` +
-          `key hash(${walletPublicKeyHash.toString()}). ` +
+        `Could not find matching UTXO on chains ` +
+          `for wallet public key hash (${walletPublicKeyHash.toString()}). ` +
           `Continue the loop execution to the next wallet...`
       )
+      continue
     }
 
     const pendingRedemption = await bridge.pendingRedemptions(
@@ -489,38 +490,6 @@ export async function findWalletForRedemption(
       continue
     }
 
-    const walletBitcoinAddress = encodeToBitcoinAddress(
-      wallet.walletPublicKeyHash.toString(),
-      true,
-      bitcoinNetwork
-    )
-
-    // TODO: In case a wallet is working on something (e.g. redemption) and a
-    // Bitcoin transaction was already submitted by the wallet to the bitcoin
-    // chain (new utxo returned from bitcoin client), but proof hasn't been
-    // submitted yet to the Bridge (old main utxo returned from the Bridge) the
-    // `findWalletForRedemption` function will not find such a wallet. To cover
-    // this case, we should take, for example, the last 5 transactions made by
-    // the wallet into account. We will address this issue in a follow-up work.
-    const utxos = await bitcoinClient.findAllUnspentTransactionOutputs(
-      walletBitcoinAddress
-    )
-
-    // We need to find correct utxo- utxo components must point to the recent
-    // main UTXO of the given wallet, as currently known on the chain.
-    const mainUtxo = utxos.find((utxo) =>
-      mainUtxoHash.equals(bridge.buildUtxoHash(utxo))
-    )
-
-    if (!mainUtxo) {
-      console.debug(
-        `Could not find matching UTXO on chains ` +
-          `for wallet public key hash(${walletPublicKeyHash.toString()}). ` +
-          `Continue the loop execution to the next wallet...`
-      )
-      continue
-    }
-
     const walletBTCBalance = mainUtxo.value.sub(pendingRedemptionsValue)
 
     // Save the max possible redemption amount.

typescript/src/wallet.ts

@@ -1,6 +1,14 @@
 import { BigNumber } from "ethers"
 import { Hex } from "./hex"
-import { Event, Identifier } from "./chain"
+import { Bridge, Event, Identifier } from "./chain"
+import {
+  Client as BitcoinClient,
+  createOutputScriptFromAddress,
+  encodeToBitcoinAddress,
+  TransactionOutput,
+  UnspentTransactionOutput,
+} from "./bitcoin"
+import { BitcoinNetwork } from "./bitcoin-network"
 
 /* eslint-disable no-unused-vars */
 export enum WalletState {
@@ -209,3 +217,117 @@ type DkgResult = {
    */
   membersHash: Hex
 }
+
+/**
+ * Determines the plain-text wallet main UTXO currently registered in the
+ * Bridge on-chain contract. The returned main UTXO can be undefined if the
+ * wallet does not have a main UTXO registered in the Bridge at the moment.
+ *
+ * WARNING: THIS FUNCTION CANNOT DETERMINE THE MAIN UTXO IF IT COMES FROM A
+ * BITCOIN TRANSACTION THAT IS NOT ONE OF THE LATEST FIVE TRANSACTIONS
+ * TARGETING THE GIVEN WALLET PUBLIC KEY HASH. HOWEVER, SUCH A CASE IS
+ * VERY UNLIKELY.
+ *
+ * @param walletPublicKeyHash - Public key hash of the wallet.
+ * @param bridge - The handle to the Bridge on-chain contract.
+ * @param bitcoinClient - Bitcoin client used to interact with the network.
+ * @param bitcoinNetwork - Bitcoin network.
+ * @returns Promise holding the wallet main UTXO or undefined value.
+ */
+export async function determineWalletMainUtxo(
+  walletPublicKeyHash: Hex,
+  bridge: Bridge,
+  bitcoinClient: BitcoinClient,
+  bitcoinNetwork: BitcoinNetwork
+): Promise<UnspentTransactionOutput | undefined> {
+  const { mainUtxoHash } = await bridge.wallets(walletPublicKeyHash)
+
+  // Valid case when the wallet doesn't have a main UTXO registered into
+  // the Bridge.
+  if (
+    mainUtxoHash.equals(
+      Hex.from(
+        "0x0000000000000000000000000000000000000000000000000000000000000000"
+      )
+    )
+  ) {
+    return undefined
+  }
+
+  // Declare a helper function that will try to determine the main UTXO for
+  // the given wallet address type.
+  const determine = async (
+    witnessAddress: boolean
+  ): Promise<UnspentTransactionOutput | undefined> => {
+    // Build the wallet Bitcoin address based on its public key hash.
+    const walletAddress = encodeToBitcoinAddress(
+      walletPublicKeyHash.toString(),
+      witnessAddress,
+      bitcoinNetwork
+    )
+
+    // Get the wallet transaction history. The wallet main UTXO registered in the
+    // Bridge almost always comes from the latest BTC transaction made by the wallet.
+    // However, there may be cases where the BTC transaction was made but their
+    // SPV proof is not yet submitted to the Bridge thus the registered main UTXO
+    // points to the second last BTC transaction. In theory, such a gap between
+    // the actual latest BTC transaction and the registered main UTXO in the
+    // Bridge may be even wider. The exact behavior is a wallet implementation
+    // detail and not a protocol invariant so, it may be subject of changes.
+    // To cover the worst possible cases, we always take the five latest
+    // transactions made by the wallet for consideration.
+    const walletTransactions = await bitcoinClient.getTransactionHistory(
+      walletAddress,
+      5
+    )
+
+    // Get the wallet script based on the wallet address. This is required
+    // to find transaction outputs that lock funds on the wallet.
+    const walletScript = createOutputScriptFromAddress(walletAddress)
+    const isWalletOutput = (output: TransactionOutput) =>
+      walletScript.equals(output.scriptPubKey)
+
+    // Start iterating from the latest transaction as the chance it matches
+    // the wallet main UTXO is the highest.
+    for (let i = walletTransactions.length - 1; i >= 0; i--) {
+      const walletTransaction = walletTransactions[i]
+
+      // Find the output that locks the funds on the wallet. Only such an output
+      // can be a wallet main UTXO.
+      const outputIndex = walletTransaction.outputs.findIndex(isWalletOutput)
+
+      // Should never happen as all transactions come from wallet history. Just
+      // in case check whether the wallet output was actually found.
+      if (outputIndex < 0) {
+        continue
+      }
+
+      // Build a candidate UTXO instance based on the detected output.
+      const utxo: UnspentTransactionOutput = {
+        transactionHash: walletTransaction.transactionHash,
+        outputIndex: outputIndex,
+        value: walletTransaction.outputs[outputIndex].value,
+      }
+
+      // Check whether the candidate UTXO hash matches the main UTXO hash stored
+      // on the Bridge.
+      if (mainUtxoHash.equals(bridge.buildUtxoHash(utxo))) {
+        return utxo
+      }
+    }
+
+    return undefined
+  }
+
+  // The most common case is that the wallet uses a witness address for all
+  // operations. Try to determine the main UTXO for that address first as the
+  // chance for success is the highest here.
+  const mainUtxo = await determine(true)
+  if (mainUtxo) {
+    return mainUtxo
+  }
+
+  // In case the main UTXO was not found for witness address, there is still
+  // a chance it exists for the legacy wallet address.
+  return determine(false)
+}