@alchemy/common 0.0.0-alpha.0

package/src/transport/alchemy.ts

@@ -0,0 +1,242 @@
+import {
+  createTransport,
+  http,
+  type Chain,
+  type EIP1193RequestFn,
+  type HttpTransportConfig,
+  type RpcSchema,
+  type Transport,
+} from "viem";
+import { BaseError } from "../errors/BaseError.js";
+import { mutateRemoveTrackingHeaders } from "../tracing/updateHeaders.js";
+import { ChainNotFoundError } from "../errors/ChainNotFoundError.js";
+import { getAlchemyRpcUrl } from "./chainRegistry.js";
+import {
+  convertHeadersToObject,
+  withAlchemyHeaders,
+} from "../utils/headers.js";
+
+/**
+ * Configuration options for the Alchemy transport.
+ * Extends viem's HttpTransportConfig with Alchemy-specific options while omitting
+ * options that are not relevant or supported by Alchemy.
+ */
+export interface AlchemyTransportConfig
+  extends Omit<
+    HttpTransportConfig,
+    "batch" | "key" | "methods" | "name" | "raw"
+  > {
+  /** API key for Alchemy authentication */
+  apiKey?: string;
+  /** JWT token for authentication */
+  jwt?: string;
+  /** Custom RPC URL (optional - defaults to chain's Alchemy URL, but can be used to override the chain's Alchemy URL) */
+  url?: string;
+}
+
+type AlchemyTransportBase<rpcSchema extends RpcSchema | undefined = undefined> =
+  Transport<
+    "alchemyHttp",
+    {
+      alchemyRpcUrl: string;
+      fetchOptions: AlchemyTransportConfig["fetchOptions"];
+      config: AlchemyTransportConfig;
+    },
+    EIP1193RequestFn<rpcSchema>
+  >;
+
+export type AlchemyTransport<
+  rpcSchema extends RpcSchema | undefined = undefined,
+> = AlchemyTransportBase<rpcSchema> & {
+  updateHeaders(newHeaders: HeadersInit): void;
+};
+
+/**
+ * A type guard for the transport to determine if it is an Alchemy transport.
+ * Used in cases where we would like to do switching depending on the transport.
+ *
+ * @param {Transport} transport The transport to check
+ * @param {Chain} chain Chain for the transport to run its function to return the transport config
+ * @returns {boolean} `true` if the transport is an Alchemy transport, otherwise `false`
+ */
+export function isAlchemyTransport(
+  transport: Transport,
+  chain: Chain,
+): transport is AlchemyTransport {
+  return transport({ chain }).config.type === "alchemyHttp";
+}
+
+/**
+ * Creates an Alchemy HTTP transport for connecting to Alchemy's services.
+ *
+ * @example
+ * Using API Key:
+ * ```ts
+ * import { alchemyTransport } from "@alchemy/common";
+ *
+ * const transport = alchemyTransport({ apiKey: "your-api-key" });
+ * ```
+ *
+ * @example
+ * Using JWT:
+ * ```ts
+ * import { alchemyTransport } from "@alchemy/common";
+ *
+ * const transport = alchemyTransport({ jwt: "your-jwt-token" });
+ * ```
+ *
+ * @example
+ * Using URL directly:
+ * ```ts
+ * import { alchemyTransport } from "@alchemy/common";
+ *
+ * const transport = alchemyTransport({ url: "https://eth-mainnet.g.alchemy.com/v2/your-key" });
+ * ```
+ *
+ * @example
+ * Using custom URL with API key:
+ * ```ts
+ * import { alchemyTransport } from "@alchemy/common";
+ *
+ * const transport = alchemyTransport({
+ *   url: "https://custom-alchemy.com/v2",
+ *   apiKey: "your-api-key"
+ * });
+ * ```
+ *
+ * @example
+ * Using custom URL with JWT:
+ * ```ts
+ * import { alchemyTransport } from "@alchemy/common";
+ *
+ * const transport = alchemyTransport({
+ *   url: "https://custom-alchemy.com/v2",
+ *   jwt: "your-jwt-token"
+ * });
+ * ```
+ *
+ * @example
+ * Using HTTP debugging options:
+ * ```ts
+ * import { alchemyTransport } from "@alchemy/common";
+ *
+ * const transport = alchemyTransport({
+ *   apiKey: "your-api-key",
+ *   onFetchRequest: (request) => console.log("Request:", request),
+ *   onFetchResponse: (response) => console.log("Response:", response),
+ *   timeout: 30000,
+ *   retryCount: 3,
+ *   retryDelay: 1000
+ * });
+ * ```
+ *
+ * @param {AlchemyTransportConfig} config - The configuration object for the Alchemy transport (extends viem's HttpTransportConfig)
+ * @param {string} [config.apiKey] - API key for Alchemy authentication
+ * @param {string} [config.jwt] - JWT token for authentication
+ * @param {string} [config.url] - Direct URL to Alchemy endpoint or a proxy URL
+ * @param {Function} [config.onFetchRequest] - Callback for debugging outgoing requests
+ * @param {Function} [config.onFetchResponse] - Callback for debugging responses
+ * @param {number} [config.timeout] - Request timeout in milliseconds
+ * @param {number} [config.retryCount] - The number of retry attempts
+ * @param {number} [config.retryDelay] - The delay between retries, in milliseconds
+ * @param {object} [config.fetchOptions] - Optional fetch options for HTTP requests
+ * @param {object} [config.httpOptions] - HTTP transport options for debugging (onFetchRequest, onFetchResponse, timeout, batch)
+ * @returns {AlchemyTransport} The configured Alchemy transport function
+ */
+export function alchemyTransport<
+  rpcSchema extends RpcSchema | undefined = undefined,
+>(config: AlchemyTransportConfig): AlchemyTransport<rpcSchema> {
+  const {
+    apiKey,
+    jwt,
+    url,
+    fetchOptions: fetchOptions_,
+    retryCount,
+    retryDelay,
+    ...httpTransportConfig
+  } = config;
+
+  // Create a copy of fetch options for modification
+  const fetchOptions = { ...fetchOptions_ };
+
+  fetchOptions.headers = withAlchemyHeaders({
+    headers: fetchOptions.headers,
+    apiKey,
+    jwt,
+  });
+
+  const transport: AlchemyTransportBase = (opts) => {
+    const { chain } = opts;
+
+    mutateRemoveTrackingHeaders(config?.fetchOptions?.headers);
+
+    const rpcUrl = (() => {
+      if (url) {
+        return url;
+      }
+
+      if (!chain) {
+        throw new ChainNotFoundError();
+      }
+
+      const alchemyUrl = getAlchemyRpcUrl(chain.id);
+      if (alchemyUrl) {
+        return alchemyUrl;
+      }
+
+      // Fallback: check for legacy alchemy RPC URLs in chain definition
+      if (chain.rpcUrls?.alchemy?.http?.[0]) {
+        return chain.rpcUrls.alchemy.http[0];
+      }
+
+      throw new BaseError(
+        `Chain ${chain.id} (${chain.name}) is not supported by Alchemy. To use this chain:\n\n` +
+          `1. Use a direct RPC URL:\n` +
+          `   alchemyTransport({ url: "https://your-alchemy-endpoint.com/v2/your-key" })\n\n` +
+          `2. Add alchemy RPC to your chain definition:\n` +
+          `   defineChain({ rpcUrls: { alchemy: { http: ["https://your-alchemy-url/v2"] }}})\n\n` +
+          `3. Or use a standard RPC provider:\n` +
+          `   import { http } from "viem";\n` +
+          `   http("https://your-standard-rpc.com")`,
+      );
+    })();
+
+    const innerTransport = http(rpcUrl, {
+      // Standard viem options are passed through to the underlying transport, with
+      // the exception of retryCount and retryDelay because those are handled by
+      // the outer Alchemy transport.
+      ...httpTransportConfig,
+      fetchOptions,
+      // Retry count must be 0 here in order to respect the retry
+      // count that is already specified on the underlying transport.
+      retryCount: 0,
+    });
+
+    return createTransport(
+      {
+        key: "alchemyHttp",
+        name: "Alchemy HTTP Transport",
+        request: innerTransport(opts).request,
+        retryCount: retryCount ?? opts?.retryCount,
+        retryDelay,
+        type: "alchemyHttp",
+      },
+      {
+        alchemyRpcUrl: rpcUrl,
+        fetchOptions,
+        config,
+      },
+    );
+  };
+
+  return Object.assign(transport, {
+    updateHeaders(newHeaders_: HeadersInit) {
+      const newHeaders = convertHeadersToObject(newHeaders_);
+
+      fetchOptions.headers = {
+        ...fetchOptions.headers,
+        ...newHeaders,
+      };
+    },
+  });
+}

