@bigmi/core 0.1.1 → 0.2.0-beta.0

package/src/factories/createClient.ts

@@ -0,0 +1,199 @@
+import type { Address } from '../types/address.js'
+
+import type { ErrorType } from '../errors/utils.js'
+import type { Transport } from '../factories/createTransport.js'
+import type { Account } from '../types/account.js'
+import type { Chain } from '../types/chain.js'
+
+import type { BtcRpcRequestFn, RpcSchema } from '../types/request.js'
+import type { BitcoinRpcMethods } from '../types/rpc.js'
+import type { Prettify } from '../types/utils.js'
+
+import { parseAccount } from '../utils/parseAccount.js'
+import { uid } from '../utils/uid.js'
+
+export type ClientConfig<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  accountOrAddress extends Account | Address | undefined =
+    | Account
+    | Address
+    | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+> = {
+  /** The Account to use for the Client. This will be used for Actions that require an account as an argument. */
+  account?: accountOrAddress | Account | Address | undefined
+  /** Flags for batch settings. */
+  batch?:
+    | {
+        /** Toggle to enable `eth_call` multicall aggregation. */
+        multicall?: boolean | Prettify<MulticallBatchOptions> | undefined
+      }
+    | undefined
+  /**
+   * Time (in ms) that cached data will remain in memory.
+   * @default 4_000
+   */
+  cacheTime?: number | undefined
+  /** Chain for the client. */
+  chain?: Chain | undefined | chain
+  /** A key for the client. */
+  key?: string | undefined
+  /** A name for the client. */
+  name?: string | undefined
+  /**
+   * Frequency (in ms) for polling enabled actions & events.
+   * @default 4_000
+   */
+  pollingInterval?: number | undefined
+  /**
+   * Typed JSON-RPC schema for the client.
+   */
+  rpcSchema?: rpcSchema | undefined
+  /** The RPC transport */
+  transport: transport
+  /** The type of client. */
+  type?: string | undefined
+}
+
+// TODO: Move `transport` to slot index 2 since `chain` and `account` used more frequently.
+// Otherwise, we end up with a lot of `Client<Transport, chain, account>` in actions.
+export type Client<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+  extended extends Extended | undefined = Extended | undefined,
+> = Client_Base<transport, chain, account, rpcSchema> &
+  (extended extends Extended ? extended : unknown) & {
+    extend: <const client extends Extended>(
+      fn: (
+        client: Client<transport, chain, account, rpcSchema, extended>
+      ) => client
+    ) => Client<
+      transport,
+      chain,
+      account,
+      rpcSchema,
+      Prettify<client> & (extended extends Extended ? extended : unknown)
+    >
+  }
+
+type Client_Base<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+> = {
+  /** The Account of the Client. */
+  account: account
+  /** Time (in ms) that cached data will remain in memory. */
+  cacheTime: number
+  /** Chain for the client. */
+  chain: chain
+  /** A key for the client. */
+  key: string
+  /** A name for the client. */
+  name: string
+  /** Frequency (in ms) for polling enabled actions & events. Defaults to 4_000 milliseconds. */
+  pollingInterval: number
+  /** Request function wrapped with friendly error handling */
+  request: BtcRpcRequestFn<
+    rpcSchema extends undefined ? BitcoinRpcMethods : rpcSchema
+  >
+  /** The RPC transport */
+  transport: ReturnType<transport>['config'] & ReturnType<transport>['value']
+  /** The type of client. */
+  type: string
+  /** A unique ID for the client. */
+  uid: string
+}
+
+type Extended = Prettify<
+  // disallow redefining base properties
+  { [_ in keyof Client_Base]?: undefined } & {
+    [key: string]: unknown
+  }
+>
+
+export type MulticallBatchOptions = {
+  /** The maximum size (in bytes) for each calldata chunk. @default 1_024 */
+  batchSize?: number | undefined
+  /** The maximum number of milliseconds to wait before sending a batch. @default 0 */
+  wait?: number | undefined
+}
+
+export type CreateClientErrorType = ErrorType
+
+export function createClient<
+  transport extends Transport,
+  chain extends Chain | undefined = undefined,
+  accountOrAddress extends Account | Address | undefined = undefined,
+  rpcSchema extends RpcSchema | undefined = undefined,
+>(
+  parameters: ClientConfig<transport, chain, accountOrAddress, rpcSchema>
+): Prettify<
+  Client<
+    transport,
+    chain,
+    accountOrAddress extends Address ? Prettify<Account> : accountOrAddress,
+    rpcSchema
+  >
+>
+
+export function createClient(parameters: ClientConfig): Client {
+  const {
+    cacheTime = parameters.pollingInterval ?? 4_000,
+
+    key = 'base',
+    name = 'Base Client',
+    pollingInterval = 4_000,
+    type = 'base',
+  } = parameters
+
+  const chain = parameters.chain
+  const account = parameters.account
+    ? parseAccount(parameters.account)
+    : undefined
+  const { config, request, value } = parameters.transport({
+    chain,
+    pollingInterval,
+  })
+  const transport = { ...config, ...value }
+
+  const client = {
+    account,
+    cacheTime,
+
+    chain,
+    key,
+    name,
+    pollingInterval,
+    request,
+    transport,
+    type,
+    uid: uid(),
+  }
+
+  function extend(base: typeof client) {
+    type ExtendFn = (base: typeof client) => unknown
+    return (extendFn: ExtendFn) => {
+      const extended = extendFn(base) as Extended
+      for (const key in client) {
+        delete extended[key]
+      }
+      const combined = { ...base, ...extended }
+      return Object.assign(combined, { extend: extend(combined as any) })
+    }
+  }
+
+  return Object.assign(client, { extend: extend(client) as any })
+}
+
+/**
+ * Defines a typed JSON-RPC schema for the client.
+ * Note: This is a runtime noop function.
+ */
+export function rpcSchema<rpcSchema extends RpcSchema>(): rpcSchema {
+  return null as any
+}

