@hashspan/core 0.6.0 → 0.8.0

package/dist/index.mjs

@@ -1,11 +1,11 @@
-import { SpanKind, SpanStatusCode, context, diag, propagation, trace } from "@opentelemetry/api";
+import { SpanKind, SpanStatusCode, context, diag, metrics, propagation, trace } from "@opentelemetry/api";
 //#region src/agent.ts
 const ATTR_GEN_AI_AGENT_ID = "gen_ai.agent.id";
 const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
 /**
 * Agent identity as GenAI attributes. A field set in the static identity always wins; Baggage, which a remote caller
 * can set, only fills fields it leaves unset, and is not read at all with `fromBaggage` 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).
 */
 function agentAttributes(ctx, identity, fromBaggage = true) {
 	const baggage = fromBaggage ? propagation.getBaggage(ctx) : void 0;
@@ -21,7 +21,7 @@ function agentAttributes(ctx, identity, fromBaggage = true) {
 /**
 * 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.
 */
 const ATTR_BLOCKCHAIN_SYSTEM = "blockchain.system";
@@ -45,12 +45,12 @@ const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME = "blockchain.contract.function.nam
 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.
 */
 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.
 */
 const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = "blockchain.payment.protocol";
 const ATTR_BLOCKCHAIN_PAYMENT_PAYER = "blockchain.payment.payer";
@@ -63,12 +63,33 @@ const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT = "blockchain.payment.settled_amoun
 /**
 * 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.
 */
 const ATTR_BLOCKCHAIN_PAYMENT_VERIFIED = "blockchain.payment.verified";
 /** x402's own payment fields. */
 const ATTR_X402_SCHEME = "x402.scheme";
 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.
+*/
+const ATTR_BLOCKCHAIN_USER_OPERATION_HASH = "blockchain.user_operation.hash";
+const ATTR_BLOCKCHAIN_USER_OPERATION_SENDER = "blockchain.user_operation.sender";
+const ATTR_BLOCKCHAIN_USER_OPERATION_ENTRY_POINT = "blockchain.user_operation.entry_point";
+const ATTR_BLOCKCHAIN_USER_OPERATION_CALL_COUNT = "blockchain.user_operation.call_count";
+const ATTR_BLOCKCHAIN_USER_OPERATION_NONCE = "blockchain.user_operation.nonce";
+const ATTR_BLOCKCHAIN_USER_OPERATION_SUCCESS = "blockchain.user_operation.success";
+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. */
+const ATTR_BLOCKCHAIN_USER_OPERATION_GAS_COST = "blockchain.user_operation.gas.cost";
+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.
+*/
+const ATTR_BLOCKCHAIN_OPERATION_SUBJECT = "blockchain.operation.subject";
+/** Values for {@link ATTR_BLOCKCHAIN_OPERATION_SUBJECT}. */
+const BLOCKCHAIN_OPERATION_SUBJECT_VALUE_USER_OPERATION = "user_operation";
 /** Values for {@link ATTR_BLOCKCHAIN_SYSTEM}. */
 const BLOCKCHAIN_SYSTEM_VALUE_EVM = "evm";
 /** Values for {@link ATTR_BLOCKCHAIN_OPERATION_NAME}. */
@@ -87,7 +108,7 @@ 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.
 */
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -100,6 +121,107 @@ const ATTR_ERROR_TYPE = "error.type";
 /** Fallback {@link ATTR_ERROR_TYPE} value when the error has no name. */
 const ERROR_TYPE_VALUE_OTHER = "_OTHER";
 //#endregion
+//#region src/metrics.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.
+*/
+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.
+*/
+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).
+*/
+const METRIC_BLOCKCHAIN_CLIENT_FEE = "blockchain.client.fee";
+const DURATION_BUCKETS = [
+	.05,
+	.1,
+	.25,
+	.5,
+	1,
+	2,
+	5,
+	10,
+	20,
+	30,
+	60,
+	120,
+	300
+];
+const FEE_BUCKETS = Array.from({ length: 11 }, (_, i) => 10 ** (i + 8));
+const ERROR_CLASS = /^[A-Z][A-Za-z]{0,62}Error$|^Error$/;
+const ERROR_CODE = /^[a-z]{1,32}(_[a-z]{1,32}){0,7}$/;
+/**
+* `attributes` with `error.type` kept only if it is an error class name or a lower-case code, else `_OTHER`. Error
+* names are free text (any `Error.name`), and metrics do not pass through the `redact` hook; the span keeps its own
+* `error.type`.
+*/
+function withMetricErrorType(attributes) {
+	const type = attributes[ATTR_ERROR_TYPE];
+	if (type === void 0) return attributes;
+	return typeof type === "string" && (type === "_OTHER" || ERROR_CLASS.test(type) || ERROR_CODE.test(type)) ? attributes : {
+		...attributes,
+		[ATTR_ERROR_TYPE]: ERROR_TYPE_VALUE_OTHER
+	};
+}
+/** Milliseconds since the epoch of a span time, as the OpenTelemetry API accepts it. */
+function toEpochMs(time) {
+	if (time === void 0) return Date.now();
+	if (time instanceof Date) return time.getTime();
+	if (Array.isArray(time)) return time[0] * 1e3 + time[1] / 1e6;
+	if (typeof time !== "number") return Date.now();
+	const origin = globalThis.performance?.timeOrigin;
+	return typeof origin === "number" && time < origin ? origin + time : time;
+}
+function createTxMetrics(meterProvider, name, version) {
+	let histograms;
+	const get = () => {
+		histograms ??= (() => {
+			const meter = (meterProvider ?? metrics.getMeterProvider()).getMeter(name, version);
+			return {
+				send: meter.createHistogram(METRIC_BLOCKCHAIN_CLIENT_SEND_DURATION, {
+					unit: "s",
+					description: "Duration of sending a transaction or user operation, until its hash is known",
+					advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+				}),
+				confirmation: meter.createHistogram(METRIC_BLOCKCHAIN_CLIENT_CONFIRMATION_DURATION, {
+					unit: "s",
+					description: "Duration of waiting for a transaction or user operation receipt",
+					advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+				}),
+				fee: meter.createHistogram(METRIC_BLOCKCHAIN_CLIENT_FEE, {
+					unit: "{wei}",
+					description: "Total fee of a mined transaction, or the cost of a user operation",
+					advice: { explicitBucketBoundaries: FEE_BUCKETS }
+				})
+			};
+		})();
+		return histograms;
+	};
+	const record = (what, run) => {
+		try {
+			run();
+		} catch (error) {
+			diag.error(`hashspan: failed to record the ${what} metric`, error);
+		}
+	};
+	return {
+		sendDuration: (seconds, attributes) => record("send duration", () => {
+			if (seconds >= 0) get().send.record(seconds, withMetricErrorType(attributes));
+		}),
+		confirmationDuration: (seconds, attributes) => record("confirmation duration", () => {
+			if (seconds >= 0) get().confirmation.record(seconds, withMetricErrorType(attributes));
+		}),
+		fee: (wei, attributes) => record("fee", () => {
+			if (wei >= 0n) get().fee.record(Number(wei), attributes);
+		})
+	};
+}
+//#endregion
 //#region src/confirm-registry.ts
 /**
 * Bounded registry from (chainId, tx hash) to its in-flight confirm span, or to "settled" for a while after a
@@ -385,7 +507,7 @@ function sanitizeResource(resource) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.6.0";
+const VERSION = "0.8.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -408,13 +530,20 @@ const NON_SENSITIVE_KEYS = /* @__PURE__ */ new Set([
 	ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL,
 	ATTR_BLOCKCHAIN_PAYMENT_STATUS,
 	ATTR_BLOCKCHAIN_PAYMENT_VERIFIED,
+	ATTR_BLOCKCHAIN_USER_OPERATION_HASH,
+	ATTR_BLOCKCHAIN_USER_OPERATION_SUCCESS,
 	ATTR_ERROR_TYPE,
 	ATTR_EXCEPTION_TYPE
 ]);
 const TX_HASH = /^0x[0-9a-fA-F]{64}$/;
 const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const ZERO_ADDRESS = /^0x0{40}$/;
 /** A non-negative integer that fits in 256 bits. */
 const AMOUNT = /^(0|[1-9][0-9]{0,77})$/;
+/** A `0x` hex quantity of at most 256 bits, as JSON-RPC encodes integers. */
+const HEX_QUANTITY = /^0x[0-9a-fA-F]{1,64}$/;
+const MAX_UINT256 = 2n ** 256n - 1n;
+const MAX_SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
 /** `error.type` of a wait that gave up: a confirmation or a payment whose outcome was never learned. */
 const OBSERVER_TIMEOUT = "timeout";
 const PAYMENT_STATUSES = /* @__PURE__ */ new Set([
@@ -433,6 +562,11 @@ const noopSend = (parent) => ({
 	end: () => {},
 	fail: () => {}
 });
+const noopUserOperationSend = (parent) => ({
+	context: parent,
+	end: () => {},
+	fail: () => {}
+});
 const NOOP_PAYMENT = {
 	end: () => {},
 	fail: () => {},
@@ -444,6 +578,11 @@ const NOOP_CONFIRM = {
 	timeout: () => {},
 	fail: () => {}
 };
+const NOOP_USER_OPERATION_CONFIRM = {
+	end: () => {},
+	timeout: () => {},
+	fail: () => {}
+};
 /** Runs `fn`, logging instead of throwing: instrumentation must never break the caller. */
 function safely(what, fn, fallback) {
 	try {
@@ -466,6 +605,22 @@ const ERROR_TYPE_OVERRIDE = /^[A-Za-z0-9_.-]{1,64}$/;
 function identifier(value) {
 	return typeof value === "string" && ERROR_TYPE_OVERRIDE.test(value) ? value : void 0;
 }
+/**
+* A non-negative integer of at most 256 bits, from a bigint, a safe integer, or a decimal or `0x` hex string, as
+* bundlers return them; undefined for anything else.
+*/
+function quantity(value) {
+	let parsed;
+	if (typeof value === "bigint") parsed = value;
+	else if (typeof value === "number" && Number.isSafeInteger(value)) parsed = BigInt(value);
+	else if (typeof value === "string" && (AMOUNT.test(value) || HEX_QUANTITY.test(value))) parsed = BigInt(value);
+	return parsed !== void 0 && parsed >= 0n && parsed <= MAX_UINT256 ? parsed : void 0;
+}
+/** A quantity as a number, or undefined when it is none or too large to be one exactly. */
+function smallQuantity(value) {
+	const parsed = quantity(value);
+	return parsed !== void 0 && parsed <= MAX_SAFE_INTEGER ? Number(parsed) : void 0;
+}
 /** A decimal amount, or undefined when `value` is not a non-negative integer. */
 function amount(value) {
 	const text = typeof value === "bigint" ? value.toString() : value;
@@ -511,8 +666,44 @@ function reportedErrorType(error, options) {
 	return errorType(error);
 }
 /**
+* Joins the confirm span for `hash` in `registry`, opening it with `open` for the first handle; undefined when the
+* key recently got a receipt. A receipt from any handle ends the span; a timeout or failure only ends it when it is the
+* last handle still waiting.
+*/
+function joinConfirm(registry, chainId, hash, open) {
+	const current = registry.get(chainId, hash);
+	if (current === "settled") return void 0;
+	let confirm = current;
+	if (!confirm) {
+		confirm = open();
+		registry.start(chainId, hash, confirm);
+	}
+	const shared = confirm;
+	shared.active += 1;
+	let done = false;
+	return {
+		shared,
+		receive: () => {
+			if (done || shared.ended) return false;
+			done = true;
+			shared.active -= 1;
+			shared.ended = true;
+			return true;
+		},
+		withdraw: (end) => {
+			if (done || shared.ended) return;
+			done = true;
+			shared.active -= 1;
+			if (shared.active > 0) return;
+			shared.ended = true;
+			registry.release(chainId, hash, shared);
+			end();
+		}
+	};
+}
+/**
 * 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.
 */
@@ -528,6 +719,27 @@ function createTxTracker(options = {}) {
 	const formatAddress = safely("configure address mode", () => resolveAddressFormatter(options.address), OFF_ADDRESS_FORMATTER);
 	const errorMessages = safely("configure error message mode", () => resolveErrorMessageMode(options.errorMessages), "off");
 	const paymentResource = safely("configure payment resource mode", () => resolvePaymentResourceMode(options.paymentResource), "off");
+	const userOperationLinks = new LinkStore({
+		ttlMs: options.linkTtlMs ?? DEFAULT_LINK_TTL_MS,
+		maxEntries: options.maxTrackedTransactions ?? DEFAULT_MAX_TRACKED
+	});
+	const userOperationConfirmations = new ConfirmRegistry({
+		ttlMs: options.linkTtlMs ?? DEFAULT_LINK_TTL_MS,
+		maxEntries: options.maxTrackedTransactions ?? DEFAULT_MAX_TRACKED
+	});
+	const txMetrics = createTxMetrics(options.meterProvider, INSTRUMENTATION_NAME, VERSION);
+	/** Attributes of a metric: low-cardinality only, never an address, hash or agent identity. */
+	const metricAttributes = (chainId, extra = {}) => ({
+		[ATTR_BLOCKCHAIN_SYSTEM]: "evm",
+		[ATTR_BLOCKCHAIN_CHAIN_ID]: chainId,
+		...extra
+	});
+	/** Metric attributes of a user operation sample: as for transactions, plus what the sample is about. */
+	const userOperationMetricAttributes = (chainId, extra = {}) => metricAttributes(chainId, {
+		[ATTR_BLOCKCHAIN_OPERATION_SUBJECT]: BLOCKCHAIN_OPERATION_SUBJECT_VALUE_USER_OPERATION,
+		...extra
+	});
+	const secondsSince = (startMs, endTime) => (toEpochMs(endTime) - startMs) / 1e3;
 	let tracer;
 	const getTracer = () => {
 		tracer ??= (options.tracerProvider ?? trace.getTracerProvider()).getTracer(INSTRUMENTATION_NAME, VERSION);
@@ -552,7 +764,7 @@ function createTxTracker(options = {}) {
 	/**
 	* Exception event attributes for `error`, per the error message mode. The error object itself is never handed to
 	* the SDK: its message and stack can carry addresses and calldata
-	* (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).
 	*/
 	const exceptionAttributes = (type, error) => {
 		const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -585,6 +797,7 @@ function createTxTracker(options = {}) {
 			code: SpanStatusCode.ERROR,
 			...message !== void 0 ? { message } : {}
 		});
+		return type;
 	};
 	/** Ends a span exactly once; the span is always ended even if recording attributes fails. */
 	const finisher = (span) => {
@@ -606,8 +819,8 @@ function createTxTracker(options = {}) {
 		const formatted = formatAddress(address);
 		if (formatted !== void 0) attributes[key] = formatted;
 	};
-	/** Records `address` only if it is one: payment addresses come from remote parties. */
-	const setPaymentAddress = (attributes, key, address) => {
+	/** Records `address` only if it is one: payment and user operation addresses come from remote parties. */
+	const setRemoteAddress = (attributes, key, address) => {
 		if (typeof address === "string" && ADDRESS.test(address)) setAddress(attributes, key, address);
 	};
 	const baseAttributes = (chainId, operation, ctx) => ({
@@ -636,6 +849,8 @@ function createTxTracker(options = {}) {
 			...input.startTime !== void 0 ? { startTime: input.startTime } : {}
 		}, parent);
 		const finish = finisher(span);
+		const startMs = toEpochMs(input.startTime);
+		const recordSend = (endTime, errorType) => txMetrics.sendDuration(secondsSince(startMs, endTime), metricAttributes(input.chainId, errorType === void 0 ? {} : { [ATTR_ERROR_TYPE]: errorType }));
 		return {
 			context: trace.setSpan(parent, span),
 			end: (result, second) => finish("record transaction hash", () => {
@@ -649,10 +864,11 @@ function createTxTracker(options = {}) {
 					parent
 				});
 				span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_HASH]: hash }));
+				recordSend(handleOptions(second).endTime);
 			}, handleOptions(second).endTime),
 			fail: (error, second, third) => {
 				const options = handleOptions(second, third);
-				finish("record send failure", () => markError(span, reportedErrorType(error, options), error, errorType(error)), options.endTime);
+				finish("record send failure", () => recordSend(options.endTime, markError(span, reportedErrorType(error, options), error, errorType(error))), options.endTime);
 			}
 		};
 	};
@@ -688,6 +904,8 @@ function createTxTracker(options = {}) {
 			...explicitStart !== void 0 ? { startTime: explicitStart } : {}
 		}, parent);
 		const finish = finisher(span);
+		const startMs = toEpochMs(explicitStart);
+		const recordConfirmation = (endTime, outcome) => txMetrics.confirmationDuration(secondsSince(startMs, endTime), metricAttributes(input.chainId, outcome));
 		return {
 			active: 0,
 			ended: false,
@@ -697,11 +915,16 @@ function createTxTracker(options = {}) {
 				links: [{ context: span.spanContext() }, ...sent ? [{ context: sent.spanContext }] : []]
 			},
 			receipt: (receipt, endTime) => finish("record receipt", () => {
-				span.setAttributes(redact(receiptAttributes(receipt)));
+				const attributes = receiptAttributes(receipt);
+				span.setAttributes(redact(attributes));
 				if (receipt.status === "reverted") markError(span, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED);
+				const status = { [ATTR_BLOCKCHAIN_TX_STATUS]: attributes[ATTR_BLOCKCHAIN_TX_STATUS] };
+				recordConfirmation(endTime, status);
+				const fee = attributes[ATTR_BLOCKCHAIN_TX_FEE];
+				if (typeof fee === "string") txMetrics.fee(BigInt(fee), metricAttributes(input.chainId, status));
 			}, endTime),
-			timeout: (endTime) => finish("record confirmation timeout", () => markError(span, OBSERVER_TIMEOUT), endTime),
-			fail: (error, endTime) => finish("record confirmation failure", () => markError(span, errorType(error), error), endTime),
+			timeout: (endTime) => finish("record confirmation timeout", () => recordConfirmation(endTime, { [ATTR_ERROR_TYPE]: markError(span, OBSERVER_TIMEOUT) }), endTime),
+			fail: (error, endTime) => finish("record confirmation failure", () => recordConfirmation(endTime, { [ATTR_ERROR_TYPE]: markError(span, errorType(error), error) }), endTime),
 			replaced: (hash, reason, endTime) => finish("record replacement", () => {
 				const attributes = {
 					[ATTR_BLOCKCHAIN_TX_STATUS]: BLOCKCHAIN_TX_STATUS_VALUE_REPLACED,
@@ -709,8 +932,9 @@ function createTxTracker(options = {}) {
 				};
 				if (reason !== void 0 && REPLACEMENT_REASONS.has(reason)) attributes[ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON] = reason;
 				span.setAttributes(redact(attributes));
+				recordConfirmation(endTime, { [ATTR_BLOCKCHAIN_TX_STATUS]: BLOCKCHAIN_TX_STATUS_VALUE_REPLACED });
 			}, endTime),
-			unattributable: (endTime) => finish("record unattributable receipt", () => markError(span, ERROR_TYPE_VALUE_OTHER), endTime)
+			unattributable: (endTime) => finish("record unattributable receipt", () => recordConfirmation(endTime, { [ATTR_ERROR_TYPE]: markError(span, ERROR_TYPE_VALUE_OTHER) }), endTime)
 		};
 	};
 	/**
@@ -732,7 +956,7 @@ function createTxTracker(options = {}) {
 	};
 	/**
 	* Ends `shared` with `receipt`, attributing it to the transaction that was mined
-	* (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).
 	*/
 	const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
 		const mined = receipt.transactionHash;
@@ -762,41 +986,22 @@ function createTxTracker(options = {}) {
 	*/
 	const startConfirm = (input, parentCtx) => {
 		const { chainId, hash } = input;
-		const current = confirmations.get(chainId, hash);
-		if (current === "settled") return NOOP_CONFIRM;
-		let confirm = current;
-		if (!confirm) {
-			confirm = openConfirm(input, parentCtx);
-			confirmations.start(chainId, hash, confirm);
-		}
-		const shared = confirm;
-		shared.active += 1;
-		let done = false;
-		const withdraw = (end) => {
-			if (done || shared.ended) return;
-			done = true;
-			shared.active -= 1;
-			if (shared.active > 0) return;
-			shared.ended = true;
-			confirmations.release(chainId, hash, shared);
-			end();
-		};
+		const claim = joinConfirm(confirmations, chainId, hash, () => openConfirm(input, parentCtx));
+		if (!claim) return NOOP_CONFIRM;
+		const { shared } = claim;
 		return {
 			end: (receipt, second) => {
 				const { endTime } = handleOptions(second);
-				if (done || shared.ended) return;
-				done = true;
-				shared.active -= 1;
-				shared.ended = true;
+				if (!claim.receive()) return;
 				safely("record receipt", () => endWithReceipt(chainId, hash, shared, receipt, endTime), void 0);
 			},
 			timeout: (second) => {
 				const { endTime } = handleOptions(second);
-				withdraw(() => shared.timeout(endTime));
+				claim.withdraw(() => shared.timeout(endTime));
 			},
 			fail: (error, second) => {
 				const { endTime } = handleOptions(second);
-				withdraw(() => shared.fail(error, endTime));
+				claim.withdraw(() => shared.fail(error, endTime));
 			}
 		};
 	};
@@ -805,10 +1010,10 @@ function createTxTracker(options = {}) {
 		const attributes = baseAttributes(input.chainId, BLOCKCHAIN_OPERATION_NAME_VALUE_PAYMENT, parent);
 		const protocol = identifier(input.protocol);
 		if (protocol !== void 0) attributes[ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL] = protocol;
-		setPaymentAddress(attributes, ATTR_BLOCKCHAIN_PAYMENT_PAYER, input.payer);
+		setRemoteAddress(attributes, ATTR_BLOCKCHAIN_PAYMENT_PAYER, input.payer);
 		const knownPayer = typeof input.payer === "string" && ADDRESS.test(input.payer);
-		setPaymentAddress(attributes, ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT, input.recipient);
-		setPaymentAddress(attributes, ATTR_BLOCKCHAIN_PAYMENT_ASSET, input.asset);
+		setRemoteAddress(attributes, ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT, input.recipient);
+		setRemoteAddress(attributes, ATTR_BLOCKCHAIN_PAYMENT_ASSET, input.asset);
 		const paid = amount(input.amount);
 		if (paid !== void 0) attributes[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = paid;
 		const scheme = identifier(input.x402?.scheme);
@@ -840,7 +1045,7 @@ function createTxTracker(options = {}) {
 			const settled = { [ATTR_BLOCKCHAIN_PAYMENT_STATUS]: status };
 			const hash = settlement.hash;
 			if (linkHash(hash)) settled[ATTR_BLOCKCHAIN_TX_HASH] = hash;
-			if (!knownPayer) setPaymentAddress(settled, ATTR_BLOCKCHAIN_PAYMENT_PAYER, settlement.payer);
+			if (!knownPayer) setRemoteAddress(settled, ATTR_BLOCKCHAIN_PAYMENT_PAYER, settlement.payer);
 			const settledAmount = amount(settlement.amount);
 			if (settledAmount !== void 0) {
 				settled[ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT] = settledAmount;
@@ -861,11 +1066,139 @@ function createTxTracker(options = {}) {
 			link: (hash) => safely("link the payment span", () => void linkHash(hash), void 0)
 		};
 	};
+	const startUserOperationSend = (input, parentCtx) => {
+		const parent = parentCtx ?? context.active();
+		const { chainId } = input;
+		const attributes = baseAttributes(chainId, BLOCKCHAIN_OPERATION_NAME_VALUE_SEND, parent);
+		setRemoteAddress(attributes, ATTR_BLOCKCHAIN_USER_OPERATION_SENDER, input.sender);
+		setRemoteAddress(attributes, ATTR_BLOCKCHAIN_USER_OPERATION_ENTRY_POINT, input.entryPoint);
+		const callCount = smallQuantity(input.callCount);
+		if (callCount !== void 0) attributes[ATTR_BLOCKCHAIN_USER_OPERATION_CALL_COUNT] = callCount;
+		const span = getTracer().startSpan(`send ${chainId}`, {
+			kind: SpanKind.CLIENT,
+			attributes: redact(attributes),
+			...input.startTime !== void 0 ? { startTime: input.startTime } : {}
+		}, parent);
+		const finish = finisher(span);
+		const startMs = toEpochMs(input.startTime);
+		const recordSend = (endTime, errorType) => txMetrics.sendDuration(secondsSince(startMs, endTime), userOperationMetricAttributes(chainId, errorType === void 0 ? {} : { [ATTR_ERROR_TYPE]: errorType }));
+		return {
+			context: trace.setSpan(parent, span),
+			end: (result, second) => {
+				const { endTime } = handleOptions(second);
+				finish("record user operation hash", () => {
+					const hash = result?.userOpHash;
+					if (typeof hash !== "string" || !TX_HASH.test(hash)) {
+						diag.debug("hashspan: ending a send span without a valid user operation hash");
+						return;
+					}
+					userOperationLinks.set(chainId, hash, {
+						spanContext: span.spanContext(),
+						parent
+					});
+					span.setAttributes(redact({ [ATTR_BLOCKCHAIN_USER_OPERATION_HASH]: hash }));
+					recordSend(endTime);
+				}, endTime);
+			},
+			fail: (error, second) => {
+				const read = handleOptions(second);
+				finish("record user operation send failure", () => recordSend(read.endTime, markError(span, reportedErrorType(error, read), error, errorType(error))), read.endTime);
+			}
+		};
+	};
+	/**
+	* Attributes of a user operation receipt. Its values come from a bundler: what is malformed is left out. The bundle
+	* transaction's status, gas and fee are not recorded: they cover every operation in the bundle (ADR 0021).
+	*/
+	const userOperationReceiptAttributes = (receipt) => {
+		const attributes = {};
+		const success = receipt.success;
+		if (typeof success === "boolean") attributes[ATTR_BLOCKCHAIN_USER_OPERATION_SUCCESS] = success;
+		const gasUsed = smallQuantity(receipt.actualGasUsed);
+		if (gasUsed !== void 0) attributes[ATTR_BLOCKCHAIN_USER_OPERATION_GAS_USED] = gasUsed;
+		const gasCost = quantity(receipt.actualGasCost);
+		if (gasCost !== void 0) attributes[ATTR_BLOCKCHAIN_USER_OPERATION_GAS_COST] = gasCost.toString();
+		setRemoteAddress(attributes, ATTR_BLOCKCHAIN_USER_OPERATION_SENDER, receipt.sender);
+		const nonce = quantity(receipt.nonce);
+		if (nonce !== void 0) attributes[ATTR_BLOCKCHAIN_USER_OPERATION_NONCE] = nonce.toString();
+		const paymaster = receipt.paymaster;
+		if (typeof paymaster === "string" && !ZERO_ADDRESS.test(paymaster)) setRemoteAddress(attributes, ATTR_BLOCKCHAIN_USER_OPERATION_PAYMASTER, paymaster);
+		setRemoteAddress(attributes, ATTR_BLOCKCHAIN_USER_OPERATION_ENTRY_POINT, receipt.entryPoint);
+		const reason = receipt.revertReason;
+		if (typeof reason === "string") attributes[ATTR_BLOCKCHAIN_TX_REVERT_REASON] = formatAddressesIn(reason, formatAddress);
+		const bundle = receipt.transactionHash;
+		if (typeof bundle === "string" && TX_HASH.test(bundle)) attributes[ATTR_BLOCKCHAIN_TX_HASH] = bundle;
+		const block = smallQuantity(receipt.blockNumber);
+		if (block !== void 0) attributes[ATTR_BLOCKCHAIN_BLOCK_NUMBER] = block;
+		return attributes;
+	};
+	/** Opens the confirm span of a user operation. */
+	const openUserOperationConfirm = (input, parentCtx) => {
+		const { chainId, userOpHash } = input;
+		const sent = userOperationLinks.get(chainId, userOpHash);
+		const active = context.active();
+		const parent = parentCtx ?? (trace.getSpan(active) ? active : sent?.parent ?? active);
+		const attributes = baseAttributes(chainId, BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM, parent);
+		attributes[ATTR_BLOCKCHAIN_USER_OPERATION_HASH] = userOpHash;
+		const span = getTracer().startSpan(`confirm ${chainId}`, {
+			kind: SpanKind.CLIENT,
+			attributes: redact(attributes),
+			links: sent ? [{ context: sent.spanContext }] : [],
+			...input.startTime !== void 0 ? { startTime: input.startTime } : {}
+		}, parent);
+		const finish = finisher(span);
+		const startMs = toEpochMs(input.startTime);
+		const recordConfirmation = (endTime, outcome) => txMetrics.confirmationDuration(secondsSince(startMs, endTime), userOperationMetricAttributes(chainId, outcome));
+		return {
+			active: 0,
+			ended: false,
+			receipt: (receipt, endTime) => finish("record user operation receipt", () => {
+				const attributes = userOperationReceiptAttributes(receipt ?? {});
+				span.setAttributes(redact(attributes));
+				const success = attributes[ATTR_BLOCKCHAIN_USER_OPERATION_SUCCESS];
+				if (success === false) markError(span, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED);
+				const outcome = typeof success === "boolean" ? { [ATTR_BLOCKCHAIN_USER_OPERATION_SUCCESS]: success } : {};
+				recordConfirmation(endTime, outcome);
+				const cost = attributes[ATTR_BLOCKCHAIN_USER_OPERATION_GAS_COST];
+				if (typeof cost === "string") txMetrics.fee(BigInt(cost), userOperationMetricAttributes(chainId, outcome));
+			}, endTime),
+			timeout: (endTime) => finish("record user operation confirmation timeout", () => recordConfirmation(endTime, { [ATTR_ERROR_TYPE]: markError(span, OBSERVER_TIMEOUT) }), endTime),
+			fail: (error, read) => finish("record user operation confirmation failure", () => recordConfirmation(read.endTime, { [ATTR_ERROR_TYPE]: markError(span, reportedErrorType(error, read), error, errorType(error)) }), read.endTime)
+		};
+	};
+	const startUserOperationConfirm = (input, parentCtx) => {
+		const { chainId, userOpHash } = input;
+		if (typeof userOpHash !== "string" || !TX_HASH.test(userOpHash)) {
+			diag.debug("hashspan: not confirming a user operation without a valid hash");
+			return NOOP_USER_OPERATION_CONFIRM;
+		}
+		const claim = joinConfirm(userOperationConfirmations, chainId, userOpHash, () => openUserOperationConfirm(input, parentCtx));
+		if (!claim) return NOOP_USER_OPERATION_CONFIRM;
+		const { shared } = claim;
+		return {
+			end: (receipt, second) => {
+				const { endTime } = handleOptions(second);
+				if (!claim.receive()) return;
+				userOperationConfirmations.settle(chainId, userOpHash, shared);
+				shared.receipt(receipt, endTime);
+			},
+			timeout: (second) => {
+				const { endTime } = handleOptions(second);
+				claim.withdraw(() => shared.timeout(endTime));
+			},
+			fail: (error, second) => {
+				const read = handleOptions(second);
+				claim.withdraw(() => shared.fail(error, read));
+			}
+		};
+	};
 	return {
 		startSend: (input, parent) => safely("start send span", () => startSend(input, parent), noopSend(parent ?? context.active())),
 		startConfirm: (input, parent) => safely("start confirm span", () => startConfirm(input, parent), NOOP_CONFIRM),
-		startPayment: (input, parent) => safely("start payment span", () => startPayment(input, parent), NOOP_PAYMENT)
+		startPayment: (input, parent) => safely("start payment span", () => startPayment(input, parent), NOOP_PAYMENT),
+		startUserOperationSend: (input, parent) => safely("start user operation send span", () => startUserOperationSend(input, parent), noopUserOperationSend(parent ?? context.active())),
+		startUserOperationConfirm: (input, parent) => safely("start user operation confirm span", () => startUserOperationConfirm(input, parent), NOOP_USER_OPERATION_CONFIRM)
 	};
 }
 //#endregion
-export { ATTR_BLOCKCHAIN_BLOCK_NUMBER, ATTR_BLOCKCHAIN_CHAIN_ID, ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS, ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME, ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR, ATTR_BLOCKCHAIN_OPERATION_NAME, ATTR_BLOCKCHAIN_PAYMENT_AMOUNT, ATTR_BLOCKCHAIN_PAYMENT_ASSET, ATTR_BLOCKCHAIN_PAYMENT_PAYER, ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL, ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT, ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT, ATTR_BLOCKCHAIN_PAYMENT_STATUS, ATTR_BLOCKCHAIN_PAYMENT_VERIFIED, ATTR_BLOCKCHAIN_SYSTEM, ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE, ATTR_BLOCKCHAIN_TX_FEE, ATTR_BLOCKCHAIN_TX_FROM, ATTR_BLOCKCHAIN_TX_GAS_USED, ATTR_BLOCKCHAIN_TX_HASH, ATTR_BLOCKCHAIN_TX_L1_FEE, ATTR_BLOCKCHAIN_TX_NONCE, ATTR_BLOCKCHAIN_TX_REPLACEMENT_HASH, ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON, ATTR_BLOCKCHAIN_TX_REVERT_REASON, ATTR_BLOCKCHAIN_TX_STATUS, ATTR_BLOCKCHAIN_TX_TO, ATTR_BLOCKCHAIN_TX_VALUE, ATTR_ERROR_TYPE, ATTR_GEN_AI_AGENT_ID, ATTR_GEN_AI_AGENT_NAME, ATTR_X402_RESOURCE, ATTR_X402_SCHEME, BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM, BLOCKCHAIN_OPERATION_NAME_VALUE_PAYMENT, BLOCKCHAIN_OPERATION_NAME_VALUE_SEND, BLOCKCHAIN_PAYMENT_PROTOCOL_VALUE_X402, BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED, BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING, BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED, BLOCKCHAIN_SYSTEM_VALUE_EVM, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPRICED, BLOCKCHAIN_TX_STATUS_VALUE_REPLACED, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED, BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS, BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT, ERROR_TYPE_VALUE_OTHER, VERSION, createTxTracker };
+export { ATTR_BLOCKCHAIN_BLOCK_NUMBER, ATTR_BLOCKCHAIN_CHAIN_ID, ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS, ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME, ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR, ATTR_BLOCKCHAIN_OPERATION_NAME, ATTR_BLOCKCHAIN_OPERATION_SUBJECT, ATTR_BLOCKCHAIN_PAYMENT_AMOUNT, ATTR_BLOCKCHAIN_PAYMENT_ASSET, ATTR_BLOCKCHAIN_PAYMENT_PAYER, ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL, ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT, ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT, ATTR_BLOCKCHAIN_PAYMENT_STATUS, ATTR_BLOCKCHAIN_PAYMENT_VERIFIED, ATTR_BLOCKCHAIN_SYSTEM, ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE, ATTR_BLOCKCHAIN_TX_FEE, ATTR_BLOCKCHAIN_TX_FROM, ATTR_BLOCKCHAIN_TX_GAS_USED, ATTR_BLOCKCHAIN_TX_HASH, ATTR_BLOCKCHAIN_TX_L1_FEE, ATTR_BLOCKCHAIN_TX_NONCE, ATTR_BLOCKCHAIN_TX_REPLACEMENT_HASH, ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON, ATTR_BLOCKCHAIN_TX_REVERT_REASON, ATTR_BLOCKCHAIN_TX_STATUS, ATTR_BLOCKCHAIN_TX_TO, ATTR_BLOCKCHAIN_TX_VALUE, ATTR_BLOCKCHAIN_USER_OPERATION_CALL_COUNT, ATTR_BLOCKCHAIN_USER_OPERATION_ENTRY_POINT, ATTR_BLOCKCHAIN_USER_OPERATION_GAS_COST, ATTR_BLOCKCHAIN_USER_OPERATION_GAS_USED, ATTR_BLOCKCHAIN_USER_OPERATION_HASH, ATTR_BLOCKCHAIN_USER_OPERATION_NONCE, ATTR_BLOCKCHAIN_USER_OPERATION_PAYMASTER, ATTR_BLOCKCHAIN_USER_OPERATION_SENDER, ATTR_BLOCKCHAIN_USER_OPERATION_SUCCESS, ATTR_ERROR_TYPE, ATTR_GEN_AI_AGENT_ID, ATTR_GEN_AI_AGENT_NAME, ATTR_X402_RESOURCE, ATTR_X402_SCHEME, BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM, BLOCKCHAIN_OPERATION_NAME_VALUE_PAYMENT, BLOCKCHAIN_OPERATION_NAME_VALUE_SEND, BLOCKCHAIN_OPERATION_SUBJECT_VALUE_USER_OPERATION, BLOCKCHAIN_PAYMENT_PROTOCOL_VALUE_X402, BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED, BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING, BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED, BLOCKCHAIN_SYSTEM_VALUE_EVM, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPRICED, BLOCKCHAIN_TX_STATUS_VALUE_REPLACED, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED, BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS, BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT, ERROR_TYPE_VALUE_OTHER, METRIC_BLOCKCHAIN_CLIENT_CONFIRMATION_DURATION, METRIC_BLOCKCHAIN_CLIENT_FEE, METRIC_BLOCKCHAIN_CLIENT_SEND_DURATION, VERSION, createTxTracker };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashspan/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Transaction lifecycle tracing for on-chain actions of AI agents, built on OpenTelemetry.",
   "license": "Apache-2.0",
   "author": "Selim Aytac",