@hashspan/core 0.3.0 → 0.4.0

package/README.md

@@ -8,8 +8,11 @@ Transaction lifecycle tracing for the on-chain actions of AI agents, built on Op
 - **`confirm {chainId}`**: waiting for the receipt: status, block, gas, fees (including the OP-stack L1 fee) and
   revert reason. It carries a span link to its `send` span.
 
+Payments that another party settles on chain, such as x402 payments, become a **`payment {chainId}`** span instead
+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.3.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.4.0/packages/viem) call it for you. Use the core directly to instrument any other send path.
 
 ## Install
 
@@ -17,7 +20,7 @@ The core is library-agnostic and read-only: it never signs, sends or fetches any
 npm install @hashspan/core @opentelemetry/api
 ```
 
-`@opentelemetry/api` is the only peer dependency. Bring your own OpenTelemetry SDK and exporter. Requires Node.js 22.3
+`@opentelemetry/api` is the only peer dependency. Bring your own [OpenTelemetry SDK and exporter](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/). Requires Node.js 22.3
 or later; in other runtimes, `hashed` address mode needs a custom `hash` function and otherwise records no addresses,
 with a `diag` warning.
 
@@ -25,15 +28,17 @@ with a `diag` warning.
 
 ```ts
 import { createTxTracker } from '@hashspan/core';
+import { context } from '@opentelemetry/api';
 
 const tracker = createTxTracker({ agent: { name: 'treasury-bot' } });
 
 // Inside your tool, where the agent framework's span is active:
 const send = tracker.startSend({ chainId: 8453, from, to, value, functionName: 'transfer' });
