@hashspan/core 0.5.0 → 0.6.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.6.0/packages/viem) call it for you. Use the core directly to instrument any other send path.
 
 ## Install
 
@@ -69,14 +69,14 @@ 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.6.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.6.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.6.0/docs/adr/0014-core-api-boundary.md)).
 
 ## Options
 
@@ -84,7 +84,7 @@ until 1.0 ([ADR 0014](https://github.com/selimaytac/hashspan/blob/@hashspan/core
 |---|---|---|
 | `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.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.6.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` |
@@ -99,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.5.0/docs/semconv.md).
+[docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/semconv.md).
 
 ## Privacy notes
 
@@ -114,7 +114,7 @@ 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)).
+  ([ADR 0011](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.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,

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.6.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.6.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.6.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.6.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.6.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.6.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
 */
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -380,7 +386,7 @@ function sanitizeResource(resource) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.5.0";
+const VERSION = "0.6.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -402,6 +408,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 +437,8 @@ const noopSend = (parent) => ({
 const NOOP_PAYMENT = {
 	end: () => {},
 	fail: () => {},
-	timeout: () => {}
+	timeout: () => {},
+	link: () => {}
 };
 const NOOP_CONFIRM = {
 	end: () => {},
@@ -505,7 +513,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.6.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.
 */
@@ -545,7 +553,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.6.0/docs/adr/0006-error-privacy.md).
 	*/
 	const exceptionAttributes = (type, error) => {
 		const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -725,7 +733,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.6.0/docs/adr/0008-replaced-transactions.md).
 	*/
 	const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
 		const mined = receipt.transactionHash;
@@ -815,6 +823,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 +840,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 +858,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 +882,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;

package/dist/index.d.cts

@@ -2,12 +2,12 @@ import { Attributes, Context, TimeInput, TracerProvider } from "@opentelemetry/a
 //#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.6.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.6.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
@@ -61,7 +61,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.6.0/docs/adr/0011-agent-identity-precedence.md).
    */
   agent?: AgentIdentity | undefined;
   /**
@@ -75,8 +75,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 +103,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.6.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 +112,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.6.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.6.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 +182,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.6.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 +192,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.6.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 +216,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.6.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 +257,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.6.0/docs/adr/0014-core-api-boundary.md).
  */
 interface PaymentHandle {
   /** Ends the payment span with its settlement. */
@@ -279,6 +284,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 +300,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.6.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 +324,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.6.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.6.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 +339,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.6.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 +366,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.6.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";
@@ -366,7 +383,7 @@ export declare const ERROR_TYPE_VALUE_OTHER: "_OTHER";
 /**
  * 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.6.0/docs/adr/0014-core-api-boundary.md).
  */
 interface TxTracker {
   /**
@@ -384,7 +401,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.6.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 +409,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.6.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

@@ -2,12 +2,12 @@ import { Attributes, Context, TimeInput, TracerProvider } from "@opentelemetry/a
 //#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.6.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.6.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
@@ -61,7 +61,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.6.0/docs/adr/0011-agent-identity-precedence.md).
    */
   agent?: AgentIdentity | undefined;
   /**
@@ -75,8 +75,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 +103,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.6.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 +112,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.6.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.6.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 +182,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.6.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 +192,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.6.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 +216,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.6.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 +257,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.6.0/docs/adr/0014-core-api-boundary.md).
  */
 interface PaymentHandle {
   /** Ends the payment span with its settlement. */
@@ -279,6 +284,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 +300,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.6.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 +324,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.6.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.6.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 +339,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.6.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 +366,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.6.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";
@@ -366,7 +383,7 @@ export declare const ERROR_TYPE_VALUE_OTHER: "_OTHER";
 /**
  * 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.6.0/docs/adr/0014-core-api-boundary.md).
  */
 interface TxTracker {
   /**
@@ -384,7 +401,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.6.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 +409,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.6.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

@@ -5,7 +5,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.6.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.6.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.6.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.6.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.6.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.6.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
 */
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -379,7 +385,7 @@ function sanitizeResource(resource) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.5.0";
+const VERSION = "0.6.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -401,6 +407,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 +436,8 @@ const noopSend = (parent) => ({
 const NOOP_PAYMENT = {
 	end: () => {},
 	fail: () => {},
-	timeout: () => {}
+	timeout: () => {},
+	link: () => {}
 };
 const NOOP_CONFIRM = {
 	end: () => {},
@@ -504,7 +512,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.6.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.
 */
@@ -544,7 +552,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.6.0/docs/adr/0006-error-privacy.md).
 	*/
 	const exceptionAttributes = (type, error) => {
 		const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -724,7 +732,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.6.0/docs/adr/0008-replaced-transactions.md).
 	*/
 	const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
 		const mined = receipt.transactionHash;
@@ -814,6 +822,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 +839,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 +857,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 +868,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, VERSION, createTxTracker };

package/package.json

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