@bigmi/core 0.1.0 → 0.2.0-beta.0

package/src/clients/decorators/public.ts

@@ -0,0 +1,62 @@
+import {
+  type GetBalanceParameters,
+  type GetBalanceReturnType,
+  getBalance,
+} from '../../actions/getBalance.js'
+import {
+  type GetBlockParameters,
+  type GetBlockReturnType,
+  getBlock,
+} from '../../actions/getBlock.js'
+import {
+  type GetBlockCountReturnType,
+  getBlockCount,
+} from '../../actions/getBlockCount.js'
+import {
+  type GetBlockStatsParameters,
+  type GetBlockStatsReturnType,
+  getBlockStats,
+} from '../../actions/getBlockStats.js'
+import {
+  type GetUTXOTransactionParameters,
+  type GetUTXOTransactionReturnType,
+  getUTXOTransaction,
+} from '../../actions/getUTXOTransaction.js'
+
+import type { Client } from '../../factories/createClient.js'
+import type { Transport } from '../../factories/createTransport.js'
+import type { UTXOSchema } from '../../transports/types.js'
+import type { Account } from '../../types/account.js'
+
+import type { Chain } from '../../types/chain.js'
+
+export type PublicActions = {
+  getBalance: (args: GetBalanceParameters) => Promise<GetBalanceReturnType>
+
+  getBlockCount: () => Promise<GetBlockCountReturnType>
+
+  getBlockStats: (
+    args: GetBlockStatsParameters
+  ) => Promise<GetBlockStatsReturnType>
+
+  getUTXOTransaction: (
+    args: GetUTXOTransactionParameters
+  ) => Promise<GetUTXOTransactionReturnType>
+
+  getBlock: (args: GetBlockParameters) => Promise<GetBlockReturnType>
+}
+
+export function publicActions<
+  transport extends Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  schema extends UTXOSchema = UTXOSchema,
+>(client: Client<transport, chain, account, schema>): PublicActions {
+  return {
+    getBlock: (args) => getBlock(client, args),
+    getBalance: (args) => getBalance(client, args),
+    getBlockCount: () => getBlockCount(client),
+    getBlockStats: (args) => getBlockStats(client, args),
+    getUTXOTransaction: (args) => getUTXOTransaction(client, args),
+  }
+}

package/src/clients/decorators/wallet.ts

@@ -0,0 +1,37 @@
+import {
+  type SendUTXOTransactionParameters,
+  type SendUTXOTransactionReturnType,
+  sendUTXOTransaction,
+} from '../../actions/sendUTXOTransaction.js'
+import { signPsbt } from '../../actions/signPsbt.js'
+import type { Transport } from '../../factories/createTransport.js'
+import type { Account } from '../../types/account.js'
+import type { Client } from '../../types/client.js'
+
+import type {
+  SignPsbtParameters,
+  SignPsbtReturnType,
+} from '../../transports/types.js'
+import type { Chain } from '../../types/chain.js'
+
+export type WalletActions = {
+  /**
+   * Creates, signs, and sends a new transaction to the network.
+   */
+  sendUTXOTransaction: (
+    args: SendUTXOTransactionParameters
+  ) => Promise<SendUTXOTransactionReturnType>
+
+  signPbst: (args: SignPsbtParameters) => Promise<SignPsbtReturnType>
+}
+
+export function walletActions<
+  transport extends Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+>(client: Client<transport, chain, account>): WalletActions {
+  return {
+    sendUTXOTransaction: (args) => sendUTXOTransaction(client, args),
+    signPbst: (args) => signPsbt(client, args),
+  }
+}

package/src/errors/address.ts

@@ -0,0 +1,16 @@
+import { BaseError } from './base.js'
+
+export type InvalidAddressErrorType = InvalidAddressError & {
+  name: 'InvalidAddressError'
+}
+export class InvalidAddressError extends BaseError {
+  constructor({ address }: { address: string }) {
+    super(`Address "${address}" is invalid.`, {
+      metaMessages: [
+        '- Address must be a hex value of 20 bytes (40 hex characters).',
+        '- Address must match its checksum counterpart.',
+      ],
+      name: 'InvalidAddressError',
+    })
+  }
+}

