@aa-sdk/core 4.20.1 → 4.22.0

package/dist/types/utils/traceHeader.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Some tools that are useful when dealing with the values
+ * of the trace header. Follows the W3C trace context standard.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export declare class TraceHeader {
+    readonly traceId: string;
+    readonly parentId: string;
+    readonly traceFlags: string;
+    readonly traceState: Record<string, string>;
+    /**
+     * Initializes a new instance with the provided trace identifiers and state information.
+     *
+     * @param {string} traceId The unique identifier for the trace
+     * @param {string} parentId The identifier of the parent trace
+     * @param {string} traceFlags Flags containing trace-related options
+     * @param {TraceHeader["traceState"]} traceState The trace state information for additional trace context
+     */
+    constructor(traceId: string, parentId: string, traceFlags: string, traceState: TraceHeader["traceState"]);
+    /**
+     * Creating a default trace id that is a random setup for both trace id and parent id
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+     * ```
+     *
+     * @returns {TraceHeader} A default trace header
+     */
+    static default(): TraceHeader;
+    /**
+     * Should be able to consume a trace header from the headers of an http request
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers);
+     * ```
+     *
+     * @param {Record<string,string>} headers The headers from the http request
+     * @returns {TraceHeader | undefined} The trace header object, or nothing if not found
+     */
+    static fromTraceHeader(headers: Record<string, string>): TraceHeader | undefined;
+    /**
+     * Should be able to convert the trace header to the format that is used in the headers of an http request
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+     * const headers = traceHeader.toTraceHeader();
+     * ```
+     *
+     * @returns {{stracheader: string, tracestate: string}} The trace header in the format of a record, used in our http client
+     */
+    toTraceHeader(): {
+        readonly traceheader: `00-${string}-${string}-${string}`;
+        readonly tracestate: string;
+    };
+    /**
+     * Should be able to create a new trace header with a new event in the trace state,
+     *  as the key of the eventName as breadcrumbs appending onto previous breadcrumbs with the - infix if exists. And the
+     * trace parent gets updated as according to the docs
+     *
+     * @example ```ts
+     * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+     * const newTraceHeader = traceHeader.withEvent("newEvent");
+     * ```
+     *
+     * @param {string} eventName The key of the new event
+     * @returns {TraceHeader} The new trace header
+     */
+    withEvent(eventName: string): TraceHeader;
+}
+//# sourceMappingURL=traceHeader.d.ts.map

package/dist/types/utils/traceHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceHeader.d.ts","sourceRoot":"","sources":["../../../src/utils/traceHeader.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5C;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,WAAW,CAAC,YAAY,CAAC;IAQvC;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO;IAQd;;;;;;;;;OASG;IACH,MAAM,CAAC,eAAe,CACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,WAAW,GAAG,SAAS;IAsB1B;;;;;;;;;OASG;IACH,aAAa;;;;IASb;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW;CAS1C"}

package/dist/types/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "4.20.1";
+export declare const VERSION = "4.22.0";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aa-sdk/core",
   "license": "MIT",
-  "version": "4.20.1",
+  "version": "4.22.0",
   "description": "viem based SDK that enables interactions with ERC-4337 Smart Accounts. ABIs are based off the definitions generated in @account-abstraction/contracts",
   "author": "Alchemy",
   "type": "module",
@@ -65,5 +65,5 @@
     "url": "https://github.com/alchemyplatform/aa-sdk/issues"
   },
   "homepage": "https://github.com/alchemyplatform/aa-sdk#readme",
-  "gitHead": "8ee8571d4bbf78d75fb7c2a40e299808eaa63bfb"
+  "gitHead": "07a9e38db91c0a8937f3e2f28e25c95605e31698"
 }

package/src/actions/smartAccount/buildUserOperation.ts

