@bigmi/core 0.1.0 → 0.2.0-beta.0

package/src/types/block.ts

@@ -0,0 +1,19 @@
+/**
+ * Specifies a particular block in the blockchain.
+ *
+ * - `"latest"`: the latest proposed block
+ * - `"earliest"`: the earliest/genesis block – lowest numbered block the client has available
+ * - `"pending"`: pending state/transactions – next block built by the client on top
+ *   of unsafe and containing the set of transactions usually taken from local mempool
+ * - `"safe"`: the latest safe head block – the most recent block that is safe from
+ *   re-orgs under honest majority and certain synchronicity assumptions
+ * - `"finalized"`: the latest finalized block – the most recent crypto-economically secure block;
+ *   cannot be re-orged outside of manual intervention driven by community coordination
+ *
+ * Using `pending`, while allowed, is not advised, as it may lead
+ * to internally inconsistent results. Use of `latest` is safe and will not
+ * lead to inconsistent results. Depending on the backing RPC networks caching system,
+ * the usage of `pending` may lead to inconsistencies as a result of an
+ * overly aggressive cache system. This may cause downstream errors/invalid states.
+ */
+export type BlockTag = 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'

package/src/types/chain.ts

@@ -0,0 +1,72 @@
+export type Chain<
+  formatters extends ChainFormatters | undefined = ChainFormatters | undefined,
+  custom extends Record<string, unknown> | undefined =
+    | Record<string, unknown>
+    | undefined,
+> = {
+  /** Collection of block explorers */
+  blockExplorers?:
+    | {
+        [key: string]: ChainBlockExplorer
+        default: ChainBlockExplorer
+      }
+    | undefined
+  /** ID in number form */
+  id: number
+  /** Human-readable name */
+  name: string
+  /** Collection of RPC endpoints */
+  rpcUrls: {
+    [key: string]: ChainRpcUrls
+    default: ChainRpcUrls
+  }
+  /** Flag for test networks */
+  testnet?: boolean | undefined
+} & ChainConfig<formatters, custom>
+
+export type ChainConfig<
+  formatters extends ChainFormatters | undefined = ChainFormatters | undefined,
+  custom extends Record<string, unknown> | undefined =
+    | Record<string, unknown>
+    | undefined,
+> = {
+  /** Custom chain data. */
+  custom?: custom | undefined
+  /** Modifies how data is formatted and typed (e.g. blocks and transactions) */
+  formatters?: formatters | undefined
+}
+
+/////////////////////////////////////////////////////////////////////
+// Formatters
+/////////////////////////////////////////////////////////////////////
+
+export type ChainFormatters = {
+  /** Modifies how the Block structure is formatted & typed. */
+  block?: ChainFormatter<'block'> | undefined
+  /** Modifies how the Transaction structure is formatted & typed. */
+  transaction?: ChainFormatter<'transaction'> | undefined
+  /** Modifies how the TransactionReceipt structure is formatted & typed. */
+  transactionReceipt?: ChainFormatter<'transactionReceipt'> | undefined
+  /** Modifies how the TransactionRequest structure is formatted & typed. */
+  transactionRequest?: ChainFormatter<'transactionRequest'> | undefined
+}
+
+export type ChainFormatter<type extends string = string> = {
+  format: (args: any) => any
+  type: type
+}
+
+/////////////////////////////////////////////////////////////////////
+// Constants
+/////////////////////////////////////////////////////////////////////
+
+type ChainBlockExplorer = {
+  name: string
+  url: string
+  apiUrl?: string | undefined
+}
+
+type ChainRpcUrls = {
+  http: readonly string[]
+  webSocket?: readonly string[] | undefined
+}

package/src/types/client.ts

@@ -0,0 +1,108 @@
+import type { ErrorType } from '../errors/utils.js'
+
+import type { Account } from './account.js'
+import type { Address } from './address.js'
+import type { Chain } from './chain.js'
+import type { BtcRpcRequestFn, RpcSchema } from './request.js'
+import type { BitcoinRpcMethods } from './rpc.js'
+import type { Transport } from './transport.js'
+import type { Prettify } from './utils.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
+  /**
+   * 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 CreateClientErrorType = ErrorType

package/src/types/hash.ts

@@ -0,0 +1 @@
+export type Hash = `0x${string}`

package/src/types/request.ts

@@ -0,0 +1,87 @@
+import type { ErrorType } from '../errors/utils.js'
+import type { OneOf } from './utils.js'
+
+export type RpcSchema = readonly {
+  Method: string
+  Parameters?: unknown | undefined
+  ReturnType: unknown
+}[]
+
+export type RpcSchemaOverride = Omit<RpcSchema[number], 'Method'>
+
+type DerivedRpcSchema<rpcSchema extends RpcSchema | undefined> =
+  rpcSchema extends RpcSchema ? rpcSchema : never
+
+export type RpcParameters<rpcSchema extends RpcSchema | undefined = undefined> =
+  rpcSchema extends RpcSchema
+    ? {
+        [K in keyof rpcSchema]: rpcSchema[K] extends RpcSchema[number]
+          ? {
+              method: rpcSchema[K]['Method']
+              params: rpcSchema[K]['Parameters']
+            }
+          : never
+      }[number]
+    : {
+        method: string
+        params?: unknown | undefined
+      }
+
+export type BtcRpcRequestOptions = {
+  /** Deduplicate in-flight requests. */
+  dedupe?: boolean | undefined
+  /** Methods to include or exclude from executing RPC requests. */
+  methods?:
+    | OneOf<
+        | {
+            include?: string[] | undefined
+          }
+        | {
+            exclude?: string[] | undefined
+          }
+      >
+    | undefined
+  /** The base delay (in ms) between retries. */
+  retryDelay?: number | undefined
+  /** The max number of times to retry. */
+  retryCount?: number | undefined
+  /** Unique identifier for the request. */
+  uid?: string | undefined
+}
+
+export type BtcRpcRequestFn<
+  rpcSchema extends RpcSchema | undefined = undefined,
+  raw extends boolean = false,
+> = <
+  _parameters extends RpcParameters<
+    DerivedRpcSchema<rpcSchema>
+  > = RpcParameters<DerivedRpcSchema<rpcSchema>>,
+  _returnType = DerivedRpcSchema<rpcSchema> extends RpcSchema
+    ? raw extends true
+      ? OneOf<
+          | {
+              result: Extract<
+                DerivedRpcSchema<rpcSchema>[number],
+                { Method: _parameters['method'] }
+              >['ReturnType']
+            }
+          | { error: ErrorType }
+        >
+      : Extract<
+          DerivedRpcSchema<rpcSchema>[number],
+          { Method: _parameters['method'] }
+        >['ReturnType']
+    : raw extends true
+      ? OneOf<
+          | {
+              result: unknown
+            }
+          | {
+              error: ErrorType
+            }
+        >
+      : unknown,
+>(
+  args: _parameters,
+  options?: BtcRpcRequestOptions | undefined
+) => Promise<_returnType>

package/src/types/rpc.ts

@@ -0,0 +1,37 @@
+export type RpcRequest = {
+  jsonrpc?: '2.0' | undefined
+  method: string
+  params?: any | undefined
+  id?: number | undefined
+}
+
+export type RpcResponse<result = any, error = any> = {
+  jsonrpc: `${number}`
+  id: number
+} & (SuccessResult<result> | ErrorResult<error>)
+
+type SuccessResult<result> = {
+  method?: undefined
+  result: result
+  error?: undefined
+}
+type ErrorResult<error> = {
+  method?: undefined
+  result?: undefined
+  error: error
+}
+
+export type BitcoinRpcMethods = [...WalletRpcSchema]
+
+export type WalletRpcSchema = [
+  {
+    Method: 'getAddressInfo'
+    Parameters?: undefined
+    ReturnType: string
+  },
+  {
+    Method: 'getBalance'
+    Parameters?: undefined
+    ReturnType: bigint
+  },
+]

package/src/types/storage.ts

@@ -0,0 +1,44 @@
+import type { Compute } from './utils.js'
+
+export type StorageItemMap = {
+  recentConnectorId: string
+  state: any
+}
+
+export type Storage<
+  itemMap extends Record<string, unknown> = Record<string, unknown>,
+  ///
+  storageItemMap extends StorageItemMap = StorageItemMap & itemMap,
+> = {
+  key: string
+  getItem<
+    key extends keyof storageItemMap,
+    value extends storageItemMap[key],
+    defaultValue extends value | null | undefined,
+  >(
+    key: key,
+    defaultValue?: defaultValue | undefined
+  ):
+    | (defaultValue extends null ? value | null : value)
+    | Promise<defaultValue extends null ? value | null : value>
+  setItem<
+    key extends keyof storageItemMap,
+    value extends storageItemMap[key] | null,
+  >(key: key, value: value): void | Promise<void>
+  removeItem(key: keyof storageItemMap): void | Promise<void>
+}
+
+export type BaseStorage = {
+  getItem(
+    key: string
+  ): string | null | undefined | Promise<string | null | undefined>
+  setItem(key: string, value: string): void | Promise<void>
+  removeItem(key: string): void | Promise<void>
+}
+
+export type CreateStorageParameters = {
+  deserialize?: (<type>(value: string) => type | unknown) | undefined
+  key?: string | undefined
+  serialize?: (<type>(value: type | any) => string) | undefined
+  storage?: Compute<BaseStorage> | undefined
+}

package/src/types/transport.ts