package/src/errors/base.ts

@@ -0,0 +1,85 @@
+import { version } from '../version.js'
+
+type ErrorConfig = {
+  version?: string | undefined
+}
+
+let errorConfig: ErrorConfig = {
+  version: `bigmi@${version}`,
+}
+
+export function setErrorConfig(config: ErrorConfig) {
+  errorConfig = config
+}
+
+type BaseErrorParameters = {
+  cause?: BaseError | Error | undefined
+  details?: string | undefined
+  docsSlug?: string | undefined
+  metaMessages?: string[] | undefined
+  name?: string | undefined
+}
+
+export type BaseErrorType = BaseError & { name: 'BaseError' }
+export class BaseError extends Error {
+  code?: number
+  details: string
+  docsPath?: string | undefined
+  metaMessages?: string[] | undefined
+  shortMessage: string
+  version: string
+
+  override name = 'BaseError'
+
+  constructor(shortMessage: string, args: BaseErrorParameters = {}) {
+    const details = (() => {
+      if (args.cause instanceof BaseError) {
+        return args.cause.details
+      }
+      if (args.cause?.message) {
+        return args.cause.message
+      }
+      return args.details!
+    })()
+
+    const message = [
+      shortMessage || 'An error occurred.',
+      '',
+      ...(args.metaMessages ? [...args.metaMessages, ''] : []),
+      ...(details ? [`Details: ${details}`] : []),
+      ...(errorConfig.version ? [`Version: ${errorConfig.version}`] : []),
+    ].join('\n')
+
+    super(message, args.cause ? { cause: args.cause } : undefined)
+
+    this.details = details
+    this.metaMessages = args.metaMessages
+    this.name = args.name ?? this.name
+    this.shortMessage = shortMessage
+    this.version = version
+  }
+
+  walk(): Error
+  walk(fn: (err: unknown) => boolean): Error | null
+  walk(fn?: any): any {
+    return walk(this, fn)
+  }
+}
+
+function walk(
+  err: unknown,
+  fn?: ((err: unknown) => boolean) | undefined
+): unknown {
+  if (fn?.(err)) {
+    return err
+  }
+  if (
+    err &&
+    typeof err === 'object' &&
+    'cause' in err &&
+    err.cause !== undefined
+  ) {
+    return walk(err.cause, fn)
+  }
+  return fn ? null : err
+}

package/src/errors/block.ts

@@ -0,0 +1,24 @@
+import type { Hash } from '../types/hash.js'
+import { BaseError } from './base.js'
+
+export type BlockNotFoundErrorType = BlockNotFoundError & {
+  name: 'BlockNotFoundError'
+}
+export class BlockNotFoundError extends BaseError {
+  constructor({
+    blockHash,
+    blockNumber,
+  }: {
+    blockHash?: Hash | undefined
+    blockNumber?: bigint | undefined
+  }) {
+    let identifier = 'Block'
+    if (blockHash) {
+      identifier = `Block at hash "${blockHash}"`
+    }
+    if (blockNumber) {
+      identifier = `Block at number "${blockNumber}"`
+    }
+    super(`${identifier} could not be found.`, { name: 'BlockNotFoundError' })
+  }
+}

package/src/errors/config.ts