@@ -1,4 +1,4 @@
-import type { Chain, Client, Transport } from "viem";
+import { type Chain, type Client, type Transport } from "viem";
 import {
   type GetEntryPointFromAccount,
   type SmartContractAccount,
@@ -13,7 +13,9 @@ import type {
   BuildUserOperationParameters,
   UserOperationContext,
 } from "./types";
+import { clientHeaderTrack } from "../../client/addBreadcrumb.js";
 
+const USER_OPERATION_METHOD = "buildUserOperation";
 /**
  * Builds a user operation using the provided client and operation parameters. Ensures that the account exists and the client is compatible.
  *
@@ -33,7 +35,7 @@ import type {
  * });
  * ```
  *
- * @param {Client<TTransport, TChain, TAccount>} client the client instance used to build the user operation
+ * @param {Client<TTransport, TChain, TAccount>} client_ the client instance used to build the user operation
  * @param {BuildUserOperationParameters<TAccount, TContext, TEntryPointVersion>} args the parameters required to build the user operation, including account, overrides, and context
  * @returns {Promise<UserOperationStruct<TEntryPointVersion>>} a promise that resolves to a `UserOperationStruct` object containing the built user operation details
  */
@@ -48,9 +50,10 @@ export async function buildUserOperation<
     | undefined,
   TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
 >(
-  client: Client<TTransport, TChain, TAccount>,
+  client_: Client<TTransport, TChain, TAccount>,
   args: BuildUserOperationParameters<TAccount, TContext, TEntryPointVersion>
 ): Promise<UserOperationStruct<TEntryPointVersion>> {
+  const client = clientHeaderTrack(client_, USER_OPERATION_METHOD);
   const { account = client.account, overrides, context } = args;
   if (!account) {
     throw new AccountNotFoundError();
@@ -59,7 +62,7 @@ export async function buildUserOperation<
   if (!isBaseSmartAccountClient(client)) {
     throw new IncompatibleClientError(
       "BaseSmartAccountClient",
-      "buildUserOperation",
+      USER_OPERATION_METHOD,
       client
     );
   }

package/src/actions/smartAccount/buildUserOperationFromTx.ts

@@ -18,6 +18,7 @@ import type {
 } from "../../types.js";
 import { buildUserOperation } from "./buildUserOperation.js";
 import type { UserOperationContext } from "./types.js";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Performs `buildUserOperationFromTx` in batch and builds into a single, yet to be signed `UserOperation` (UO) struct. The output user operation struct will be filled with all gas fields (and paymaster data if a paymaster is used) based on the transactions data (`to`, `data`, `value`, `maxFeePerGas`, `maxPriorityFeePerGas`) computed using the configured `ClientMiddlewares` on the `SmartAccountClient`
@@ -52,7 +53,7 @@ import type { UserOperationContext } from "./types.js";
  * const uoHash = await smartAccountClient.sendRawUserOperation({ request, entryPoint: entryPointAddress });
  * ```
  *
- * @param {Client<Transport, TChain, TAccount>} client the smart account client to use for RPC requests
+ * @param {Client<Transport, TChain, TAccount>} client_ the smart account client to use for RPC requests
  * @param {SendTransactionParameters} args the send tx parameters
  * @param {UserOperationOverrides} overrides optional overrides to use for any of the fields
  * @param {TContext} context if the smart account client requires additinoal context for building UOs
@@ -69,11 +70,12 @@ export async function buildUserOperationFromTx<
     | undefined,
   TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
 >(
-  client: Client<Transport, TChain, TAccount>,
+  client_: Client<Transport, TChain, TAccount>,
   args: SendTransactionParameters<TChain, TAccount, TChainOverride>,
   overrides?: UserOperationOverrides<TEntryPointVersion>,
   context?: TContext
 ): Promise<UserOperationStruct<TEntryPointVersion>> {
+  const client = clientHeaderTrack(client_, "buildUserOperationFromTx");
   const { account = client.account, ...request } = args;
   if (!account || typeof account === "string") {
     throw new AccountNotFoundError();

package/src/actions/smartAccount/buildUserOperationFromTxs.ts

@@ -15,6 +15,7 @@ import type {
   BuildUserOperationFromTransactionsResult,
   UserOperationContext,
 } from "./types";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Performs `buildUserOperationFromTx` in batch and builds into a single,
@@ -66,7 +67,7 @@ import type {
  * });
  * ```
  *
- * @param {Client<TTransport, TChain, TAccount>} client the smart account client to use to make RPC calls
+ * @param {Client<TTransport, TChain, TAccount>} client_ the smart account client to use to make RPC calls
  * @param {BuildTransactionParameters} args  an object containing the requests to build as well as, the account if not hoisted, the context, the overrides, and optionally a flag to enable signing of the UO via the underlying middleware
  * @returns {Promise<BuildUserOperationFromTransactionsResult<TEntryPointVersion>>} a Promise containing the built user operation
  */
@@ -81,9 +82,10 @@ export async function buildUserOperationFromTxs<
     | UserOperationContext
     | undefined
 >(
-  client: Client<TTransport, TChain, TAccount>,
+  client_: Client<TTransport, TChain, TAccount>,
   args: BuildTransactionParameters<TAccount, TContext, TEntryPointVersion>
 ): Promise<BuildUserOperationFromTransactionsResult<TEntryPointVersion>> {
+  const client = clientHeaderTrack(client_, "buildUserOperationFromTxs");
   const { account = client.account, requests, overrides, context } = args;
   if (!account) {
     throw new AccountNotFoundError();

package/src/actions/smartAccount/checkGasSponsorshipEligibility.ts

@@ -12,6 +12,7 @@ import type {
   SendUserOperationParameters,
   UserOperationContext,
 } from "./types";
+import { clientHeaderTrack } from "../../index.js";
 
 export type CheckGasSponsorshipEligibilityResult<
   TAccount extends SmartContractAccount | undefined =
@@ -47,7 +48,7 @@ export type CheckGasSponsorshipEligibilityResult<
  * );
  * ```
  *
- * @param {Client<TTransport, TChain, TAccount>} client the smart account client to use for making RPC calls
+ * @param {Client<TTransport, TChain, TAccount>} client_ the smart account client to use for making RPC calls
  * @param {SendUserOperationParameters} args containing the user operation, account, context, and overrides
  * @returns {Promise<CheckGasSponsorshipEligibilityResult<TAccount>>} a Promise containing a boolean indicating if the account is elgibile for sponsorship and the sponsored UO
  */
@@ -61,9 +62,10 @@ export function checkGasSponsorshipEligibility<
     | UserOperationContext
     | undefined
 >(
-  client: Client<TTransport, TChain, TAccount>,
+  client_: Client<TTransport, TChain, TAccount>,
   args: SendUserOperationParameters<TAccount, TContext>
 ): Promise<CheckGasSponsorshipEligibilityResult<TAccount>> {
+  const client = clientHeaderTrack(client_, "checkGasSponsorshipEligibility");
   const { account = client.account, overrides, context } = args;
 
   if (!account) {

package/src/actions/smartAccount/dropAndReplaceUserOperation.ts

@@ -23,6 +23,7 @@ import type {
   DropAndReplaceUserOperationParameters,
   UserOperationContext,
 } from "./types";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Drops an existing user operation and replaces it with a new one while ensuring the appropriate fees and overrides are applied.
@@ -42,7 +43,7 @@ import type {
  * });
  * ```
  *
- * @param {Client<TTransport, TChain, TAccount>} client The client instance with the transport, chain, and account information
+ * @param {Client<TTransport, TChain, TAccount>} client_ The client instance with the transport, chain, and account information
  * @param {DropAndReplaceUserOperationParameters<TAccount, TContext>} args The parameters required for dropping and replacing the user operation including the account, operation to drop, overrides, and context
  * @returns {Promise<SendUserOperationResult<TEntryPointVersion>>} A promise that resolves to the result of sending the new user operation
  */
@@ -57,9 +58,10 @@ export async function dropAndReplaceUserOperation<
     | undefined,
   TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
 >(
-  client: Client<TTransport, TChain, TAccount>,
+  client_: Client<TTransport, TChain, TAccount>,
   args: DropAndReplaceUserOperationParameters<TAccount, TContext>
 ): Promise<SendUserOperationResult<TEntryPointVersion>> {
+  const client = clientHeaderTrack(client_, "dropAndReplaceUserOperation");
   const { account = client.account, uoToDrop, overrides, context } = args;
   if (!account) {
     throw new AccountNotFoundError();

package/src/actions/smartAccount/estimateUserOperationGas.ts

@@ -13,6 +13,7 @@ import type {
   SendUserOperationParameters,
   UserOperationContext,
 } from "./types.js";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Description SmartAccountClientAction for estimating the gas cost of a user operation
@@ -23,7 +24,7 @@ import type {
  * @template {SmartContractAccount | undefined} TAccount
  * @template {UserOperationContext | undefined} TContext
  * @template {GetEntryPointFromAccount<TAccount>} TEntryPointVersion
- * @param {Client<TTransport, TChain, TAccount>} client smart account client
+ * @param {Client<TTransport, TChain, TAccount>} client_ smart account client
  * @param {SendUserOperationParameters<TAccount, TContext>} args send user operation parameters
  * @returns {Promise<UserOperationEstimateGasResponse<TEntryPointVersion>>}user operation gas estimate response
  */
@@ -38,9 +39,10 @@ export async function estimateUserOperationGas<
     | undefined,
   TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
 >(
-  client: Client<TTransport, TChain, TAccount>,
+  client_: Client<TTransport, TChain, TAccount>,
   args: SendUserOperationParameters<TAccount, TContext>
 ): Promise<UserOperationEstimateGasResponse<TEntryPointVersion>> {
+  const client = clientHeaderTrack(client_, "estimateUserOperationGas");
   const { account = client.account, overrides } = args;
   if (!account) {
     throw new AccountNotFoundError();

package/src/actions/smartAccount/sendTransaction.ts

@@ -19,6 +19,7 @@ import { buildUserOperationFromTx } from "./buildUserOperationFromTx.js";
 import { _sendUserOperation } from "./internal/sendUserOperation.js";
 import type { UserOperationContext } from "./types.js";
 import { waitForUserOperationTransaction } from "./waitForUserOperationTransacation.js";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Sends a transaction using the provided client, arguments, optional overrides, and context.
@@ -38,7 +39,7 @@ import { waitForUserOperationTransaction } from "./waitForUserOperationTransacat
  * });
  * ```
  *
- * @param {Client<Transport, TChain, TAccount>} client The client to send the transaction through
+ * @param {Client<Transport, TChain, TAccount>} client_ The client to send the transaction through
  * @param {SendTransactionParameters<TChain, TAccount, TChainOverride>} args The parameters required to send the transaction
  * @param {UserOperationOverrides<TEntryPointVersion>} [overrides] Optional overrides for the user operation
  * @param {UserOperationContext} [context] Optional context for the user operation
@@ -55,11 +56,12 @@ export async function sendTransaction<
     | undefined,
   TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
 >(
-  client: Client<Transport, TChain, TAccount>,
+  client_: Client<Transport, TChain, TAccount>,
   args: SendTransactionParameters<TChain, TAccount, TChainOverride>,
   overrides?: UserOperationOverrides<TEntryPointVersion>,
   context?: TContext
 ): Promise<Hex> {
+  const client = clientHeaderTrack(client_, "estimateUserOperationGas");
   const { account = client.account } = args;
   if (!account || typeof account === "string") {
     throw new AccountNotFoundError();

package/src/actions/smartAccount/sendTransactions.ts

@@ -8,6 +8,7 @@ import { buildUserOperationFromTxs } from "./buildUserOperationFromTxs.js";
 import { _sendUserOperation } from "./internal/sendUserOperation.js";
 import type { SendTransactionsParameters, UserOperationContext } from "./types";
 import { waitForUserOperationTransaction } from "./waitForUserOperationTransacation.js";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Sends transactions using the provided client and transaction parameters. This function builds user operations from the transactions, sends them, and waits for the transaction to be mined.
@@ -28,7 +29,7 @@ import { waitForUserOperationTransaction } from "./waitForUserOperationTransacat
  * });
  * ```
  *
- * @param {Client<TTransport, TChain, TAccount>} client The client used to send the transactions
+ * @param {Client<TTransport, TChain, TAccount>} client_ The client used to send the transactions
  * @param {SendTransactionsParameters<TAccount, TContext>} args The parameters for sending the transactions, including requests, overrides, account, and context
  * @returns {Promise<Hex>} A promise that resolves to the transaction hash of the sent transactions
  */
@@ -40,9 +41,10 @@ export async function sendTransactions<
     | undefined,
   TContext extends UserOperationContext | undefined = UserOperationContext
 >(
-  client: Client<TTransport, TChain, TAccount>,
+  client_: Client<TTransport, TChain, TAccount>,
   args: SendTransactionsParameters<TAccount, TContext>
 ): Promise<Hex> {
+  const client = clientHeaderTrack(client_, "estimateUserOperationGas");
   const { requests, overrides, account = client.account, context } = args;
   if (!account) {
     throw new AccountNotFoundError();

package/src/actions/smartAccount/sendUserOperation.ts

@@ -13,6 +13,7 @@ import type {
   SendUserOperationParameters,
   UserOperationContext,
 } from "./types.js";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Sends a user operation or batch of user operations using the connected account. Before executing, sendUserOperation will run the user operation through the middleware pipeline.
@@ -31,7 +32,7 @@ import type {
  * });
  * ```
  *
- * @param {Client<TTransport, TChain, TAccount>} client the smart account client to use for RPC requests
+ * @param {Client<TTransport, TChain, TAccount>} client_ the smart account client to use for RPC requests
  * @param {SendUserOperationParameters<TAccount, TContext>} args contains the UO or batch to send, context, overrides, and account if not hoisted on the client
  * @returns {Promise<SendUserOperationResult<TEntryPointVersion>>} a Promise containing the result of the user operation
  */
@@ -46,9 +47,10 @@ export async function sendUserOperation<
     | undefined,
   TEntryPointVersion extends GetEntryPointFromAccount<TAccount> = GetEntryPointFromAccount<TAccount>
 >(
-  client: Client<TTransport, TChain, TAccount>,
+  client_: Client<TTransport, TChain, TAccount>,
   args: SendUserOperationParameters<TAccount, TContext>
 ): Promise<SendUserOperationResult<TEntryPointVersion>> {
+  const client = clientHeaderTrack(client_, "sendUserOperation");
   const { account = client.account, context, overrides } = args;
 
   if (!account) {

package/src/actions/smartAccount/upgradeAccount.ts

@@ -6,6 +6,7 @@ import { IncompatibleClientError } from "../../errors/client.js";
 import { sendUserOperation } from "./sendUserOperation.js";
 import type { UpgradeAccountParams, UserOperationContext } from "./types.js";
 import { waitForUserOperationTransaction } from "./waitForUserOperationTransacation.js";
+import { clientHeaderTrack } from "../../index.js";
 
 export const upgradeAccount: <
   TTransport extends Transport = Transport,
@@ -19,7 +20,8 @@ export const upgradeAccount: <
 >(
   client: Client<TTransport, TChain, TAccount>,
   args: UpgradeAccountParams<TAccount, TContext>
-) => Promise<Hash> = async (client, args) => {
+) => Promise<Hash> = async (client_, args) => {
+  const client = clientHeaderTrack(client_, "upgradeAccount");
   const {
     account = client.account,
     upgradeTo,

package/src/actions/smartAccount/waitForUserOperationTransacation.ts

@@ -4,6 +4,7 @@ import { IncompatibleClientError } from "../../errors/client.js";
 import { FailedToFindTransactionError } from "../../errors/transaction.js";
 import { Logger } from "../../logger.js";
 import type { WaitForUserOperationTxParameters } from "./types.js";
+import { clientHeaderTrack } from "../../index.js";
 
 /**
  * Waits for a user operation transaction to be confirmed by checking the receipt periodically until it is found or a maximum number of retries is reached.
@@ -20,7 +21,7 @@ import type { WaitForUserOperationTxParameters } from "./types.js";
  * });
  * ```
  *
- * @param {Client<TTransport, TChain, any>} client The client instance used to interact with the blockchain
+ * @param {Client<TTransport, TChain, any>} client_ The client instance used to interact with the blockchain
  * @param {WaitForUserOperationTxParameters} args The parameters for the transaction to wait for
  * @param {Hex} args.hash The transaction hash to wait for
  * @param {WaitForUserOperationTxParameters["retries"]} [args.retries] Optional retry parameters
@@ -35,7 +36,8 @@ export const waitForUserOperationTransaction: <
 >(
   client: Client<TTransport, TChain, any>,
   args: WaitForUserOperationTxParameters
-) => Promise<Hex> = async (client, args) => {
+) => Promise<Hex> = async (client_, args) => {
+  const client = clientHeaderTrack(client_, "waitForUserOperationTransaction");
   if (!isBaseSmartAccountClient(client)) {
     throw new IncompatibleClientError(
       "BaseSmartAccountClient",

package/src/client/addBreadcrumb.ts

@@ -0,0 +1,25 @@
+/**
+ * The symbol that is used to add a breadcrumb to the headers. Is an optional
+ * function that is used to add a breadcrumb to the headers.
+ */
+export const ADD_BREADCRUMB = Symbol("addBreadcrumb");
+
+function hasAddBreadcrumb<A extends {}>(
+  a: A
+): a is A & { [ADD_BREADCRUMB]: (breadcrumb: string) => A } {
+  return ADD_BREADCRUMB in a;
+}
+
+/**
+ * Add a crumb to the breadcrumb.
+ *
+ * @param {X} client Clients are somethings like viem, that we are adding breadcrumbs to, and could be owning the transport. Usually a alchemy client.
+ * @param {string} crumb The crumb to add to the breadcrumb
+ * @returns {Function} A function that updates the headers
+ */
+export function clientHeaderTrack<X extends {}>(client: X, crumb: string): X {
+  if (hasAddBreadcrumb(client)) {
+    return client[ADD_BREADCRUMB](crumb);
+  }
+  return client;
+}

package/src/client/smartAccountClient.ts

@@ -29,6 +29,7 @@ import {
 } from "./decorators/smartAccountClient.js";
 import { SmartAccountClientOptsSchema } from "./schema.js";
 import type { ClientMiddlewareConfig } from "./types.js";
+import { ADD_BREADCRUMB } from "./addBreadcrumb.js";
 
 type SmartAccountClientOpts = z.output<typeof SmartAccountClientOptsSchema>;
 
@@ -54,6 +55,15 @@ export type SmartAccountClientConfig<
   > & {
     account?: account;
     opts?: z.input<typeof SmartAccountClientOptsSchema>;
+    /**
+     * A function that adds a breadcrumb to the current context
+     * Note, most implementations will override the client with the default alchemy transport and this
+     * leads to the fact that a transport could be overwritten and not known until later.
+     *
+     * @param crumb A crumb, or span is telling that we are in a next step part of a multi step action
+     * @returns
+     */
+    addBreadCrumb?: <T>(crumb: string) => T;
   } & ClientMiddlewareConfig<context>
 >;
 
@@ -163,6 +173,7 @@ export function createSmartAccountClient(
     name = "account provider",
     transport,
     type = "SmartAccountClient",
+    addBreadCrumb,
     ...params
   } = config;
 
@@ -179,6 +190,7 @@ export function createSmartAccountClient(
       const rpcTransport = transport(opts);
 
       return custom({
+        name: "SmartAccountClientTransport",
         async request({ method, params }) {
           switch (method) {
             case "eth_accounts": {
@@ -263,9 +275,17 @@ export function createSmartAccountClient(
       })(opts);
     },
   })
-    .extend(() => ({
-      ...SmartAccountClientOptsSchema.parse(config.opts ?? {}),
-    }))
+    .extend(() => {
+      const addBreadCrumbs = addBreadCrumb
+        ? {
+            [ADD_BREADCRUMB]: addBreadCrumb,
+          }
+        : {};
+      return {
+        ...SmartAccountClientOptsSchema.parse(config.opts ?? {}),
+        ...addBreadCrumbs,
+      };
+    })
     .extend(middlewareActions(config))
     .extend(smartAccountClientActions);
 

package/src/index.ts

@@ -91,6 +91,7 @@ export {
   InvalidUserOperationError,
   WaitForUserOperationError,
 } from "./errors/useroperation.js";
+export * from "./client/addBreadcrumb.js";
 export { LogLevel, Logger } from "./logger.js";
 export { middlewareActions } from "./middleware/actions.js";
 export { default7702UserOpSigner } from "./middleware/defaults/7702signer.js";
@@ -114,6 +115,7 @@ export { WalletClientSigner } from "./signer/wallet-client.js";
 export { split, type SplitTransportParams } from "./transport/split.js";
 export type * from "./types.js";
 export type * from "./utils/index.js";
+export { TraceHeader } from "./utils/traceHeader.js";
 export {
   BigNumberishRangeSchema,
   BigNumberishSchema,

package/src/utils/traceHeader.ts

@@ -0,0 +1,133 @@
+function generateRandomHexString(numBytes: number) {
+  const bytes = crypto.getRandomValues(new Uint8Array(numBytes));
+  const array = Array.from(bytes);
+  const hexPairs = array.map((b) => b.toString(16).padStart(2, "0"));
+  return hexPairs.join("");
+}
+
+const clientTraceId = generateRandomHexString(16);
+/**
+ * Some tools that are useful when dealing with the values
+ * of the trace header. Follows the W3C trace context standard.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export class TraceHeader {
+  readonly traceId: string;
+  readonly parentId: string;
+  readonly traceFlags: string;
+  readonly traceState: Record<string, string>;
+
+  /**
+   * Initializes a new instance with the provided trace identifiers and state information.
+   *
+   * @param {string} traceId The unique identifier for the trace
+   * @param {string} parentId The identifier of the parent trace
+   * @param {string} traceFlags Flags containing trace-related options
+   * @param {TraceHeader["traceState"]} traceState The trace state information for additional trace context
+   */
+  constructor(
+    traceId: string,
+    parentId: string,
+    traceFlags: string,
+    traceState: TraceHeader["traceState"]
+  ) {
+    this.traceId = traceId;
+    this.parentId = parentId;
+    this.traceFlags = traceFlags;
+    this.traceState = traceState;
+  }
+
+  /**
+   * Creating a default trace id that is a random setup for both trace id and parent id
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+   * ```
+   *
+   * @returns {TraceHeader} A default trace header
+   */
+  static default() {
+    return new TraceHeader(
+      clientTraceId,
+      generateRandomHexString(8),
+      "00", //Means no flag have been set, and no sampled state https://www.w3.org/TR/trace-context/#trace-flags
+      {}
+    );
+  }
+  /**
+   * Should be able to consume a trace header from the headers of an http request
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers);
+   * ```
+   *
+   * @param {Record<string,string>} headers The headers from the http request
+   * @returns {TraceHeader | undefined} The trace header object, or nothing if not found
+   */
+  static fromTraceHeader(
+    headers: Record<string, string>
+  ): TraceHeader | undefined {
+    if (!headers["traceheader"]) {
+      return undefined;
+    }
+    const [version, traceId, parentId, traceFlags] =
+      headers["traceheader"]?.split("-");
+
+    const traceState =
+      headers["tracestate"]?.split(",").reduce((acc, curr) => {
+        const [key, value] = curr.split("=");
+        acc[key] = value;
+        return acc;
+      }, {} as Record<string, string>) || {};
+    if (version !== "00") {
+      console.debug(
+        new Error(`Invalid version for traceheader: ${headers["traceheader"]}`)
+      );
+      return undefined;
+    }
+    return new TraceHeader(traceId, parentId, traceFlags, traceState);
+  }
+
+  /**
+   * Should be able to convert the trace header to the format that is used in the headers of an http request
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+   * const headers = traceHeader.toTraceHeader();
+   * ```
+   *
+   * @returns {{stracheader: string, tracestate: string}} The trace header in the format of a record, used in our http client
+   */
+  toTraceHeader() {
+    return {
+      traceheader: `00-${this.traceId}-${this.parentId}-${this.traceFlags}`,
+      tracestate: Object.entries(this.traceState)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(","),
+    } as const;
+  }
+
+  /**
+   * Should be able to create a new trace header with a new event in the trace state,
+   *  as the key of the eventName as breadcrumbs appending onto previous breadcrumbs with the - infix if exists. And the
+   * trace parent gets updated as according to the docs
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+   * const newTraceHeader = traceHeader.withEvent("newEvent");
+   * ```
+   *
+   * @param {string} eventName The key of the new event
+   * @returns {TraceHeader} The new trace header
+   */
+  withEvent(eventName: string): TraceHeader {
+    const breadcrumbs = this.traceState.breadcrumbs
+      ? `${this.traceState.breadcrumbs}-${eventName}`
+      : eventName;
+    return new TraceHeader(this.traceId, this.parentId, this.traceFlags, {
+      ...this.traceState,
+      breadcrumbs,
+    });
+  }
+}