@bigmi/core 0.0.1

package/src/index.ts

@@ -0,0 +1,97 @@
+// Exporting actions
+export { getBalance } from './actions/getBalance.js'
+export { getBlock } from './actions/getBlock.js'
+export type {
+  GetBlockParameters,
+  GetBlockReturnType,
+} from './actions/getBlock.js'
+export { getBlockCount } from './actions/getBlockCount.js'
+export type { GetBlockCountReturnType } from './actions/getBlockCount.js'
+export { getBlockStats } from './actions/getBlockStats.js'
+export type {
+  GetBlockStatsParameters,
+  GetBlockStatsReturnType,
+} from './actions/getBlockStats.js'
+export { getUTXOTransaction } from './actions/getUTXOTransaction.js'
+export type {
+  GetUTXOTransactionParameters,
+  GetUTXOTransactionReturnType,
+} from './actions/getUTXOTransaction.js'
+export { sendUTXOTransaction } from './actions/sendUTXOTransaction.js'
+export type {
+  SendUTXOTransactionParameters,
+  SendUTXOTransactionReturnType,
+} from './actions/sendUTXOTransaction.js'
+export { signPsbt } from './actions/signPsbt.js'
+export { waitForTransaction } from './actions/waitForTransaction.js'
+export type {
+  ReplacementReason,
+  ReplacementReturnType,
+  WaitForTransactionReceiptParameters,
+  WaitForTransactionReceiptReturnType,
+  WithRetryParameters,
+} from './actions/waitForTransaction.js'
+export { watchBlockNumber } from './actions/watchBlockNumber.js'
+export type {
+  OnBlockNumberFn,
+  OnBlockNumberParameter,
+  WatchBlockNumberParameters,
+  WatchBlockNumberReturnType,
+} from './actions/watchBlockNumber.js'
+
+// Exporting clients
+export type {
+  BtcAccount,
+  SignPsbtParameters,
+  SignPsbtReturnType,
+  UTXOWalletProvider,
+  UTXOWalletSchema,
+} from './clients/types.js'
+
+// Exporting decorators
+export { UTXOActions } from './decorators/UTXOActions.js'
+export { UTXOAPIActions } from './decorators/UTXOAPIActions.js'
+
+// Exporting transports
+export { ankrMethods } from './transports/ankr.js'
+export { blockchairMethods } from './transports/blockchair.js'
+export { blockcypherMethods } from './transports/blockcypher.js'
+export { getHttpRpcClient } from './transports/getHttpRpcClient.js'
+export type {
+  HttpRequestParameters,
+  HttpRpcClient,
+  RpcRequest,
+} from './transports/getHttpRpcClient.js'
+export { getRpcProviderMethods } from './transports/getRpcProviderMethods.js'
+export { mempoolMethods } from './transports/mempool.js'
+export type {
+  ErrorResult,
+  RpcMethodHandler,
+  RpcMethods,
+  RpcResponse,
+  SuccessResult,
+  UTXOAPIMethod,
+  UTXOAPISchema,
+  UTXOSchema,
+} from './transports/types.js'
+export { utxo } from './transports/utxo.js'
+
+// Exporting types
+export type { BlockStats, BlockStatsKeys } from './types/blockStats.js'
+export type { UTXOTransaction } from './types/transaction.js'
+
+// Exporting utils
+export { cancelTransaction } from './utils/cancelTransaction.js'
+export {
+  UTXOAddressType,
+  UTXONetwork,
+  getUTXOAddress,
+} from './utils/getUTXOAddress.js'
+export type { UTXOAddress } from './utils/getUTXOAddress.js'
+export { isUTXOAddress } from './utils/isUTXOAddress.js'
+export { modifyFee } from './utils/modifyFee.js'
+export { cleanupCache, listenersCache, observe } from './utils/observe.js'
+export { poll } from './utils/poll.js'
+
+// Exporting chains
+export { bitcoin } from './chains/bitcoin.js'

package/src/transports/ankr.ts