package/src/transport/chainRegistry.ts

@@ -0,0 +1,115 @@
+/**
+ * Internal registry mapping chain IDs to Alchemy RPC base URLs.
+ * This replaces the need for custom chain exports with embedded Alchemy URLs.
+ */
+export const ALCHEMY_RPC_MAPPING: Record<number, string> = {
+  // Ethereum networks
+  1: "https://eth-mainnet.g.alchemy.com/v2", // mainnet
+  11155111: "https://eth-sepolia.g.alchemy.com/v2", // sepolia
+  5: "https://eth-goerli.g.alchemy.com/v2", // goerli
+
+  // Arbitrum networks
+  42161: "https://arb-mainnet.g.alchemy.com/v2", // arbitrum
+  421613: "https://arb-goerli.g.alchemy.com/v2", // arbitrumGoerli
+  421614: "https://arb-sepolia.g.alchemy.com/v2", // arbitrumSepolia
+
+  // Optimism networks
+  10: "https://opt-mainnet.g.alchemy.com/v2", // optimism
+  420: "https://opt-goerli.g.alchemy.com/v2", // optimismGoerli
+  11155420: "https://opt-sepolia.g.alchemy.com/v2", // optimismSepolia
+
+  // Base networks
+  8453: "https://base-mainnet.g.alchemy.com/v2", // base
+  84531: "https://base-goerli.g.alchemy.com/v2", // baseGoerli
+  84532: "https://base-sepolia.g.alchemy.com/v2", // baseSepolia
+
+  // Polygon networks
+  137: "https://polygon-mainnet.g.alchemy.com/v2", // polygon
+  80001: "https://polygon-mumbai.g.alchemy.com/v2", // polygonMumbai
+  80002: "https://polygon-amoy.g.alchemy.com/v2", // polygonAmoy
+
+  // World Chain networks
+  480: "https://worldchain-mainnet.g.alchemy.com/v2", // worldChain
+  4801: "https://worldchain-sepolia.g.alchemy.com/v2", // worldChainSepolia
+
+  // Shape networks
+  360: "https://shape-mainnet.g.alchemy.com/v2", // shape
+  11011: "https://shape-sepolia.g.alchemy.com/v2", // shapeSepolia
+
+  // Unichain networks
+  130: "https://unichain-mainnet.g.alchemy.com/v2", // unichainMainnet
+  1301: "https://unichain-sepolia.g.alchemy.com/v2", // unichainSepolia
+
+  // Soneium networks
+  1868: "https://soneium-mainnet.g.alchemy.com/v2", // soneiumMainnet
+  1946: "https://soneium-minato.g.alchemy.com/v2", // soneiumMinato
+
+  // OPBNB networks
+  204: "https://opbnb-mainnet.g.alchemy.com/v2", // opbnbMainnet
+  5611: "https://opbnb-testnet.g.alchemy.com/v2", // opbnbTestnet
+
+  // BeraChain networks
+  80084: "https://berachain-bartio.g.alchemy.com/v2", // beraChainBartio
+
+  // Ink networks
+  57073: "https://ink-mainnet.g.alchemy.com/v2", // inkMainnet
+  763373: "https://ink-sepolia.g.alchemy.com/v2", // inkSepolia
+
+  // Monad networks
+  10143: "https://monad-testnet.g.alchemy.com/v2", // monadTestnet
+
+  // Openloot networks
+  905905: "https://openloot-sepolia.g.alchemy.com/v2", // openlootSepolia
+
+  // Gensyn networks
+  685685: "https://gensyn-testnet.g.alchemy.com/v2", // gensynTestnet
+
+  // Rise networks
+  11155931: "https://rise-testnet.g.alchemy.com/v2", // riseTestnet
+
+  // Story networks
+  1514: "https://story-mainnet.g.alchemy.com/v2", // storyMainnet
+  1315: "https://story-aeneid.g.alchemy.com/v2", // storyAeneid
+
+  // Celo networks
+  42220: "https://celo-mainnet.g.alchemy.com/v2", // celoMainnet
+  44787: "https://celo-alfajores.g.alchemy.com/v2", // celoAlfajores
+
+  // Tea networks
+  10218: "https://tea-sepolia.g.alchemy.com/v2", // teaSepolia
+};
+
+/**
+ * Gets the Alchemy RPC base URL for a given chain ID.
+ *
+ * @param {number} chainId The chain ID to lookup
+ * @returns {string | undefined} The Alchemy RPC base URL or undefined if not supported
+ *
+ * @example
+ * ```ts
+ * const rpcUrl = getAlchemyRpcUrl(1); // "https://eth-mainnet.g.alchemy.com/v2"
+ * const customUrl = getAlchemyRpcUrl(999); // undefined
+ * ```
+ */
+export function getAlchemyRpcUrl(chainId: number): string | undefined {
+  return ALCHEMY_RPC_MAPPING[chainId];
+}
+
+/**
+ * Checks if a chain ID is supported by the Alchemy RPC registry.
+ *
+ * @param {number} chainId The chain ID to check
+ * @returns {boolean} True if the chain is supported, false otherwise
+ */
+export function isChainSupported(chainId: number): boolean {
+  return chainId in ALCHEMY_RPC_MAPPING;
+}
+
+/**
+ * Gets all supported chain IDs from the registry.
+ *
+ * @returns {number[]} Array of supported chain IDs
+ */
+export function getSupportedChainIds(): number[] {
+  return Object.keys(ALCHEMY_RPC_MAPPING).map(Number);
+}

package/src/transport/connection.ts

@@ -0,0 +1,19 @@
+import type { Never } from "../utils/types";
+
+// TODO(v5): remove this file and use connectionSchema.ts instead once other packages are migrated over
+type AlchemyConnectionBaseConfig =
+  // TODO(v5): is this really the best devex? can we do better?
+  // basic configuration for connecting to alchemy.
+  // proxyUrl is used when making calls to the developer backend.
+  | { proxyUrl: string; apiKey?: never; jwt?: never }
+  | { proxyUrl?: never; apiKey: string; jwt?: never }
+  | { proxyUrl?: never; apiKey?: never; jwt: string };
+
+type AAOnlyChainConfig = {
+  alchemyConnection: AlchemyConnectionBaseConfig;
+  nodeRpcUrl: string;
+};
+
+export type AlchemyConnectionConfig =
+  | (AlchemyConnectionBaseConfig & Never<AAOnlyChainConfig>)
+  | (AAOnlyChainConfig & Never<AlchemyConnectionBaseConfig>);

package/src/transport/connectionSchema.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { ConnectionConfigError } from "../errors/ConnectionConfigError.js";
+
+/**
+ * Alchemy Connection Configuration Schema
+ *
+ * Provides three authentication options for connecting to Alchemy services:
+ *
+ * 1. **API Key**: Authenticate using your Alchemy API key
+ * 2. **JWT**: Authenticate using a JWT token
+ * 3. **URL**: Connect directly using a full RPC URL
+ *
+ * @example
+ * Using API Key (uses chain's Alchemy URL):
+ * ```ts
+ * { apiKey: 'abc123' }
+ * ```
+ *
+ * @example
+ * Using JWT (uses chain's Alchemy URL):
+ * ```ts
+ * { jwt: 'eyJhbGc...' }
+ * ```
+ *
+ * @example
+ * Using direct URL only:
+ * ```ts
+ * { url: 'https://eth-mainnet.g.alchemy.com/v2/your-key' }
+ * ```
+ *
+ * @example
+ * Using custom URL with API key:
+ * ```ts
+ * { url: 'https://custom-alchemy.com/v2', apiKey: 'abc123' }
+ * ```
+ *
+ * @example
+ * Using custom URL with JWT:
+ * ```ts
+ * { url: 'https://custom-alchemy.com/v2', jwt: 'eyJhbGc...' }
+ * ```
+ */
+
+/**
+ * Main connection configuration allowing flexible combinations.
+ * Can specify URL, auth method, or both together.
+ */
+export const AlchemyConnectionConfigSchema = z
+  .object({
+    /** API key for Alchemy authentication */
+    apiKey: z.string().min(1, "API key cannot be empty").optional(),
+    /** JWT token for authentication */
+    jwt: z.string().min(1, "JWT cannot be empty").optional(),
+    /** Custom RPC URL (optional - defaults to chain's Alchemy URL) */
+    url: z.string().url("Invalid URL format").optional(),
+  })
+  .strict()
+  .refine(
+    (data) => {
+      // Must have at least one field
+      return data.apiKey || data.jwt || data.url;
+    },
+    {
+      message: "Must specify at least one of: apiKey, jwt, or url",
+    },
+  )
+  .refine(
+    (data) => {
+      // Cannot have both apiKey and jwt
+      return !(data.apiKey && data.jwt);
+    },
+    {
+      message:
+        "Cannot specify both apiKey and jwt - choose only one authentication method",
+    },
+  );
+
+/**
+ * TypeScript type derived from the schema for external consumption.
+ * This provides clean type inference without exposing Zod implementation details.
+ */
+export type AlchemyConnectionConfig = z.infer<
+  typeof AlchemyConnectionConfigSchema
+>;
+
+/**
+ * Validates an Alchemy connection configuration object.
+ *
+ * @param {unknown} config - The configuration object to validate
+ * @returns {AlchemyConnectionConfig} The validated configuration object
+ * @throws {ConnectionConfigError} If the configuration is invalid
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const config = validateAlchemyConnectionConfig({
+ *     apiKey: 'your-api-key'
+ *   });
+ *   // config is now typed as AlchemyConnectionConfig
+ * } catch (error) {
+ *   if (error instanceof ConnectionConfigError) {
+ *     console.error('Invalid config:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export function validateAlchemyConnectionConfig(
+  config: unknown,
+): AlchemyConnectionConfig {
+  const result = AlchemyConnectionConfigSchema.safeParse(config);
+
+  if (!result.success) {
+    const firstError = result.error.issues[0];
+    const details = firstError?.message || "Invalid connection configuration";
+    throw new ConnectionConfigError(details);
+  }
+
+  return result.data;
+}
+
+/**
+ * Type guard to check if a value is a valid Alchemy connection config.
+ *
+ * @param {unknown} value - The value to check for validity
+ * @returns {boolean} True if the value is a valid Alchemy connection config
+ *
+ * @example
+ * ```ts
+ * const maybeConfig: unknown = { apiKey: 'test' };
+ * if (isAlchemyConnectionConfig(maybeConfig)) {
+ *   // TypeScript knows maybeConfig is AlchemyConnectionConfig here
+ *   if (maybeConfig.apiKey) {
+ *     console.log('Using API key:', maybeConfig.apiKey);
+ *   }
+ *   if (maybeConfig.url) {
+ *     console.log('Using custom URL:', maybeConfig.url);
+ *   }
+ * }
+ * ```
+ */
+export function isAlchemyConnectionConfig(
+  value: unknown,
+): value is AlchemyConnectionConfig {
+  return AlchemyConnectionConfigSchema.safeParse(value).success;
+}

