Security, privacy and stability

Evaluating hashspan for a team? This page collects the answers in one place, with a link to the source of each.

Can it touch my keys or move funds?

No. hashspan never signs or broadcasts a transaction, and it needs no private key. Its own RPC calls are read-only: it reads receipts, and replays a reverted transaction as a call to decode the reason (requests it adds).

It runs inside your app, and its instrumentation never throws into or changes the result of your call.

What does it record by default?

Data	Default	How to change it
Addresses (sender, recipient, payer, paymaster…)	Recorded, in lower case	address: 'hashed' or 'off', or your own hash function
Transaction hash	Recorded	Keep it: it is how spans are matched to the chain
Amounts (value, payment amount, fees)	Recorded	Remove from spans with a redact hook; the fee histogram keeps fees, so drop it with a metrics View
Agent identity (gen_ai.agent.*)	Recorded when set, also from incoming Baggage	agentFromBaggage: false; don’t put personal names in agent
Calldata arguments	Not recorded	Opt in with recordFunctionArguments
Error messages	Not recorded, only the error type	errorMessages: 'sanitized' or 'raw' to opt in
Paid URLs (x402, MPP)	Only the origin	paymentResource: 'path' or 'off'
JSON-RPC spans (RPC host and method)	Not recorded	Opt in with traceTransport() (viem)
Metrics	Durations and fees, by chain, operation and outcome; never an address, hash or agent identity	Drop a histogram with a metrics View

The full list is in what is recorded. The redact hook runs on every span attribute set, but not on metrics or JSON-RPC spans.

For strict privacy reviews

• Hashed mode is not secret. It is an unkeyed SHA-256, and addresses are public, so a hash can be matched by hashing candidates. Use 'off', or a keyed hash such as an HMAC with a secret you keep.
• Retention and location are your backend’s. hashspan keeps nothing; spans live where your OpenTelemetry backend stores them, for as long as it keeps them.

A strict setup:

import { createHmac } from 'node:crypto';
import { withHashspan } from '@hashspan/viem';

declare const key: string; // a secret from your secret store, not from code

// Strict: no plain addresses, no error text, no identity from incoming Baggage, no paid URLs.
export const strict = withHashspan({
  address: { mode: 'hashed', hash: (address) => `hmac:${createHmac('sha256', key).update(address).digest('hex').slice(0, 32)}` },
  errorMessages: 'off',
  agentFromBaggage: false,
  paymentResource: 'off',
});

The library sends no telemetry to the project. Spans go only to the OpenTelemetry backend you set up. Hashing or dropping addresses limits what your backend stores, but it is not anonymity: a transaction hash leads to its parties on chain. The privacy section lists every attribute each mode covers. To drop them in a Collector instead, see the Collector recipe.

How do I report a vulnerability?

Privately, through GitHub’s private vulnerability reporting, not in a public issue. The security policy says to expect an acknowledgement within 5 business days. A confirmed report then gets a fix, a disclosure date agreed with you, and a published advisory.

Security fixes go to the latest minor of each package: 1.x for core, viem, cdp and x402, and the latest 0.x for mpp. The policy also lists what is in and out of scope, such as an address recorded in a mode that should keep it out.

What does 1.0 keep stable?

• The public API. Since 1.0, a breaking change to the TypeScript API needs a major release. Each package’s API report lists what is public, and CI fails when it is stale (ADR 0027).
• Not yet the span and attribute names. They stay development. A renamed attribute or metric is recorded under both names for at least one minor release, announced in the changelog, with a schema version bump. A span name changes only in a minor release, announced the same way (change policy).

So your code keeps compiling across 1.x. Check the changelog before a minor upgrade if dashboards depend on attribute names.

How is it released?

From GitHub Actions, with npm provenance: npm shows a provenance badge for each version, linking it to its build. Each GitHub release carries a CycloneDX SBOM of the lockfile.

Who maintains it?

hashspan is open source under the Apache-2.0 license, maintained in the open on GitHub. Significant design decisions are recorded as ADRs. The license lets anyone use, change and fork it.