@@ -0,0 +1,30 @@
+import type { RpcMethods } from './types.js'
+
+type AnkrBalanceResponse = {
+  address: string
+  balance: string
+  totalReceived: string
+  totalSent: string
+  unconfirmedBalance: string
+  unconfirmedTxs: number
+  txs: number
+  error: string
+}
+
+export const ankrMethods: RpcMethods = {
+  getBalance: async (client, baseUrl, { address }) => {
+    const apiUrl = `${baseUrl}/address/${address}?details=basic`
+    const response = (await client.request({
+      url: apiUrl,
+      fetchOptions: { method: 'GET' },
+    })) as unknown as AnkrBalanceResponse
+    if (response.error) {
+      return {
+        error: { code: -1, message: response.error },
+      }
+    }
+    return {
+      result: BigInt(response.balance),
+    }
+  },
+}

package/src/transports/blockchair.ts

@@ -0,0 +1,27 @@
+import type { RpcMethods } from './types.js'
+
+type BlockchairBalanceResponse = {
+  data: Record<string, any>
+  context: { code: number; error: string }
+}
+
+export const blockchairMethods: RpcMethods = {
+  getBalance: async (client, baseUrl, { address }) => {
+    const apiUrl = `${baseUrl}/addresses/balances/?addresses=${address}`
+    const response = (await client.request({
+      url: apiUrl,
+      fetchOptions: { method: 'GET' },
+    })) as unknown as BlockchairBalanceResponse
+    if (response.context?.code !== 200) {
+      return {
+        error: {
+          code: response.context?.code,
+          message: response.context?.error,
+        },
+      }
+    }
+    return {
+      result: BigInt(response.data[address]),
+    }
+  },
+}

package/src/transports/blockcypher.ts

@@ -0,0 +1,32 @@
+import type { RpcMethods } from './types.js'
+
+type BlockcypherBalanceResponse = {
+  address: string
+  total_received: number
+  total_sent: number
+  balance: number
+  unconfirmed_balance: number
+  final_balance: number
+  n_tx: number
+  unconfirmed_n_tx: number
+  final_n_tx: number
+  error?: string
+}
+
+export const blockcypherMethods: RpcMethods = {
+  getBalance: async (client, baseUrl, { address }) => {
+    const apiUrl = `${baseUrl}/addrs/${address}`
+    const response = (await client.request({
+      url: apiUrl,
+      fetchOptions: { method: 'GET' },
+    })) as unknown as BlockcypherBalanceResponse
+    if (response.error) {
+      return {
+        error: { code: -1, message: response.error },
+      }
+    }
+    return {
+      result: BigInt(response.balance),
+    }
+  },
+}

package/src/transports/getHttpRpcClient.ts

