@hashspan/core 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,13 +1,13 @@
-import { Attributes, Context, TimeInput, TracerProvider } from "@opentelemetry/api";
+import { Attributes, Context, MeterProvider, TimeInput, TracerProvider } from "@opentelemetry/api";
 //#region src/types.d.ts
 /**
  * How wallet addresses are recorded. See
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0004-privacy-defaults.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0004-privacy-defaults.md.
  */
 type AddressMode = "raw" | "hashed" | "off";
 /**
  * How error messages are recorded on exception events and span status. See
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0006-error-privacy.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0006-error-privacy.md.
  * - `off`: error type only
  * - `sanitized`: first line, addresses per address mode, other long hex data removed
  * - `raw`: full message and stack trace, as thrown
@@ -43,6 +43,11 @@ interface AgentIdentity {
 interface TxTrackerOptions {
   /** Defaults to the globally registered tracer provider. */
   tracerProvider?: TracerProvider | undefined;
+  /**
+   * Meter provider for the send, confirmation and fee histograms. Defaults to the globally registered one, which
+   * records nothing until an OpenTelemetry metrics SDK is set up.
+   */
+  meterProvider?: MeterProvider | undefined;
   /** Address recording mode. Default: `raw`. */
   address?: AddressMode | AddressOptions | undefined;
   /**
@@ -61,7 +66,7 @@ interface TxTrackerOptions {
   /**
    * Agent identity. A field set here always wins; fields left unset are taken from the Baggage entries
    * `gen_ai.agent.id` / `gen_ai.agent.name` unless `agentFromBaggage` is false
-   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0011-agent-identity-precedence.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0011-agent-identity-precedence.md).
    */
   agent?: AgentIdentity | undefined;
   /**
@@ -75,13 +80,17 @@ interface TxTrackerOptions {
    * If it throws or returns something other than an attributes object, the tracker fails closed and records only
    * `blockchain.system`, `blockchain.chain.id`, `blockchain.operation.name`, `blockchain.tx.hash`,
    * `blockchain.tx.status`, `blockchain.tx.replacement.hash`, `blockchain.tx.replacement.reason`,
-   * `blockchain.payment.protocol`, `blockchain.payment.status`, `blockchain.payment.verified`, `error.type` and
-   * `exception.type`, and logs the failure via `diag`.
+   * `blockchain.payment.protocol`, `blockchain.payment.status`, `blockchain.payment.verified`,
+   * `blockchain.user_operation.hash`, `blockchain.user_operation.success`, `error.type` and `exception.type`, and logs
+   * the failure via `diag`.
    */
   redact?: ((attributes: Attributes) => Attributes) | undefined;
-  /** How long a sent transaction can be linked from its confirmation. Default: 10 minutes. */
+  /** How long a sent transaction or user operation can be linked from its confirmation. Default: 10 minutes. */
   linkTtlMs?: number | undefined;
