@hashspan/core 0.2.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
 
@@ -57,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
@@ -68,7 +72,7 @@ the instrumentation are reported through `diag` and never thrown into your code.
 |---|---|---|
 | `tracerProvider` | global provider | Tracer provider to use |
 | `address` | `'raw'` | `'raw'`, `'hashed'`, `'off'`, or `{ mode: 'hashed', hash: (address) => string }` |
-| `errorMessages` | `'off'` | What failed spans record about the error: `'off'` (type only), `'sanitized'` (first line, addresses per `address` mode, calldata removed; in `hashed` and `off` mode any hex longer than an address) or `'raw'` (full message and stack trace). `'raw'` can record RPC URLs that include API keys, as some libraries put the request URL in the message; `'sanitized'` keeps only the first line (viem puts the URL on a later line), which is best effort. See [ADR 0006](https://github.com/selimaytac/hashspan/blob/main/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.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 | 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 |
@@ -82,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
 
@@ -97,7 +101,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/main/docs/adr/0011-agent-identity-precedence.md)).
+  ([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

@@ -302,7 +302,7 @@ function resolveErrorMessageMode(mode) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -357,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,
@@ -406,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;
@@ -476,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

@@ -82,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;
@@ -196,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

@@ -82,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;
@@ -196,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

@@ -301,7 +301,7 @@ function resolveErrorMessageMode(mode) {
 }
 //#endregion
 //#region src/version.ts
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 //#endregion
 //#region src/tracker.ts
 const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -356,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,
@@ -405,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;
@@ -475,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.2.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",