@@ -0,0 +1,122 @@
+import { HttpRequestError, TimeoutError, stringify, withTimeout } from 'viem'
+import type { HttpRequestReturnType, HttpRpcClientOptions } from 'viem/utils'
+
+export type RpcRequest = {
+  jsonrpc?: '2.0'
+  method: string
+  params?: any
+  id?: number
+}
+
+export type HttpRequestParameters<
+  body extends RpcRequest | RpcRequest[] = RpcRequest,
+> = {
+  url?: string
+  /** The RPC request body. */
+  body?: body
+  /** Request configuration to pass to `fetch`. */
+  fetchOptions?: HttpRpcClientOptions['fetchOptions'] | undefined
+  /** A callback to handle the response. */
+  onRequest?: ((request: Request) => Promise<void> | void) | undefined
+  /** A callback to handle the response. */
+  onResponse?: ((response: Response) => Promise<void> | void) | undefined
+  /** The timeout (in ms) for the request. */
+  timeout?: HttpRpcClientOptions['timeout'] | undefined
+}
+
+export type HttpRpcClient = {
+  request<body extends RpcRequest | RpcRequest[]>(
+    params: HttpRequestParameters<body>
+  ): Promise<HttpRequestReturnType<body>>
+}
+
+export function getHttpRpcClient(
+  url: string,
+  options: HttpRpcClientOptions = {}
+): HttpRpcClient {
+  return {
+    async request(params) {
+      const {
+        body,
+        onRequest = options.onRequest,
+        onResponse = options.onResponse,
+        timeout = options.timeout ?? 10_000,
+      } = params
+
+      const fetchOptions = {
+        ...(options.fetchOptions ?? {}),
+        ...(params.fetchOptions ?? {}),
+      }
+
+      const { headers, method, signal: signal_ } = fetchOptions
+
+      try {
+        const response = await withTimeout(
+          async ({ signal }) => {
+            const init: RequestInit = {
+              ...fetchOptions,
+              body: body ? stringify(body) : undefined,
+              headers: {
+                ...(method !== 'GET'
+                  ? { 'Content-Type': 'application/json' }
+                  : undefined),
+                ...headers,
+              },
+              method: method,
+              signal: signal_ || (timeout > 0 ? signal : null),
+            }
+            const request = new Request(params.url ?? url, init)
+            if (onRequest) {
+              await onRequest(request, init)
+            }
+            const response = await fetch(params.url ?? url, init)
+            return response
+          },
+          {
+            errorInstance: new TimeoutError({ body: body ?? {}, url }),
+            timeout,
+            signal: true,
+          }
+        )
+
+        if (onResponse) {
+          await onResponse(response)
+        }
+
+        let data: any
+        if (
+          response.headers.get('Content-Type')?.startsWith('application/json')
+        ) {
+          data = await response.json()
+        } else {
+          data = await response.text()
+          data = JSON.parse(data || '{}')
+        }
+
+        if (!response.ok) {
+          throw new HttpRequestError({
+            body,
+            details: stringify(data.error) || response.statusText,
+            headers: response.headers,
+            status: response.status,
+            url,
+          })
+        }
+
+        return data
+      } catch (err) {
+        if (err instanceof HttpRequestError) {
+          throw err
+        }
+        if (err instanceof TimeoutError) {
+          throw err
+        }
+        throw new HttpRequestError({
+          body,
+          cause: err as Error,
+          url,
+        })
+      }
+    },
+  }
+}

package/src/transports/getRpcProviderMethods.ts

@@ -0,0 +1,22 @@
+import { ankrMethods } from './ankr.js'
+import { blockchairMethods } from './blockchair.js'
+import { blockcypherMethods } from './blockcypher.js'
+import { mempoolMethods } from './mempool.js'
+import type { RpcMethods } from './types.js'
+
+export function getRpcProviderMethods(
+  key: 'blockchair' | 'ankr' | 'blockcypher' | 'mempool' | string
+): RpcMethods | null {
+  switch (key) {
+    case 'blockchair':
+      return blockchairMethods
+    case 'ankr':
+      return ankrMethods
+    case 'blockcypher':
+      return blockcypherMethods
+    case 'mempool':
+      return mempoolMethods
+    default:
+      return null
+  }
+}

package/src/transports/mempool.ts

@@ -0,0 +1,34 @@
+import type { RpcMethods } from './types.js'
+
+type MempoolBalanceResponse = {
+  address: string
+  chain_stats: {
+    funded_txo_count: number
+    funded_txo_sum: number
+    spent_txo_count: number
+    spent_txo_sum: number
+    tx_count: number
+  }
+  mempool_stats: {
+    funded_txo_count: number
+    funded_txo_sum: number
+    spent_txo_count: number
+    spent_txo_sum: number
+    tx_count: number
+  }
+}
+
+export const mempoolMethods: RpcMethods = {
+  getBalance: async (client, baseUrl, { address }) => {
+    const apiUrl = `${baseUrl}/address/${address}`
+    const response = (await client.request({
+      url: apiUrl,
+      fetchOptions: { method: 'GET' },
+    })) as unknown as MempoolBalanceResponse
+    const balance =
+      response.chain_stats.funded_txo_sum - response.chain_stats.spent_txo_sum
+    return {
+      result: BigInt(balance),
+    }
+  },
+}

package/src/transports/types.ts

