@lifi/sdk 3.3.0-alpha.3 → 3.3.0-beta.1

package/src/core/UTXO/isUTXOAddress.ts

@@ -1,5 +1,5 @@
 import { sha256 } from '@noble/hashes/sha256'
-import { bech32, bech32m } from 'bech32'
+import { type Decoded, bech32, bech32m } from 'bech32'
 import bs58 from 'bs58'
 
 export enum UTXONetwork {
@@ -26,26 +26,26 @@ export type UTXOAddress = {
 const addressTypes: {
   [key: number]: { type: UTXOAddressType; network: UTXONetwork }
 } = {
-  0x00: {
+  0: {
     type: UTXOAddressType.p2pkh,
     network: UTXONetwork.Mainnet,
   },
-  0x6f: {
+  111: {
     type: UTXOAddressType.p2pkh,
     network: UTXONetwork.Testnet,
   },
-  0x05: {
+  5: {
     type: UTXOAddressType.p2sh,
     network: UTXONetwork.Mainnet,
   },
-  0xc4: {
+  196: {
     type: UTXOAddressType.p2sh,
     network: UTXONetwork.Testnet,
   },
 }
 
 const parseBech32 = (address: string): UTXOAddress => {
-  let decoded
+  let decoded: Decoded
 
   try {
     if (
@@ -57,7 +57,7 @@ const parseBech32 = (address: string): UTXOAddress => {
     } else {
       decoded = bech32.decode(address)
     }
-  } catch (error) {
+  } catch (_error) {
     throw new Error('Invalid address')
   }
 
@@ -80,8 +80,7 @@ const parseBech32 = (address: string): UTXOAddress => {
   }
   const data = bech32.fromWords(decoded.words.slice(1))
 
-  let type
-
+  let type: UTXOAddressType
   if (data.length === 20) {
     type = UTXOAddressType.p2wpkh
   } else if (witnessVersion === 1) {
@@ -108,7 +107,7 @@ export const getUTXOAddress = (address: string): UTXOAddress => {
 
   try {
     decoded = bs58.decode(address)
-  } catch (error) {
+  } catch (_error) {
     throw new Error('Invalid address')
   }
 
@@ -160,7 +159,7 @@ export const isUTXOAddress = (
     }
 
     return true
-  } catch (error) {
+  } catch (_error) {
     return false
   }
 }

package/src/core/UTXO/parseUTXOErrors.ts

@@ -1,8 +1,8 @@
 import type { LiFiStep, Process } from '@lifi/types'
+import { SDKError } from '../../errors/SDKError.js'
 import { BaseError } from '../../errors/baseError.js'
 import { ErrorMessage, LiFiErrorCode } from '../../errors/constants.js'
 import { TransactionError, UnknownError } from '../../errors/errors.js'
-import { SDKError } from '../../errors/SDKError.js'
 
 export const parseUTXOErrors = async (
   e: Error,
@@ -21,6 +21,17 @@ export const parseUTXOErrors = async (
 }
 
 const handleSpecificErrors = (e: any) => {
+  // txn-mempool-conflict
+  if (
+    e.details?.includes?.('conflict') ||
+    e.cause?.message?.includes?.('conflict')
+  ) {
+    return new TransactionError(
+      LiFiErrorCode.TransactionConflict,
+      'Your transaction conflicts with another transaction already in the mempool. One or more inputs have been spent by another transaction.',
+      e
+    )
+  }
   if (e.code === 4001 || e.code === -32000 || e.cause?.includes?.('rejected')) {
     return new TransactionError(LiFiErrorCode.SignatureRejected, e.message, e)
   }

package/src/core/UTXO/types.ts

@@ -1,6 +1,6 @@
 import { ChainType } from '@lifi/types'
 import type { Client } from 'viem'
-import { type SDKProvider } from '../types.js'
+import type { SDKProvider } from '../types.js'
 
 export interface UTXOProviderOptions {
   getWalletClient?: () => Promise<Client>

package/src/core/UTXO/utxo-stack/actions/getBalance.ts

@@ -1,4 +1,4 @@
-import { type Account, type Chain, type Client, type Transport } from 'viem'
+import type { Account, Chain, Client, Transport } from 'viem'
 import type { UTXOAPISchema } from '../transports/utxo/types.js'
 
 export type GetBalanceParameters = {

package/src/core/UTXO/utxo-stack/actions/getBlock.ts

@@ -0,0 +1,58 @@
+import { Block } from 'bitcoinjs-lib'
+import {
+  type Account,
+  BlockNotFoundError,
+  type Chain,
+  type Client,
+  type Transport,
+} from 'viem'
+import type { UTXOSchema } from '../transports/utxo/types.js'
+
+export type GetBlockParameters =
+  | {
+      blockHash: string
+      blockNumber?: never
+    }
+  | {
+      blockHash?: never
+      blockNumber: number
+    }
+
+export type GetBlockReturnType = Block
+
+export async function getBlock<
+  C extends Chain | undefined,
+  A extends Account | undefined = Account | undefined,
+>(
+  client: Client<Transport, C, A, UTXOSchema>,
+  { blockHash, blockNumber }: GetBlockParameters
+): Promise<GetBlockReturnType> {
+  let blockHex: string | undefined
+  try {
+    let _blockHash = blockHash
+    if (!_blockHash && blockNumber) {
+      _blockHash = await client.request(
+        {
+          method: 'getblockhash',
+          params: [blockNumber],
+        },
+        { dedupe: true }
+      )
+    }
+    if (_blockHash) {
+      blockHex = await client.request(
+        {
+          method: 'getblock',
+          params: [_blockHash, 0],
+        },
+        { dedupe: true }
+      )
+    }
+  } catch (_error) {
+    throw new BlockNotFoundError({ blockHash, blockNumber } as never)
+  }
+  if (!blockHex) {
+    throw new BlockNotFoundError({ blockHash, blockNumber } as never)
+  }
+  return Block.fromHex(blockHex)
+}

package/src/core/UTXO/utxo-stack/actions/getBlockCount.ts

@@ -1,4 +1,4 @@
-import { type Account, type Chain, type Client, type Transport } from 'viem'
+import type { Account, Chain, Client, Transport } from 'viem'
 import type { UTXOSchema } from '../transports/utxo/types.js'
 
 export type GetBlockCountReturnType = number

package/src/core/UTXO/utxo-stack/actions/getBlockStats.ts

@@ -0,0 +1,55 @@
+import {
+  type Account,
+  BlockNotFoundError,
+  type Chain,
+  type Client,
+  type Transport,
+} from 'viem'
+import type { UTXOSchema } from '../transports/utxo/types.js'
+import type { BlockStats, BlockStatsKeys } from '../types/blockStats.js'
+
+export type GetBlockStatsParameters = (
+  | {
+      blockHash: string
+      blockNumber?: never
+    }
+  | {
+      blockHash?: never
+      blockNumber: number
+    }
+) & {
+  stats?: Array<BlockStatsKeys>
+}
+
+export type GetBlockStatsReturnType = BlockStats
+
+export async function getBlockStats<
+  C extends Chain | undefined,
+  A extends Account | undefined = Account | undefined,
+>(
+  client: Client<Transport, C, A, UTXOSchema>,
+  { blockHash, blockNumber, stats }: GetBlockStatsParameters
+): Promise<GetBlockStatsReturnType> {
+  const blockHashOrNumber = blockHash || blockNumber
+  if (!blockHashOrNumber) {
+    throw new BlockNotFoundError({ blockHash, blockNumber } as never)
+  }
+  try {
+    const params: [string | number, Array<BlockStatsKeys>?] = [
+      blockHashOrNumber,
+    ]
+    if (stats) {
+      params.push(stats)
+    }
+    const data = await client.request(
+      {
+        method: 'getblockstats',
+        params: params,
+      },
+      { dedupe: true }
+    )
+    return data
+  } catch (_error) {
+    throw new BlockNotFoundError({ blockHash, blockNumber } as never)
+  }
+}

package/src/core/UTXO/utxo-stack/actions/getUTXOTransaction.ts

@@ -1,4 +1,10 @@
-import { type Account, type Chain, type Client, type Transport } from 'viem'
+import {
+  type Account,
+  type Chain,
+  type Client,
+  TransactionNotFoundError,
+  type Transport,
+} from 'viem'
 import type { UTXOSchema } from '../transports/utxo/types.js'
 import type { UTXOTransaction } from '../types/transaction.js'
 
@@ -6,7 +12,7 @@ export type GetUTXOTransactionParameters = {
   /** The Id of the transaction */
   txId: string
   /** The block in which to look for the transaction */
-  blockhash?: string
+  blockHash?: string
 }
 
 export type GetUTXOTransactionReturnType = UTXOTransaction
@@ -16,15 +22,22 @@ export async function getUTXOTransaction<
   A extends Account | undefined = Account | undefined,
 >(
   client: Client<Transport, C, A, UTXOSchema>,
-  { txId, blockhash }: GetUTXOTransactionParameters
+  { txId, blockHash }: GetUTXOTransactionParameters
 ): Promise<GetUTXOTransactionReturnType> {
-  const params: [string, boolean, string?] = [txId, true]
-  if (blockhash) {
-    params.push(blockhash)
+  try {
+    const params: [string, boolean, string?] = [txId, true]
+    if (blockHash) {
+      params.push(blockHash)
+    }
+    const data = await client.request({
+      method: 'getrawtransaction',
+      params: params,
+    })
+    return data
+  } catch (_error) {
+    throw new TransactionNotFoundError({
+      blockHash: blockHash as never,
+      hash: txId as never,
+    })
   }
-  const data = await client.request({
-    method: 'getrawtransaction',
-    params: params,
-  })
-  return data
 }

package/src/core/UTXO/utxo-stack/actions/sendUTXOTransaction.ts

@@ -1,8 +1,8 @@
-import { type Account, type Chain, type Client, type Transport } from 'viem'
+import type { Account, Chain, Client, Transport } from 'viem'
 import type { UTXOSchema } from '../transports/utxo/types.js'
 
 export type SendUTXOTransactionParameters = {
-  /** The hex string of the raw transaction */
+  /** The hex string of the raw transaction. */
   hex: string
   /** Rejects transactions whose fee rate is higher than the specified value, expressed in BTC/kB. Set to 0 to accept any fee rate. Default = 0.10 */
   maxFeeRate?: number

package/src/core/UTXO/utxo-stack/actions/signPsbt.ts

@@ -1,4 +1,4 @@
-import { type Account, type Chain, type Client, type Transport } from 'viem'
+import type { Account, Chain, Client, Transport } from 'viem'
 import type {
   SignPsbtParameters,
   SignPsbtReturnType,

package/src/core/UTXO/utxo-stack/actions/waitForTransaction.ts

@@ -0,0 +1,387 @@
+import { Transaction, address } from 'bitcoinjs-lib'
+import {
+  type Chain,
+  type Client,
+  TransactionNotFoundError,
+  TransactionReceiptNotFoundError,
+  type Transport,
+  WaitForTransactionReceiptTimeoutError,
+  stringify,
+  withRetry,
+} from 'viem'
+import { getAction } from 'viem/utils'
+import type { UTXOTransaction } from '../types/transaction.js'
+import { observe } from '../utils/observe.js'
+import { getBlock } from './getBlock.js'
+import { getBlockStats } from './getBlockStats.js'
+import { getUTXOTransaction } from './getUTXOTransaction.js'
+import { watchBlockNumber } from './watchBlockNumber.js'
+
+export type ReplacementReason = 'cancelled' | 'replaced' | 'repriced'
+export type ReplacementReturnType = {
+  reason: ReplacementReason
+  replacedTransaction: Transaction
+  transaction: UTXOTransaction
+}
+
+export type WaitForTransactionReceiptReturnType = UTXOTransaction
+
+export type WithRetryParameters = {
+  // The delay (in ms) between retries.
+  delay?:
+    | ((config: { count: number; error: Error }) => number)
+    | number
+    | undefined
+  // The max number of times to retry.
+  retryCount?: number | undefined
+}
+
+export type WaitForTransactionReceiptParameters = {
+  /** The Id of the transaction. */
+  txId: string
+  /** The hex string of the raw transaction. */
+  txHex: string
+  /** The sender address of the transaction. */
+  senderAddress?: string
+  /**
+   * The number of confirmations (blocks that have passed) to wait before resolving.
+   * @default 1
+   */
+  confirmations?: number | undefined
+  /** Optional callback to emit if the transaction has been replaced. */
+  onReplaced?: ((response: ReplacementReturnType) => void) | undefined
+  /**
+   * Polling frequency (in ms). Defaults to the client's pollingInterval config.
+   * @default client.pollingInterval
+   */
+  pollingInterval?: number | undefined
+  /**
+   * Number of times to retry if the transaction or block is not found.
+   * @default 6 (exponential backoff)
+   */
+  retryCount?: number
+  /**
+   * Time to wait (in ms) between retries.
+   */
+  retryDelay?: ((config: { count: number; error: Error }) => number) | number
+  /** Optional timeout (in milliseconds) to wait before stopping polling. */
+  timeout?: number | undefined
+}
+
+/**
+ * Waits for the transaction to be included on a block (one confirmation), and then returns the transaction.
+ * - JSON-RPC Methods:
+ * - Polls getrawtransaction on each block until it has been processed.
+ * - If a transaction has been replaced:
+ * - Calls getblock and extracts the transactions
+ * - Checks if one of the transactions is a replacement
+ * - If so, calls getrawtransaction.
+ *
+ * The `waitForTransaction` action additionally supports replacement detection (e.g. RBF - transactions replaced-by-fee ).
+ *
+ * Transactions can be replaced when a user modifies their transaction in their wallet (to speed up or cancel).
+ * https://bitcoinops.org/en/topics/replace-by-fee/
+ *
+ * There are 3 types of Transaction Replacement reasons:
+ *
+ * - `repriced`: The fee has been modified (e.g. same outputs, different amounts)
+ * - `cancelled`: The Transaction has been cancelled (e.g. output is sender address)
+ * - `replaced`: The Transaction has been replaced (e.g. different outputs)
+ * @param client - Client to use
+ * @param parameters - {@link WaitForTransactionReceiptParameters}
+ * @returns The UTXO transaction. {@link WaitForTransactionReceiptReturnType}
+ */
+export async function waitForTransaction<chain extends Chain | undefined>(
+  client: Client<Transport, chain>,
+  {
+    confirmations = 1,
+    txId,
+    txHex,
+    senderAddress,
+    onReplaced,
+    pollingInterval = client.pollingInterval,
+    retryCount = 10,
+    retryDelay = 3_000,
+    timeout,
+  }: WaitForTransactionReceiptParameters
+): Promise<WaitForTransactionReceiptReturnType> {
+  const observerId = stringify(['waitForTransaction', client.uid, txId])
+
+  let count = 0
+  let transaction: UTXOTransaction | undefined
+  let replacedTransaction: Transaction | undefined
+  let retrying = false
+
+  return new Promise((resolve, reject) => {
+    if (timeout) {
+      setTimeout(
+        () =>
+          reject(
+            new WaitForTransactionReceiptTimeoutError({ hash: txId as never })
+          ),
+        timeout
+      )
+    }
+
+    const _unobserve = observe(
+      observerId,
+      { onReplaced, resolve, reject },
+      (emit) => {
+        const _unwatch = getAction(
+          client,
+          watchBlockNumber,
+          'watchBlockNumber'
+        )({
+          emitMissed: true,
+          emitOnBegin: true,
+          pollingInterval,
+          async onBlockNumber(blockNumber_) {
+            const done = (fn: () => void) => {
+              _unwatch()
+              fn()
+              _unobserve()
+            }
+
+            let blockNumber = blockNumber_
+
+            if (retrying) {
+              return
+            }
+            if (count > retryCount) {
+              done(() =>
+                emit.reject(
+                  new WaitForTransactionReceiptTimeoutError({
+                    hash: txId as never,
+                  })
+                )
+              )
+            }
+
+            try {
+              // If we already have a valid receipt, let's check if we have enough
+              // confirmations. If we do, then we can resolve.
+              if (transaction?.blockhash) {
+                const blockStats = await getAction(
+                  client,
+                  getBlockStats,
+                  'getBlockStats'
+                )({
+                  blockHash: transaction.blockhash,
+                  stats: ['height'],
+                })
+                if (
+                  confirmations > 1 &&
+                  (!blockStats.height ||
+                    blockNumber - blockStats.height + 1 < confirmations)
+                ) {
+                  return
+                }
+                done(() => emit.resolve(transaction!))
+                return
+              }
+
+              // Get the transaction to check if it's been replaced.
+              // We need to retry as some RPC Providers may be slow to sync
+              // up mined transactions.
+              retrying = true
+              transaction = await withRetry(
+                () =>
+                  getAction(
+                    client,
+                    getUTXOTransaction,
+                    'getUTXOTransaction'
+                    // If transaction exists it might be the replaced one with different txId
+                  )({ txId: transaction?.txid || txId }),
+                {
+                  delay: retryDelay,
+                  retryCount,
+                }
+              )
+              if (transaction.blockhash) {
+                const blockStats = await getAction(
+                  client,
+                  getBlockStats,
+                  'getBlockStats'
+                )({
+                  blockHash: transaction.blockhash,
+                  stats: ['height'],
+                })
+                if (blockStats.height) {
+                  blockNumber = blockStats.height
+                }
+              }
+              retrying = false
+
+              // Check if transaction has been processed.
+              if (!transaction?.confirmations) {
+                throw new TransactionReceiptNotFoundError({
+                  hash: txId as never,
+                })
+              }
+
+              // Check if we have enough confirmations. If not, continue polling.
+              if (transaction.confirmations < confirmations) {
+                return
+              }
+
+              done(() => emit.resolve(transaction!))
+            } catch (err) {
+              // If the receipt is not found, the transaction will be pending.
+              // We need to check if it has potentially been replaced.
+              if (
+                err instanceof TransactionNotFoundError ||
+                err instanceof TransactionReceiptNotFoundError
+              ) {
+                try {
+                  replacedTransaction = Transaction.fromHex(
+                    transaction?.hex || txHex
+                  )
+
+                  // Let's retrieve the transactions from the current block.
+                  // We need to retry as some RPC Providers may be slow to sync
+                  // up mined blocks.
+                  retrying = true
+                  const block = await withRetry(
+                    () =>
+                      getAction(
+                        client,
+                        getBlock,
+                        'getBlock'
+                      )({
+                        blockNumber,
+                      }),
+                    {
+                      delay: retryDelay,
+                      retryCount,
+                      // shouldRetry: ({ error }) =>
+                      //   error instanceof BlockNotFoundError,
+                    }
+                  )
+                  retrying = false
+
+                  // Create a set of input identifiers for mempool transaction
+                  const replacedTransactionInputs = new Set<string>()
+
+                  for (const input of replacedTransaction.ins) {
+                    const txid = Array.from(input.hash)
+                      .reverse()
+                      .map((byte) => `00${byte.toString(16)}`.slice(-2))
+                      .join('')
+                    const vout = input.index
+                    const inputId = `${txid}:${vout}`
+                    replacedTransactionInputs.add(inputId)
+                  }
+
+                  let replacementTransaction: Transaction | undefined
+
+                  for (const tx of block.transactions!) {
+                    if (tx.isCoinbase()) {
+                      continue
+                    }
+
+                    // Check if any input of this transaction matches an input of mempool transaction
+                    for (const input of tx.ins) {
+                      const txid = Array.from(input.hash)
+                        .reverse()
+                        .map((byte) => `00${byte.toString(16)}`.slice(-2))
+                        .join('')
+                      const vout = input.index
+                      const inputId = `${txid}:${vout}`
+                      if (replacedTransactionInputs.has(inputId)) {
+                        replacementTransaction = tx
+                        break
+                      }
+                    }
+                    if (replacementTransaction) {
+                      break
+                    }
+                  }
+
+                  // If we couldn't find a replacement transaction, continue polling.
+                  if (!replacementTransaction) {
+                    return
+                  }
+
+                  // If we found a replacement transaction, return it's receipt.
+                  transaction = await getAction(
+                    client,
+                    getUTXOTransaction,
+                    'getUTXOTransaction'
+                  )({
+                    txId: replacementTransaction.getId(),
+                  })
+
+                  // Check if we have enough confirmations. If not, continue polling.
+                  if (
+                    transaction.confirmations &&
+                    transaction.confirmations < confirmations
+                  ) {
+                    return
+                  }
+
+                  let reason: ReplacementReason = 'replaced'
+
+                  // Function to get output addresses
+                  function getOutputAddresses(tx: Transaction): string[] {
+                    const addresses: string[] = []
+                    for (const output of tx.outs) {
+                      try {
+                        const outputAddress = address.fromOutputScript(
+                          output.script
+                        )
+                        addresses.push(outputAddress)
+                      } catch (_e) {
+                        // Handle non-standard scripts (e.g., OP_RETURN)
+                      }
+                    }
+                    return addresses
+                  }
+
+                  // Get the recipient addresses from the original transaction
+                  const originalOutputAddresses =
+                    getOutputAddresses(replacedTransaction)
+
+                  // Get the recipient addresses from the replacement transaction
+                  const replacementOutputAddresses = getOutputAddresses(
+                    replacementTransaction
+                  )
+
+                  if (
+                    originalOutputAddresses.length ===
+                      replacementOutputAddresses.length &&
+                    originalOutputAddresses.every((address) =>
+                      replacementOutputAddresses.includes(address)
+                    )
+                  ) {
+                    reason = 'repriced'
+                  } else if (
+                    senderAddress &&
+                    replacementOutputAddresses.length === 1 &&
+                    replacementOutputAddresses.includes(senderAddress)
+                  ) {
+                    reason = 'cancelled'
+                  }
+
+                  done(() => {
+                    emit.onReplaced?.({
+                      reason,
+                      replacedTransaction: replacedTransaction!,
+                      transaction: transaction!,
+                    })
+                    emit.resolve(transaction!)
+                  })
+                } catch (err_) {
+                  done(() => emit.reject(err_))
+                }
+              } else {
+                done(() => emit.reject(err))
+              }
+            } finally {
+              count++
+            }
+          },
+        })
+      }
+    )
+  })
+}