@hashspan/core 0.5.0 → 0.7.0

package/README.md

@@ -12,7 +12,7 @@ Payments that another party settles on chain, such as x402 payments, become a **
 of a `send` span.
 
 The core is library-agnostic and read-only: it never signs, sends or fetches anything. Adapters such as
-[`@hashspan/viem`](https://github.com/selimaytac/hashspan/tree/@hashspan/core@0.5.0/packages/viem) call it for you. Use the core directly to instrument any other send path.
+[`@hashspan/viem`](https://github.com/selimaytac/hashspan/tree/@hashspan/core@0.7.0/packages/viem) call it for you. Use the core directly to instrument any other send path.
 
 ## Install
 
@@ -69,27 +69,28 @@ stays the class name.
 `tracker.startPayment({ chainId, protocol, payer, recipient, asset, amount })` records a payment that another
 party settles on chain, such as an x402 facilitator, as a `payment {chainId}` span; end it with
 `end({ status, hash })` or `fail(error)`. A settlement with a hash links the transaction's confirm span to the payment
-span ([ADR 0013](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md)).
+span ([ADR 0013](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0013-x402-payments.md)).
 
 All three calls accept an explicit parent `Context` as a second argument. An integration that learns about a call only
 after it started can record it after the fact: pass `startTime` in the input and `endTime` in the options of the
-handle method, e.g. `send.end({ hash }, { endTime })` ([ADR 0009](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0009-telemetry-off-the-call-path.md)). Every method is safe to call: failures inside
+handle method, e.g. `send.end({ hash }, { endTime })` ([ADR 0009](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0009-telemetry-off-the-call-path.md)). Every method is safe to call: failures inside
 the instrumentation are reported through `diag` and never thrown into your code. The positional forms of earlier
 releases, `send.end(hash, endTime)` and `send.fail(error, endTime, { errorType })`, still work and are deprecated
-until 1.0 ([ADR 0014](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md)).
+until 1.0 ([ADR 0014](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0014-core-api-boundary.md)).
 
 ## Options
 
 | Option | Default | Description |
 |---|---|---|
 | `tracerProvider` | global provider | Tracer provider to use |
+| `meterProvider` | global provider | Meter provider for the [metrics](#metrics) |
 | `address` | `'raw'` | `'raw'`, `'hashed'`, `'off'`, or `{ mode: 'hashed', hash: (address) => string }` |
-| `errorMessages` | `'off'` | What failed spans record about the error: `'off'` (type only), `'sanitized'` (first line, addresses per `address` mode, calldata removed; in `hashed` and `off` mode any hex longer than an address) or `'raw'` (full message and stack trace). `'raw'` can record RPC URLs that include API keys, as some libraries put the request URL in the message; `'sanitized'` keeps only the first line (viem puts the URL on a later line), which is best effort. See [ADR 0006](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0006-error-privacy.md) |
+| `errorMessages` | `'off'` | What failed spans record about the error: `'off'` (type only), `'sanitized'` (first line, addresses per `address` mode, calldata removed; in `hashed` and `off` mode any hex longer than an address) or `'raw'` (full message and stack trace). `'raw'` can record RPC URLs that include API keys, as some libraries put the request URL in the message; `'sanitized'` keeps only the first line (viem puts the URL on a later line), which is best effort. See [ADR 0006](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0006-error-privacy.md) |
 | `paymentResource` | `'origin'` | How much of a paid resource's URL `x402.resource` records: `'origin'` (scheme, host and port; nothing for a resource that is not a URL), `'path'` (also the path, never the query string, fragment or user info) or `'off'`. Paths often carry user or account identifiers. At most 512 characters are recorded |
 | `recordFunctionArguments` | `false` | Record `functionArguments` as a JSON array in `blockchain.contract.function.arguments`: bigints as decimal strings, addresses per `address` mode (longer hex values become `<hex>` in `hashed` and `off` mode), at most 4096 characters. Reads only own enumerable data properties: `toJSON()` and getters are never called, so a `Date` records as `{}`; a Proxy's traps still run |
 | `agent` | none | Agent `{ id, name }`; a field set here always wins, unset fields come from the Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` |
 | `agentFromBaggage` | `true` | Read agent identity fields that `agent` leaves unset from Baggage; set to `false` in services that accept requests from outside their trust boundary |
-| `redact` | none | `(attributes) => attributes`, runs last on every attribute set, including exception event attributes; if it throws, only non-sensitive identifiers are kept |
+| `redact` | none | `(attributes) => attributes`, runs last on every span attribute set, including exception event attributes, but not on [metrics](#metrics); if it throws, only non-sensitive identifiers are kept |
 | `linkTtlMs` | `600000` | How long a sent transaction can be linked from its confirmation |
 | `maxTrackedTransactions` | `10000` | Upper bound on transactions kept for linking |
 
@@ -99,7 +100,17 @@ Chain id, transaction hash, sender/recipient (per `address` mode), value, nonce,
 on confirmation, status, block number, gas used, effective gas price, L1 fee, total fee and revert reason. Decoded
 call arguments are recorded only with `recordFunctionArguments`, and error messages only with `errorMessages`.
 Attribute definitions:
-[docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md).
+[docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/semconv.md).
+
+## Metrics
+
+With an OpenTelemetry metrics SDK set up (or `meterProvider`), the tracker records three histograms:
+`blockchain.client.send.duration` and `blockchain.client.confirmation.duration` in seconds, and
+`blockchain.client.fee` in wei. Their attributes are the chain and the outcome only, never an address, hash or
+agent identity. The `redact` hook does not run on metrics: a fee it removes from spans is still recorded by
+`blockchain.client.fee`. To keep a histogram out of your backend, drop it with a View of your metrics SDK (drop
+aggregation). Definitions:
+[docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/semconv.md#metrics).
 
 ## Privacy notes
 
@@ -114,9 +125,9 @@ Attribute definitions:
   propagated, or strip the entries before outbound calls.
 - **Inbound Baggage can claim an identity.** A caller can send Baggage entries with any agent id. A field set in the
   `agent` option cannot be overridden that way; to ignore identity from Baggage entirely, set `agentFromBaggage: false`
-  ([ADR 0011](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0011-agent-identity-precedence.md)).
-- The redaction hook (`redact`) runs last on every attribute set and on exception attributes; use it for anything
-  else your policy forbids.
+  ([ADR 0011](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0011-agent-identity-precedence.md)).
+- The redaction hook (`redact`) runs last on every span attribute set and on exception attributes; use it for
+  anything else your policy forbids. It does not run on [metrics](#metrics), which carry no address or hash.
 - **Your callbacks' errors go to the diagnostic logger.** If a custom `hash` function or the `redact` hook throws,
   its error object is logged through the OpenTelemetry `diag` logger, outside the address mode and the redaction
   hook. Errors of the instrumented call never are. Do not put sensitive values, such as the address being hashed,

package/dist/index.cjs

@@ -6,7 +6,7 @@ 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.5.0/docs/adr/0011-agent-identity-precedence.md).
+* (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0011-agent-identity-precedence.md).
 */
 function agentAttributes(ctx, identity, fromBaggage = true) {
 	const baggage = fromBaggage ? _opentelemetry_api.propagation.getBaggage(ctx) : void 0;
@@ -22,7 +22,7 @@ function agentAttributes(ctx, identity, fromBaggage = true) {
 /**
 * Attribute keys emitted by hashspan.
 *
-* Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md for
+* Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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";
@@ -46,12 +46,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.5.0/docs/adr/0004-privacy-defaults.md.
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0013-x402-payments.md.
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0013-x402-payments.md.
 */
 const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = "blockchain.payment.protocol";
 const ATTR_BLOCKCHAIN_PAYMENT_PAYER = "blockchain.payment.payer";
@@ -61,6 +61,12 @@ const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT = "blockchain.payment.amount";
 const ATTR_BLOCKCHAIN_PAYMENT_STATUS = "blockchain.payment.status";
 /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
 const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT = "blockchain.payment.settled_amount";
+/**
+* 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.7.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";
@@ -82,7 +88,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.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
 */
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -95,6 +101,83 @@ 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: 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: 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), 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));
+/** 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 ?? _opentelemetry_api.metrics.getMeterProvider()).getMeter(name, version);
+			return {
+				send: meter.createHistogram(METRIC_BLOCKCHAIN_CLIENT_SEND_DURATION, {
+					unit: "s",
+					description: "Duration of sending a transaction, 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 receipt",
+					advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+				}),
+				fee: meter.createHistogram(METRIC_BLOCKCHAIN_CLIENT_FEE, {
+					unit: "{wei}",
+					description: "Total fee of a mined transaction",
+					advice: { explicitBucketBoundaries: FEE_BUCKETS }
+				})
+			};
+		})();
+		return histograms;
+	};
+	const record = (what, run) => {
+		try {
+			run();
+		} catch (error) {
+			_opentelemetry_api.diag.error(`hashspan: failed to record the ${what} metric`, error);
+		}
+	};
+	return {
+		sendDuration: (seconds, attributes) => record("send duration", () => {
+			if (seconds >= 0) get().send.record(seconds, attributes);
+		}),
+		confirmationDuration: (seconds, attributes) => record("confirmation duration", () => {
+			if (seconds >= 0) get().confirmation.record(seconds, 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
@@ -380,7 +463,7 @@ function sanitizeResource(resource) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.5.0";
+const VERSION = "0.7.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -402,6 +485,7 @@ const NON_SENSITIVE_KEYS = /* @__PURE__ */ new Set([
 	ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON,
 	ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL,
 	ATTR_BLOCKCHAIN_PAYMENT_STATUS,
+	ATTR_BLOCKCHAIN_PAYMENT_VERIFIED,
 	ATTR_ERROR_TYPE,
 	ATTR_EXCEPTION_TYPE
 ]);
@@ -430,7 +514,8 @@ const noopSend = (parent) => ({
 const NOOP_PAYMENT = {
 	end: () => {},
 	fail: () => {},
-	timeout: () => {}
+	timeout: () => {},
+	link: () => {}
 };
 const NOOP_CONFIRM = {
 	end: () => {},
@@ -505,7 +590,7 @@ function reportedErrorType(error, options) {
 }
 /**
 * 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.5.0/docs/semconv.md). It makes
+* `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.
 */
@@ -521,6 +606,14 @@ 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 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
+	});
+	const secondsSince = (startMs, endTime) => (toEpochMs(endTime) - startMs) / 1e3;
 	let tracer;
 	const getTracer = () => {
 		tracer ??= (options.tracerProvider ?? _opentelemetry_api.trace.getTracerProvider()).getTracer(INSTRUMENTATION_NAME, VERSION);
@@ -545,7 +638,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.5.0/docs/adr/0006-error-privacy.md).
+	* (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0006-error-privacy.md).
 	*/
 	const exceptionAttributes = (type, error) => {
 		const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -578,6 +671,7 @@ function createTxTracker(options = {}) {
 			code: _opentelemetry_api.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) => {
@@ -629,6 +723,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: _opentelemetry_api.trace.setSpan(parent, span),
 			end: (result, second) => finish("record transaction hash", () => {
@@ -642,10 +738,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);
 			}
 		};
 	};
@@ -681,6 +778,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,
@@ -690,11 +789,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,
@@ -702,8 +806,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)
 		};
 	};
 	/**
@@ -725,7 +830,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.5.0/docs/adr/0008-replaced-transactions.md).
+	* (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0008-replaced-transactions.md).
 	*/
 	const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
 		const mined = receipt.transactionHash;