-  /** Maximum number of sent transactions kept for linking. Default: 10 000. */
+  /**
+   * Maximum number of sent transactions kept for linking. Default: 10 000. User operations are kept separately, up to
+   * the same number.
+   */
   maxTrackedTransactions?: number | undefined;
 }
 interface SendInput {
@@ -103,7 +112,7 @@ interface SendInput {
   functionArguments?: readonly unknown[] | undefined;
   /**
    * When the send started, for adapters that record it after the fact
-   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0009-telemetry-off-the-call-path.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0009-telemetry-off-the-call-path.md).
    * Omit it otherwise: with an explicit start time, the SDK measures the span by the wall clock, so pass the end time
    * to the handle too.
    */
@@ -112,14 +121,14 @@ interface SendInput {
 /**
  * Ends a send span. Only the first call counts; methods never throw.
  * Produced by the tracker only; methods may be added in minor releases
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0014-core-api-boundary.md).
  */
 interface SendHandle {
   /**
    * The parent context with the send span set. Run the call that sends the transaction in it, e.g.
    * `await context.with(send.context, () => sendSomehow())`, so that spans of wallet, RPC or HTTP instrumentation
    * nest under the send span
-   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0015-send-span-as-active-context.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0015-send-span-as-active-context.md).
    * Run only that call in it: a confirm span started in it becomes a child of the send span.
    */
   readonly context: Context;
@@ -182,7 +191,7 @@ interface ReceiptLike {
   /**
    * Hash of the mined transaction. When it differs from the awaited hash, the awaited transaction was replaced: its
    * confirm span ends as `replaced` and the receipt is recorded for this hash
-   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0008-replaced-transactions.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0008-replaced-transactions.md).
    */
   transactionHash?: string | undefined;
   /** Replacement reason reported by the library, when {@link transactionHash} differs from the awaited hash. */
@@ -192,7 +201,7 @@ interface ReceiptLike {
  * One wait for a transaction's receipt, joined to the transaction's shared confirm span. Only the first call counts;
  * methods never throw.
  * Produced by the tracker only; methods may be added in minor releases
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0014-core-api-boundary.md).
  */
 interface ConfirmHandle {
   /** Ends the shared confirm span with the receipt, for every handle of the transaction. */
@@ -216,7 +225,7 @@ interface ConfirmHandle {
 }
 /**
  * A payment the agent authorizes and another party settles on chain, e.g. an x402 facilitator
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0013-x402-payments.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0013-x402-payments.md).
  * Values often come from a remote server: addresses, amounts and identifiers that are malformed are not recorded.
  */
 interface PaymentInput {
@@ -268,7 +277,7 @@ interface PaymentSettlement {
 /**
  * Ends a payment span. Only the first call counts; methods never throw.
  * Produced by the tracker only; methods may be added in minor releases
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0014-core-api-boundary.md).
  */
 interface PaymentHandle {
   /** Ends the payment span with its settlement. */
@@ -291,6 +300,107 @@ interface PaymentHandle {
    */
   link(hash: string): void;
 }
+/**
+ * A user operation of an ERC-4337 smart account, handed to a bundler
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0021-user-operations.md). It has no
+ * transaction of its own: the bundler includes it in a bundle transaction that the bundler sends.
+ */
+interface UserOperationInput {
+  /** EIP-155 chain id. */
+  chainId: number;
+  /** Address of the smart account, recorded as `blockchain.user_operation.sender` per the address mode. */
+  sender?: string | undefined;
+  /** Address of the EntryPoint contract, recorded as `blockchain.user_operation.entry_point` per the address mode. */
+  entryPoint?: string | undefined;
+  /** Number of calls the operation makes, recorded as `blockchain.user_operation.call_count`. */
+  callCount?: number | undefined;
+  /** When the send started, for adapters that record it after the fact; see {@link SendInput.startTime}. */
+  startTime?: TimeInput | undefined;
+}
+/** What handing a user operation to a bundler produced. */
+interface UserOperationResult {
+  /** Hash of the user operation, `0x`-prefixed 32 bytes, as the bundler returned it. */
+  userOpHash: string;
+}
+/**
+ * Ends the send span of a user operation. Only the first call counts; methods never throw.
+ * Produced by the tracker only; methods may be added in minor releases
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0014-core-api-boundary.md).
+ */
+interface UserOperationSendHandle {
+  /**
+   * The parent context with the send span set. Run the call that hands the operation to the bundler in it, as for
+   * {@link SendHandle.context}.
+   */
+  readonly context: Context;
+  /** Ends the send span successfully once the user operation hash is known. */
+  end(result: UserOperationResult, options?: EndOptions): void;
+  /** Ends the send span with an error (preparing, signing or handing the operation to the bundler failed). */
+  fail(error: unknown, options?: FailOptions): void;
+}
+interface UserOperationConfirmInput {
+  /** EIP-155 chain id; with `userOpHash`, it identifies the user operation and its confirm span. */
+  chainId: number;
+  /** Hash of the user operation awaited, `0x`-prefixed. */
+  userOpHash: string;
+  /** When the wait started, for adapters that record it after the fact; see {@link SendInput.startTime}. */
+  startTime?: TimeInput | undefined;
+}
+/**
+ * Library-agnostic view of a user operation receipt (ERC-4337 `eth_getUserOperationReceipt`, or the EntryPoint's
+ * `UserOperationEvent`). Every field is optional, since some SDKs report less; values usually come from a bundler,
+ * and malformed ones are not recorded.
+ */
+interface UserOperationReceiptLike {
+  /**
+   * Whether the operation's calls succeeded. `false` ends the confirm span with an error status and `error.type`
+   * `reverted`; the bundle transaction itself can still have succeeded.
+   */
+  success?: boolean | undefined;
+  /** What the operation paid, in wei (`actualGasCost`), recorded as `blockchain.user_operation.gas.cost`. */
+  actualGasCost?: bigint | string | undefined;
+  /** Gas the operation used (`actualGasUsed`), recorded as `blockchain.user_operation.gas.used`. */
+  actualGasUsed?: bigint | number | string | undefined;
+  /** Address of the smart account. */
+  sender?: string | undefined;
+  /**
+   * The operation's nonce, recorded as a decimal string: it holds a 192-bit key and a 64-bit sequence number. Bundlers
+   * return it as a hex string, which some libraries pass on unchanged.
+   */
+  nonce?: bigint | string | undefined;
+  /** Address of the paymaster that paid for the operation; the zero address means none. */
+  paymaster?: string | undefined;
+  /** Address of the EntryPoint contract. */
+  entryPoint?: string | undefined;
+  /** Decoded revert reason, recorded as `blockchain.tx.revert.reason` with addresses per the address mode. */
+  revertReason?: string | undefined;
+  /** Hash of the bundle transaction that included the operation, recorded as `blockchain.tx.hash`. */
+  transactionHash?: string | undefined;
+  /** Block of the bundle transaction. */
+  blockNumber?: bigint | number | undefined;
+}
+/**
+ * One wait for a user operation's receipt, joined to the operation's shared confirm span, as for transactions
+ * ({@link ConfirmHandle}). Only the first call counts; methods never throw.
+ * Produced by the tracker only; methods may be added in minor releases
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0014-core-api-boundary.md).
+ */
+interface UserOperationConfirmHandle {
+  /** Ends the shared confirm span with the receipt, for every handle of the user operation. */
+  end(receipt: UserOperationReceiptLike, options?: EndOptions): void;
+  /**
+   * Withdraws this handle because waiting for the receipt timed out. The confirm span ends as `timeout` only if no
+   * other handle of the user operation is still waiting.
+   */
+  timeout(options?: EndOptions): void;
+  /**
+   * Withdraws this handle because the operation failed or its receipt could not be retrieved. The confirm span ends
+   * as a failure only if no other handle is still waiting. Called without an error, as
+   * `fail(undefined, { errorType })`, it records no exception event: for an SDK that reports a failed operation
+   * without an error.
+   */
+  fail(error: unknown, options?: FailOptions): void;
+}
 //#endregion
 //#region src/agent.d.ts
 export declare const ATTR_GEN_AI_AGENT_ID: "gen_ai.agent.id";
@@ -300,7 +410,7 @@ export declare const ATTR_GEN_AI_AGENT_NAME: "gen_ai.agent.name";
 /**
  * Attribute keys emitted by hashspan.
  *
- * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/semconv.md for
+ * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/semconv.md for
  * definitions and value types. These names are a public contract: changes follow the deprecation policy in AGENTS.md.
  */
 export declare const ATTR_BLOCKCHAIN_SYSTEM: "blockchain.system";
@@ -324,12 +434,12 @@ export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME: "blockchain.contrac
 export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR: "blockchain.contract.function.selector";
 /**
  * Opt-in: decoded call arguments as a JSON array. See
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0004-privacy-defaults.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0004-privacy-defaults.md.
  */
 export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS: "blockchain.contract.function.arguments";
 /**
  * Payments settled on chain by a party other than the agent, e.g. an x402 facilitator. See
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0013-x402-payments.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0013-x402-payments.md.
  */
 export declare const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL: "blockchain.payment.protocol";
 export declare const ATTR_BLOCKCHAIN_PAYMENT_PAYER: "blockchain.payment.payer";
@@ -342,12 +452,33 @@ export declare const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT: "blockchain.payment
 /**
  * Whether the settlement transaction's receipt carries the payment, as checked by the adapter; absent when no check
  * was possible. See
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0017-x402-payment-verification.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0017-x402-payment-verification.md.
  */
 export declare const ATTR_BLOCKCHAIN_PAYMENT_VERIFIED: "blockchain.payment.verified";
 /** x402's own payment fields. */
 export declare const ATTR_X402_SCHEME: "x402.scheme";
 export declare const ATTR_X402_RESOURCE: "x402.resource";
+/**
+ * User operations of ERC-4337 smart accounts. See
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0021-user-operations.md.
+ */
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_HASH: "blockchain.user_operation.hash";
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_SENDER: "blockchain.user_operation.sender";
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_ENTRY_POINT: "blockchain.user_operation.entry_point";
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_CALL_COUNT: "blockchain.user_operation.call_count";
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_NONCE: "blockchain.user_operation.nonce";
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_SUCCESS: "blockchain.user_operation.success";
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_GAS_USED: "blockchain.user_operation.gas.used";
+/** What the operation itself paid, in wei; the bundle transaction's fee covers every operation in the bundle. */
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_GAS_COST: "blockchain.user_operation.gas.cost";
+export declare const ATTR_BLOCKCHAIN_USER_OPERATION_PAYMASTER: "blockchain.user_operation.paymaster";
+/**
+ * Metrics only: what a send, confirmation or fee sample is about. Recorded as `user_operation` on samples of user
+ * operations, and absent on those of transactions.
+ */
+export declare const ATTR_BLOCKCHAIN_OPERATION_SUBJECT: "blockchain.operation.subject";
+/** Values for {@link ATTR_BLOCKCHAIN_OPERATION_SUBJECT}. */
+export declare const BLOCKCHAIN_OPERATION_SUBJECT_VALUE_USER_OPERATION: "user_operation";
 /** Values for {@link ATTR_BLOCKCHAIN_SYSTEM}. */
 export declare const BLOCKCHAIN_SYSTEM_VALUE_EVM: "evm";
 /** Values for {@link ATTR_BLOCKCHAIN_OPERATION_NAME}. */
@@ -366,7 +497,7 @@ export declare const BLOCKCHAIN_TX_STATUS_VALUE_REVERTED: "reverted";
 /**
  * @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
  * `blockchain.tx.status`. The constant is removed in 1.0. See
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
  */
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT: "timeout";
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED: "replaced";
@@ -379,11 +510,28 @@ export declare const ATTR_ERROR_TYPE: "error.type";
 /** Fallback {@link ATTR_ERROR_TYPE} value when the error has no name. */
 export declare const ERROR_TYPE_VALUE_OTHER: "_OTHER";
 //#endregion
+//#region src/metrics.d.ts
+/**
+ * Duration of a send of a transaction or user operation: from the start of the sending call until the hash is known or
+ * the call failed.
+ */
+export declare const METRIC_BLOCKCHAIN_CLIENT_SEND_DURATION: "blockchain.client.send.duration";
+/**
+ * Duration of a confirmation of a transaction or user operation: from the start of the wait until the receipt, a
+ * timeout or a failure.
+ */
+export declare const METRIC_BLOCKCHAIN_CLIENT_CONFIRMATION_DURATION: "blockchain.client.confirmation.duration";
+/**
+ * Total fee of a mined transaction (execution fee plus L1 data fee), or the cost of a user operation, in the chain's
+ * smallest unit (wei).
+ */
+export declare const METRIC_BLOCKCHAIN_CLIENT_FEE: "blockchain.client.fee";
+//#endregion
 //#region src/tracker.d.ts
 /**
- * Records transactions and payments as spans. Obtain one from {@link createTxTracker}: it is not meant to be
+ * Records transactions, payments and user operations as spans. Obtain one from {@link createTxTracker}: it is not meant to be
  * implemented, and members may be added to it and to its handles in minor releases
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0014-core-api-boundary.md).
  */
 interface TxTracker {
   /**
@@ -401,15 +549,28 @@ interface TxTracker {
   /**
    * Starts a `payment` span as a child of `parent` (default: the active context), for a payment that another party
    * settles on chain
-   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0013-x402-payments.md). Call
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0013-x402-payments.md). Call
    * `end(settlement)` with the settlement, or `fail(error)`. A settlement with a hash links the transaction's confirm
    * span to this span, as a send span would.
    */
   startPayment(input: PaymentInput, parent?: Context): PaymentHandle;
+  /**
+   * Starts a `send` span for a user operation of a smart account as a child of `parent` (default: the active context)
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/adr/0021-user-operations.md). Call
+   * `end({ userOpHash })` once the bundler returned the operation's hash, or `fail(error)`.
+   */
+  startUserOperationSend(input: UserOperationInput, parent?: Context): UserOperationSendHandle;
+  /**
+   * Joins the `confirm` span of a user operation, starting it for the first caller; linked to its `send` span when
+   * known. As for {@link TxTracker.startConfirm}, calls for the same chain id and user operation hash share one span,
+   * apart from those of transactions. Returns a no-op handle for an operation that recently got a receipt. Every
+   * returned handle must be ended.
+   */
+  startUserOperationConfirm(input: UserOperationConfirmInput, parent?: Context): UserOperationConfirmHandle;
 }
 /**
  * Creates a tracker that records transactions as `send` and `confirm` spans, and payments as `payment` spans, with
- * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/semconv.md). It makes
+ * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.8.0/docs/semconv.md). It makes
  * no network calls; the caller passes hashes and receipts. Its methods and handles never throw: failures are logged
  * via `diag`, and a method that fails returns a handle that records nothing.
  */
@@ -418,4 +579,4 @@ export declare function createTxTracker(options?: TxTrackerOptions): TxTracker;
 //#region src/version.d.ts
 export declare const VERSION: string;
 //#endregion
-export type { AddressMode, AddressOptions, AgentIdentity, ConfirmHandle, ConfirmInput, EndOptions, ErrorMessageMode, FailOptions, PaymentHandle, PaymentInput, PaymentResourceMode, PaymentSettlement, PaymentStatus, ReceiptLike, ReplacementReason, SendHandle, SendInput, SendResult, TxTracker, TxTrackerOptions, X402PaymentDetails };
+export type { AddressMode, AddressOptions, AgentIdentity, ConfirmHandle, ConfirmInput, EndOptions, ErrorMessageMode, FailOptions, PaymentHandle, PaymentInput, PaymentResourceMode, PaymentSettlement, PaymentStatus, ReceiptLike, ReplacementReason, SendHandle, SendInput, SendResult, TxTracker, TxTrackerOptions, UserOperationConfirmHandle, UserOperationConfirmInput, UserOperationInput, UserOperationReceiptLike, UserOperationResult, UserOperationSendHandle, X402PaymentDetails };