@hashspan/core 0.1.0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ Transaction lifecycle tracing for the on-chain actions of AI agents, built on Op
   revert reason. It carries a span link to its `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/main/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.3.0/packages/viem) call it for you. Use the core directly to instrument any other send path.
 
 ## Install
 
@@ -17,7 +17,9 @@ The core is library-agnostic and read-only: it never signs, sends or fetches any
 npm install @hashspan/core @opentelemetry/api
 ```
 
-`@opentelemetry/api` is the only peer dependency. Bring your own OpenTelemetry SDK and exporter.
+`@opentelemetry/api` is the only peer dependency. Bring your own OpenTelemetry SDK and exporter. Requires Node.js 22.3
+or later; in other runtimes, `hashed` address mode needs a custom `hash` function and otherwise records no addresses,
+with a `diag` warning.
 
 ## Usage
 
@@ -55,9 +57,13 @@ confirm.end({
 share one confirm span. A receipt from any of them ends it; a timeout or failure ends it once every caller gave up.
 End every handle you start, since an open handle keeps the shared span open.
 
+`send.fail(error, endTime, { errorType })` records a library's machine-readable error code as `error.type` instead
+of the error's class name, if it is a short identifier (`[A-Za-z0-9_.-]`, at most 64 characters); `exception.type`
+stays the class name.
+
 Both calls accept an explicit parent `Context` as a second argument. An integration that learns about a call only
 after it started can record it after the fact: pass `startTime` in the input and the end time as the last argument
-of the handle method, e.g. `send.end(hash, endTime)` ([ADR 0009](https://github.com/selimaytac/hashspan/blob/main/docs/adr/0009-telemetry-off-the-call-path.md)). Every method is safe to call: failures inside
+of the handle method, e.g. `send.end(hash, endTime)` ([ADR 0009](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.3.0/docs/adr/0009-telemetry-off-the-call-path.md)). Every method is safe to call: failures inside
 the instrumentation are reported through `diag` and never thrown into your code.
 
 ## Options
@@ -66,9 +72,10 @@ the instrumentation are reported through `diag` and never thrown into your code.
 |---|---|---|
 | `tracerProvider` | global provider | Tracer provider to use |
 | `address` | `'raw'` | `'raw'`, `'hashed'`, `'off'`, or `{ mode: 'hashed', hash: (address) => string }` |
-| `errorMessages` | `'off'` | What failed spans record about the error: `'off'` (type only), `'sanitized'` (first line, addresses per `address` mode, calldata removed; in `hashed` and `off` mode any hex longer than an address) or `'raw'` (full message and stack trace) |
+| `errorMessages` | `'off'` | What failed spans record about the error: `'off'` (type only), `'sanitized'` (first line, addresses per `address` mode, calldata removed; in `hashed` and `off` mode any hex longer than an address) or `'raw'` (full message and stack trace). `'raw'` can record RPC URLs that include API keys, as some libraries put the request URL in the message; `'sanitized'` keeps only the first line (viem puts the URL on a later line), which is best effort. See [ADR 0006](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.3.0/docs/adr/0006-error-privacy.md) |
 | `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 | Fallback `{ id, name }`; Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` take precedence |
+| `agent` | none | Agent `{ id, name }`; a field set here always wins, unset fields come from the Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` |
+| `agentFromBaggage` | `true` | Read agent identity fields that `agent` leaves unset from Baggage; set to `false` in services that accept requests from outside their trust boundary |
 | `redact` | none | `(attributes) => attributes`, runs last on every attribute set, including exception event attributes; if it throws, only non-sensitive identifiers are kept |
 | `linkTtlMs` | `600000` | How long a sent transaction can be linked from its confirmation |
 | `maxTrackedTransactions` | `10000` | Upper bound on transactions kept for linking |
@@ -79,7 +86,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/main/docs/semconv.md).
+[docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.3.0/docs/semconv.md).
 
 ## Privacy notes
 
@@ -92,6 +99,9 @@ Attribute definitions:
   party APIs. Put only identifiers there that may leave your system, such as an opaque agent id. For identifiers
   that must stay internal, use the tracker's static `agent` option instead, which is recorded on spans but never
   propagated, or strip the entries before outbound calls.
+- **Inbound Baggage can claim an identity.** A caller can send Baggage entries with any agent id. A field set in the
+  `agent` option cannot be overridden that way; to ignore identity from Baggage entirely, set `agentFromBaggage: false`
+  ([ADR 0011](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.3.0/docs/adr/0011-agent-identity-precedence.md)).
 - The redaction hook (`redact`) runs last on every attribute set and on exception attributes; use it for anything
   else your policy forbids.
 

package/dist/index.cjs

@@ -3,11 +3,14 @@ let _opentelemetry_api = require("@opentelemetry/api");
 //#region src/agent.ts
 const ATTR_GEN_AI_AGENT_ID = "gen_ai.agent.id";
 const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
-/** Agent identity from baggage (preferred) or the static fallback, as GenAI attributes. */
-function agentAttributes(ctx, fallback) {
-	const baggage = _opentelemetry_api.propagation.getBaggage(ctx);
-	const id = baggage?.getEntry("gen_ai.agent.id")?.value ?? fallback?.id;
-	const name = baggage?.getEntry("gen_ai.agent.name")?.value ?? fallback?.name;
+/**
+* Agent identity as GenAI attributes. A field set in the static identity always wins; Baggage, which a remote caller
+* can set, only fills fields it leaves unset, and is not read at all with `fromBaggage` false (docs/adr/0011).
+*/
+function agentAttributes(ctx, identity, fromBaggage = true) {
+	const baggage = fromBaggage ? _opentelemetry_api.propagation.getBaggage(ctx) : void 0;
+	const id = identity?.id ?? baggage?.getEntry("gen_ai.agent.id")?.value;
+	const name = identity?.name ?? baggage?.getEntry("gen_ai.agent.name")?.value;
 	const attributes = {};
 	if (id !== void 0) attributes[ATTR_GEN_AI_AGENT_ID] = id;
 	if (name !== void 0) attributes[ATTR_GEN_AI_AGENT_NAME] = name;
@@ -299,7 +302,7 @@ function resolveErrorMessageMode(mode) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.1.0";
+const VERSION = "0.3.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -354,6 +357,15 @@ function toInt(value) {
 function errorType(error) {
 	return error instanceof Error && error.name ? error.name : ERROR_TYPE_VALUE_OTHER;
 }
+const ERROR_TYPE_OVERRIDE = /^[A-Za-z0-9_.-]{1,64}$/;
+/** The `error.type` for a failure: an adapter's override when it is a short identifier, else the class name. */
+function reportedErrorType(error, options) {
+	const override = options?.errorType;
+	if (override === void 0) return errorType(error);
+	if (typeof override === "string" && ERROR_TYPE_OVERRIDE.test(override)) return override;
+	_opentelemetry_api.diag.debug("hashspan: ignoring an error type that is not a short identifier");
+	return errorType(error);
+}
 function createTxTracker(options = {}) {
 	const links = new LinkStore({
 		ttlMs: options.linkTtlMs ?? DEFAULT_LINK_TTL_MS,
@@ -403,12 +415,15 @@ function createTxTracker(options = {}) {
 		if (error instanceof Error && error.stack) attributes[ATTR_EXCEPTION_STACKTRACE] = error.stack;
 		return attributes;
 	};
-	/** Error names are free text too: they follow the address mode and pass through the redaction hook. */
-	const markError = (span, errorName, error) => {
+	/**
+	* Error names are free text too: they follow the address mode and pass through the redaction hook.
+	* `exceptionName` is the class name for `exception.type` when `errorName` is an adapter's error type.
+	*/
+	const markError = (span, errorName, error, exceptionName = errorName) => {
 		const type = formatAddressesIn(errorName, formatAddress);
 		let message;
 		if (error !== void 0) {
-			const exception = redact(exceptionAttributes(type, error));
+			const exception = redact(exceptionAttributes(formatAddressesIn(exceptionName, formatAddress), error));
 			span.addEvent(EXCEPTION_EVENT, exception);
 			const recorded = exception[ATTR_EXCEPTION_MESSAGE];
 			if (typeof recorded === "string") message = recorded;
@@ -443,7 +458,7 @@ function createTxTracker(options = {}) {
 		[ATTR_BLOCKCHAIN_SYSTEM]: "evm",
 		[ATTR_BLOCKCHAIN_CHAIN_ID]: chainId,
 		[ATTR_BLOCKCHAIN_OPERATION_NAME]: operation,
-		...agentAttributes(ctx, options.agent)
+		...agentAttributes(ctx, options.agent, options.agentFromBaggage !== false)
 	});
 	const startSend = (input, parentCtx) => {
 		const parent = parentCtx ?? _opentelemetry_api.context.active();
@@ -473,7 +488,7 @@ function createTxTracker(options = {}) {
 				});
 				span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_HASH]: hash }));
 			}, endTime),
-			fail: (error, endTime) => finish("record send failure", () => markError(span, errorType(error), error), endTime)
+			fail: (error, endTime, options) => finish("record send failure", () => markError(span, reportedErrorType(error, options), error, errorType(error)), endTime)
 		};
 	};
 	const receiptAttributes = (receipt) => {

package/dist/index.d.cts

@@ -38,8 +38,17 @@ interface TxTrackerOptions {
    * text; addresses in them follow the address mode and the redaction hook runs on them.
    */
   recordFunctionArguments?: boolean | undefined;
-  /** Fallback agent identity. Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` take precedence. */
+  /**
+   * 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 (docs/adr/0011).
+   */
   agent?: AgentIdentity | undefined;
+  /**
+   * Read agent identity fields that `agent` leaves unset from Baggage. Default: true. Baggage travels with requests
+   * between services, so a remote caller can set it; services that accept requests from outside their trust boundary
+   * should set this to false.
+   */
+  agentFromBaggage?: boolean | undefined;
   /**
    * Runs last on every attribute set and returns the attributes to record.
    * If it throws, only non-sensitive identifiers (system, chain id, operation, hash) are recorded.
@@ -73,7 +82,16 @@ interface SendHandle {
   /** Ends the send span successfully once the transaction hash is known; `endTime` defaults to now. */
   end(hash: string, endTime?: TimeInput): void;
   /** Ends the send span with an error (signing, simulation or broadcast failure); `endTime` defaults to now. */
-  fail(error: unknown, endTime?: TimeInput): void;
+  fail(error: unknown, endTime?: TimeInput, options?: FailOptions): void;
+}
+interface FailOptions {
+  /**
+   * `error.type` to record instead of the error's class name, for adapters whose library reports a stable,
+   * machine-readable error code (for example a wallet API's error type). Recorded only if it matches
+   * `/^[A-Za-z0-9_.-]{1,64}$/`, so that the attribute keeps a bounded set of values; otherwise the class name is
+   * recorded. `exception.type` is always the class name.
+   */
+  errorType?: string | undefined;
 }
 interface ConfirmInput {
   chainId: number;
@@ -187,4 +205,4 @@ export declare function createTxTracker(options?: TxTrackerOptions): TxTracker;
 //#region src/version.d.ts
 export declare const VERSION: string;
 //#endregion
-export type { AddressMode, AddressOptions, AgentIdentity, ConfirmHandle, ConfirmInput, ErrorMessageMode, ReceiptLike, ReplacementReason, SendHandle, SendInput, TxTracker, TxTrackerOptions };
+export type { AddressMode, AddressOptions, AgentIdentity, ConfirmHandle, ConfirmInput, ErrorMessageMode, FailOptions, ReceiptLike, ReplacementReason, SendHandle, SendInput, TxTracker, TxTrackerOptions };

package/dist/index.d.mts

@@ -38,8 +38,17 @@ interface TxTrackerOptions {
    * text; addresses in them follow the address mode and the redaction hook runs on them.
    */
   recordFunctionArguments?: boolean | undefined;
-  /** Fallback agent identity. Baggage entries `gen_ai.agent.id` / `gen_ai.agent.name` take precedence. */
+  /**
+   * 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 (docs/adr/0011).
+   */
   agent?: AgentIdentity | undefined;
+  /**
+   * Read agent identity fields that `agent` leaves unset from Baggage. Default: true. Baggage travels with requests
+   * between services, so a remote caller can set it; services that accept requests from outside their trust boundary
+   * should set this to false.
+   */
+  agentFromBaggage?: boolean | undefined;
   /**
    * Runs last on every attribute set and returns the attributes to record.
    * If it throws, only non-sensitive identifiers (system, chain id, operation, hash) are recorded.
@@ -73,7 +82,16 @@ interface SendHandle {
   /** Ends the send span successfully once the transaction hash is known; `endTime` defaults to now. */
   end(hash: string, endTime?: TimeInput): void;
   /** Ends the send span with an error (signing, simulation or broadcast failure); `endTime` defaults to now. */
-  fail(error: unknown, endTime?: TimeInput): void;
+  fail(error: unknown, endTime?: TimeInput, options?: FailOptions): void;
+}
+interface FailOptions {
+  /**
+   * `error.type` to record instead of the error's class name, for adapters whose library reports a stable,
+   * machine-readable error code (for example a wallet API's error type). Recorded only if it matches
+   * `/^[A-Za-z0-9_.-]{1,64}$/`, so that the attribute keeps a bounded set of values; otherwise the class name is
+   * recorded. `exception.type` is always the class name.
+   */
+  errorType?: string | undefined;
 }
 interface ConfirmInput {
   chainId: number;
@@ -187,4 +205,4 @@ export declare function createTxTracker(options?: TxTrackerOptions): TxTracker;
 //#region src/version.d.ts
 export declare const VERSION: string;
 //#endregion
-export type { AddressMode, AddressOptions, AgentIdentity, ConfirmHandle, ConfirmInput, ErrorMessageMode, ReceiptLike, ReplacementReason, SendHandle, SendInput, TxTracker, TxTrackerOptions };
+export type { AddressMode, AddressOptions, AgentIdentity, ConfirmHandle, ConfirmInput, ErrorMessageMode, FailOptions, ReceiptLike, ReplacementReason, SendHandle, SendInput, TxTracker, TxTrackerOptions };

package/dist/index.mjs

@@ -2,11 +2,14 @@ import { SpanKind, SpanStatusCode, context, diag, propagation, trace } from "@op
 //#region src/agent.ts
 const ATTR_GEN_AI_AGENT_ID = "gen_ai.agent.id";
 const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
-/** Agent identity from baggage (preferred) or the static fallback, as GenAI attributes. */
-function agentAttributes(ctx, fallback) {
-	const baggage = propagation.getBaggage(ctx);
-	const id = baggage?.getEntry("gen_ai.agent.id")?.value ?? fallback?.id;
-	const name = baggage?.getEntry("gen_ai.agent.name")?.value ?? fallback?.name;
+/**
+* Agent identity as GenAI attributes. A field set in the static identity always wins; Baggage, which a remote caller
+* can set, only fills fields it leaves unset, and is not read at all with `fromBaggage` false (docs/adr/0011).
+*/
+function agentAttributes(ctx, identity, fromBaggage = true) {
+	const baggage = fromBaggage ? propagation.getBaggage(ctx) : void 0;
+	const id = identity?.id ?? baggage?.getEntry("gen_ai.agent.id")?.value;
+	const name = identity?.name ?? baggage?.getEntry("gen_ai.agent.name")?.value;
 	const attributes = {};
 	if (id !== void 0) attributes[ATTR_GEN_AI_AGENT_ID] = id;
 	if (name !== void 0) attributes[ATTR_GEN_AI_AGENT_NAME] = name;
@@ -298,7 +301,7 @@ function resolveErrorMessageMode(mode) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.1.0";
+const VERSION = "0.3.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -353,6 +356,15 @@ function toInt(value) {
 function errorType(error) {
 	return error instanceof Error && error.name ? error.name : ERROR_TYPE_VALUE_OTHER;
 }
+const ERROR_TYPE_OVERRIDE = /^[A-Za-z0-9_.-]{1,64}$/;
+/** The `error.type` for a failure: an adapter's override when it is a short identifier, else the class name. */
+function reportedErrorType(error, options) {
+	const override = options?.errorType;
+	if (override === void 0) return errorType(error);
+	if (typeof override === "string" && ERROR_TYPE_OVERRIDE.test(override)) return override;
+	diag.debug("hashspan: ignoring an error type that is not a short identifier");
+	return errorType(error);
+}
 function createTxTracker(options = {}) {
 	const links = new LinkStore({
 		ttlMs: options.linkTtlMs ?? DEFAULT_LINK_TTL_MS,
@@ -402,12 +414,15 @@ function createTxTracker(options = {}) {
 		if (error instanceof Error && error.stack) attributes[ATTR_EXCEPTION_STACKTRACE] = error.stack;
 		return attributes;
 	};
-	/** Error names are free text too: they follow the address mode and pass through the redaction hook. */
-	const markError = (span, errorName, error) => {
+	/**
+	* Error names are free text too: they follow the address mode and pass through the redaction hook.
+	* `exceptionName` is the class name for `exception.type` when `errorName` is an adapter's error type.
+	*/
+	const markError = (span, errorName, error, exceptionName = errorName) => {
 		const type = formatAddressesIn(errorName, formatAddress);
 		let message;
 		if (error !== void 0) {
-			const exception = redact(exceptionAttributes(type, error));
+			const exception = redact(exceptionAttributes(formatAddressesIn(exceptionName, formatAddress), error));
 			span.addEvent(EXCEPTION_EVENT, exception);
 			const recorded = exception[ATTR_EXCEPTION_MESSAGE];
 			if (typeof recorded === "string") message = recorded;
@@ -442,7 +457,7 @@ function createTxTracker(options = {}) {
 		[ATTR_BLOCKCHAIN_SYSTEM]: "evm",
 		[ATTR_BLOCKCHAIN_CHAIN_ID]: chainId,
 		[ATTR_BLOCKCHAIN_OPERATION_NAME]: operation,
-		...agentAttributes(ctx, options.agent)
+		...agentAttributes(ctx, options.agent, options.agentFromBaggage !== false)
 	});
 	const startSend = (input, parentCtx) => {
 		const parent = parentCtx ?? context.active();
@@ -472,7 +487,7 @@ function createTxTracker(options = {}) {
 				});
 				span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_HASH]: hash }));
 			}, endTime),
-			fail: (error, endTime) => finish("record send failure", () => markError(span, errorType(error), error), endTime)
+			fail: (error, endTime, options) => finish("record send failure", () => markError(span, reportedErrorType(error, options), error, errorType(error)), endTime)
 		};
 	};
 	const receiptAttributes = (receipt) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hashspan/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Transaction lifecycle tracing for on-chain actions of AI agents, built on OpenTelemetry.",
   "license": "Apache-2.0",
   "author": "Selim Aytac",
@@ -57,7 +57,7 @@
     "@opentelemetry/sdk-trace-node": "^2.11.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.3.0"
   },
   "scripts": {
     "build": "tsdown",