@@ -0,0 +1,71 @@
+import type { BlockStats, BlockStatsKeys } from '../types/blockStats.js'
+import type { UTXOTransaction } from '../types/transaction.js'
+import type { HttpRpcClient } from './getHttpRpcClient.js'
+
+export type UTXOSchema = [
+  {
+    Method: 'getblockcount'
+    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?]
+    ReturnType: string
+  },
+  {
+    Method: 'getrawtransaction'
+    Parameters: [string, boolean, string?]
+    ReturnType: UTXOTransaction
+  },
+]
+
+export type UTXOAPISchema = [
+  {
+    Method: 'getBalance'
+    Parameters: { address: string }
+    ReturnType: bigint
+  },
+]
+
+export type UTXOAPIMethod = UTXOAPISchema[number]['Method']
+
+export type SuccessResult<result> = {
+  method?: undefined
+  result: result
+  error?: undefined
+}
+export type ErrorResult<error> = {
+  method?: undefined
+  result?: undefined
+  error: error
+}
+
+export type RpcResponse<result = any, error = any> =
+  | SuccessResult<result>
+  | ErrorResult<error>
+
+export type RpcMethodHandler = (
+  client: HttpRpcClient,
+  baseUrl: string,
+  params: any
+) => Promise<RpcResponse>
+
+export type RpcMethods = {
+  [key in UTXOAPIMethod]: RpcMethodHandler
+}

package/src/transports/utxo.ts

@@ -0,0 +1,84 @@
+import {
+  type HttpTransport,
+  type HttpTransportConfig,
+  RpcRequestError,
+  UrlRequiredError,
+  createTransport,
+} from 'viem'
+import { getHttpRpcClient } from './getHttpRpcClient.js'
+import { getRpcProviderMethods } from './getRpcProviderMethods.js'
+import type { UTXOAPIMethod } from './types.js'
+
+type UTXOHttpTransportConfig = HttpTransportConfig & {
+  includeChainToURL?: boolean
+}
+
+export function utxo(
+  url?: string,
+  config: UTXOHttpTransportConfig = {}
+): HttpTransport {
+  const {
+    fetchOptions,
+    key = 'utxo',
+    name = 'UTXO HTTP API',
+    onFetchRequest,
+    onFetchResponse,
+    retryDelay,
+  } = config
+  return ({ chain, retryCount: retryCount_, timeout: timeout_ }) => {
+    const retryCount = config.retryCount ?? retryCount_
+    const timeout = timeout_ ?? config.timeout ?? 10_000
+    let url_ = url
+    if (config.includeChainToURL) {
+      const chainName = chain?.name.replace(' ', '-').toLowerCase()
+      url_ = `${url}${chainName ? `/${chainName}` : ''}`
+    }
+    if (!url_) {
+      throw new UrlRequiredError()
+    }
+
+    const client = getHttpRpcClient(url_, {
+      fetchOptions,
+      onRequest: onFetchRequest,
+      onResponse: onFetchResponse,
+      timeout,
+    })
+
+    const rpcMethods = getRpcProviderMethods(key)
+
+    return createTransport(
+      {
+        key,
+        name,
+        async request({ method, params }) {
+          const body = { method, params }
+          const methodHandler = rpcMethods?.[method as UTXOAPIMethod]
+          const { error, result } = await (methodHandler?.(
+            client,
+            url_,
+            params
+          ) ??
+            client.request({
+              body,
+            }))
+          if (error) {
+            throw new RpcRequestError({
+              body,
+              error,
+              url: url_,
+            })
+          }
+          return result
+        },
+        retryCount,
+        retryDelay,
+        timeout,
+        type: 'http',
+      },
+      {
+        fetchOptions,
+        url: url_,
+      }
+    )
+  }
+}

package/src/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/types/transaction.ts

@@ -0,0 +1,43 @@
+export type UTXOTransaction = {
+  blockhash?: string
+  blocktime?: number
+  confirmations?: number
+  hash: string
+  hex: string
+  in_active_chain?: boolean
+  locktime: number
+  size: number
+  time?: number
+  txid: string
+  version: number
+  vsize: number
+  weight: number
+  vin: {
+    scriptSig: {
+      asm: string
+      hex: string
+    }
+    sequence: number
+    txid: string
+    txinwitness: string[]
+    vout: number
+  }[]
+  vout: {
+    n: 0
+    scriptPubKey:
+      | {
+          address: string
+          asm: string
+          desc: string
+          hex: string
+          type: string
+        }
+      | {
+          asm: string
+          desc: string
+          hex: string
+          type: string
+        }
+    value: number
+  }[]
+}

package/src/utils/cancelTransaction.ts

@@ -0,0 +1,75 @@
+import { Psbt, address } 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
+}