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

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

@@ -0,0 +1,387 @@
+import { address, Transaction } from 'bitcoinjs-lib'
+import {
+  stringify,
+  TransactionNotFoundError,
+  TransactionReceiptNotFoundError,
+  WaitForTransactionReceiptTimeoutError,
+  withRetry,
+  type Chain,
+  type Client,
+  type Transport,
+} 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>()
+
+                  replacedTransaction.ins.forEach((input) => {
+                    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++
+            }
+          },
+        })
+      }
+    )
+  })
+}

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

@@ -0,0 +1,105 @@
+import { stringify, type Chain, type Client, type Transport } from 'viem'
+import { getAction } from 'viem/utils'
+import { observe } from '../utils/observe.js'
+import { poll } from '../utils/poll.js'
+import { getBlockCount, type GetBlockCountReturnType } from './getBlockCount.js'
+
+export type OnBlockNumberParameter = GetBlockCountReturnType
+export type OnBlockNumberFn = (
+  blockNumber: OnBlockNumberParameter,
+  prevBlockNumber: OnBlockNumberParameter | undefined
+) => Promise<void>
+
+export type WatchBlockNumberParameters = {
+  /** The callback to call when a new block number is received. */
+  onBlockNumber: OnBlockNumberFn
+  /** The callback to call when an error occurred when trying to get for a new block. */
+  onError?: ((error: Error) => void) | undefined
+} & {
+  /** Whether or not to emit the missed block numbers to the callback. */
+  emitMissed?: boolean | undefined
+  /** Whether or not to emit the latest block number to the callback when the subscription opens. */
+  emitOnBegin?: boolean | undefined
+  /** Polling frequency (in ms). Defaults to Client's pollingInterval config. */
+  pollingInterval?: number | undefined
+}
+
+export type WatchBlockNumberReturnType = () => void
+
+/**
+ * Watches and returns incoming block numbers.
+ * @param client - Client to use
+ * @param parameters - {@link WatchBlockNumberParameters}
+ * @returns A function that can be invoked to stop watching for new block numbers. {@link WatchBlockNumberReturnType}
+ */
+export function watchBlockNumber<
+  chain extends Chain | undefined,
+  transport extends Transport,
+>(
+  client: Client<transport, chain>,
+  {
+    emitOnBegin = false,
+    emitMissed = false,
+    onBlockNumber,
+    onError,
+    pollingInterval = client.pollingInterval,
+  }: WatchBlockNumberParameters
+): WatchBlockNumberReturnType {
+  let prevBlockNumber: GetBlockCountReturnType | undefined
+
+  const observerId = stringify([
+    'watchBlockNumber',
+    client.uid,
+    emitOnBegin,
+    emitMissed,
+    pollingInterval,
+  ])
+
+  // TODO (edge cases):
+  // 1) Stop iterating block numbers if we are happy with the result of one onBlockNumber execution but there is more in the queue.
+  // 2) If we missed some time - user closed the page and came back when the block is already mined.
+  // In this case we probably want to save the block when we send the transaction and track the currently checked blocks until we find the relevant one.
+  return observe(observerId, { onBlockNumber, onError }, (emit) =>
+    poll(
+      async () => {
+        try {
+          const blockNumber = await getAction(
+            client,
+            getBlockCount,
+            'getBlockCount'
+          )({ cacheTime: 0 })
+
+          if (prevBlockNumber) {
+            // If the current block number is the same as the previous,
+            // we can skip.
+            if (blockNumber === prevBlockNumber) {
+              return
+            }
+
+            // If we have missed out on some previous blocks, and the
+            // `emitMissed` flag is truthy, let's emit those blocks.
+            if (blockNumber - prevBlockNumber > 1 && emitMissed) {
+              for (let i = prevBlockNumber + 1; i < blockNumber; i++) {
+                await emit.onBlockNumber(i, prevBlockNumber)
+                prevBlockNumber = i
+              }
+            }
+          }
+
+          // If the next block number is greater than the previous,
+          // it is not in the past, and we can emit the new block number.
+          if (!prevBlockNumber || blockNumber > prevBlockNumber) {
+            await emit.onBlockNumber(blockNumber, prevBlockNumber)
+            prevBlockNumber = blockNumber
+          }
+        } catch (err) {
+          emit.onError?.(err as Error)
+        }
+      },
+      {
+        emitOnBegin,
+        interval: pollingInterval,
+      }
+    )
+  )
+}

package/src/core/UTXO/utxo-stack/transports/utxo/types.ts

@@ -1,3 +1,4 @@
+import type { BlockStats, BlockStatsKeys } from '../../types/blockStats.js'
 import type { UTXOTransaction } from '../../types/transaction.js'
 import type { HttpRpcClient } from './getHttpRpcClient.js'
 
@@ -7,6 +8,21 @@ export type UTXOSchema = [
     Parameters: []
     ReturnType: number
   },
