@hashspan/core 0.0.0 → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,621 @@
+import { SpanKind, SpanStatusCode, context, diag, propagation, trace } from "@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 = 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;
+	const attributes = {};
+	if (id !== void 0) attributes[ATTR_GEN_AI_AGENT_ID] = id;
+	if (name !== void 0) attributes[ATTR_GEN_AI_AGENT_NAME] = name;
+	return attributes;
+}
+//#endregion
+//#region src/attributes.ts
+/**
+* Attribute keys emitted by hashspan.
+*
+* Stability: development. See 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";
+const ATTR_BLOCKCHAIN_CHAIN_ID = "blockchain.chain.id";
+const ATTR_BLOCKCHAIN_OPERATION_NAME = "blockchain.operation.name";
+const ATTR_BLOCKCHAIN_TX_HASH = "blockchain.tx.hash";
+const ATTR_BLOCKCHAIN_TX_FROM = "blockchain.tx.from";
+const ATTR_BLOCKCHAIN_TX_TO = "blockchain.tx.to";
+const ATTR_BLOCKCHAIN_TX_VALUE = "blockchain.tx.value";
+const ATTR_BLOCKCHAIN_TX_NONCE = "blockchain.tx.nonce";
+const ATTR_BLOCKCHAIN_TX_STATUS = "blockchain.tx.status";
+const ATTR_BLOCKCHAIN_TX_GAS_USED = "blockchain.tx.gas.used";
+const ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE = "blockchain.tx.effective_gas_price";
+const ATTR_BLOCKCHAIN_TX_L1_FEE = "blockchain.tx.l1_fee";
+const ATTR_BLOCKCHAIN_TX_FEE = "blockchain.tx.fee";
+const ATTR_BLOCKCHAIN_TX_REVERT_REASON = "blockchain.tx.revert.reason";
+const ATTR_BLOCKCHAIN_TX_REPLACEMENT_HASH = "blockchain.tx.replacement.hash";
+const ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON = "blockchain.tx.replacement.reason";
+const ATTR_BLOCKCHAIN_BLOCK_NUMBER = "blockchain.block.number";
+const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME = "blockchain.contract.function.name";
+const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR = "blockchain.contract.function.selector";
+/** Opt-in: decoded call arguments as a JSON array. See docs/adr/0004-privacy-defaults.md. */
+const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS = "blockchain.contract.function.arguments";
+/** Values for {@link ATTR_BLOCKCHAIN_SYSTEM}. */
+const BLOCKCHAIN_SYSTEM_VALUE_EVM = "evm";
+/** Values for {@link ATTR_BLOCKCHAIN_OPERATION_NAME}. */
+const BLOCKCHAIN_OPERATION_NAME_VALUE_SEND = "send";
+const BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM = "confirm";
+/** Values for {@link ATTR_BLOCKCHAIN_TX_STATUS}. */
+const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS = "success";
+const BLOCKCHAIN_TX_STATUS_VALUE_REVERTED = "reverted";
+const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
+const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
+/** Values for {@link ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON}, as reported by the instrumented library. */
+const BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPRICED = "repriced";
+const BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED = "cancelled";
+const BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED = "replaced";
+/** Reused from OpenTelemetry general conventions. */
+const ATTR_ERROR_TYPE = "error.type";
+/** Fallback {@link ATTR_ERROR_TYPE} value when the error has no name. */
+const ERROR_TYPE_VALUE_OTHER = "_OTHER";
+//#endregion
+//#region src/confirm-registry.ts
+/**
+* Bounded registry from (chainId, tx hash) to its in-flight confirm span, or to "settled" for a while after a
+* receipt was recorded, so each transaction gets one confirm span per tracker.
+*/
+var ConfirmRegistry = class ConfirmRegistry {
+	entries = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxEntries;
+	constructor(options) {
+		this.ttlMs = options.ttlMs;
+		this.maxEntries = options.maxEntries;
+	}
+	/** The in-flight confirm span, `'settled'` if the transaction recently got a receipt, else undefined. */
+	get(chainId, hash) {
+		const key = ConfirmRegistry.key(chainId, hash);
+		const entry = this.entries.get(key);
+		if (!entry) return void 0;
+		if ("confirm" in entry) return entry.confirm;
+		if (entry.settledUntil > Date.now()) return "settled";
+		this.entries.delete(key);
+	}
+	start(chainId, hash, confirm) {
+		this.put(ConfirmRegistry.key(chainId, hash), { confirm });
+	}
+	/** Marks `confirm` as settled, unless the registry has since moved on from it. */
+	settle(chainId, hash, confirm) {
+		const key = ConfirmRegistry.key(chainId, hash);
+		if (this.isCurrent(key, confirm)) this.put(key, { settledUntil: Date.now() + this.ttlMs });
+	}
+	/** Forgets `confirm` so that a retry starts a new span, unless the registry has since moved on from it. */
+	release(chainId, hash, confirm) {
+		const key = ConfirmRegistry.key(chainId, hash);
+		if (this.isCurrent(key, confirm)) this.entries.delete(key);
+	}
+	isCurrent(key, confirm) {
+		const entry = this.entries.get(key);
+		return entry !== void 0 && "confirm" in entry && entry.confirm === confirm;
+	}
+	put(key, entry) {
+		this.entries.delete(key);
+		this.entries.set(key, entry);
+		for (const oldest of this.entries.keys()) {
+			if (this.entries.size <= this.maxEntries) break;
+			this.entries.delete(oldest);
+		}
+	}
+	static key(chainId, hash) {
+		return `${chainId}:${hash.toLowerCase()}`;
+	}
+};
+//#endregion
+//#region src/link-store.ts
+/** Bounded, TTL-evicted map from (chainId, tx hash) to the send span it came from. */
+var LinkStore = class LinkStore {
+	entries = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxEntries;
+	constructor(options) {
+		this.ttlMs = options.ttlMs;
+		this.maxEntries = options.maxEntries;
+	}
+	get size() {
+		return this.entries.size;
+	}
+	set(chainId, hash, value) {
+		const key = LinkStore.key(chainId, hash);
+		this.entries.delete(key);
+		this.entries.set(key, {
+			...value,
+			expiresAt: Date.now() + this.ttlMs
+		});
+		for (const oldest of this.entries.keys()) {
+			if (this.entries.size <= this.maxEntries) break;
+			this.entries.delete(oldest);
+		}
+	}
+	get(chainId, hash) {
+		const key = LinkStore.key(chainId, hash);
+		const entry = this.entries.get(key);
+		if (!entry) return void 0;
+		if (entry.expiresAt <= Date.now()) {
+			this.entries.delete(key);
+			return;
+		}
+		return entry;
+	}
+	static key(chainId, hash) {
+		return `${chainId}:${hash.toLowerCase()}`;
+	}
+};
+//#endregion
+//#region src/privacy.ts
+const formatter = (format, protectsAddresses) => Object.assign(format, { protectsAddresses });
+/** Records no addresses; the fallback whenever the address mode cannot be applied. */
+const OFF_ADDRESS_FORMATTER = formatter(() => void 0, true);
+/** Loads node:crypto lazily so the package stays importable in non-Node runtimes. */
+function defaultHash() {
+	const getBuiltinModule = globalThis.process?.getBuiltinModule;
+	const crypto = getBuiltinModule?.("node:crypto");
+	if (!crypto) return void 0;
+	return (address) => `sha256:${crypto.createHash("sha256").update(address).digest("hex").slice(0, 32)}`;
+}
+function resolveAddressFormatter(option) {
+	const { mode, hash } = typeof option === "object" ? option : {
+		mode: option ?? "raw",
+		hash: void 0
+	};
+	switch (mode) {
+		case "raw": return formatter((address) => address, false);
+		case "off": return OFF_ADDRESS_FORMATTER;
+		case "hashed": {
+			const hashFn = hash ?? defaultHash();
+			if (!hashFn) {
+				diag.warn("hashspan: no SHA-256 available in this runtime; addresses will not be recorded");
+				return OFF_ADDRESS_FORMATTER;
+			}
+			return formatter((address) => hashFn(address.toLowerCase()), true);
+		}
+		default:
+			diag.warn(`hashspan: unknown address mode "${String(mode)}"; addresses will not be recorded`);
+			return OFF_ADDRESS_FORMATTER;
+	}
+}
+/** 0x-prefixed hex. Unprefixed hex and addresses written as numbers are not detected. */
+const HEX = /0[xX][0-9a-fA-F]+/g;
+const ADDRESS_LENGTH = 42;
+/**
+* Longest hex kept in sanitized error messages in raw address mode: a 32-byte word such as a transaction hash. In
+* `off` and `hashed` mode, {@link formatAddressesIn} already replaces any hex longer than an address.
+*/
+const MAX_HEX_LENGTH = 66;
+const MAX_MESSAGE_LENGTH = 256;
+/**
+* Rewrites every address in `text` with the address mode (`<address>` when it records none). In `off` and `hashed`
+* mode, hex values longer than an address become `<hex>`, because they can embed one.
+*/
+function formatAddressesIn(text, formatAddress) {
+	return text.replace(HEX, (hex) => {
+		if (hex.length === ADDRESS_LENGTH) return formatAddress(hex) ?? "<address>";
+		return hex.length > ADDRESS_LENGTH && formatAddress.protectsAddresses ? "<hex>" : hex;
+	});
+}
+/**
+* First line of an error message with addresses per address mode and longer hex data (such as calldata)
+* replaced by `<hex>`. Best effort: other free text is kept, so the redaction hook still runs on the result.
+*/
+function sanitizeErrorMessage(message, formatAddress) {
+	const sanitized = formatAddressesIn(message.split("\n", 1)[0]?.trim() ?? "", formatAddress).replace(HEX, (hex) => hex.length > MAX_HEX_LENGTH ? "<hex>" : hex);
+	return sanitized.length > MAX_MESSAGE_LENGTH ? `${sanitized.slice(0, MAX_MESSAGE_LENGTH)}...` : sanitized;
+}
+const MAX_ARGUMENTS_LENGTH = 4096;
+const MAX_ARGUMENTS_DEPTH = 32;
+var ArgumentsLimitReached = class extends Error {};
+/**
+* Call arguments as a JSON array: bigints as decimal strings, addresses per address mode (see
+* {@link formatAddressesIn}), at most `MAX_ARGUMENTS_LENGTH` characters followed by `...`.
+*
+* Side-effect free for ordinary values: it reads only own enumerable data properties and never calls `toJSON()` or
+* getters (so a `Date` records as `{}`). A Proxy's traps still run, as for any property read; use the redaction
+* hook, or leave arguments off, for values that are Proxies. It stops after the value that crosses the length limit instead of walking the rest. Functions, symbols and `undefined` are skipped in objects and written as `null` in arrays, as in
+* JSON. Throws for cycles and for nesting deeper than `MAX_ARGUMENTS_DEPTH`.
+*/
+function serializeFunctionArguments(args, formatAddress) {
+	let out = "";
+	const write = (chunk) => {
+		out += chunk;
+		if (out.length > MAX_ARGUMENTS_LENGTH) throw new ArgumentsLimitReached();
+	};
+	const text = (value) => JSON.stringify(formatAddressesIn(value, formatAddress));
+	const ancestors = /* @__PURE__ */ new Set();
+	/** Writes `value`; returns false, writing nothing, when it has no JSON representation. */
+	const walk = (value, depth) => {
+		switch (typeof value) {
+			case "string":
+				write(text(value));
+				return true;
+			case "bigint":
+				write(`"${value.toString()}"`);
+				return true;
+			case "number":
+				write(Number.isFinite(value) ? String(value) : "null");
+				return true;
+			case "boolean":
+				write(value ? "true" : "false");
+				return true;
+			case "object": break;
+			default: return false;
+		}
+		if (value === null) {
+			write("null");
+			return true;
+		}
+		if (ancestors.has(value)) throw new TypeError("cyclic function arguments");
+		if (depth >= MAX_ARGUMENTS_DEPTH) throw new TypeError("function arguments nested too deeply");
+		ancestors.add(value);
+		const own = (key) => Object.getOwnPropertyDescriptor(value, key);
+		if (Array.isArray(value)) {
+			write("[");
+			const length = own("length")?.value;
+			for (let i = 0; i < (typeof length === "number" ? length : 0); i++) {
+				if (i > 0) write(",");
+				const element = own(String(i));
+				if (!element || !("value" in element) || !walk(element.value, depth + 1)) write("null");
+			}
+			write("]");
+		} else {
+			write("{");
+			let first = true;
+			for (const key of Object.keys(value)) {
+				const descriptor = own(key);
+				if (!descriptor || !("value" in descriptor)) continue;
+				const kind = typeof descriptor.value;
+				if (kind === "undefined" || kind === "function" || kind === "symbol") continue;
+				write(`${first ? "" : ","}${text(key)}:`);
+				first = false;
+				walk(descriptor.value, depth + 1);
+			}
+			write("}");
+		}
+		ancestors.delete(value);
+		return true;
+	};
+	try {
+		walk(args, 0);
+		return out;
+	} catch (error) {
+		if (error instanceof ArgumentsLimitReached) return `${out.slice(0, MAX_ARGUMENTS_LENGTH)}...`;
+		throw error;
+	}
+}
+function resolveErrorMessageMode(mode) {
+	if (mode === void 0 || mode === "off" || mode === "sanitized" || mode === "raw") return mode ?? "off";
+	diag.warn(`hashspan: unknown error message mode "${String(mode)}"; recording error types only`);
+	return "off";
+}
+//#endregion
+//#region src/version.ts
+const VERSION = "0.1.0";
+//#endregion
+//#region src/tracker.ts
+const INSTRUMENTATION_NAME = "@hashspan/core";
+const DEFAULT_LINK_TTL_MS = 6e5;
+const DEFAULT_MAX_TRACKED = 1e4;
+/** OpenTelemetry exception event and attributes. */
+const EXCEPTION_EVENT = "exception";
+const ATTR_EXCEPTION_TYPE = "exception.type";
+const ATTR_EXCEPTION_MESSAGE = "exception.message";
+const ATTR_EXCEPTION_STACKTRACE = "exception.stacktrace";
+/** Attributes kept when the redaction hook fails (fail closed). */
+const NON_SENSITIVE_KEYS = /* @__PURE__ */ new Set([
+	ATTR_BLOCKCHAIN_SYSTEM,
+	ATTR_BLOCKCHAIN_CHAIN_ID,
+	ATTR_BLOCKCHAIN_OPERATION_NAME,
+	ATTR_BLOCKCHAIN_TX_HASH,
+	ATTR_BLOCKCHAIN_TX_STATUS,
+	ATTR_BLOCKCHAIN_TX_REPLACEMENT_HASH,
+	ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON,
+	ATTR_ERROR_TYPE,
+	ATTR_EXCEPTION_TYPE
+]);
+const TX_HASH = /^0x[0-9a-fA-F]{64}$/;
+const REPLACEMENT_REASONS = /* @__PURE__ */ new Set([
+	BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPRICED,
+	BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED,
+	BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED
+]);
+const NOOP_SEND = {
+	end: () => {},
+	fail: () => {}
+};
+const NOOP_CONFIRM = {
+	end: () => {},
+	timeout: () => {},
+	fail: () => {}
+};
+/** Runs `fn`, logging instead of throwing: instrumentation must never break the caller. */
+function safely(what, fn, fallback) {
+	try {
+		return fn();
+	} catch (error) {
+		diag.error(`hashspan: failed to ${what}`, error);
+		return fallback;
+	}
+}
+function toInt(value) {
+	if (typeof value === "bigint") return Number(value);
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	throw new TypeError(`expected bigint or number, got ${typeof value}`);
+}
+function errorType(error) {
+	return error instanceof Error && error.name ? error.name : ERROR_TYPE_VALUE_OTHER;
+}
+function createTxTracker(options = {}) {
+	const links = new LinkStore({
+		ttlMs: options.linkTtlMs ?? DEFAULT_LINK_TTL_MS,
+		maxEntries: options.maxTrackedTransactions ?? DEFAULT_MAX_TRACKED
+	});
+	const confirmations = new ConfirmRegistry({
+		ttlMs: options.linkTtlMs ?? DEFAULT_LINK_TTL_MS,
+		maxEntries: options.maxTrackedTransactions ?? DEFAULT_MAX_TRACKED
+	});
+	const formatAddress = safely("configure address mode", () => resolveAddressFormatter(options.address), OFF_ADDRESS_FORMATTER);
+	const errorMessages = safely("configure error message mode", () => resolveErrorMessageMode(options.errorMessages), "off");
+	let tracer;
+	const getTracer = () => {
+		tracer ??= (options.tracerProvider ?? trace.getTracerProvider()).getTracer(INSTRUMENTATION_NAME, VERSION);
+		return tracer;
+	};
+	const nonSensitive = (attributes) => Object.fromEntries(Object.entries(attributes).filter(([key]) => NON_SENSITIVE_KEYS.has(key)));
+	const redact = (attributes) => {
+		if (!options.redact) return attributes;
+		let redacted;
+		try {
+			redacted = options.redact({ ...attributes });
+		} catch (error) {
+			diag.error("hashspan: redaction hook failed; recording non-sensitive attributes only", error);
+			return nonSensitive(attributes);
+		}
+		if (typeof redacted !== "object" || redacted === null || Array.isArray(redacted)) {
+			diag.error("hashspan: redaction hook must return an attributes object; recording non-sensitive attributes only");
+			return nonSensitive(attributes);
+		}
+		return redacted;
+	};
+	/**
+	* 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 (docs/adr/0006-error-privacy.md).
+	*/
+	const exceptionAttributes = (type, error) => {
+		const attributes = { [ATTR_EXCEPTION_TYPE]: type };
+		if (errorMessages === "off") return attributes;
+		const message = error instanceof Error ? error.message : String(error);
+		if (errorMessages === "sanitized") {
+			const sanitized = sanitizeErrorMessage(message, formatAddress);
+			if (sanitized) attributes[ATTR_EXCEPTION_MESSAGE] = sanitized;
+			return attributes;
+		}
+		attributes[ATTR_EXCEPTION_MESSAGE] = message;
+		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) => {
+		const type = formatAddressesIn(errorName, formatAddress);
+		let message;
+		if (error !== void 0) {
+			const exception = redact(exceptionAttributes(type, error));
+			span.addEvent(EXCEPTION_EVENT, exception);
+			const recorded = exception[ATTR_EXCEPTION_MESSAGE];
+			if (typeof recorded === "string") message = recorded;
+		}
+		span.setAttributes(redact({ [ATTR_ERROR_TYPE]: type }));
+		span.setStatus({
+			code: SpanStatusCode.ERROR,
+			...message !== void 0 ? { message } : {}
+		});
+	};
+	/** Ends a span exactly once; the span is always ended even if recording attributes fails. */
+	const finisher = (span) => {
+		let ended = false;
+		return (what, record, endTime) => {
+			if (ended) return;
+			ended = true;
+			try {
+				record();
+			} catch (error) {
+				diag.error(`hashspan: failed to ${what}`, error);
+			} finally {
+				safely("end span", () => span.end(endTime), void 0);
+			}
+		};
+	};
+	const setAddress = (attributes, key, address) => {
+		if (address === void 0) return;
+		const formatted = formatAddress(address);
+		if (formatted !== void 0) attributes[key] = formatted;
+	};
+	const baseAttributes = (chainId, operation, ctx) => ({
+		[ATTR_BLOCKCHAIN_SYSTEM]: "evm",
+		[ATTR_BLOCKCHAIN_CHAIN_ID]: chainId,
+		[ATTR_BLOCKCHAIN_OPERATION_NAME]: operation,
+		...agentAttributes(ctx, options.agent)
+	});
+	const startSend = (input, parentCtx) => {
+		const parent = parentCtx ?? context.active();
+		const attributes = baseAttributes(input.chainId, BLOCKCHAIN_OPERATION_NAME_VALUE_SEND, parent);
+		setAddress(attributes, ATTR_BLOCKCHAIN_TX_FROM, input.from);
+		setAddress(attributes, ATTR_BLOCKCHAIN_TX_TO, input.to);
+		if (input.value !== void 0) attributes[ATTR_BLOCKCHAIN_TX_VALUE] = input.value.toString();
+		if (input.nonce !== void 0) attributes[ATTR_BLOCKCHAIN_TX_NONCE] = input.nonce;
+		if (input.functionName !== void 0) attributes[ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME] = input.functionName;
+		if (input.functionSelector !== void 0) attributes[ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR] = input.functionSelector;
+		if (options.recordFunctionArguments === true && input.functionArguments !== void 0) try {
+			attributes[ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS] = serializeFunctionArguments(input.functionArguments, formatAddress);
+		} catch (error) {
+			diag.debug(`hashspan: could not serialize function arguments (${errorType(error)})`);
+		}
+		const span = getTracer().startSpan(`send ${input.chainId}`, {
+			kind: SpanKind.CLIENT,
+			attributes: redact(attributes),
+			...input.startTime !== void 0 ? { startTime: input.startTime } : {}
+		}, parent);
+		const finish = finisher(span);
+		return {
+			end: (hash, endTime) => finish("record transaction hash", () => {
+				links.set(input.chainId, hash, {
+					spanContext: span.spanContext(),
+					parent
+				});
+				span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_HASH]: hash }));
+			}, endTime),
+			fail: (error, endTime) => finish("record send failure", () => markError(span, errorType(error), error), endTime)
+		};
+	};
+	const receiptAttributes = (receipt) => {
+		const attributes = {
+			[ATTR_BLOCKCHAIN_TX_STATUS]: receipt.status === "reverted" ? BLOCKCHAIN_TX_STATUS_VALUE_REVERTED : BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS,
+			[ATTR_BLOCKCHAIN_BLOCK_NUMBER]: toInt(receipt.blockNumber),
+			[ATTR_BLOCKCHAIN_TX_GAS_USED]: toInt(receipt.gasUsed)
+		};
+		const l1Fee = receipt.l1Fee ?? void 0;
+		if (l1Fee !== void 0) attributes[ATTR_BLOCKCHAIN_TX_L1_FEE] = l1Fee.toString();
+		if (receipt.effectiveGasPrice !== void 0) {
+			attributes[ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE] = receipt.effectiveGasPrice.toString();
+			const executionFee = BigInt(receipt.gasUsed) * receipt.effectiveGasPrice;
+			attributes[ATTR_BLOCKCHAIN_TX_FEE] = (executionFee + (l1Fee ?? 0n)).toString();
+		}
+		if (receipt.revertReason !== void 0) attributes[ATTR_BLOCKCHAIN_TX_REVERT_REASON] = formatAddressesIn(receipt.revertReason, formatAddress);
+		return attributes;
+	};
+	/** Opens the confirm span of a transaction; `replacing` is the confirm span of the transaction it replaced. */
+	const openConfirm = (input, parentCtx, replacing) => {
+		const sent = links.get(input.chainId, input.hash);
+		const active = context.active();
+		const parent = replacing?.parent ?? parentCtx ?? (trace.getSpan(active) ? active : sent?.parent ?? active);
+		const attributes = baseAttributes(input.chainId, BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM, parent);
+		attributes[ATTR_BLOCKCHAIN_TX_HASH] = input.hash;
+		const spanLinks = [...replacing?.links ?? [], ...sent ? [{ context: sent.spanContext }] : []];
+		const explicitStart = input.startTime ?? replacing?.startTime;
+		const span = getTracer().startSpan(`confirm ${input.chainId}`, {
+			kind: SpanKind.CLIENT,
+			attributes: redact(attributes),
+			links: spanLinks,
+			...explicitStart !== void 0 ? { startTime: explicitStart } : {}
+		}, parent);
+		const finish = finisher(span);
+		return {
+			active: 0,
+			ended: false,
+			origin: {
+				parent,
+				startTime: explicitStart ?? /* @__PURE__ */ new Date(),
+				links: [{ context: span.spanContext() }, ...sent ? [{ context: sent.spanContext }] : []]
+			},
+			receipt: (receipt, endTime) => finish("record receipt", () => {
+				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),
+			fail: (error, endTime) => finish("record confirmation failure", () => markError(span, errorType(error), error), endTime),
+			replaced: (hash, reason, endTime) => finish("record replacement", () => {
+				const attributes = {
+					[ATTR_BLOCKCHAIN_TX_STATUS]: BLOCKCHAIN_TX_STATUS_VALUE_REPLACED,
+					[ATTR_BLOCKCHAIN_TX_REPLACEMENT_HASH]: hash
+				};
+				if (reason !== void 0 && REPLACEMENT_REASONS.has(reason)) attributes[ATTR_BLOCKCHAIN_TX_REPLACEMENT_REASON] = reason;
+				span.setAttributes(redact(attributes));
+			}, endTime),
+			unattributable: (endTime) => finish("record unattributable receipt", () => markError(span, ERROR_TYPE_VALUE_OTHER), endTime)
+		};
+	};
+	/**
+	* Records `receipt` for the replacing transaction `hash`: ends its in-flight confirm span, does nothing if it
+	* already settled, and otherwise opens one that inherits parent, start time and links from `original`.
+	*/
+	const recordReplacing = (chainId, hash, receipt, original, endTime) => {
+		const current = confirmations.get(chainId, hash);
+		if (current === "settled" || current?.ended) return;
+		const confirm = current ?? openConfirm({
+			chainId,
+			hash
+		}, void 0, original);
+		if (!current) confirmations.start(chainId, hash, confirm);
+		confirm.ended = true;
+		confirmations.settle(chainId, hash, confirm);
+		const { replacementReason: _reason, ...mined } = receipt;
+		confirm.receipt(mined, endTime);
+	};
+	/** Ends `shared` with `receipt`, attributing it to the transaction that was mined (docs/adr/0008). */
+	const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
+		const mined = receipt.transactionHash;
+		if (mined === void 0) {
+			confirmations.settle(chainId, hash, shared);
+			shared.receipt(receipt, endTime);
+			return;
+		}
+		if (typeof mined !== "string" || !TX_HASH.test(mined)) {
+			diag.warn("hashspan: receipt has an invalid transaction hash; not recording it");
+			confirmations.release(chainId, hash, shared);
+			shared.unattributable(endTime);
+			return;
+		}
+		if (mined.toLowerCase() === hash.toLowerCase()) {
+			confirmations.settle(chainId, hash, shared);
+			shared.receipt(receipt, endTime);
+			return;
+		}
+		confirmations.settle(chainId, hash, shared);
+		shared.replaced(mined, receipt.replacementReason, endTime);
+		safely("record replacing transaction", () => recordReplacing(chainId, mined, receipt, shared.origin, endTime), void 0);
+	};
+	/**
+	* Joins the confirm span of the transaction, opening it for the first handle. A receipt from any handle ends the
+	* span; a timeout or failure only ends it when it is the last handle still waiting.
+	*/
+	const startConfirm = (input, parentCtx) => {
+		const { chainId, hash } = input;
+		const current = confirmations.get(chainId, hash);
+		if (current === "settled") return NOOP_CONFIRM;
+		let confirm = current;
+		if (!confirm) {
+			confirm = openConfirm(input, parentCtx);
+			confirmations.start(chainId, hash, confirm);
+		}
+		const shared = confirm;
+		shared.active += 1;
+		let done = false;
+		const withdraw = (end) => {
+			if (done || shared.ended) return;
+			done = true;
+			shared.active -= 1;
+			if (shared.active > 0) return;
+			shared.ended = true;
+			confirmations.release(chainId, hash, shared);
+			end();
+		};
+		return {
+			end: (receipt, endTime) => {
+				if (done || shared.ended) return;
+				done = true;
+				shared.active -= 1;
+				shared.ended = true;
+				safely("record receipt", () => endWithReceipt(chainId, hash, shared, receipt, endTime), void 0);
+			},
+			timeout: (endTime) => withdraw(() => shared.timeout(endTime)),
+			fail: (error, endTime) => withdraw(() => shared.fail(error, endTime))
+		};
+	};
+	return {
+		startSend: (input, parent) => safely("start send span", () => startSend(input, parent), NOOP_SEND),
+		startConfirm: (input, parent) => safely("start confirm span", () => startConfirm(input, parent), NOOP_CONFIRM)
+	};
+}
+//#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_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, BLOCKCHAIN_OPERATION_NAME_VALUE_CONFIRM, BLOCKCHAIN_OPERATION_NAME_VALUE_SEND, BLOCKCHAIN_SYSTEM_VALUE_EVM, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_CANCELLED, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPLACED, BLOCKCHAIN_TX_REPLACEMENT_REASON_VALUE_REPRICED, BLOCKCHAIN_TX_STATUS_VALUE_REPLACED, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED, BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS, BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT, ERROR_TYPE_VALUE_OTHER, VERSION, createTxTracker };

package/package.json

@@ -1,7 +1,66 @@
 {
   "name": "@hashspan/core",
-  "version": "0.0.0",
-  "description": "Placeholder; see https://github.com/selimaytac/hashspan",
+  "version": "0.1.0",
+  "description": "Transaction lifecycle tracing for on-chain actions of AI agents, built on OpenTelemetry.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/selimaytac/hashspan.git" }
-}
+  "author": "Selim Aytac",
+  "homepage": "https://github.com/selimaytac/hashspan/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/selimaytac/hashspan/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/selimaytac/hashspan.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "opentelemetry",
+    "tracing",
+    "blockchain",
+    "evm",
+    "ai-agents",
+    "observability"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
+    "@opentelemetry/sdk-trace-node": "^2.11.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json"
+  }
+}