@@ -0,0 +1,102 @@
+import type { Address } from '../types/address.js'
+
+import { BaseError } from './base.js'
+
+export type ChainNotConfiguredErrorType = ChainNotConfiguredError & {
+  name: 'ChainNotConfiguredError'
+}
+export class ChainNotConfiguredError extends BaseError {
+  override name = 'ChainNotConfiguredError'
+  constructor() {
+    super('Chain not configured.')
+  }
+}
+
+export type ConnectorAlreadyConnectedErrorType =
+  ConnectorAlreadyConnectedError & {
+    name: 'ConnectorAlreadyConnectedError'
+  }
+export class ConnectorAlreadyConnectedError extends BaseError {
+  override name = 'ConnectorAlreadyConnectedError'
+  constructor() {
+    super('Connector already connected.')
+  }
+}
+
+export type ConnectorNotConnectedErrorType = ConnectorNotConnectedError & {
+  name: 'ConnectorNotConnectedError'
+}
+export class ConnectorNotConnectedError extends BaseError {
+  override name = 'ConnectorNotConnectedError'
+  constructor() {
+    super('Connector not connected.')
+  }
+}
+
+export type ConnectorNotFoundErrorType = ConnectorNotFoundError & {
+  name: 'ConnectorNotFoundError'
+}
+export class ConnectorNotFoundError extends BaseError {
+  override name = 'ConnectorNotFoundError'
+  constructor() {
+    super('Connector not found.')
+  }
+}
+
+export type ConnectorAccountNotFoundErrorType =
+  ConnectorAccountNotFoundError & {
+    name: 'ConnectorAccountNotFoundError'
+  }
+export class ConnectorAccountNotFoundError extends BaseError {
+  override name = 'ConnectorAccountNotFoundError'
+  constructor({
+    address,
+    connector,
+  }: {
+    address: Address
+    connector: string
+  }) {
+    super(`Account "${address}" not found for connector "${connector}".`)
+  }
+}
+
+export type ConnectorChainMismatchErrorType = ConnectorAccountNotFoundError & {
+  name: 'ConnectorChainMismatchError'
+}
+export class ConnectorChainMismatchError extends BaseError {
+  override name = 'ConnectorChainMismatchError'
+  constructor({
+    connectionChainId,
+    connectorChainId,
+  }: {
+    connectionChainId: number
+    connectorChainId: number
+  }) {
+    super(
+      `The current chain of the connector (id: ${connectorChainId}) does not match the connection's chain (id: ${connectionChainId}).`,
+      {
+        metaMessages: [
+          `Current Chain ID:  ${connectorChainId}`,
+          `Expected Chain ID: ${connectionChainId}`,
+        ],
+      }
+    )
+  }
+}
+
+export type ConnectorUnavailableReconnectingErrorType =
+  ConnectorUnavailableReconnectingError & {
+    name: 'ConnectorUnavailableReconnectingError'
+  }
+export class ConnectorUnavailableReconnectingError extends BaseError {
+  override name = 'ConnectorUnavailableReconnectingError'
+  constructor({ connector }: { connector: { name: string } }) {
+    super(`Connector "${connector.name}" unavailable while reconnecting.`, {
+      details: [
+        'During the reconnection step, the only connector methods guaranteed to be available are: `id`, `name`, `type`, `uid`.',
+        'All other methods are not guaranteed to be available until reconnection completes and connectors are fully restored.',
+        'This error commonly occurs for connectors that asynchronously inject after reconnection has already started.',
+      ].join(' '),
+    })
+  }
+}

package/src/errors/provider.ts

@@ -0,0 +1,11 @@
+import { BaseError } from './base.js'
+
+export class ProviderNotFoundError extends BaseError {
+  constructor(message?: string) {
+    const name = 'ProviderNotFoundError'
+    const defaultMessage = 'The provider for this connector was not found'
+    super(`${name}: ${message || defaultMessage}`, {
+      name,
+    })
+  }
+}

package/src/errors/request.ts