package/src/factories/createTransport.ts

@@ -0,0 +1,93 @@
+import type { ErrorType } from '../errors/utils.js'
+import type { Chain } from '../types/chain.js'
+import type { ClientConfig } from '../types/client.js'
+import type { BtcRpcRequestFn } from '../types/request.js'
+import type { OneOf } from '../types/utils.js'
+import { buildRequest } from '../utils/buildRequest.js'
+import { uid as uid_ } from '../utils/uid.js'
+
+export type TransportConfig<
+  type extends string = string,
+  rpcRequestFn extends BtcRpcRequestFn = BtcRpcRequestFn,
+> = {
+  /** The name of the transport. */
+  name: string
+  /** The key of the transport. */
+  key: string
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?:
+    | OneOf<
+        | {
+            include?: string[] | undefined
+          }
+        | {
+            exclude?: string[] | undefined
+          }
+      >
+    | undefined
+  /** The JSON-RPC request function that matches the EIP-1193 request spec. */
+  request: rpcRequestFn
+  /** The base delay (in ms) between retries. */
+  retryDelay?: number | undefined
+  /** The max number of times to retry. */
+  retryCount?: number | undefined
+  /** The timeout (in ms) for requests. */
+  timeout?: number | undefined
+  /** The type of the transport. */
+  type: type
+}
+
+export type Transport<
+  type extends string = string,
+  rpcAttributes = Record<string, any>,
+  rpcRequestFn extends BtcRpcRequestFn = BtcRpcRequestFn,
+> = <chain extends Chain | undefined = Chain>({
+  chain,
+}: {
+  chain?: chain | undefined
+  pollingInterval?: ClientConfig['pollingInterval'] | undefined
+  retryCount?: TransportConfig['retryCount'] | undefined
+  timeout?: TransportConfig['timeout'] | undefined
+}) => {
+  config: TransportConfig<type>
+  request: rpcRequestFn
+  value?: rpcAttributes | undefined
+}
+
+export type CreateTransportErrorType = ErrorType
+
+/**
+ * @description Creates an transport intended to be used with a client.
+ */
+export function createTransport<
+  type extends string,
+  rpcAttributes extends Record<string, any>,
+>(
+  {
+    key,
+    methods,
+    name,
+    request,
+    retryCount = 3,
+    retryDelay = 150,
+    timeout,
+    type,
+  }: TransportConfig<type>,
+  value?: rpcAttributes | undefined
+): ReturnType<Transport<type, rpcAttributes>> {
+  const uid = uid_()
+  return {
+    config: {
+      key,
+      methods,
+      name,
+      request,
+      retryCount,
+      retryDelay,
+      timeout,
+      type,
+    },
+    request: buildRequest(request, { methods, retryCount, retryDelay, uid }),
+    value,
+  }
+}

package/src/index.ts

@@ -40,17 +40,14 @@ export type {
 } 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'
+export {
+  type PublicActions,
+  publicActions,
+} from './clients/decorators/public.js'
+export {
+  type WalletActions,
+  walletActions,
+} from './clients/decorators/wallet.js'
 
 // Exporting transports
 export { ankrMethods } from './transports/ankr.js'
@@ -70,15 +67,54 @@ export type {
   RpcMethods,
   RpcResponse,
   SuccessResult,
-  UTXOAPIMethod,
-  UTXOAPISchema,
   UTXOSchema,
+  UTXOWalletSchema,
+  SignPsbtParameters,
+  SignPsbtReturnType,
 } from './transports/types.js'
 export { utxo } from './transports/utxo.js'
+export { custom } from './transports/custom.js'
 
 // Exporting types
+export type { Account } from './types/account.js'
+export type { Address } from './types/address.js'
+export type { BlockTag } from './types/block.js'
 export type { BlockStats, BlockStatsKeys } from './types/blockStats.js'