-let hash;
+let hash: string;
 try {
-  hash = await sendSomehow();
-  send.end(hash);
+  // Run in the send span's context, so that wallet or RPC spans of the call nest under it.
+  hash = await context.with(send.context, () => sendSomehow());
+  send.end({ hash });
 } catch (error) {
   send.fail(error);
   throw error;
@@ -57,14 +62,21 @@ confirm.end({
 share one confirm span. A receipt from any of them ends it; a timeout or failure ends it once every caller gave up.
 End every handle you start, since an open handle keeps the shared span open.
 
-`send.fail(error, endTime, { errorType })` records a library's machine-readable error code as `error.type` instead
+`send.fail(error, { errorType })` records a library's machine-readable error code as `error.type` instead
 of the error's class name, if it is a short identifier (`[A-Za-z0-9_.-]`, at most 64 characters); `exception.type`
 stays the class name.
 
-Both 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 the end time as the last argument
-of the handle method, e.g. `send.end(hash, endTime)` ([ADR 0009](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.3.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.
+`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.4.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.4.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.4.0/docs/adr/0014-core-api-boundary.md)).
 
 ## Options
 
@@ -72,7 +84,8 @@ the instrumentation are reported through `diag` and never thrown into your code.
 |---|---|---|
 | `tracerProvider` | global provider | Tracer provider to use |
 | `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.3.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.4.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 |
@@ -86,7 +99,7 @@ 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.3.0/docs/semconv.md).
+[docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md).
 
 ## Privacy notes
 
@@ -101,9 +114,13 @@ 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.3.0/docs/adr/0011-agent-identity-precedence.md)).
+  ([ADR 0011](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.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.
+- **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,
+  into errors your callbacks throw, or route `diag` to a sink your policy allows.
 
 ## License
 

package/dist/index.cjs

@@ -5,7 +5,8 @@ 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 (docs/adr/0011).
+* 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.4.0/docs/adr/0011-agent-identity-precedence.md).
 */
 function agentAttributes(ctx, identity, fromBaggage = true) {
 	const baggage = fromBaggage ? _opentelemetry_api.propagation.getBaggage(ctx) : void 0;
@@ -21,8 +22,8 @@ function agentAttributes(ctx, identity, fromBaggage = true) {
 /**
 * Attribute keys emitted by hashspan.
 *
-* Stability: development. See docs/semconv.md for definitions and value types.
-* These names are a public contract: changes follow the deprecation policy in AGENTS.md.
+* Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.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";
 const ATTR_BLOCKCHAIN_CHAIN_ID = "blockchain.chain.id";
@@ -43,16 +44,44 @@ const ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON = "blockchain.tx.replacement.reason"
 const ATTR_BLOCKCHAIN_BLOCK_NUMBER = "blockchain.block.number";
 const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME = "blockchain.contract.function.name";
 const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR = "blockchain.contract.function.selector";
-/** Opt-in: decoded call arguments as a JSON array. See docs/adr/0004-privacy-defaults.md. */
+/**
+* Opt-in: decoded call arguments as a JSON array. See
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.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.4.0/docs/adr/0013-x402-payments.md.
+*/
+const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = "blockchain.payment.protocol";
+const ATTR_BLOCKCHAIN_PAYMENT_PAYER = "blockchain.payment.payer";
+const ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT = "blockchain.payment.recipient";
+const ATTR_BLOCKCHAIN_PAYMENT_ASSET = "blockchain.payment.asset";
+const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT = "blockchain.payment.amount";
+const ATTR_BLOCKCHAIN_PAYMENT_STATUS = "blockchain.payment.status";
+/** x402's own payment fields. */
+const ATTR_X402_SCHEME = "x402.scheme";
+const ATTR_X402_RESOURCE = "x402.resource";
 /** Values for {@link ATTR_BLOCKCHAIN_SYSTEM}. */
 const BLOCKCHAIN_SYSTEM_VALUE_EVM = "evm";
 /** Values for {@link ATTR_BLOCKCHAIN_OPERATION_NAME}. */
 const BLOCKCHAIN_OPERATION_NAME_VALUE_SEND = "send";
 const BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM = "confirm";
+const BLOCKCHAIN_OPERATION_NAME_VALUE_PAYMENT = "payment";
+/** Values for {@link ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL}. */
+const BLOCKCHAIN_PAYMENT_PROTOCOL_VALUE_X402 = "x402";
+/** Values for {@link ATTR_BLOCKCHAIN_PAYMENT_STATUS}. */
+const BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED = "settled";
+const BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING = "pending";
+const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED = "failed";
 /** Values for {@link ATTR_BLOCKCHAIN_TX_STATUS}. */
 const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS = "success";
 const BLOCKCHAIN_TX_STATUS_VALUE_REVERTED = "reverted";
+/**
+* @deprecated A confirm span that gave up waiting records `error.type` `timeout`; this value of
+* `blockchain.tx.status` stops being recorded in a later minor release and the constant is removed in 1.0. See
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
+*/
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
 /** Values for {@link ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON}, as reported by the instrumented library. */
@@ -300,9 +329,56 @@ function resolveErrorMessageMode(mode) {
 	_opentelemetry_api.diag.warn(`hashspan: unknown error message mode "${String(mode)}"; recording error types only`);
 	return "off";
 }
+function resolvePaymentResourceMode(mode) {
+	if (mode === void 0 || mode === "origin" || mode === "path" || mode === "off") return mode ?? "origin";
+	_opentelemetry_api.diag.warn(`hashspan: unknown payment resource mode "${String(mode)}"; not recording payment resources`);
+	return "off";
+}
+/** The origin of a URL: `scheme://`, then the host and port, without user info. */
+const URL_ORIGIN = /^([A-Za-z][A-Za-z0-9+.-]*:\/\/)(?:[^/?#]*@)?([^/?#]+)/;
+/**
+* The part of a payment's resource that `mode` records, or undefined for none. Works on the text, so it never throws
+* for a resource that is not a URL.
+*/
+function paymentResourceOf(resource, mode) {
+	if (mode === "off" || hidesUserInfo(resource)) return void 0;
+	const recorded = mode === "path" ? sanitizeResource(resource) : originOf(resource);
+	if (recorded === void 0) return void 0;
+	return recorded.length > MAX_RESOURCE_LENGTH ? `${recorded.slice(0, MAX_RESOURCE_LENGTH)}...` : recorded;
+}
+/** Longest `x402.resource` recorded; the value comes from the server that asks for the payment. */
+const MAX_RESOURCE_LENGTH = 512;
+function originOf(resource) {
+	const origin = URL_ORIGIN.exec(resource);
+	return origin ? `${origin[1]}${origin[2]}` : void 0;
+}
+/**
+* True for `scheme://` text whose user info contains `?` or `#`, such as `https://user:p?ss@host`. A valid URL
+* percent-encodes them; reading such text by its first `?` or `#` would record part of the user info as the host.
+*/
+function hidesUserInfo(resource) {
+	const scheme = URL_SCHEME.exec(resource);
+	if (!scheme) return false;
+	const rest = resource.slice(scheme[0].length);
+	const slash = rest.indexOf("/");
+	const authority = slash === -1 ? rest : rest.slice(0, slash);
+	const at = authority.lastIndexOf("@");
+	return at !== -1 && /[?#]/.test(authority.slice(0, at));
+}
+const URL_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
+/** `scheme://user:password@` at the start of a URL; the user info is removed. */
+const URL_USER_INFO = /^([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^/?#]*@/;
+/**
+* The resource of a payment without what can carry credentials: the query string, the fragment and the user info.
+* Works on the text, so names that are not URLs are kept as they are.
+*/
+function sanitizeResource(resource) {
+	const end = resource.search(/[?#]/);
+	return (end === -1 ? resource : resource.slice(0, end)).replace(URL_USER_INFO, "$1");
+}
 //#endregion
 //#region src/version.ts
-const VERSION = "0.3.0";
+const VERSION = "0.4.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -322,18 +398,37 @@ const NON_SENSITIVE_KEYS = /* @__PURE__ */ new Set([
 	ATTR_BLOCKCHAIN_TX_STATUS,
 	ATTR_BLOCKCHAIN_TX_REPLACEMENT_HASH,
 	ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON,
+	ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL,
+	ATTR_BLOCKCHAIN_PAYMENT_STATUS,
 	ATTR_ERROR_TYPE,
 	ATTR_EXCEPTION_TYPE
 ]);
 const TX_HASH = /^0x[0-9a-fA-F]{64}$/;
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+/** A non-negative integer that fits in 256 bits. */
+const AMOUNT = /^(0|[1-9][0-9]{0,77})$/;
+/** `error.type` of a payment whose outcome was never learned, as for a confirmation that timed out. */
+const PAYMENT_TIMEOUT = "timeout";
+const PAYMENT_STATUSES = /* @__PURE__ */ new Set([
+	BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED,
+	BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING,
+	BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED
+]);
 const REPLACEMENT_REASONS = /* @__PURE__ */ new Set([
 	BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPRICED,
 	BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED,
 	BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED
 ]);
-const NOOP_SEND = {
+/** Records nothing; its context is the parent, so a call run in it still nests under the caller. */
+const noopSend = (parent) => ({
+	context: parent,
 	end: () => {},
 	fail: () => {}
+});
+const NOOP_PAYMENT = {
+	end: () => {},
+	fail: () => {},
+	timeout: () => {}
 };
 const NOOP_CONFIRM = {
 	end: () => {},
@@ -358,7 +453,47 @@ function errorType(error) {
 	return error instanceof Error && error.name ? error.name : ERROR_TYPE_VALUE_OTHER;
 }
 const ERROR_TYPE_OVERRIDE = /^[A-Za-z0-9_.-]{1,64}$/;
+/** `value` if it is a short identifier, the only kind of free text recorded from a remote party. */
+function identifier(value) {
+	return typeof value === "string" && ERROR_TYPE_OVERRIDE.test(value) ? value : 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;
+	return typeof text === "string" && AMOUNT.test(text) ? text : void 0;
+}
 /** The `error.type` for a failure: an adapter's override when it is a short identifier, else the class name. */
+/** A finite number, an `HrTime` pair or a `Date`: what the deprecated positional `endTime` argument takes. */
+function isTimeInput(value) {
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.length === 2 && typeof value[0] === "number" && typeof value[1] === "number";
+	return Object.prototype.toString.call(value) === "[object Date]";
+}
+/**
+* Reads the options of a handle method called as `(what, options?)` or, deprecated, as `(what, endTime?, options?)`
+* (ADR 0014). A positional end time wins over `options.endTime`. Never throws: an argument of neither form, or an
+* end time that is not one, is ignored.
+*/
+function handleOptions(second, third) {
+	try {
+		const positional = isTimeInput(second) ? second : void 0;
+		const given = positional !== void 0 || second === void 0 ? third : second;
+		if (given !== void 0 && (typeof given !== "object" || given === null || isTimeInput(given))) {
+			_opentelemetry_api.diag.debug("hashspan: ignoring a handle argument that is neither options nor an end time");
+			return positional !== void 0 ? { endTime: positional } : {};
+		}
+		const options = given;
+		const endTime = positional ?? options?.endTime;
+		if (endTime !== void 0 && !isTimeInput(endTime)) _opentelemetry_api.diag.debug("hashspan: ignoring an end time that is not a TimeInput");
+		return {
+			endTime: isTimeInput(endTime) ? endTime : void 0,
+			errorType: options?.errorType
+		};
+	} catch (error) {
+		_opentelemetry_api.diag.debug(`hashspan: could not read handle options (${errorType(error)})`);
+		return {};
+	}
+}
 function reportedErrorType(error, options) {
 	const override = options?.errorType;
 	if (override === void 0) return errorType(error);
@@ -366,6 +501,12 @@ function reportedErrorType(error, options) {
 	_opentelemetry_api.diag.debug("hashspan: ignoring an error type that is not a short identifier");
 	return errorType(error);
 }
+/**
+* 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.4.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.
+*/
 function createTxTracker(options = {}) {
 	const links = new LinkStore({
 		ttlMs: options.linkTtlMs ?? DEFAULT_LINK_TTL_MS,
@@ -377,6 +518,7 @@ 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");
 	let tracer;
 	const getTracer = () => {
 		tracer ??= (options.tracerProvider ?? _opentelemetry_api.trace.getTracerProvider()).getTracer(INSTRUMENTATION_NAME, VERSION);
@@ -399,8 +541,9 @@ function createTxTracker(options = {}) {
 		return redacted;
 	};
 	/**
-	* 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 (docs/adr/0006-error-privacy.md).
+	* 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.4.0/docs/adr/0006-error-privacy.md).
 	*/
 	const exceptionAttributes = (type, error) => {
 		const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -454,6 +597,10 @@ 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) => {
+		if (typeof address === "string" && ADDRESS.test(address)) setAddress(attributes, key, address);
+	};
 	const baseAttributes = (chainId, operation, ctx) => ({
 		[ATTR_BLOCKCHAIN_SYSTEM]: "evm",
 		[ATTR_BLOCKCHAIN_CHAIN_ID]: chainId,
@@ -481,14 +628,23 @@ function createTxTracker(options = {}) {
 		}, parent);
 		const finish = finisher(span);
 		return {
-			end: (hash, endTime) => finish("record transaction hash", () => {
+			context: _opentelemetry_api.trace.setSpan(parent, span),
+			end: (result, second) => finish("record transaction hash", () => {
+				const hash = typeof result === "string" ? result : result?.hash;
+				if (typeof hash !== "string") {
+					_opentelemetry_api.diag.debug("hashspan: ending a send span without a transaction hash");
+					return;
+				}
 				links.set(input.chainId, hash, {
 					spanContext: span.spanContext(),
 					parent
 				});
 				span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_HASH]: hash }));
-			}, endTime),
-			fail: (error, endTime, options) => finish("record send failure", () => markError(span, reportedErrorType(error, options), error, errorType(error)), 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);
+			}
 		};
 	};
 	const receiptAttributes = (receipt) => {
@@ -568,7 +724,10 @@ function createTxTracker(options = {}) {
 		const { replacementReason: _reason, ...mined } = receipt;
 		confirm.receipt(mined, endTime);
 	};
-	/** Ends `shared` with `receipt`, attributing it to the transaction that was mined (docs/adr/0008). */
+	/**
+	* Ends `shared` with `receipt`, attributing it to the transaction that was mined
+	* (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0008-replaced-transactions.md).
+	*/
 	const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
 		const mined = receipt.transactionHash;
 		if (mined === void 0) {
@@ -617,20 +776,80 @@ function createTxTracker(options = {}) {
 			end();
 		};
 		return {
-			end: (receipt, endTime) => {
+			end: (receipt, second) => {
+				const { endTime } = handleOptions(second);
 				if (done || shared.ended) return;
 				done = true;
 				shared.active -= 1;
 				shared.ended = true;
 				safely("record receipt", () => endWithReceipt(chainId, hash, shared, receipt, endTime), void 0);
 			},
-			timeout: (endTime) => withdraw(() => shared.timeout(endTime)),
-			fail: (error, endTime) => withdraw(() => shared.fail(error, endTime))
+			timeout: (second) => {
+				const { endTime } = handleOptions(second);
+				withdraw(() => shared.timeout(endTime));
+			},
+			fail: (error, second) => {
+				const { endTime } = handleOptions(second);
+				withdraw(() => shared.fail(error, endTime));
+			}
+		};
+	};
+	const startPayment = (input, parentCtx) => {
+		const parent = parentCtx ?? _opentelemetry_api.context.active();
+		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);
+		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);
+		const paid = amount(input.amount);
+		if (paid !== void 0) attributes[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = paid;
+		const scheme = identifier(input.x402?.scheme);
+		if (scheme !== void 0) attributes[ATTR_X402_SCHEME] = scheme;
+		const resource = input.x402?.resource;
+		const recorded = typeof resource === "string" ? paymentResourceOf(resource, paymentResource) : void 0;
+		if (recorded) attributes[ATTR_X402_RESOURCE] = formatAddressesIn(recorded, formatAddress);
+		const span = getTracer().startSpan(`payment ${input.chainId}`, {
+			kind: _opentelemetry_api.SpanKind.CLIENT,
+			attributes: redact(attributes),
+			...input.startTime !== void 0 ? { startTime: input.startTime } : {}
+		}, parent);
+		const finish = finisher(span);
+		const recordSettlement = (settlement) => {
+			const status = settlement.status;
+			if (!PAYMENT_STATUSES.has(status)) {
+				_opentelemetry_api.diag.debug("hashspan: ignoring a payment settlement with an unknown status");
+				return;
+			}
+			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 (!knownPayer) setPaymentAddress(settled, ATTR_BLOCKCHAIN_PAYMENT_PAYER, settlement.payer);
+			const settledAmount = paid === void 0 ? amount(settlement.amount) : void 0;
+			if (settledAmount !== void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
+			span.setAttributes(redact(settled));
+			if (status === "failed") markError(span, identifier(settlement.errorReason) ?? "_OTHER");
+		};
+		return {
+			end: (settlement, options) => finish("record payment settlement", () => recordSettlement(settlement), handleOptions(options).endTime),
+			fail: (error, 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, PAYMENT_TIMEOUT), handleOptions(options).endTime)
 		};
 	};
 	return {
-		startSend: (input, parent) => safely("start send span", () => startSend(input, parent), NOOP_SEND),
-		startConfirm: (input, parent) => safely("start confirm span", () => startConfirm(input, parent), NOOP_CONFIRM)
+		startSend: (input, parent) => safely("start send span", () => startSend(input, parent), noopSend(parent ?? _opentelemetry_api.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)
 	};
 }
 //#endregion
@@ -640,6 +859,12 @@ exports.ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS = ATTR_BLOCKCHAIN_CONTRACT_F
 exports.ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME = ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME;
 exports.ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR = ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR;
 exports.ATTR_BLOCKCHAIN_OPERATION_NAME = ATTR_BLOCKCHAIN_OPERATION_NAME;
+exports.ATTR_BLOCKCHAIN_PAYMENT_AMOUNT = ATTR_BLOCKCHAIN_PAYMENT_AMOUNT;
+exports.ATTR_BLOCKCHAIN_PAYMENT_ASSET = ATTR_BLOCKCHAIN_PAYMENT_ASSET;
+exports.ATTR_BLOCKCHAIN_PAYMENT_PAYER = ATTR_BLOCKCHAIN_PAYMENT_PAYER;
+exports.ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL;
+exports.ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT = ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT;
+exports.ATTR_BLOCKCHAIN_PAYMENT_STATUS = ATTR_BLOCKCHAIN_PAYMENT_STATUS;
 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;
@@ -657,8 +882,15 @@ exports.ATTR_BLOCKCHAIN_TX_VALUE = ATTR_BLOCKCHAIN_TX_VALUE;
 exports.ATTR_ERROR_TYPE = ATTR_ERROR_TYPE;
 exports.ATTR_GEN_AI_AGENT_ID = ATTR_GEN_AI_AGENT_ID;
 exports.ATTR_GEN_AI_AGENT_NAME = ATTR_GEN_AI_AGENT_NAME;
+exports.ATTR_X402_RESOURCE = ATTR_X402_RESOURCE;
+exports.ATTR_X402_SCHEME = ATTR_X402_SCHEME;
 exports.BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM = BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM;
+exports.BLOCKCHAIN_OPERATION_NAME_VALUE_PAYMENT = BLOCKCHAIN_OPERATION_NAME_VALUE_PAYMENT;
 exports.BLOCKCHAIN_OPERATION_NAME_VALUE_SEND = BLOCKCHAIN_OPERATION_NAME_VALUE_SEND;
+exports.BLOCKCHAIN_PAYMENT_PROTOCOL_VALUE_X402 = BLOCKCHAIN_PAYMENT_PROTOCOL_VALUE_X402;
+exports.BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED = BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED;
+exports.BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING = BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING;
+exports.BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED = BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED;
 exports.BLOCKCHAIN_SYSTEM_VALUE_EVM = BLOCKCHAIN_SYSTEM_VALUE_EVM;
 exports.BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED = BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED;
 exports.BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED = BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED;