@alchemy/common 0.0.0-alpha.0

package/src/actions/addBreadCrumb.ts

@@ -0,0 +1,38 @@
+import { createClient, type Client } from "viem";
+import { headersUpdate } from "../tracing/updateHeaders.js";
+import {
+  alchemyTransport,
+  type AlchemyTransport,
+} from "../transport/alchemy.js";
+import { convertHeadersToObject } from "../utils/headers.js";
+
+/**
+ * TODO: need to figure out if there's a better way than this...
+ * This adds a tracing breadcrumb to the client during requests.
+ * It returns a basic client without the previously extended actions.
+ * That means you MUST use viem's `getAction` method within actions in case the action is being called from an action that attached a breadcrumb.
+ * That method works by taking a fallback, looking up the action on the client, if it finds it calls it, otherwise it calls the fallback.
+ *
+ * @param {Client<AlchemyTransport>} client a client using the alchemy transport
+ * @param {string} breadcrumb the breadcrumb to add to the tracing headers
+ * @returns {Client<AlchemyTransport>} a client with the transport updated to include the breadcrumb
+ */
+export function addBreadCrumb(
+  client: Client<AlchemyTransport>,
+  breadcrumb: string,
+): Client<AlchemyTransport> {
+  const oldConfig = client.transport.config;
+  const dynamicFetchOptions = client.transport.fetchOptions;
+  const newTransport = alchemyTransport({ ...oldConfig });
+  newTransport.updateHeaders(
+    headersUpdate(breadcrumb)(
+      convertHeadersToObject(dynamicFetchOptions?.headers),
+    ),
+  );
+
+  return createClient({
+    ...client,
+    transport: newTransport,
+    chain: client.chain,
+  });
+}

package/src/chains.ts

@@ -0,0 +1,118 @@
+/**
+ * Custom chain definitions for Alchemy SDK.
+ *
+ * This module provides chain definitions for networks not yet available in viem.
+ * For standard networks (Ethereum, Arbitrum, Base, etc.), import directly from "viem/chains".
+ * All chains work automatically with alchemyTransport via the internal registry lookup.
+ *
+ * @example
+ * ```typescript
+ * // Standard chains - import from viem
+ * import { sepolia, arbitrum, base } from "viem/chains";
+ *
+ * // Custom chains - import from here
+ * import { worldChain, unichainMainnet } from "@alchemy/common/chains";
+ * ```
+ */
+import { defineChain } from "viem";
+
+export const fraxtalSepolia = defineChain({
+  id: 2523,
+  name: "Fraxtal Sepolia",
+  nativeCurrency: { name: "Frax Ether", symbol: "frxETH", decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ["https://rpc.testnet-sepolia.frax.com"],
+    },
+  },
+  testnet: true,
+});
+
+export const openlootSepolia = defineChain({
+  id: 905905,
+  name: "Openloot Sepolia",
+  nativeCurrency: { name: "Openloot", symbol: "OL", decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ["https://openloot-sepolia.g.alchemy.com/v2"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Block Explorer",
+      url: "https://openloot-sepolia.explorer.alchemy.com",
+    },
+  },
+  testnet: true,
+});
+
+export const gensynTestnet = defineChain({
+  id: 685685,
+  name: "Gensyn Testnet",
+  nativeCurrency: { name: "eth", symbol: "eth", decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ["https://gensyn-testnet.g.alchemy.com/v2"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Block Explorer",
+      url: "https://gensyn-testnet.explorer.alchemy.com",
+    },
+  },
+  testnet: true,
+});
+
+export const riseTestnet = defineChain({
+  id: 11155931,
+  name: "Rise Testnet",
+  nativeCurrency: { name: "eth", symbol: "eth", decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ["https://rise-testnet.g.alchemy.com/v2"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Block Explorer",
+      url: "https://explorer.testnet.riselabs.xyz",
+    },
+  },
+  testnet: true,
+});
+
+export const storyMainnet = defineChain({
+  id: 1514,
+  name: "Story Mainnet",
+  nativeCurrency: { name: "IP", symbol: "IP", decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ["https://story-mainnet.g.alchemy.com/v2"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Block Explorer",
+      url: "https://www.storyscan.io",
+    },
+  },
+});
+
+export const teaSepolia = defineChain({
+  id: 10218,
+  name: "Tea Sepolia",
+  nativeCurrency: { name: "TEA", symbol: "TEA", decimals: 18 },
+  rpcUrls: {
+    default: {
+      http: ["https://tea-sepolia.g.alchemy.com/v2"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Block Explorer",
+      url: "https://sepolia.tea.xyz/",
+    },
+  },
+  testnet: true,
+});

package/src/errors/AccountNotFoundError.ts

@@ -0,0 +1,16 @@
+import { BaseError } from "./BaseError.js";
+
+/**
+ * This error is thrown when an account could not be found to execute a specific action. It extends the `BaseError` class.
+ */
+export class AccountNotFoundError extends BaseError {
+  override name = "AccountNotFoundError";
+
+  // TODO: extend this further using docs path as well
+
+  /**
+   * Constructor for initializing an error message indicating that an account could not be found to execute the specified action.
+   */ constructor() {
+    super("Could not find an Account to execute with this Action.");
+  }
+}

package/src/errors/BaseError.ts

@@ -0,0 +1,51 @@
+import { BaseError as ViemBaseError } from "viem";
+import { VERSION } from "../version.js";
+
+type BaseErrorParameters = {
+  docsPath?: string;
+  docsSlug?: string;
+  metaMessages?: string[];
+} & (
+  | {
+      cause?: never;
+      details?: string;
+    }
+  | {
+      cause: BaseError | Error;
+      details?: never;
+    }
+);
+
+/**
+ * A custom error class that extends from `ViemBaseError`. This class allows for error messages to include links to relevant documentation based on provided `docsPath` and `docsSlug` parameters.
+ * This is based on on viem's BaseError type (obviously from the import and extend)
+ * we want the errors here to point to our docs if we supply a docsPath though
+ */
+export class BaseError extends ViemBaseError {
+  override name = "AlchemySDKError";
+  override version = VERSION;
+
+  constructor(shortMessage: string, args: BaseErrorParameters = {}) {
+    super(shortMessage, args);
+
+    const docsPath =
+      args.cause instanceof BaseError
+        ? args.cause.docsPath || args.docsPath
+        : args.docsPath;
+
+    this.message = [
+      shortMessage || "An error occurred.",
+      "",
+      ...(args.metaMessages ? [...args.metaMessages, ""] : []),
+      ...(docsPath
+        ? [
+            `Docs: https://www.alchemy.com/docs/wallets${docsPath}${
+              args.docsSlug ? `#${args.docsSlug}` : ""
+            }`,
+          ]
+        : []),
+      ...(this.details ? [`Details: ${this.details}`] : []),
+      `Version: ${this.version}`,
+    ].join("\n");
+  }
+}

package/src/errors/ChainNotFoundError.ts

@@ -0,0 +1,15 @@
+import { BaseError } from "./BaseError.js";
+
+/**
+ * Error class representing a "Chain Not Found" error, typically thrown when no chain is supplied to the client.
+ */
+export class ChainNotFoundError extends BaseError {
+  override name = "ChainNotFoundError";
+
+  /**
+   * Initializes a new instance of the error message with a default message indicating that no chain was supplied to the client.
+   */
+  constructor() {
+    super("No chain supplied to the client");
+  }
+}

package/src/errors/ConnectionConfigError.ts

@@ -0,0 +1,22 @@
+import { BaseError } from "./BaseError.js";
+
+/**
+ * Error class for connection configuration validation failures.
+ */
+export class ConnectionConfigError extends BaseError {
+  override name = "ConnectionConfigError";
+
+  // TODO: extend this further using docs path as well for debugging connection-related problems
+
+  /**
+   * Creates a new ConnectionConfigError with details about the validation failure.
+   *
+   * @param {string} [details] Optional details about the specific validation failure
+   */
+  constructor(details?: string) {
+    const message = details
+      ? `Invalid Alchemy connection configuration: ${details}`
+      : "Invalid Alchemy connection configuration";
+    super(message);
+  }
+}

package/src/errors/FetchError.ts

@@ -0,0 +1,21 @@
+import { BaseError } from "./BaseError.js";
+
+/**
+ * Error class representing a "Fetch Error" error, typically thrown when a fetch request fails.
+ */
+export class FetchError extends BaseError {
+  override name = "FetchError";
+
+  /**
+   * Initializes a new instance of the error message with a default message indicating that no chain was supplied to the client.
+   *
+   * @param {string} route - The route that failed to fetch.
+   * @param {string} method - The HTTP method that was used.
+   * @param {Error} cause - The cause of the error.
+   */
+  constructor(route: string, method: string, cause?: Error) {
+    super(`[${method}] ${route} failed to fetch`, {
+      cause,
+    });
+  }
+}

package/src/errors/InvalidRequestError.ts

@@ -0,0 +1,19 @@
+import { BaseError } from "./BaseError.js";
+
+/**
+ * This error is thrown when an invalid request is made. It extends the `BaseError` class.
+ */
+export class InvalidRequestError extends BaseError {
+  override name = "InvalidRequestError";
+
+  // TODO: extend this further using docs path as well
+
+  /**
+   * Constructor for initializing an InvalidRequestError.
+   *
+   * @param {string} message - Optional error message. Defaults to "Invalid request" if not provided.
+   */
+  constructor(message?: string) {
+    super(message || "Invalid request");
+  }
+}

package/src/errors/MethodUnsupportedError.ts

@@ -0,0 +1,17 @@
+import { BaseError } from "./BaseError.js";
+
+/**
+ * This error is thrown when an unknown method is called. It extends the `BaseError` class.
+ */
+export class MethodUnsupportedError extends BaseError {
+  override name = "MethodUnsupportedError";
+
+  /**
+   * Constructor for initializing an error message indicating the method name that is unsupported.
+   *
+   * @param {string} method - The name of the unsupported method
+   */
+  constructor(method: string) {
+    super(`Unsupported method: ${method}`);
+  }
+}

package/src/errors/ServerError.ts

@@ -0,0 +1,21 @@
+import { BaseError } from "./BaseError.js";
+
+/**
+ * Error class representing a "Server Error" error, typically thrown when a server request fails.
+ */
+export class ServerError extends BaseError {
+  override name = "ServerError";
+
+  /**
+   * Initializes a new instance of the error message with a default message indicating that no chain was supplied to the client.
+   *
+   * @param {string} message - The error message.
+   * @param {number} status - The HTTP status code of the error.
+   * @param {Error} cause - The cause of the error.
+   */
+  constructor(message: string, status: number, cause?: Error) {
+    super(`HTTP request failed with status ${status}: ${message}`, {
+      cause,
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,60 @@
+// http
+export type * from "./rest/restClient.js";
+export type * from "./rest/types.js";
+export { AlchemyRestClient } from "./rest/restClient.js";
+
+// transport
+export type * from "./transport/alchemy.js";
+export { alchemyTransport, isAlchemyTransport } from "./transport/alchemy.js";
+
+// chain registry utilities
+export {
+  getAlchemyRpcUrl,
+  isChainSupported,
+  getSupportedChainIds,
+} from "./transport/chainRegistry.js";
+
+// utils
+export type * from "./utils/types.js";
+export { assertNever } from "./utils/assertNever.js";
+export { raise } from "./utils/raise.js";
+export { bigIntMultiply } from "./utils/bigint.js";
+export { lowerAddress } from "./utils/lowerAddress.js";
+export { createEip1193HandlerFactory } from "./utils/createEip1193HandlerFactory.js";
+
+// config
+export type { AlchemyConnectionConfig } from "./transport/connectionSchema.js";
+export {
+  AlchemyConnectionConfigSchema,
+  validateAlchemyConnectionConfig,
+  isAlchemyConnectionConfig,
+} from "./transport/connectionSchema.js";
+
+// errors
+export { BaseError } from "./errors/BaseError.js";
+export { ChainNotFoundError } from "./errors/ChainNotFoundError.js";
+export { AccountNotFoundError } from "./errors/AccountNotFoundError.js";
+export { ConnectionConfigError } from "./errors/ConnectionConfigError.js";
+export { FetchError } from "./errors/FetchError.js";
+export { ServerError } from "./errors/ServerError.js";
+export { InvalidRequestError } from "./errors/InvalidRequestError.js";
+export { MethodUnsupportedError } from "./errors/MethodUnsupportedError.js";
+
+// actions
+export type * from "./actions/addBreadCrumb.js";
+export { addBreadCrumb } from "./actions/addBreadCrumb.js";
+
+// chains (convenience exports for Alchemy-supported chains)
+export * from "./chains.js";
+
+// diagnostics logging
+export { createLogger } from "./logging/logger.js";
+export {
+  setGlobalLoggerConfig,
+  getGlobalLoggerConfig,
+  LogLevel,
+  isLevelEnabled,
+  isNamespaceEnabled,
+} from "./logging/config.js";
+export type { DiagnosticsLogger } from "./logging/logger.js";
+export { InMemorySink } from "./logging/sinks.js";