@@ -0,0 +1,134 @@
+import { stringify } from '../utils/stringify.js'
+
+import { BaseError } from './base.js'
+import { getUrl } from './utils.js'
+
+export type HttpRequestErrorType = HttpRequestError & {
+  name: 'HttpRequestError'
+}
+export class HttpRequestError extends BaseError {
+  body?: { [x: string]: unknown } | { [y: string]: unknown }[] | undefined
+  headers?: Headers | undefined
+  status?: number | undefined
+  url: string
+
+  constructor({
+    body,
+    cause,
+    details,
+    headers,
+    status,
+    url,
+  }: {
+    body?: { [x: string]: unknown } | { [y: string]: unknown }[] | undefined
+    cause?: Error | undefined
+    details?: string | undefined
+    headers?: Headers | undefined
+    status?: number | undefined
+    url: string
+  }) {
+    super('HTTP request failed.', {
+      cause,
+      details,
+      metaMessages: [
+        status && `Status: ${status}`,
+        `URL: ${getUrl(url)}`,
+        body && `Request body: ${stringify(body)}`,
+      ].filter(Boolean) as string[],
+      name: 'HttpRequestError',
+    })
+    this.body = body
+    this.headers = headers
+    this.status = status
+    this.url = url
+  }
+}
+
+export type WebSocketRequestErrorType = WebSocketRequestError & {
+  name: 'WebSocketRequestError'
+}
+export class WebSocketRequestError extends BaseError {
+  constructor({
+    body,
+    cause,
+    details,
+    url,
+  }: {
+    body?: { [key: string]: unknown } | undefined
+    cause?: Error | undefined
+    details?: string | undefined
+    url: string
+  }) {
+    super('WebSocket request failed.', {
+      cause,
+      details,
+      metaMessages: [
+        `URL: ${getUrl(url)}`,
+        body && `Request body: ${stringify(body)}`,
+      ].filter(Boolean) as string[],
+      name: 'WebSocketRequestError',
+    })
+  }
+}
+
+export type RpcRequestErrorType = RpcRequestError & {
+  name: 'RpcRequestError'
+}
+export class RpcRequestError extends BaseError {
+  override code: number
+  data?: unknown
+
+  constructor({
+    body,
+    error,
+    url,
+  }: {
+    body: { [x: string]: unknown } | { [y: string]: unknown }[]
+    error: { code: number; data?: unknown; message: string }
+    url: string
+  }) {
+    super('RPC Request failed.', {
+      cause: error as any,
+      details: error.message,
+      metaMessages: [`URL: ${getUrl(url)}`, `Request body: ${stringify(body)}`],
+      name: 'RpcRequestError',
+    })
+    this.code = error.code
+    this.data = error.data
+  }
+}
+
+export type SocketClosedErrorType = SocketClosedError & {
+  name: 'SocketClosedError'
+}
+export class SocketClosedError extends BaseError {
+  constructor({
+    url,
+  }: {
+    url?: string | undefined
+  } = {}) {
+    super('The socket has been closed.', {
+      metaMessages: [url && `URL: ${getUrl(url)}`].filter(Boolean) as string[],
+      name: 'SocketClosedError',
+    })
+  }
+}
+
+export type TimeoutErrorType = TimeoutError & {
+  name: 'TimeoutError'
+}
+export class TimeoutError extends BaseError {
+  constructor({
+    body,
+    url,
+  }: {
+    body: { [x: string]: unknown } | { [y: string]: unknown }[]
+    url: string
+  }) {
+    super('The request took too long to respond.', {
+      details: 'The request timed out.',
+      metaMessages: [`URL: ${getUrl(url)}`, `Request body: ${stringify(body)}`],
+      name: 'TimeoutError',
+    })
+  }
+}

package/src/errors/rpc.ts

@@ -0,0 +1,77 @@
+import { BaseError } from './base.js'
+
+/**
+ * @enum {number} RpcErrorCode
+ * @description JSON-RPC error codes
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+export enum RpcErrorCode {
+  /**
+   * Parse error Invalid JSON
+   **/
+  PARSE_ERROR = -32700,
+  /**
+   * The JSON sent is not a valid Request object.
+   **/
+  INVALID_REQUEST = -32600,
+  /**
+   * The method does not exist/is not available.
+   **/
+  METHOD_NOT_FOUND = -32601,
+  /**
+   * Invalid method parameter(s).
+   */
+  INVALID_PARAMS = -32602,
+  /**
+   * Internal JSON-RPC error.
+   * This is a generic error, used when the server encounters an error in performing the request.
+   **/
+  INTERNAL_ERROR = -32603,
+  /**
+   * user rejected/canceled the request
+   */
+  USER_REJECTION = -32000,
+  /**
+   * method is not supported for the address provided
+   */
+  METHOD_NOT_SUPPORTED = -32001,
+  /**
+   * The client does not have permission to access the requested resource.
+   */
+  ACCESS_DENIED = -32002,
+}
+
+export class UserRejectedRequestError extends BaseError {
+  override code = RpcErrorCode.USER_REJECTION
+  constructor(message?: string) {
+    const name = 'UserRejectedRequestError'
+    const errMessage =
+      message || 'The user rejected your request, please try again'
+    super(`${name}:  ${errMessage}`, {
+      name,
+    })
+  }
+}
+
+export class MethodNotSupportedRpcError extends BaseError {
+  override code = RpcErrorCode.METHOD_NOT_SUPPORTED
+  constructor(method?: string) {
+    const name = 'MethodNotSupportedError'
+    const message = `The method ${method} you are calling is not supported`
+    super(`${name}: ${message}`, {
+      name,
+    })
+  }
+}
+
+export class ParseError extends BaseError {
+  override code = RpcErrorCode.PARSE_ERROR
+  constructor(message?: string) {
+    const name = 'ParseError'
+    const errMessage =
+      message || 'Invalid JSON, there was an error parsing your request.'
+    super(`${name}: ${errMessage}`, {
+      name,
+    })
+  }
+}