@@ -815,6 +920,15 @@ function createTxTracker(options = {}) {
 			...input.startTime !== void 0 ? { startTime: input.startTime } : {}
 		}, parent);
 		const finish = finisher(span);
+		/** Links the confirm span of `hash` to this payment span, unless the tracker already links that hash. */
+		const linkHash = (hash) => {
+			if (typeof hash !== "string" || !TX_HASH.test(hash)) return false;
+			if (!links.get(input.chainId, hash)) links.set(input.chainId, hash, {
+				spanContext: span.spanContext(),
+				parent
+			});
+			return true;
+		};
 		const recordSettlement = (settlement) => {
 			const status = settlement.status;
 			if (!PAYMENT_STATUSES.has(status)) {
@@ -823,19 +937,15 @@ function createTxTracker(options = {}) {
 			}
 			const settled = { [ATTR_BLOCKCHAIN_PAYMENT_STATUS]: status };
 			const hash = settlement.hash;
-			if (typeof hash === "string" && TX_HASH.test(hash)) {
-				if (!links.get(input.chainId, hash)) links.set(input.chainId, hash, {
-					spanContext: span.spanContext(),
-					parent
-				});
-				settled[ATTR_BLOCKCHAIN_TX_HASH] = hash;
-			}
+			if (linkHash(hash)) settled[ATTR_BLOCKCHAIN_TX_HASH] = hash;
 			if (!knownPayer) setPaymentAddress(settled, ATTR_BLOCKCHAIN_PAYMENT_PAYER, settlement.payer);
 			const settledAmount = amount(settlement.amount);
 			if (settledAmount !== void 0) {
 				settled[ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT] = settledAmount;
 				if (paid === void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
 			}
+			const verified = settlement.verified;
+			if (typeof verified === "boolean") settled[ATTR_BLOCKCHAIN_PAYMENT_VERIFIED] = verified;
 			span.setAttributes(redact(settled));
 			if (status === "failed") markError(span, identifier(settlement.errorReason) ?? "_OTHER");
 		};
@@ -845,7 +955,8 @@ function createTxTracker(options = {}) {
 				const read = handleOptions(options);
 				finish("record payment failure", () => markError(span, reportedErrorType(error, read), error, errorType(error)), read.endTime);
 			},
-			timeout: (options) => finish("record payment timeout", () => markError(span, OBSERVER_TIMEOUT), handleOptions(options).endTime)
+			timeout: (options) => finish("record payment timeout", () => markError(span, OBSERVER_TIMEOUT), handleOptions(options).endTime),
+			link: (hash) => safely("link the payment span", () => void linkHash(hash), void 0)
 		};
 	};
 	return {
@@ -868,6 +979,7 @@ exports.ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL;
 exports.ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT = ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT;
 exports.ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT = ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT;
 exports.ATTR_BLOCKCHAIN_PAYMENT_STATUS = ATTR_BLOCKCHAIN_PAYMENT_STATUS;
+exports.ATTR_BLOCKCHAIN_PAYMENT_VERIFIED = ATTR_BLOCKCHAIN_PAYMENT_VERIFIED;
 exports.ATTR_BLOCKCHAIN_SYSTEM = ATTR_BLOCKCHAIN_SYSTEM;
 exports.ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE = ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE;
 exports.ATTR_BLOCKCHAIN_TX_FEE = ATTR_BLOCKCHAIN_TX_FEE;
@@ -903,5 +1015,8 @@ exports.BLOCKCHAIN_TX_STATUS_VALUE_REVERTED = BLOCKCHAIN_TX_STATUS_VALUE_REVERTE
 exports.BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS = BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS;
 exports.BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT;
 exports.ERROR_TYPE_VALUE_OTHER = ERROR_TYPE_VALUE_OTHER;
+exports.METRIC_BLOCKCHAIN_CLIENT_CONFIRMATION_DURATION = METRIC_BLOCKCHAIN_CLIENT_CONFIRMATION_DURATION;
+exports.METRIC_BLOCKCHAIN_CLIENT_FEE = METRIC_BLOCKCHAIN_CLIENT_FEE;
+exports.METRIC_BLOCKCHAIN_CLIENT_SEND_DURATION = METRIC_BLOCKCHAIN_CLIENT_SEND_DURATION;
 exports.VERSION = VERSION;
 exports.createTxTracker = createTxTracker;

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.5.0/docs/adr/0004-privacy-defaults.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0006-error-privacy.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0011-agent-identity-precedence.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0011-agent-identity-precedence.md).
    */
   agent?: AgentIdentity | undefined;
   /**
@@ -75,8 +80,8 @@ 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`, `error.type` and `exception.type`, and logs the
-   * failure via `diag`.
+   * `blockchain.payment.protocol`, `blockchain.payment.status`, `blockchain.payment.verified`, `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. */
@@ -103,7 +108,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.5.0/docs/adr/0009-telemetry-off-the-call-path.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +117,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.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0015-send-span-as-active-context.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +187,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.5.0/docs/adr/0008-replaced-transactions.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +197,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.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +221,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.5.0/docs/adr/0013-x402-payments.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 {
@@ -257,13 +262,18 @@ interface PaymentSettlement {
    * `blockchain.payment.amount` when the input had none.
    */
   amount?: bigint | string | undefined;
+  /**
+   * Whether the settlement transaction's receipt carries this payment, as the adapter checked it from the payer's own
+   * data; recorded as `blockchain.payment.verified`. Leave it unset when no check was possible.
+   */
+  verified?: boolean | undefined;
   /** Why a `failed` settlement failed, recorded as `error.type` if it is a short identifier, else `_OTHER`. */
   errorReason?: string | undefined;
 }
 /**
  * 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.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0014-core-api-boundary.md).
  */
 interface PaymentHandle {
   /** Ends the payment span with its settlement. */
@@ -279,6 +289,12 @@ interface PaymentHandle {
    * learned, e.g. no response arrived before the authorization expired.
    */
   timeout(options?: EndOptions): void;
+  /**
+   * Makes the confirm span of the settling transaction `hash` link to this payment span before it ends, for an
+   * adapter that ends it only after checking that transaction's receipt (ADR 0017). A hash this tracker already links,
+   * such as one of its own sends, keeps its link; `end` with a hash links it as well.
+   */
+  link(hash: string): void;
 }
 //#endregion
 //#region src/agent.d.ts
@@ -289,7 +305,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.5.0/docs/semconv.md for
+ * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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";
@@ -313,12 +329,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.5.0/docs/adr/0004-privacy-defaults.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0013-x402-payments.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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";
@@ -328,6 +344,12 @@ export declare const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT: "blockchain.payment.amount"
 export declare const ATTR_BLOCKCHAIN_PAYMENT_STATUS: "blockchain.payment.status";
 /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
 export declare const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT: "blockchain.payment.settled_amount";
+/**
+ * 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.7.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";
@@ -349,7 +371,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.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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";
@@ -362,11 +384,19 @@ 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: 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: 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), 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
  * implemented, and members may be added to it and to its handles in minor releases
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0014-core-api-boundary.md).
  */
 interface TxTracker {
   /**
@@ -384,7 +414,7 @@ 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.5.0/docs/adr/0013-x402-payments.md). Call
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.
    */
@@ -392,7 +422,7 @@ interface TxTracker {
 }
 /**
  * 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.5.0/docs/semconv.md). It makes
+ * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.
  */

package/dist/index.d.mts

@@ -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.5.0/docs/adr/0004-privacy-defaults.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0006-error-privacy.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0011-agent-identity-precedence.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0011-agent-identity-precedence.md).
    */
   agent?: AgentIdentity | undefined;
   /**
@@ -75,8 +80,8 @@ 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`, `error.type` and `exception.type`, and logs the
-   * failure via `diag`.
+   * `blockchain.payment.protocol`, `blockchain.payment.status`, `blockchain.payment.verified`, `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. */
@@ -103,7 +108,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.5.0/docs/adr/0009-telemetry-off-the-call-path.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +117,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.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0015-send-span-as-active-context.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +187,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.5.0/docs/adr/0008-replaced-transactions.md).
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +197,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.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 +221,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.5.0/docs/adr/0013-x402-payments.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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 {
@@ -257,13 +262,18 @@ interface PaymentSettlement {
    * `blockchain.payment.amount` when the input had none.
    */
   amount?: bigint | string | undefined;
+  /**
+   * Whether the settlement transaction's receipt carries this payment, as the adapter checked it from the payer's own
+   * data; recorded as `blockchain.payment.verified`. Leave it unset when no check was possible.
+   */
+  verified?: boolean | undefined;
   /** Why a `failed` settlement failed, recorded as `error.type` if it is a short identifier, else `_OTHER`. */
   errorReason?: string | undefined;
 }
 /**
  * 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.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0014-core-api-boundary.md).
  */
 interface PaymentHandle {
   /** Ends the payment span with its settlement. */
@@ -279,6 +289,12 @@ interface PaymentHandle {
    * learned, e.g. no response arrived before the authorization expired.
    */
   timeout(options?: EndOptions): void;
+  /**
+   * Makes the confirm span of the settling transaction `hash` link to this payment span before it ends, for an
+   * adapter that ends it only after checking that transaction's receipt (ADR 0017). A hash this tracker already links,
+   * such as one of its own sends, keeps its link; `end` with a hash links it as well.
+   */
+  link(hash: string): void;
 }
 //#endregion
 //#region src/agent.d.ts
@@ -289,7 +305,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.5.0/docs/semconv.md for
+ * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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";
@@ -313,12 +329,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.5.0/docs/adr/0004-privacy-defaults.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0013-x402-payments.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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";
@@ -328,6 +344,12 @@ export declare const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT: "blockchain.payment.amount"
 export declare const ATTR_BLOCKCHAIN_PAYMENT_STATUS: "blockchain.payment.status";
 /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
 export declare const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT: "blockchain.payment.settled_amount";
+/**
+ * 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.7.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";
@@ -349,7 +371,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.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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";
@@ -362,11 +384,19 @@ 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: 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: 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), 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
  * implemented, and members may be added to it and to its handles in minor releases
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0014-core-api-boundary.md).
  */
 interface TxTracker {
   /**
@@ -384,7 +414,7 @@ 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.5.0/docs/adr/0013-x402-payments.md). Call
+   * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.
    */
@@ -392,7 +422,7 @@ interface TxTracker {
 }
 /**
  * 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.5.0/docs/semconv.md). It makes
+ * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.
  */

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.5.0/docs/adr/0011-agent-identity-precedence.md).
+* (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/semconv.md for
+* Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0004-privacy-defaults.md.
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.5.0/docs/adr/0013-x402-payments.md.
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0013-x402-payments.md.
 */
 const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = "blockchain.payment.protocol";
 const ATTR_BLOCKCHAIN_PAYMENT_PAYER = "blockchain.payment.payer";
@@ -60,6 +60,12 @@ const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT = "blockchain.payment.amount";
 const ATTR_BLOCKCHAIN_PAYMENT_STATUS = "blockchain.payment.status";
 /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
 const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT = "blockchain.payment.settled_amount";
+/**
+* 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.7.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";
@@ -81,7 +87,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.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
 */
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -94,6 +100,83 @@ 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: 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: 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), 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));
+/** 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, 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 receipt",
+					advice: { explicitBucketBoundaries: DURATION_BUCKETS }
+				}),
+				fee: meter.createHistogram(METRIC_BLOCKCHAIN_CLIENT_FEE, {
+					unit: "{wei}",
+					description: "Total fee of a mined transaction",
+					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, attributes);
+		}),
+		confirmationDuration: (seconds, attributes) => record("confirmation duration", () => {
+			if (seconds >= 0) get().confirmation.record(seconds, 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
@@ -379,7 +462,7 @@ function sanitizeResource(resource) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.5.0";
+const VERSION = "0.7.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -401,6 +484,7 @@ const NON_SENSITIVE_KEYS = /* @__PURE__ */ new Set([
 	ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON,
 	ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL,
 	ATTR_BLOCKCHAIN_PAYMENT_STATUS,
+	ATTR_BLOCKCHAIN_PAYMENT_VERIFIED,
 	ATTR_ERROR_TYPE,
 	ATTR_EXCEPTION_TYPE
 ]);
@@ -429,7 +513,8 @@ const noopSend = (parent) => ({
 const NOOP_PAYMENT = {
 	end: () => {},
 	fail: () => {},
-	timeout: () => {}
+	timeout: () => {},
+	link: () => {}
 };
 const NOOP_CONFIRM = {
 	end: () => {},
@@ -504,7 +589,7 @@ function reportedErrorType(error, options) {
 }
 /**
 * 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.5.0/docs/semconv.md). It makes
+* `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.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.
 */
@@ -520,6 +605,14 @@ 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 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
+	});
+	const secondsSince = (startMs, endTime) => (toEpochMs(endTime) - startMs) / 1e3;
 	let tracer;
 	const getTracer = () => {
 		tracer ??= (options.tracerProvider ?? trace.getTracerProvider()).getTracer(INSTRUMENTATION_NAME, VERSION);
@@ -544,7 +637,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.5.0/docs/adr/0006-error-privacy.md).
+	* (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0006-error-privacy.md).
 	*/
 	const exceptionAttributes = (type, error) => {
 		const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -577,6 +670,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) => {
@@ -628,6 +722,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", () => {
@@ -641,10 +737,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);
 			}
 		};
 	};
