npm - @hashspan/core - Versions diffs - 0.4.0 → 0.6.0 - Mend

@hashspan/core 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -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.4.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.4.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.4.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.4.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.4.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.4.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.4.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 CHANGED Viewed

@@ -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.4.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.4.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.4.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.4.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";
@@ -59,6 +59,14 @@ 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";
+/** 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";
@@ -78,9 +86,9 @@ const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED = "failed";
 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.
+* @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
+* `blockchain.tx.status`. The constant is removed in 1.0. See
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
 */
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -378,7 +386,7 @@ function sanitizeResource(resource) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.4.0";
+const VERSION = "0.6.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -400,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
 ]);
@@ -407,8 +416,8 @@ 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";
+/** `error.type` of a wait that gave up: a confirmation or a payment whose outcome was never learned. */
+const OBSERVER_TIMEOUT = "timeout";
 const PAYMENT_STATUSES = /* @__PURE__ */ new Set([
 	BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED,
 	BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING,
@@ -428,7 +437,8 @@ const noopSend = (parent) => ({
 const NOOP_PAYMENT = {
 	end: () => {},
 	fail: () => {},
-	timeout: () => {}
+	timeout: () => {},
+	link: () => {}
 };
 const NOOP_CONFIRM = {
 	end: () => {},
@@ -503,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.4.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.
 */
@@ -543,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.4.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 };
@@ -691,10 +701,7 @@ function createTxTracker(options = {}) {
 				span.setAttributes(redact(receiptAttributes(receipt)));
 				if (receipt.status === "reverted") markError(span, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED);
 			}, endTime),
-			timeout: (endTime) => finish("record confirmation timeout", () => {
-				span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_STATUS]: BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT }));
-				markError(span, BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT);
-			}, 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),
 			replaced: (hash, reason, endTime) => finish("record replacement", () => {
 				const attributes = {
@@ -726,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.4.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;
@@ -816,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)) {
@@ -824,16 +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 = paid === void 0 ? amount(settlement.amount) : void 0;
-			if (settledAmount !== void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
+			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");
 		};
@@ -843,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, PAYMENT_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 {
@@ -864,7 +880,9 @@ 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_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 CHANGED Viewed

@@ -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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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 {
@@ -252,15 +252,23 @@ interface PaymentSettlement {
   hash?: string | undefined;
   /** Address that paid, when the settlement reports it; recorded instead of the input's. */
   payer?: string | undefined;
-  /** Amount settled, when the settlement reports it; recorded instead of the input's. */
+  /**
+   * Amount settled, when the settlement reports it, recorded as `blockchain.payment.settled_amount`; also as
+   * `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.4.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. */
@@ -276,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
@@ -286,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.4.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";
@@ -310,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.4.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.4.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";
@@ -323,6 +337,14 @@ export declare const ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT: "blockchain.payment.reci
 export declare const ATTR_BLOCKCHAIN_PAYMENT_ASSET: "blockchain.payment.asset";
 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";
@@ -342,9 +364,9 @@ export declare const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED: "failed";
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS: "success";
 export declare 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.
+ * @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
+ * `blockchain.tx.status`. The constant is removed in 1.0. See
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
  */
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT: "timeout";
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED: "replaced";
@@ -361,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.4.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 {
   /**
@@ -379,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.4.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.
    */
@@ -387,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.4.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 CHANGED Viewed

@@ -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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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.4.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 {
@@ -252,15 +252,23 @@ interface PaymentSettlement {
   hash?: string | undefined;
   /** Address that paid, when the settlement reports it; recorded instead of the input's. */
   payer?: string | undefined;
-  /** Amount settled, when the settlement reports it; recorded instead of the input's. */
+  /**
+   * Amount settled, when the settlement reports it, recorded as `blockchain.payment.settled_amount`; also as
+   * `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.4.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. */
@@ -276,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
@@ -286,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.4.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";
@@ -310,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.4.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.4.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";
@@ -323,6 +337,14 @@ export declare const ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT: "blockchain.payment.reci
 export declare const ATTR_BLOCKCHAIN_PAYMENT_ASSET: "blockchain.payment.asset";
 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";
@@ -342,9 +364,9 @@ export declare const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED: "failed";
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS: "success";
 export declare 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.
+ * @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
+ * `blockchain.tx.status`. The constant is removed in 1.0. See
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
  */
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT: "timeout";
 export declare const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED: "replaced";
@@ -361,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.4.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 {
   /**
@@ -379,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.4.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.
    */
@@ -387,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.4.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 CHANGED Viewed

@@ -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.4.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.4.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.4.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.4.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";
@@ -58,6 +58,14 @@ 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";
+/** 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";
@@ -77,9 +85,9 @@ const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED = "failed";
 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.
+* @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
+* `blockchain.tx.status`. The constant is removed in 1.0. See
+* https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.6.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
 */
 const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
 const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -377,7 +385,7 @@ function sanitizeResource(resource) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.4.0";
+const VERSION = "0.6.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -399,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
 ]);
@@ -406,8 +415,8 @@ 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";
+/** `error.type` of a wait that gave up: a confirmation or a payment whose outcome was never learned. */
+const OBSERVER_TIMEOUT = "timeout";
 const PAYMENT_STATUSES = /* @__PURE__ */ new Set([
 	BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED,
 	BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING,
@@ -427,7 +436,8 @@ const noopSend = (parent) => ({
 const NOOP_PAYMENT = {
 	end: () => {},
 	fail: () => {},
-	timeout: () => {}
+	timeout: () => {},
+	link: () => {}
 };
 const NOOP_CONFIRM = {
 	end: () => {},
@@ -502,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.4.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.
 */
@@ -542,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.4.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 };
@@ -690,10 +700,7 @@ function createTxTracker(options = {}) {
 				span.setAttributes(redact(receiptAttributes(receipt)));
 				if (receipt.status === "reverted") markError(span, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED);
 			}, endTime),
-			timeout: (endTime) => finish("record confirmation timeout", () => {
-				span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_STATUS]: BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT }));
-				markError(span, BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT);
-			}, 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),
 			replaced: (hash, reason, endTime) => finish("record replacement", () => {
 				const attributes = {
@@ -725,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.4.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 +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)) {
@@ -823,16 +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 = paid === void 0 ? amount(settlement.amount) : void 0;
-			if (settledAmount !== void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
+			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");
 		};
@@ -842,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, PAYMENT_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 {
@@ -852,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_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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hashspan/core",
-  "version": "0.4.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",