@bigmi/core 0.1.1 → 0.2.0-beta.0

package/src/transports/fallback.ts

@@ -0,0 +1,332 @@
+import { RpcErrorCode } from '../errors/rpc.js'
+import type { ErrorType } from '../errors/utils.js'
+import { createTransport } from '../factories/createTransport.js'
+import type { Chain } from '../types/chain.js'
+import type {
+  CreateTransportErrorType,
+  Transport,
+  TransportConfig,
+} from '../types/transport.js'
+import { wait } from '../utils/wait.js'
+
+// TODO: Narrow `method` & `params` types.
+export type OnResponseFn = (
+  args: {
+    method: string
+    params: unknown[]
+    transport: ReturnType<Transport>
+  } & (
+    | {
+        error?: undefined
+        response: unknown
+        status: 'success'
+      }
+    | {
+        error: Error
+        response?: undefined
+        status: 'error'
+      }
+  )
+) => void
+
+type RankOptions = {
+  /**
+   * The polling interval (in ms) at which the ranker should ping the RPC URL.
+   * @default client.pollingInterval
+   */
+  interval?: number | undefined
+  /**
+   * Ping method to determine latency.
+   */
+  ping?: (parameters: { transport: ReturnType<Transport> }) =>
+    | Promise<unknown>
+    | undefined
+  /**
+   * The number of previous samples to perform ranking on.
+   * @default 10
+   */
+  sampleCount?: number | undefined
+  /**
+   * Timeout when sampling transports.
+   * @default 1_000
+   */
+  timeout?: number | undefined
+  /**
+   * Weights to apply to the scores. Weight values are proportional.
+   */
+  weights?:
+    | {
+        /**
+         * The weight to apply to the latency score.
+         * @default 0.3
+         */
+        latency?: number | undefined
+        /**
+         * The weight to apply to the stability score.
+         * @default 0.7
+         */
+        stability?: number | undefined
+      }
+    | undefined
+}
+
+export type FallbackTransportConfig = {
+  /** The key of the Fallback transport. */
+  key?: TransportConfig['key'] | undefined
+  /** The name of the Fallback transport. */
+  name?: TransportConfig['name'] | undefined
+  /** Toggle to enable ranking, or rank options. */
+  rank?: boolean | RankOptions | undefined
+  /** The max number of times to retry. */
+  retryCount?: TransportConfig['retryCount'] | undefined
+  /** The base delay (in ms) between retries. */
+  retryDelay?: TransportConfig['retryDelay'] | undefined
+  /** Callback on whether an error should throw or try the next transport in the fallback. */
+  shouldThrow?: (error: Error) => boolean | undefined
+}
+
+export type FallbackTransport<
+  transports extends readonly Transport[] = readonly Transport[],
+> = Transport<
+  'fallback',
+  {
+    onResponse: (fn: OnResponseFn) => void
+    transports: {
+      [key in keyof transports]: ReturnType<transports[key]>
+    }
+  }
+>
+
+export type FallbackTransportErrorType = CreateTransportErrorType | ErrorType
+
+export function fallback<const transports extends readonly Transport[]>(
+  transports_: transports,
+  config: FallbackTransportConfig = {}
+): FallbackTransport<transports> {
+  const {
+    key = 'fallback',
+    name = 'Fallback',
+    rank = false,
+    shouldThrow: shouldThrow_ = shouldThrow,
+    retryCount,
+    retryDelay,
+  } = config
+  return (({ chain, pollingInterval = 4_000, timeout, ...rest }) => {
+    let transports = transports_
+
+    let onResponse: OnResponseFn = () => {}
+
+    const transport = createTransport(
+      {
+        key,
+        name,
+        async request({ method, params }) {
+          let includes: boolean | undefined
+
+          const fetch = async (i = 0): Promise<any> => {
+            const transport = transports[i]({
+              ...rest,
+              chain,
+              retryCount: 0,
+              timeout,
+            })
+            try {
+              const response = await transport.request({
+                method,
+                params,
+              })
+
+              onResponse({
+                method,
+                params: params as unknown[],
+                response,
+                transport,
+                status: 'success',
+              })
+
+              return response
+            } catch (err) {
+              onResponse({
+                error: err as Error,
+                method,
+                params: params as unknown[],
+                transport,
+                status: 'error',
+              })
+
+              if (shouldThrow_(err as Error)) {
+                throw err
+              }
+
+              // If we've reached the end of the fallbacks, throw the error.
+              if (i === transports.length - 1) {
+                throw err
+              }
+
+              // Check if at least one other transport includes the method
+              includes ??= transports.slice(i + 1).some((transport) => {
+                const { include, exclude } =
+                  transport({ chain }).config.methods || {}
+                if (include) {
+                  return include.includes(method)
+                }
+                if (exclude) {
+                  return !exclude.includes(method)
+                }
+                return true
+              })
+              if (!includes) {
+                throw err
+              }
+
+              // Otherwise, try the next fallback.
+              return fetch(i + 1)
+            }
+          }
+          return fetch()
+        },
+        retryCount,
+        retryDelay,
+        type: 'fallback',
+      },
+      {
+        onResponse: (fn: OnResponseFn) => {
+          onResponse = fn
+        },
+        transports: transports.map((fn) => fn({ chain, retryCount: 0 })),
+      }
+    )
+
+    if (rank) {
+      const rankOptions = (typeof rank === 'object' ? rank : {}) as RankOptions
+      rankTransports({
+        chain,
+        interval: rankOptions.interval ?? pollingInterval,
+        onTransports: (transports_) => {
+          transports = transports_ as transports
+        },
+        ping: rankOptions.ping,
+        sampleCount: rankOptions.sampleCount,
+        timeout: rankOptions.timeout,
+        transports,
+        weights: rankOptions.weights,
+      })
+    }
+    return transport
+  }) as FallbackTransport<transports>
+}
+
+export function shouldThrow(error: Error) {
+  if ('code' in error && typeof error.code === 'number') {
+    if (
+      error.code === RpcErrorCode.INTERNAL_ERROR ||
+      error.code === RpcErrorCode.USER_REJECTION ||
+      error.code === 5000 // CAIP UserRejectedRequestError
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+/** @internal */
+export function rankTransports({
+  chain,
+  interval = 4_000,
+  onTransports,
+  ping,
+  sampleCount = 10,
+  timeout = 1_000,
+  transports,
+  weights = {},
+}: {
+  chain?: Chain | undefined
+  interval: RankOptions['interval']
+  onTransports: (transports: readonly Transport[]) => void
+  ping?: RankOptions['ping'] | undefined
+  sampleCount?: RankOptions['sampleCount'] | undefined
+  timeout?: RankOptions['timeout'] | undefined
+  transports: readonly Transport[]
+  weights?: RankOptions['weights'] | undefined
+}) {
+  const { stability: stabilityWeight = 0.7, latency: latencyWeight = 0.3 } =
+    weights
+
+  type SampleData = { latency: number; success: number }
+  type Sample = SampleData[]
+  const samples: Sample[] = []
+
+  const rankTransports_ = async () => {
+    // 1. Take a sample from each Transport.
+    const sample: Sample = await Promise.all(
+      transports.map(async (transport) => {
+        const transport_ = transport({ chain, retryCount: 0, timeout })
+
+        const start = Date.now()
+        let end: number
+        let success: number
+        try {
+          await (ping
+            ? ping({ transport: transport_ })
+            : transport_.request({
+                method: 'net_listening',
+                params: undefined,
+              }))
+          success = 1
+        } catch {
+          success = 0
+        } finally {
+          end = Date.now()
+        }
+        const latency = end - start
+        return { latency, success }
+      })
+    )
+
+    // 2. Store the sample. If we have more than `sampleCount` samples, remove
+    // the oldest sample.
+    samples.push(sample)
+    if (samples.length > sampleCount) {
+      samples.shift()
+    }
+
+    // 3. Calculate the max latency from samples.
+    const maxLatency = Math.max(
+      ...samples.map((sample) =>
+        Math.max(...sample.map(({ latency }) => latency))
+      )
+    )
+
+    // 4. Calculate the score for each Transport.
+    const scores = transports
+      .map((_, i) => {
+        const latencies = samples.map((sample) => sample[i].latency)
+        const meanLatency =
+          latencies.reduce((acc, latency) => acc + latency, 0) /
+          latencies.length
+        const latencyScore = 1 - meanLatency / maxLatency
+
+        const successes = samples.map((sample) => sample[i].success)
+        const stabilityScore =
+          successes.reduce((acc, success) => acc + success, 0) /
+          successes.length
+
+        if (stabilityScore === 0) {
+          return [0, i]
+        }
+        return [
+          latencyWeight * latencyScore + stabilityWeight * stabilityScore,
+          i,
+        ]
+      })
+      .sort((a, b) => b[0] - a[0])
+
+    // 5. Sort the Transports by score.
+    onTransports(scores.map(([, i]) => transports[i]))
+
+    // 6. Wait, and then rank again.
+    await wait(interval)
+    rankTransports_()
+  }
+  rankTransports_()
+}

package/src/transports/getHttpRpcClient.ts

@@ -1,5 +1,8 @@
-import { HttpRequestError, TimeoutError, stringify, withTimeout } from 'viem'
-import type { HttpRequestReturnType, HttpRpcClientOptions } from 'viem/utils'
+import { HttpRequestError, TimeoutError } from '../errors/request.js'
+import type { RpcResponse } from '../types/rpc.js'
+import type { MaybePromise } from '../types/utils.js'
+import { stringify } from '../utils/stringify.js'
+import { withTimeout } from '../utils/withTimeout.js'
 
 export type RpcRequest = {
   jsonrpc?: '2.0'
@@ -8,6 +11,28 @@ export type RpcRequest = {
   id?: number
 }
 
+export type HttpRequestReturnType<
+  body extends RpcRequest | RpcRequest[] = RpcRequest,
+> = body extends RpcRequest[] ? RpcResponse[] : RpcResponse
+
+export type HttpRpcClientOptions = {
+  /** Request configuration to pass to `fetch`. */
+  fetchOptions?: Omit<RequestInit, 'body'> | undefined
+  /** A callback to handle the request. */
+  onRequest?:
+    | ((
+        request: Request,
+        init: RequestInit
+      ) => MaybePromise<
+        void | undefined | (RequestInit & { url?: string | undefined })
+      >)
+    | undefined
+  /** A callback to handle the response. */
+  onResponse?: ((response: Response) => Promise<void> | void) | undefined
+  /** The timeout (in ms) for the request. */
+  timeout?: number | undefined
+}
+
 export type HttpRequestParameters<
   body extends RpcRequest | RpcRequest[] = RpcRequest,
 > = {
@@ -62,7 +87,7 @@ export function getHttpRpcClient(
                   : undefined),
                 ...headers,
               },
-              method: method,
+              method: method || 'POST',
               signal: signal_ || (timeout > 0 ? signal : null),
             }
             const request = new Request(params.url ?? url, init)
@@ -102,7 +127,6 @@ export function getHttpRpcClient(
             url,
           })
         }
-
         return data
       } catch (err) {
         if (err instanceof HttpRequestError) {

package/src/transports/http.ts

@@ -0,0 +1,176 @@
+import { RpcRequestError } from '../errors/request.js'
+import {
+  UrlRequiredError,
+  type UrlRequiredErrorType,
+} from '../errors/transport.js'
+import type { ErrorType } from '../errors/utils.js'
+import {
+  type CreateTransportErrorType,
+  type Transport,
+  type TransportConfig,
+  createTransport,
+} from '../factories/createTransport.js'
+import type { BtcRpcRequestFn, RpcSchema } from '../types/request.js'
+import { createBatchScheduler } from '../utils/createBatchScheduler.js'
+import {
+  type HttpRpcClientOptions,
+  type RpcRequest,
+  getHttpRpcClient,
+} from './getHttpRpcClient.js'
+
+export type HttpTransportConfig<
+  rpcSchema extends RpcSchema | undefined = undefined,
+  raw extends boolean = false,
+> = {
+  /**
+   * Whether to enable Batch JSON-RPC.
+   * @link https://www.jsonrpc.org/specification#batch
+   */
+  batch?:
+    | boolean
+    | {
+        /** The maximum number of JSON-RPC requests to send in a batch. @default 1_000 */
+        batchSize?: number | undefined
+        /** The maximum number of milliseconds to wait before sending a batch. @default 0 */
+        wait?: number | undefined
+      }
+    | undefined
+  /**
+   * Request configuration to pass to `fetch`.
+   * @link https://developer.mozilla.org/en-US/docs/Web/API/fetch
+   */
+  fetchOptions?: HttpRpcClientOptions['fetchOptions'] | undefined
+  /** A callback to handle the response from `fetch`. */
+  onFetchRequest?: HttpRpcClientOptions['onRequest'] | undefined
+  /** A callback to handle the response from `fetch`. */
+  onFetchResponse?: HttpRpcClientOptions['onResponse'] | undefined
+  /** The key of the HTTP transport. */
+  key?: TransportConfig['key'] | undefined
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?: TransportConfig['methods'] | undefined
+  /** The name of the HTTP transport. */
+  name?: TransportConfig['name'] | undefined
+  /** Whether to return JSON RPC errors as responses instead of throwing. */
+  raw?: raw | boolean | undefined
+  /** The max number of times to retry. */
+  retryCount?: TransportConfig['retryCount'] | undefined
+  /** The base delay (in ms) between retries. */
+  retryDelay?: TransportConfig['retryDelay'] | undefined
+  /** Typed JSON-RPC schema for the transport. */
+  rpcSchema?: rpcSchema | RpcSchema | undefined
+  /** The timeout (in ms) for the HTTP request. Default: 10_000 */
+  timeout?: TransportConfig['timeout'] | undefined
+}
+
+export type HttpTransport<
+  rpcSchema extends RpcSchema | undefined = undefined,
+  raw extends boolean = false,
+> = Transport<
+  'http',
+  {
+    fetchOptions?: HttpTransportConfig['fetchOptions'] | undefined
+    url?: string | undefined
+  },
+  BtcRpcRequestFn<rpcSchema, raw>
+>
+
+export type HttpTransportErrorType =
+  | CreateTransportErrorType
+  | UrlRequiredErrorType
+  | ErrorType
+
+/**
+ * @description Creates a HTTP transport that connects to a JSON-RPC API.
+ */
+export function http<
+  rpcSchema extends RpcSchema | undefined = undefined,
+  raw extends boolean = false,
+>(
+  /** URL of the JSON-RPC API. Defaults to the chain's public RPC URL. */
+  url?: string | undefined,
+  config: HttpTransportConfig<rpcSchema, raw> = {}
+): HttpTransport<rpcSchema, raw> {
+  const {
+    batch,
+    fetchOptions,
+    key = 'http',
+    methods,
+    name = 'HTTP JSON-RPC',
+    onFetchRequest,
+    onFetchResponse,
+    retryDelay,
+    raw,
+  } = config
+  return ({ chain, retryCount: retryCount_, timeout: timeout_ }) => {
+    const { batchSize = 1000, wait = 0 } =
+      typeof batch === 'object' ? batch : {}
+    const retryCount = config.retryCount ?? retryCount_
+    const timeout = timeout_ ?? config.timeout ?? 10_000
+    const url_ = url || chain?.rpcUrls.default.http[0]
+    if (!url_) {
+      throw new UrlRequiredError()
+    }
+
+    const rpcClient = getHttpRpcClient(url_, {
+      fetchOptions,
+      onRequest: onFetchRequest,
+      onResponse: onFetchResponse,
+      timeout,
+    })
+
+    return createTransport(
+      {
+        key,
+        methods,
+        name,
+        async request({ method, params }) {
+          const body = { method, params }
+
+          const { schedule } = createBatchScheduler({
+            id: url_,
+            wait,
+            shouldSplitBatch(requests) {
+              return requests.length > batchSize
+            },
+            fn: (body: RpcRequest[]) =>
+              rpcClient.request({
+                body,
+              }),
+            sort: (a, b) => a.id - b.id,
+          })
+
+          const fn = async (body: RpcRequest) =>
+            batch
+              ? schedule(body)
+              : [
+                  await rpcClient.request({
+                    body,
+                  }),
+                ]
+
+          const [{ error, result }] = await fn(body)
+
+          if (raw) {
+            return { error, result }
+          }
+          if (error) {
+            throw new RpcRequestError({
+              body,
+              error,
+              url: url_,
+            })
+          }
+          return result
+        },
+        retryCount,
+        retryDelay,
+        timeout,
+        type: 'http',
+      },
+      {
+        fetchOptions,
+        url: url_,
+      }
+    )
+  }
+}

package/src/transports/types.ts

@@ -33,9 +33,6 @@ export type UTXOSchema = [
     Parameters: [string, boolean, string?]
     ReturnType: UTXOTransaction
   },
-]
-
-export type UTXOAPISchema = [
   {
     Method: 'getBalance'
     Parameters: { address: string }
@@ -43,7 +40,43 @@ export type UTXOAPISchema = [
   },
 ]
 
-export type UTXOAPIMethod = UTXOAPISchema[number]['Method']
+export type SignPsbtParameters = {
+  /** The PSBT encoded as a hexadecimal string */
+  psbt: string
+  /**
+   * Array of objects specifying details about the inputs to be signed
+   */
+  inputsToSign: {
+    /**
+     * The SigHash type to use for signing (e.g., SIGHASH_ALL).
+     * If not specified, a default value is used.
+     */
+    sigHash?: number
+    /** The Bitcoin address associated with the input that will be signed */
+    address: string
+    /** An array of indexes in the PSBT corresponding to the inputs that need to be signed */
+    signingIndexes: number[]
+  }[]
+  /**
+   * Whether to finalize the PSBT after signing.
+   * If `true`, the PSBT will be completed and ready for broadcasting.
+   * If `false` or omitted, the PSBT remains partially signed.
+   * Some wallets does not support it.
+   */
+  finalize?: boolean
+}
+
+export type SignPsbtReturnType = string
+
+export type UTXOWalletSchema = readonly [
+  {
+    Method: 'signPsbt'
+    Parameters: SignPsbtParameters
+    ReturnType: SignPsbtReturnType
+  },
+]
+
+export type UTXOMethod = UTXOSchema[number]['Method']
 
 export type SuccessResult<result> = {
   method?: undefined
@@ -67,5 +100,5 @@ export type RpcMethodHandler = (
 ) => Promise<RpcResponse>
 
 export type RpcMethods = {
-  [key in UTXOAPIMethod]: RpcMethodHandler
+  [key in UTXOMethod]?: RpcMethodHandler
 }

package/src/transports/utxo.ts

@@ -1,13 +1,10 @@
-import {
-  type HttpTransport,
-  type HttpTransportConfig,
-  RpcRequestError,
-  UrlRequiredError,
-  createTransport,
-} from 'viem'
+import { RpcRequestError } from '../errors/request.js'
+import { UrlRequiredError } from '../errors/transport.js'
+import { createTransport } from '../factories/createTransport.js'
 import { getHttpRpcClient } from './getHttpRpcClient.js'
 import { getRpcProviderMethods } from './getRpcProviderMethods.js'
-import type { UTXOAPIMethod } from './types.js'
+import type { HttpTransport, HttpTransportConfig } from './http.js'
+import type { UTXOMethod } from './types.js'
 
 type UTXOHttpTransportConfig = HttpTransportConfig & {
   includeChainToURL?: boolean
@@ -52,7 +49,7 @@ export function utxo(
         name,
         async request({ method, params }) {
           const body = { method, params }
-          const methodHandler = rpcMethods?.[method as UTXOAPIMethod]
+          const methodHandler = rpcMethods?.[method as UTXOMethod]
           const { error, result } = await (methodHandler?.(
             client,
             url_,

package/src/types/account.ts

@@ -0,0 +1,10 @@
+import type { Address } from './address.js'
+
+export interface Account {
+  address: Address
+  addressType: 'p2tr' | 'p2wpkh' | 'p2wsh' | 'p2sh' | 'p2pkh'
+  publicKey: string
+  purpose: 'payment' | 'ordinals'
+}
+
+export interface BtcAccount extends Account {}

package/src/types/actions.ts

@@ -0,0 +1,38 @@
+import type {
+  SendUTXOTransactionParameters,
+  SendUTXOTransactionReturnType,
+} from '../actions/sendUTXOTransaction'
+
+import type { WaitForTransactionReceiptParameters } from '../actions/waitForTransaction'
+import type {
+  SignPsbtParameters,
+  SignPsbtReturnType,
+} from '../transports/types'
+import type { UTXOTransaction } from './transaction'
+
+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 WalletActions = {
+  /**
+   * Creates, signs, and sends a new transaction to the network.
+   */
+  sendUTXOTransaction: (
+    args: SendUTXOTransactionParameters
+  ) => Promise<SendUTXOTransactionReturnType>
+
+  signPbst: (args: SignPsbtParameters) => Promise<SignPsbtReturnType>
+
+  waitForTransactionReceipt: (
+    args: WaitForTransactionReceiptParameters
+  ) => Promise<WaitForTransactionReceiptReturnType>
+}

package/src/types/address.ts

@@ -0,0 +1 @@
+export type Address = string