package/src/utils/assertNever.ts

@@ -0,0 +1,12 @@
+import { BaseError } from "../errors/BaseError.js";
+
+/**
+ * Asserts that a value is never.
+ *
+ * @param {never} _x - The value to assert.
+ * @param {string} msg - The message to throw if the value is not never.
+ * @returns {never} Always throws an error.
+ */
+export const assertNever = (_x: never, msg: string): never => {
+  throw new BaseError(msg);
+};

package/src/utils/bigint.ts

@@ -0,0 +1,58 @@
+/**
+ * BigNumberish represents values that can be converted to BigInt
+ */
+export type BigNumberish = string | number | bigint;
+
+/**
+ * Multiplier configuration for bigint multiplication
+ */
+export type Multiplier = {
+  multiplier: number;
+};
+
+export enum RoundingMode {
+  ROUND_DOWN = 0,
+  ROUND_UP = 1,
+}
+
+/**
+ * Validates if a multiplier has acceptable precision (max 4 decimal places)
+ *
+ * @param {Multiplier} multiplier - the multiplier to validate
+ * @returns {boolean} true if valid, false otherwise
+ */
+function isValidMultiplier(multiplier: Multiplier): boolean {
+  const decimalPlaces =
+    multiplier.multiplier.toString().split(".")[1]?.length ?? 0;
+  return decimalPlaces <= 4;
+}
+
+/**
+ * Given a bigint and a number (which can be a float), returns the bigint value.
+ * Note: this function has loss and will round down to the nearest integer.
+ *
+ * @param {BigNumberish} base - the number to be multiplied
+ * @param {number} multiplier - the amount to multiply by
+ * @param {RoundingMode} roundingMode - the rounding mode to use when calculating the percent. defaults to ROUND_UP
+ * @returns {bigint} the bigint value of the multiplication with the number rounded by the rounding mode
+ */
+export const bigIntMultiply = (
+  base: BigNumberish,
+  multiplier: Multiplier["multiplier"],
+  roundingMode: RoundingMode = RoundingMode.ROUND_UP,
+) => {
+  if (!isValidMultiplier({ multiplier })) {
+    throw new Error(
+      "bigIntMultiply requires a multiplier validated number as the second argument (max 4 decimal places)",
+    );
+  }
+
+  // Get decimal places of b. Max decimal places is defined by the validation above.
+  const decimalPlaces = multiplier.toString().split(".")[1]?.length ?? 0;
+  const result =
+    BigInt(base) * BigInt(Math.round(multiplier * 10 ** decimalPlaces));
+  return roundingMode === RoundingMode.ROUND_UP &&
+    result % BigInt(10 ** decimalPlaces) > 0
+    ? result / BigInt(10 ** decimalPlaces) + 1n
+    : result / BigInt(10 ** decimalPlaces);
+};