+export type {
+  Chain,
+  ChainConfig,
+  ChainFormatter,
+  ChainFormatters,
+} from './types/chain.js'
+export type {
+  Client,
+  ClientConfig,
+  CreateClientErrorType,
+} from './types/client.js'
+export type { Hash } from './types/hash.js'
+export type {
+  BtcRpcRequestFn,
+  BtcRpcRequestOptions,
+  RpcParameters,
+  RpcSchema,
+  RpcSchemaOverride,
+} from './types/request.js'
+export type {
+  BitcoinRpcMethods,
+  WalletRpcSchema,
+} from './types/rpc.js'
 export type { UTXOTransaction } from './types/transaction.js'
+export type {
+  Assign,
+  Compute,
+  ExactPartial,
+  IsNarrowable,
+  IsNever,
+  IsUnknown,
+  LooseOmit,
+  UnionStrictOmit,
+} from './types/utils.js'
+export type { BtcAccount } from './types/account.js'
 
 // Exporting utils
 export { cancelTransaction } from './utils/cancelTransaction.js'
@@ -92,6 +128,71 @@ 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'
+export { base64ToHex, hexToBase64 } from './utils/converter.js'
+export { withRetry } from './utils/withRetry.js'
+export { parseAccount } from './utils/parseAccount.js'
+export { deepEqual } from './utils/deepEqual.js'
+export { withTimeout } from './utils/withTimeout.js'
+
+// Exporting factories
+export { createClient, rpcSchema } from './factories/createClient.js'
 
 // Exporting chains
 export { bitcoin } from './chains/bitcoin.js'
+export { defineChain } from './chains/defineChain.js'
+
+// Exporting errors
+export {
+  InvalidAddressError,
+  type InvalidAddressErrorType,
+} from './errors/address.js'
+export { BaseError, type BaseErrorType } from './errors/base.js'
+export { BlockNotFoundError } from './errors/block.js'
+export {
+  ChainNotConfiguredError,
+  ConnectorAccountNotFoundError,
+  ConnectorAlreadyConnectedError,
+  ConnectorChainMismatchError,
+  ConnectorNotConnectedError,
+  ConnectorNotFoundError,
+} from './errors/config.js'
+export { ProviderNotFoundError } from './errors/provider.js'
+export {
+  HttpRequestError,
+  RpcRequestError,
+  SocketClosedError,
+  TimeoutError,
+} from './errors/request.js'
+export {
+  MethodNotSupportedRpcError,
+  ParseError,
+  RpcErrorCode,
+  UserRejectedRequestError,
+} from './errors/rpc.js'
+export {
+  TransactionNotFoundError,
+  TransactionReceiptNotFoundError,
+  WaitForTransactionReceiptTimeoutError,
+} from './errors/transaction.js'
+export { UrlRequiredError } from './errors/transport.js'
+export type { ErrorType } from './errors/utils.js'
+
+export {
+  http,
+  type HttpTransport,
+  type HttpTransportConfig,
+  type HttpTransportErrorType,
+} from './transports/http.js'
+
+export {
+  fallback,
+  type FallbackTransport,
+  type FallbackTransportConfig,
+  type FallbackTransportErrorType,
+} from './transports/fallback.js'
+
+export type { Transport } from './types/transport.js'
+
+export type { OneOf, RemoveUndefined } from './types/utils.js'
+export { uid } from './utils/uid.js'
+export { version } from './version.js'

package/src/transports/custom.ts

@@ -0,0 +1,56 @@
+import type { ErrorType } from '../errors/utils.js'
+import {
+  type CreateTransportErrorType,
+  type Transport,
+  type TransportConfig,
+  createTransport,
+} from '../factories/createTransport.js'
+
+type BitcoinProvider = { request(...args: any): Promise<any> }
+
+export type CustomTransportConfig = {
+  /** The key of the transport. */
+  key?: TransportConfig['key'] | undefined
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?: TransportConfig['methods'] | undefined
+  /** The name of the transport. */
+  name?: TransportConfig['name'] | undefined
+  /** The max number of times to retry. */
+  retryCount?: TransportConfig['retryCount'] | undefined
+  /** The base delay (in ms) between retries. */
+  retryDelay?: TransportConfig['retryDelay'] | undefined
+}
+
+export type CustomTransport = Transport<
+  'custom',
+  // biome-ignore lint/complexity/noBannedTypes: <explanation>
+  {},
+  BitcoinProvider['request']
+>
+
+export type CustomTransportErrorType = CreateTransportErrorType | ErrorType
+
+/**
+ * @description Creates a custom transport given an EIP-1193 compliant `request` attribute.
+ */
+export function custom<provider extends BitcoinProvider>(
+  provider: provider,
+  config: CustomTransportConfig = {}
+): CustomTransport {
+  const {
+    key = 'custom',
+    methods,
+    name = 'Custom Provider',
+    retryDelay,
+  } = config
+  return ({ retryCount: defaultRetryCount }) =>
+    createTransport({
+      key,
+      methods,
+      name,
+      request: provider.request.bind(provider),
+      retryCount: config.retryCount ?? defaultRetryCount,
+      retryDelay,
+      type: 'custom',
+    })
+}