package/src/errors/transaction.ts

@@ -0,0 +1,67 @@
+import type { BlockTag } from '../types/block.js'
+import type { Hash } from '../types/hash.js'
+import { BaseError } from './base.js'
+
+export type TransactionNotFoundErrorType = TransactionNotFoundError & {
+  name: 'TransactionNotFoundError'
+}
+export class TransactionNotFoundError extends BaseError {
+  constructor({
+    blockHash,
+    blockNumber,
+    blockTag,
+    hash,
+    index,
+  }: {
+    blockHash?: Hash | undefined
+    blockNumber?: bigint | undefined
+    blockTag?: BlockTag | undefined
+    hash?: Hash | undefined
+    index?: number | undefined
+  }) {
+    let identifier = 'Transaction'
+    if (blockTag && index !== undefined) {
+      identifier = `Transaction at block time "${blockTag}" at index "${index}"`
+    }
+    if (blockHash && index !== undefined) {
+      identifier = `Transaction at block hash "${blockHash}" at index "${index}"`
+    }
+    if (blockNumber && index !== undefined) {
+      identifier = `Transaction at block number "${blockNumber}" at index "${index}"`
+    }
+    if (hash) {
+      identifier = `Transaction with hash "${hash}"`
+    }
+    super(`${identifier} could not be found.`, {
+      name: 'TransactionNotFoundError',
+    })
+  }
+}
+
+export type TransactionReceiptNotFoundErrorType =
+  TransactionReceiptNotFoundError & {
+    name: 'TransactionReceiptNotFoundError'
+  }
+export class TransactionReceiptNotFoundError extends BaseError {
+  constructor({ hash }: { hash: Hash }) {
+    super(
+      `Transaction receipt with hash "${hash}" could not be found. The Transaction may not be processed on a block yet.`,
+      {
+        name: 'TransactionReceiptNotFoundError',
+      }
+    )
+  }
+}
+
+export type WaitForTransactionReceiptTimeoutErrorType =
+  WaitForTransactionReceiptTimeoutError & {
+    name: 'WaitForTransactionReceiptTimeoutError'
+  }
+export class WaitForTransactionReceiptTimeoutError extends BaseError {
+  constructor({ hash }: { hash: Hash }) {
+    super(
+      `Timed out while waiting for transaction with hash "${hash}" to be confirmed.`,
+      { name: 'WaitForTransactionReceiptTimeoutError' }
+    )
+  }
+}

package/src/errors/transport.ts

@@ -0,0 +1,15 @@
+import { BaseError } from './base.js'
+
+export type UrlRequiredErrorType = UrlRequiredError & {
+  name: 'UrlRequiredError'
+}
+export class UrlRequiredError extends BaseError {
+  constructor() {
+    super(
+      'No URL was provided to the Transport. Please provide a valid RPC URL to the Transport.',
+      {
+        name: 'UrlRequiredError',
+      }
+    )
+  }
+}

package/src/errors/utils.ts

@@ -0,0 +1,6 @@
+import type { Address } from '../types/address.js'
+
+export type ErrorType<name extends string = 'Error'> = Error & { name: name }
+
+export const getContractAddress = (address: Address) => address
+export const getUrl = (url: string) => url