package/src/utils/createEip1193HandlerFactory.ts

@@ -0,0 +1,25 @@
+/**
+ * Creates a typed handler factory for EIP1193 request methods.
+ * This helps with Viem's typing within custom EIP1193 request functions by
+ * automatically casting input params and ensuring the result matches what is required.
+ *
+ * @returns {(params: unknown) => unknown} A function that creates a handler factory for specific methods
+ */
+export const createEip1193HandlerFactory =
+  <
+    TMethods extends readonly {
+      Method: string;
+      Parameters?: unknown;
+      ReturnType?: unknown;
+    }[],
+  >() =>
+  <TMethod extends TMethods[number]["Method"]>(
+    handle: (
+      params: Extract<TMethods[number], { Method: TMethod }>["Parameters"],
+    ) => Promise<Extract<TMethods[number], { Method: TMethod }>["ReturnType"]>,
+  ) =>
+  (params: unknown) => {
+    return handle(
+      params as Extract<TMethods[number], { Method: TMethod }>["Parameters"],
+    );
+  };

package/src/utils/headers.ts

@@ -0,0 +1,48 @@
+import { VERSION } from "../version.js";
+
+export type WithAlchemyHeadersParams = {
+  headers?: HeadersInit;
+  apiKey?: string;
+  jwt?: string;
+};
+
+export function withAlchemyHeaders({
+  headers,
+  apiKey,
+  jwt,
+}: WithAlchemyHeadersParams): Record<string, string> {
+  const bearerToken = jwt ?? apiKey;
+  return {
+    ...convertHeadersToObject(headers),
+    "Alchemy-AA-Sdk-Version": VERSION,
+    ...(bearerToken ? { Authorization: `Bearer ${bearerToken}` } : {}),
+  };
+}
+
+export function convertHeadersToObject(
+  headers?: HeadersInit,
+): Record<string, string> {
+  if (!headers) {
+    return {};
+  }
+
+  if (headers instanceof Headers) {
+    const headersObject = {} as Record<string, string>;
+    headers.forEach((value, key) => {
+      headersObject[key] = value;
+    });
+    return headersObject;
+  }
+
+  if (Array.isArray(headers)) {
+    return headers.reduce(
+      (acc, header) => {
+        acc[header[0]] = header[1];
+        return acc;
+      },
+      {} as Record<string, string>,
+    );
+  }
+
+  return headers;
+}

package/src/utils/lowerAddress.ts

@@ -0,0 +1,10 @@
+import { type Address } from "viem";
+
+/**
+ * Lowercase an address
+ *
+ * @param {Address} addr - The address to lowercase
+ * @returns {Address} The lowercase address
+ */
+export const lowerAddress = (addr: Address): Address =>
+  addr.toLowerCase() as Address;

package/src/utils/raise.ts

@@ -0,0 +1,14 @@
+import { BaseError } from "viem";
+
+/**
+ * Raises an error.
+ *
+ * @param {string | BaseError} err - The error to raise.
+ * @returns {never} Always throws an error.
+ */
+export const raise = (err: string | BaseError): never => {
+  if (typeof err === "string") {
+    throw new BaseError(err);
+  }
+  throw err;
+};