@@ -680,6 +777,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,
@@ -689,11 +788,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,
@@ -701,8 +805,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)
 		};
 	};
 	/**
@@ -724,7 +829,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.5.0/docs/adr/0008-replaced-transactions.md).
+	* (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.7.0/docs/adr/0008-replaced-transactions.md).
 	*/
 	const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
 		const mined = receipt.transactionHash;
@@ -814,6 +919,15 @@ function createTxTracker(options = {}) {
 			...input.startTime !== void 0 ? { startTime: input.startTime } : {}
 		}, parent);
 		const finish = finisher(span);
+		/** Links the confirm span of `hash` to this payment span, unless the tracker already links that hash. */
+		const linkHash = (hash) => {
+			if (typeof hash !== "string" || !TX_HASH.test(hash)) return false;
+			if (!links.get(input.chainId, hash)) links.set(input.chainId, hash, {
+				spanContext: span.spanContext(),
+				parent
+			});
+			return true;
+		};
 		const recordSettlement = (settlement) => {
 			const status = settlement.status;
 			if (!PAYMENT_STATUSES.has(status)) {
@@ -822,19 +936,15 @@ function createTxTracker(options = {}) {
 			}
 			const settled = { [ATTR_BLOCKCHAIN_PAYMENT_STATUS]: status };
 			const hash = settlement.hash;
-			if (typeof hash === "string" && TX_HASH.test(hash)) {
-				if (!links.get(input.chainId, hash)) links.set(input.chainId, hash, {
-					spanContext: span.spanContext(),
-					parent
-				});
-				settled[ATTR_BLOCKCHAIN_TX_HASH] = hash;
-			}
+			if (linkHash(hash)) settled[ATTR_BLOCKCHAIN_TX_HASH] = hash;
 			if (!knownPayer) setPaymentAddress(settled, ATTR_BLOCKCHAIN_PAYMENT_PAYER, settlement.payer);
 			const settledAmount = amount(settlement.amount);
 			if (settledAmount !== void 0) {
 				settled[ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT] = settledAmount;
 				if (paid === void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
 			}
+			const verified = settlement.verified;
+			if (typeof verified === "boolean") settled[ATTR_BLOCKCHAIN_PAYMENT_VERIFIED] = verified;
 			span.setAttributes(redact(settled));
 			if (status === "failed") markError(span, identifier(settlement.errorReason) ?? "_OTHER");
 		};
@@ -844,7 +954,8 @@ function createTxTracker(options = {}) {
 				const read = handleOptions(options);
 				finish("record payment failure", () => markError(span, reportedErrorType(error, read), error, errorType(error)), read.endTime);
 			},
-			timeout: (options) => finish("record payment timeout", () => markError(span, OBSERVER_TIMEOUT), handleOptions(options).endTime)
+			timeout: (options) => finish("record payment timeout", () => markError(span, OBSERVER_TIMEOUT), handleOptions(options).endTime),
+			link: (hash) => safely("link the payment span", () => void linkHash(hash), void 0)
 		};
 	};
 	return {
@@ -854,4 +965,4 @@ function createTxTracker(options = {}) {
 	};
 }
 //#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_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_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, 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.5.0",
+  "version": "0.7.0",
   "description": "Transaction lifecycle tracing for on-chain actions of AI agents, built on OpenTelemetry.",
   "license": "Apache-2.0",
   "author": "Selim Aytac",