+  {
+    Method: 'getblockhash'
+    Parameters: [number]
+    ReturnType: string
+  },
+  {
+    Method: 'getblock'
+    Parameters: [string, number]
+    ReturnType: string
+  },
+  {
+    Method: 'getblockstats'
+    Parameters: [string | number, Array<BlockStatsKeys>?]
+    ReturnType: BlockStats
+  },
   {
     Method: 'sendrawtransaction'
     Parameters: [string, number?]

package/src/core/UTXO/utxo-stack/types/blockStats.ts

@@ -0,0 +1,35 @@
+export type BlockStats = Partial<{
+  avgfee: number
+  avgfeerate: number
+  avgtxsize: number
+  blockhash: string
+  feerate_percentiles: number[]
+  height: number
+  ins: number
+  maxfee: number
+  maxfeerate: number
+  maxtxsize: number
+  medianfee: number
+  mediantime: number
+  mediantxsize: number
+  minfee: number
+  minfeerate: number
+  mintxsize: number
+  outs: number
+  subsidy: number
+  swtotal_size: number
+  swtotal_weight: number
+  swtxs: number
+  time: number
+  total_out: number
+  total_size: number
+  total_weight: number
+  totalfee: number
+  txs: number
+  utxo_increase: number
+  utxo_size_inc: number
+  utxo_increase_actual: number
+  utxo_size_inc_actual: number
+}>
+
+export type BlockStatsKeys = keyof BlockStats

package/src/core/UTXO/utxo-stack/utils/cancelTransaction.ts

@@ -0,0 +1,75 @@
+import { address, Psbt } from 'bitcoinjs-lib'
+
+interface InputData {
+  hash: Uint8Array
+  index: number
+  nonWitnessUtxo?: Uint8Array
+  witnessUtxo?: {
+    script: Uint8Array
+    value: bigint
+  }
+  redeemScript?: Uint8Array
+  witnessScript?: Uint8Array
+}
+
+export function cancelTransaction(psbt: Psbt, accountAddress: string): Psbt {
+  const newPsbt = new Psbt()
+  const inputs = psbt.data.inputs
+  const txInputs = psbt.txInputs
+
+  // Add inputs to the new PSBT
+  for (let i = 0; i < inputs.length; i++) {
+    const input = inputs[i]
+    const txInput = txInputs[i]
+    const inputData: InputData = {
+      hash: txInput.hash,
+      index: txInput.index,
+    }
+
+    // Include UTXO information
+    if (input.nonWitnessUtxo) {
+      inputData.nonWitnessUtxo = input.nonWitnessUtxo
+    } else if (input.witnessUtxo) {
+      inputData.witnessUtxo = input.witnessUtxo
+    } else {
+      throw new Error('Input UTXO information is missing')
+    }
+
+    // Include scripts if necessary
+    if (input.redeemScript) {
+      inputData.redeemScript = input.redeemScript
+    }
+    if (input.witnessScript) {
+      inputData.witnessScript = input.witnessScript
+    }
+
+    newPsbt.addInput(inputData)
+  }
+
+  // Compute total output amount from the original transaction
+  const outputs = psbt.txOutputs
+  let totalOutputValue = BigInt(0)
+
+  for (const output of outputs) {
+    totalOutputValue += output.value
+  }
+
+  if (totalOutputValue <= BigInt(0)) {
+    throw new Error('Total output value must be greater than zero')
+  }
+
+  // Create the output to send funds back to sender's address
+  const outputScript = address.toOutputScript(accountAddress)
+  newPsbt.addOutput({
+    script: outputScript,
+    value: totalOutputValue,
+  })
+
+  // Modify the input sequence number to enable RBF
+  newPsbt.txInputs.forEach((_, index) => {
+    // Set sequence number to less than 0xfffffffe, e.g., 0xfffffffd
+    newPsbt.setInputSequence(index, 0xfffffffd)
+  })
+
+  return newPsbt
+}

package/src/core/UTXO/utxo-stack/utils/modifyFee.ts

@@ -0,0 +1,78 @@
+import { address, Psbt } from 'bitcoinjs-lib'
+
+interface InputData {
+  hash: Uint8Array
+  index: number
+  nonWitnessUtxo?: Uint8Array
+  witnessUtxo?: {
+    script: Uint8Array
+    value: bigint
+  }
+  redeemScript?: Uint8Array
+  witnessScript?: Uint8Array
+}
+
+export function modifyFee(psbt: Psbt, newFee: bigint, accountAddress: string) {
+  const newPsbt = new Psbt()
+  const inputs = psbt.data.inputs
+  const outputs = psbt.txOutputs
+
+  // Add inputs to the new PSBT
+  for (let i = 0; i < inputs.length; i++) {
+    const input = inputs[i]
+    const inputData: InputData = {
+      hash: psbt.txInputs[i].hash,
+      index: psbt.txInputs[i].index,
+    }
+
+    // Include UTXO information
+    if (input.nonWitnessUtxo) {
+      inputData.nonWitnessUtxo = input.nonWitnessUtxo
+    } else if (input.witnessUtxo) {
+      inputData.witnessUtxo = input.witnessUtxo
+    }
+
+    // Include scripts if necessary
+    if (input.redeemScript) {
+      inputData.redeemScript = input.redeemScript
+    }
+    if (input.witnessScript) {
+      inputData.witnessScript = input.witnessScript
+    }
+
+    newPsbt.addInput(inputData)
+  }
+
+  const changeOutputScript = address.toOutputScript(accountAddress)
+
+  // Add outputs to the new PSBT
+  for (const output of outputs) {
+    const outputData = {
+      script: output.script,
+      value: output.value,
+    }
+
+    const scriptsAreEqual =
+      output.script.length === changeOutputScript.length &&
+      output.script.every((value, index) => value === changeOutputScript[index])
+
+    if (scriptsAreEqual) {
+      outputData.value = output.value - newFee
+      if (outputData.value < 0) {
+        throw new Error(
+          'Insufficient funds to adjust the fee by the specified amount.'
+        )
+      }
+    }
+
+    newPsbt.addOutput(outputData)
+  }
+
+  // Modify the input sequence number to enable RBF
+  newPsbt.txInputs.forEach((_, index) => {
+    // Set sequence number to less than 0xfffffffe, e.g., 0xfffffffd
+    newPsbt.setInputSequence(index, 0xfffffffd)
+  })
+
+  return newPsbt
+}