@@ -0,0 +1,54 @@
+import type { ErrorType } from '../errors/utils.js'
+import type { Chain } from './chain.js'
+import type { BtcRpcRequestFn, RpcSchema } from './request.js'
+import type { OneOf } from './utils.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<RpcSchema>,
+> = <chain extends Chain | undefined = Chain>({
+  chain,
+}: {
+  chain?: chain | undefined
+  pollingInterval?: number | undefined
+  retryCount?: TransportConfig['retryCount'] | undefined
+  timeout?: TransportConfig['timeout'] | undefined
+}) => {
+  config: TransportConfig<type>
+  request: rpcRequestFn
+  value?: rpcAttributes | undefined
+}
+
+export type CreateTransportErrorType = ErrorType

package/src/types/utils.ts

@@ -0,0 +1,131 @@
+/** Combines members of an intersection into a readable type. */
+// https://twitter.com/mattpocockuk/status/1622730173446557697?s=20&t=NdpAcmEFXY01xkqU3KO0Mg
+export type Compute<type> = { [key in keyof type]: type[key] } & unknown
+
+/**
+ * Makes all properties of an object optional.
+ *
+ * Compatible with [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes).
+ */
+export type ExactPartial<type> = {
+  [key in keyof type]?: type[key] | undefined
+}
+
+/** Checks if {@link type} can be narrowed further than {@link type2} */
+export type IsNarrowable<type, type2> = IsUnknown<type> extends true
+  ? false
+  : undefined extends type
+    ? false
+    : IsNever<
+          (type extends type2 ? true : false) &
+            (type2 extends type ? false : true)
+        > extends true
+      ? false
+      : true
+
+/**
+ * @internal
+ * Checks if {@link type} is `never`
+ */
+export type IsNever<type> = [type] extends [never] ? true : false
+
+/**
+ * @internal
+ * Checks if {@link type} is `unknown`
+ */
+export type IsUnknown<type> = unknown extends type ? true : false
+
+/** Merges two object types into new type  */
+export type Merge<obj1, obj2> = Compute<
+  LooseOmit<obj1, keyof obj2 extends infer key extends string ? key : never> &
+    obj2
+>
+
+/** Removes `readonly` from all properties of an object. */
+export type Mutable<type extends object> = {
+  -readonly [key in keyof type]: type[key]
+}
+
+/** Strict version of built-in Omit type */
+export type StrictOmit<type, keys extends keyof type> = Pick<
+  type,
+  Exclude<keyof type, keys>
+>
+
+/** Makes objects destructurable. */
+export type OneOf<
+  union extends object,
+  ///
+  keys extends KeyofUnion<union> = KeyofUnion<union>,
+> = union extends infer Item
+  ? Compute<Item & { [K in Exclude<keys, keyof Item>]?: undefined }>
+  : never
+type KeyofUnion<type> = type extends type ? keyof type : never
+
+/** Makes {@link key} optional in {@link type} while preserving type inference. */
+// s/o trpc (https://github.com/trpc/trpc/blob/main/packages/server/src/types.ts#L6)
+export type PartialBy<type, key extends keyof type> = ExactPartial<
+  Pick<type, key>
+> &
+  StrictOmit<type, key>
+
+/* Removes `undefined` from object property */
+export type RemoveUndefined<type> = {
+  [key in keyof type]: NonNullable<type[key]>
+}
+
+///////////////////////////////////////////////////////////////////////////
+// Loose types
+
+/** Loose version of {@link StrictOmit} */
+export type LooseOmit<type, keys extends string> = Pick<
+  type,
+  Exclude<keyof type, keys>
+>
+
+///////////////////////////////////////////////////////////////////////////
+// Union types
+
+export type UnionCompute<type> = type extends object ? Compute<type> : type
+
+export type UnionLooseOmit<type, keys extends string> = type extends any
+  ? LooseOmit<type, keys>
+  : never
+
+export type UnionStrictOmit<type, keys extends keyof type> = type extends any
+  ? StrictOmit<type, keys>
+  : never
+
+export type UnionExactPartial<type> = type extends object
+  ? ExactPartial<type>
+  : type
+
+/**
+ * @description Combines members of an intersection into a readable type.
+ *
+ * @see {@link https://twitter.com/mattpocockuk/status/1622730173446557697?s=20&t=NdpAcmEFXY01xkqU3KO0Mg}
+ * @example
+ * Prettify<{ a: string } & { b: string } & { c: number, d: bigint }>
+ * => { a: string, b: string, c: number, d: bigint }
+ */
+export type Prettify<T> = {
+  [K in keyof T]: T[K]
+} & {}
+
+/**
+ * @description Assigns the properties of U onto T.
+ *
+ * @example
+ * Assign<{ a: string, b: number }, { a: undefined, c: boolean }>
+ * => { a: undefined, b: number, c: boolean }
+ */
+export type Assign<T, U> = Assign_<T, U> & U
+type Assign_<T, U> = {
+  [K in keyof T as K extends keyof U
+    ? U[K] extends void
+      ? never
+      : K
+    : K]: K extends keyof U ? U[K] : T[K]
+}
+
+export type MaybePromise<T> = T | Promise<T>