@hashspan/core 0.4.0 → 0.5.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
  1. package/README.md +7 -7
  2. package/dist/index.cjs +23 -20
  3. package/dist/index.d.cts +25 -20
  4. package/dist/index.d.mts +25 -20
  5. package/dist/index.mjs +23 -21
  6. package/package.json +1 -1
package/README.md CHANGED
@@ -12,7 +12,7 @@ Payments that another party settles on chain, such as x402 payments, become a **
12
12
  of a `send` span.
13
13
 
14
14
  The core is library-agnostic and read-only: it never signs, sends or fetches anything. Adapters such as
15
- [`@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.
15
+ [`@hashspan/viem`](https://github.com/selimaytac/hashspan/tree/@hashspan/core@0.5.0/packages/viem) call it for you. Use the core directly to instrument any other send path.
16
16
 
17
17
  ## Install
18
18
 
@@ -69,14 +69,14 @@ stays the class name.
69
69
  `tracker.startPayment({ chainId, protocol, payer, recipient, asset, amount })` records a payment that another
70
70
  party settles on chain, such as an x402 facilitator, as a `payment {chainId}` span; end it with
71
71
  `end({ status, hash })` or `fail(error)`. A settlement with a hash links the transaction's confirm span to the payment
72
- span ([ADR 0013](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md)).
72
+ span ([ADR 0013](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md)).
73
73
 
74
74
  All three calls accept an explicit parent `Context` as a second argument. An integration that learns about a call only
75
75
  after it started can record it after the fact: pass `startTime` in the input and `endTime` in the options of the
76
- 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
76
+ handle method, e.g. `send.end({ hash }, { endTime })` ([ADR 0009](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0009-telemetry-off-the-call-path.md)). Every method is safe to call: failures inside
77
77
  the instrumentation are reported through `diag` and never thrown into your code. The positional forms of earlier
78
78
  releases, `send.end(hash, endTime)` and `send.fail(error, endTime, { errorType })`, still work and are deprecated
79
- until 1.0 ([ADR 0014](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md)).
79
+ until 1.0 ([ADR 0014](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md)).
80
80
 
81
81
  ## Options
82
82
 
@@ -84,7 +84,7 @@ until 1.0 ([ADR 0014](https://github.com/selimaytac/hashspan/blob/@hashspan/core
84
84
  |---|---|---|
85
85
  | `tracerProvider` | global provider | Tracer provider to use |
86
86
  | `address` | `'raw'` | `'raw'`, `'hashed'`, `'off'`, or `{ mode: 'hashed', hash: (address) => string }` |
87
- | `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) |
87
+ | `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.5.0/docs/adr/0006-error-privacy.md) |
88
88
  | `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 |
89
89
  | `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 |
90
90
  | `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,
99
99
  on confirmation, status, block number, gas used, effective gas price, L1 fee, total fee and revert reason. Decoded
100
100
  call arguments are recorded only with `recordFunctionArguments`, and error messages only with `errorMessages`.
101
101
  Attribute definitions:
102
- [docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md).
102
+ [docs/semconv.md](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md).
103
103
 
104
104
  ## Privacy notes
105
105
 
@@ -114,7 +114,7 @@ Attribute definitions:
114
114
  propagated, or strip the entries before outbound calls.
115
115
  - **Inbound Baggage can claim an identity.** A caller can send Baggage entries with any agent id. A field set in the
116
116
  `agent` option cannot be overridden that way; to ignore identity from Baggage entirely, set `agentFromBaggage: false`
117
- ([ADR 0011](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0011-agent-identity-precedence.md)).
117
+ ([ADR 0011](https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0011-agent-identity-precedence.md)).
118
118
  - The redaction hook (`redact`) runs last on every attribute set and on exception attributes; use it for anything
119
119
  else your policy forbids.
120
120
  - **Your callbacks' errors go to the diagnostic logger.** If a custom `hash` function or the `redact` hook throws,
package/dist/index.cjs CHANGED
@@ -6,7 +6,7 @@ const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
6
6
  /**
7
7
  * Agent identity as GenAI attributes. A field set in the static identity always wins; Baggage, which a remote caller
8
8
  * can set, only fills fields it leaves unset, and is not read at all with `fromBaggage` false
9
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0011-agent-identity-precedence.md).
9
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0011-agent-identity-precedence.md).
10
10
  */
11
11
  function agentAttributes(ctx, identity, fromBaggage = true) {
12
12
  const baggage = fromBaggage ? _opentelemetry_api.propagation.getBaggage(ctx) : void 0;
@@ -22,7 +22,7 @@ function agentAttributes(ctx, identity, fromBaggage = true) {
22
22
  /**
23
23
  * Attribute keys emitted by hashspan.
24
24
  *
25
- * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md for
25
+ * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md for
26
26
  * definitions and value types. These names are a public contract: changes follow the deprecation policy in AGENTS.md.
27
27
  */
28
28
  const ATTR_BLOCKCHAIN_SYSTEM = "blockchain.system";
@@ -46,12 +46,12 @@ const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME = "blockchain.contract.function.nam
46
46
  const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR = "blockchain.contract.function.selector";
47
47
  /**
48
48
  * Opt-in: decoded call arguments as a JSON array. See
49
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0004-privacy-defaults.md.
49
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0004-privacy-defaults.md.
50
50
  */
51
51
  const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS = "blockchain.contract.function.arguments";
52
52
  /**
53
53
  * Payments settled on chain by a party other than the agent, e.g. an x402 facilitator. See
54
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md.
54
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md.
55
55
  */
56
56
  const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = "blockchain.payment.protocol";
57
57
  const ATTR_BLOCKCHAIN_PAYMENT_PAYER = "blockchain.payment.payer";
@@ -59,6 +59,8 @@ const ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT = "blockchain.payment.recipient";
59
59
  const ATTR_BLOCKCHAIN_PAYMENT_ASSET = "blockchain.payment.asset";
60
60
  const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT = "blockchain.payment.amount";
61
61
  const ATTR_BLOCKCHAIN_PAYMENT_STATUS = "blockchain.payment.status";
62
+ /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
63
+ const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT = "blockchain.payment.settled_amount";
62
64
  /** x402's own payment fields. */
63
65
  const ATTR_X402_SCHEME = "x402.scheme";
64
66
  const ATTR_X402_RESOURCE = "x402.resource";
@@ -78,9 +80,9 @@ const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED = "failed";
78
80
  const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS = "success";
79
81
  const BLOCKCHAIN_TX_STATUS_VALUE_REVERTED = "reverted";
80
82
  /**
81
- * @deprecated A confirm span that gave up waiting records `error.type` `timeout`; this value of
82
- * `blockchain.tx.status` stops being recorded in a later minor release and the constant is removed in 1.0. See
83
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
83
+ * @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
84
+ * `blockchain.tx.status`. The constant is removed in 1.0. See
85
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
84
86
  */
85
87
  const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
86
88
  const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -378,7 +380,7 @@ function sanitizeResource(resource) {
378
380
  }
379
381
  //#endregion
380
382
  //#region src/version.ts
381
- const VERSION = "0.4.0";
383
+ const VERSION = "0.5.0";
382
384
  //#endregion
383
385
  //#region src/tracker.ts
384
386
  const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -407,8 +409,8 @@ const TX_HASH = /^0x[0-9a-fA-F]{64}$/;
407
409
  const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
408
410
  /** A non-negative integer that fits in 256 bits. */
409
411
  const AMOUNT = /^(0|[1-9][0-9]{0,77})$/;
410
- /** `error.type` of a payment whose outcome was never learned, as for a confirmation that timed out. */
411
- const PAYMENT_TIMEOUT = "timeout";
412
+ /** `error.type` of a wait that gave up: a confirmation or a payment whose outcome was never learned. */
413
+ const OBSERVER_TIMEOUT = "timeout";
412
414
  const PAYMENT_STATUSES = /* @__PURE__ */ new Set([
413
415
  BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED,
414
416
  BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING,
@@ -503,7 +505,7 @@ function reportedErrorType(error, options) {
503
505
  }
504
506
  /**
505
507
  * Creates a tracker that records transactions as `send` and `confirm` spans, and payments as `payment` spans, with
506
- * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md). It makes
508
+ * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md). It makes
507
509
  * no network calls; the caller passes hashes and receipts. Its methods and handles never throw: failures are logged
508
510
  * via `diag`, and a method that fails returns a handle that records nothing.
509
511
  */
@@ -543,7 +545,7 @@ function createTxTracker(options = {}) {
543
545
  /**
544
546
  * Exception event attributes for `error`, per the error message mode. The error object itself is never handed to
545
547
  * the SDK: its message and stack can carry addresses and calldata
546
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0006-error-privacy.md).
548
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0006-error-privacy.md).
547
549
  */
548
550
  const exceptionAttributes = (type, error) => {
549
551
  const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -691,10 +693,7 @@ function createTxTracker(options = {}) {
691
693
  span.setAttributes(redact(receiptAttributes(receipt)));
692
694
  if (receipt.status === "reverted") markError(span, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED);
693
695
  }, endTime),
694
- timeout: (endTime) => finish("record confirmation timeout", () => {
695
- span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_STATUS]: BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT }));
696
- markError(span, BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT);
697
- }, endTime),
696
+ timeout: (endTime) => finish("record confirmation timeout", () => markError(span, OBSERVER_TIMEOUT), endTime),
698
697
  fail: (error, endTime) => finish("record confirmation failure", () => markError(span, errorType(error), error), endTime),
699
698
  replaced: (hash, reason, endTime) => finish("record replacement", () => {
700
699
  const attributes = {
@@ -726,7 +725,7 @@ function createTxTracker(options = {}) {
726
725
  };
727
726
  /**
728
727
  * Ends `shared` with `receipt`, attributing it to the transaction that was mined
729
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0008-replaced-transactions.md).
728
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0008-replaced-transactions.md).
730
729
  */
731
730
  const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
732
731
  const mined = receipt.transactionHash;
@@ -832,8 +831,11 @@ function createTxTracker(options = {}) {
832
831
  settled[ATTR_BLOCKCHAIN_TX_HASH] = hash;
833
832
  }
834
833
  if (!knownPayer) setPaymentAddress(settled, ATTR_BLOCKCHAIN_PAYMENT_PAYER, settlement.payer);
835
- const settledAmount = paid === void 0 ? amount(settlement.amount) : void 0;
836
- if (settledAmount !== void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
834
+ const settledAmount = amount(settlement.amount);
835
+ if (settledAmount !== void 0) {
836
+ settled[ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT] = settledAmount;
837
+ if (paid === void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
838
+ }
837
839
  span.setAttributes(redact(settled));
838
840
  if (status === "failed") markError(span, identifier(settlement.errorReason) ?? "_OTHER");
839
841
  };
@@ -843,7 +845,7 @@ function createTxTracker(options = {}) {
843
845
  const read = handleOptions(options);
844
846
  finish("record payment failure", () => markError(span, reportedErrorType(error, read), error, errorType(error)), read.endTime);
845
847
  },
846
- timeout: (options) => finish("record payment timeout", () => markError(span, PAYMENT_TIMEOUT), handleOptions(options).endTime)
848
+ timeout: (options) => finish("record payment timeout", () => markError(span, OBSERVER_TIMEOUT), handleOptions(options).endTime)
847
849
  };
848
850
  };
849
851
  return {
@@ -864,6 +866,7 @@ exports.ATTR_BLOCKCHAIN_PAYMENT_ASSET = ATTR_BLOCKCHAIN_PAYMENT_ASSET;
864
866
  exports.ATTR_BLOCKCHAIN_PAYMENT_PAYER = ATTR_BLOCKCHAIN_PAYMENT_PAYER;
865
867
  exports.ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL;
866
868
  exports.ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT = ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT;
869
+ exports.ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT = ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT;
867
870
  exports.ATTR_BLOCKCHAIN_PAYMENT_STATUS = ATTR_BLOCKCHAIN_PAYMENT_STATUS;
868
871
  exports.ATTR_BLOCKCHAIN_SYSTEM = ATTR_BLOCKCHAIN_SYSTEM;
869
872
  exports.ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE = ATTR_BLOCKCHAIN_TX_EFFECTIVE_GAS_PRICE;
package/dist/index.d.cts CHANGED
@@ -2,12 +2,12 @@ import { Attributes, Context, TimeInput, TracerProvider } from "@opentelemetry/a
2
2
  //#region src/types.d.ts
3
3
  /**
4
4
  * How wallet addresses are recorded. See
5
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0004-privacy-defaults.md.
5
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0004-privacy-defaults.md.
6
6
  */
7
7
  type AddressMode = "raw" | "hashed" | "off";
8
8
  /**
9
9
  * How error messages are recorded on exception events and span status. See
10
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0006-error-privacy.md.
10
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0006-error-privacy.md.
11
11
  * - `off`: error type only
12
12
  * - `sanitized`: first line, addresses per address mode, other long hex data removed
13
13
  * - `raw`: full message and stack trace, as thrown
@@ -61,7 +61,7 @@ interface TxTrackerOptions {
61
61
  /**
62
62
  * Agent identity. A field set here always wins; fields left unset are taken from the Baggage entries
63
63
  * `gen_ai.agent.id` / `gen_ai.agent.name` unless `agentFromBaggage` is false
64
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0011-agent-identity-precedence.md).
64
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0011-agent-identity-precedence.md).
65
65
  */
66
66
  agent?: AgentIdentity | undefined;
67
67
  /**
@@ -103,7 +103,7 @@ interface SendInput {
103
103
  functionArguments?: readonly unknown[] | undefined;
104
104
  /**
105
105
  * When the send started, for adapters that record it after the fact
106
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0009-telemetry-off-the-call-path.md).
106
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0009-telemetry-off-the-call-path.md).
107
107
  * Omit it otherwise: with an explicit start time, the SDK measures the span by the wall clock, so pass the end time
108
108
  * to the handle too.
109
109
  */
@@ -112,14 +112,14 @@ interface SendInput {
112
112
  /**
113
113
  * Ends a send span. Only the first call counts; methods never throw.
114
114
  * Produced by the tracker only; methods may be added in minor releases
115
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
115
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
116
116
  */
117
117
  interface SendHandle {
118
118
  /**
119
119
  * The parent context with the send span set. Run the call that sends the transaction in it, e.g.
120
120
  * `await context.with(send.context, () => sendSomehow())`, so that spans of wallet, RPC or HTTP instrumentation
121
121
  * nest under the send span
122
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0015-send-span-as-active-context.md).
122
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0015-send-span-as-active-context.md).
123
123
  * Run only that call in it: a confirm span started in it becomes a child of the send span.
124
124
  */
125
125
  readonly context: Context;
@@ -182,7 +182,7 @@ interface ReceiptLike {
182
182
  /**
183
183
  * Hash of the mined transaction. When it differs from the awaited hash, the awaited transaction was replaced: its
184
184
  * confirm span ends as `replaced` and the receipt is recorded for this hash
185
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0008-replaced-transactions.md).
185
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0008-replaced-transactions.md).
186
186
  */
187
187
  transactionHash?: string | undefined;
188
188
  /** Replacement reason reported by the library, when {@link transactionHash} differs from the awaited hash. */
@@ -192,7 +192,7 @@ interface ReceiptLike {
192
192
  * One wait for a transaction's receipt, joined to the transaction's shared confirm span. Only the first call counts;
193
193
  * methods never throw.
194
194
  * Produced by the tracker only; methods may be added in minor releases
195
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
195
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
196
196
  */
197
197
  interface ConfirmHandle {
198
198
  /** Ends the shared confirm span with the receipt, for every handle of the transaction. */
@@ -216,7 +216,7 @@ interface ConfirmHandle {
216
216
  }
217
217
  /**
218
218
  * A payment the agent authorizes and another party settles on chain, e.g. an x402 facilitator
219
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md).
219
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md).
220
220
  * Values often come from a remote server: addresses, amounts and identifiers that are malformed are not recorded.
221
221
  */
222
222
  interface PaymentInput {
@@ -252,7 +252,10 @@ interface PaymentSettlement {
252
252
  hash?: string | undefined;
253
253
  /** Address that paid, when the settlement reports it; recorded instead of the input's. */
254
254
  payer?: string | undefined;
255
- /** Amount settled, when the settlement reports it; recorded instead of the input's. */
255
+ /**
256
+ * Amount settled, when the settlement reports it, recorded as `blockchain.payment.settled_amount`; also as
257
+ * `blockchain.payment.amount` when the input had none.
258
+ */
256
259
  amount?: bigint | string | undefined;
257
260
  /** Why a `failed` settlement failed, recorded as `error.type` if it is a short identifier, else `_OTHER`. */
258
261
  errorReason?: string | undefined;
@@ -260,7 +263,7 @@ interface PaymentSettlement {
260
263
  /**
261
264
  * Ends a payment span. Only the first call counts; methods never throw.
262
265
  * Produced by the tracker only; methods may be added in minor releases
263
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
266
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
264
267
  */
265
268
  interface PaymentHandle {
266
269
  /** Ends the payment span with its settlement. */
@@ -286,7 +289,7 @@ export declare const ATTR_GEN_AI_AGENT_NAME: "gen_ai.agent.name";
286
289
  /**
287
290
  * Attribute keys emitted by hashspan.
288
291
  *
289
- * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md for
292
+ * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md for
290
293
  * definitions and value types. These names are a public contract: changes follow the deprecation policy in AGENTS.md.
291
294
  */
292
295
  export declare const ATTR_BLOCKCHAIN_SYSTEM: "blockchain.system";
@@ -310,12 +313,12 @@ export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME: "blockchain.contrac
310
313
  export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR: "blockchain.contract.function.selector";
311
314
  /**
312
315
  * Opt-in: decoded call arguments as a JSON array. See
313
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0004-privacy-defaults.md.
316
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0004-privacy-defaults.md.
314
317
  */
315
318
  export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS: "blockchain.contract.function.arguments";
316
319
  /**
317
320
  * Payments settled on chain by a party other than the agent, e.g. an x402 facilitator. See
318
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md.
321
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md.
319
322
  */
320
323
  export declare const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL: "blockchain.payment.protocol";
321
324
  export declare const ATTR_BLOCKCHAIN_PAYMENT_PAYER: "blockchain.payment.payer";
@@ -323,6 +326,8 @@ export declare const ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT: "blockchain.payment.reci
323
326
  export declare const ATTR_BLOCKCHAIN_PAYMENT_ASSET: "blockchain.payment.asset";
324
327
  export declare const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT: "blockchain.payment.amount";
325
328
  export declare const ATTR_BLOCKCHAIN_PAYMENT_STATUS: "blockchain.payment.status";
329
+ /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
330
+ export declare const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT: "blockchain.payment.settled_amount";
326
331
  /** x402's own payment fields. */
327
332
  export declare const ATTR_X402_SCHEME: "x402.scheme";
328
333
  export declare const ATTR_X402_RESOURCE: "x402.resource";
@@ -342,9 +347,9 @@ export declare const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED: "failed";
342
347
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS: "success";
343
348
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_REVERTED: "reverted";
344
349
  /**
345
- * @deprecated A confirm span that gave up waiting records `error.type` `timeout`; this value of
346
- * `blockchain.tx.status` stops being recorded in a later minor release and the constant is removed in 1.0. See
347
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
350
+ * @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
351
+ * `blockchain.tx.status`. The constant is removed in 1.0. See
352
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
348
353
  */
349
354
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT: "timeout";
350
355
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED: "replaced";
@@ -361,7 +366,7 @@ export declare const ERROR_TYPE_VALUE_OTHER: "_OTHER";
361
366
  /**
362
367
  * Records transactions and payments as spans. Obtain one from {@link createTxTracker}: it is not meant to be
363
368
  * implemented, and members may be added to it and to its handles in minor releases
364
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
369
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
365
370
  */
366
371
  interface TxTracker {
367
372
  /**
@@ -379,7 +384,7 @@ interface TxTracker {
379
384
  /**
380
385
  * Starts a `payment` span as a child of `parent` (default: the active context), for a payment that another party
381
386
  * settles on chain
382
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md). Call
387
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md). Call
383
388
  * `end(settlement)` with the settlement, or `fail(error)`. A settlement with a hash links the transaction's confirm
384
389
  * span to this span, as a send span would.
385
390
  */
@@ -387,7 +392,7 @@ interface TxTracker {
387
392
  }
388
393
  /**
389
394
  * Creates a tracker that records transactions as `send` and `confirm` spans, and payments as `payment` spans, with
390
- * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md). It makes
395
+ * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md). It makes
391
396
  * no network calls; the caller passes hashes and receipts. Its methods and handles never throw: failures are logged
392
397
  * via `diag`, and a method that fails returns a handle that records nothing.
393
398
  */
package/dist/index.d.mts CHANGED
@@ -2,12 +2,12 @@ import { Attributes, Context, TimeInput, TracerProvider } from "@opentelemetry/a
2
2
  //#region src/types.d.ts
3
3
  /**
4
4
  * How wallet addresses are recorded. See
5
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0004-privacy-defaults.md.
5
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0004-privacy-defaults.md.
6
6
  */
7
7
  type AddressMode = "raw" | "hashed" | "off";
8
8
  /**
9
9
  * How error messages are recorded on exception events and span status. See
10
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0006-error-privacy.md.
10
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0006-error-privacy.md.
11
11
  * - `off`: error type only
12
12
  * - `sanitized`: first line, addresses per address mode, other long hex data removed
13
13
  * - `raw`: full message and stack trace, as thrown
@@ -61,7 +61,7 @@ interface TxTrackerOptions {
61
61
  /**
62
62
  * Agent identity. A field set here always wins; fields left unset are taken from the Baggage entries
63
63
  * `gen_ai.agent.id` / `gen_ai.agent.name` unless `agentFromBaggage` is false
64
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0011-agent-identity-precedence.md).
64
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0011-agent-identity-precedence.md).
65
65
  */
66
66
  agent?: AgentIdentity | undefined;
67
67
  /**
@@ -103,7 +103,7 @@ interface SendInput {
103
103
  functionArguments?: readonly unknown[] | undefined;
104
104
  /**
105
105
  * When the send started, for adapters that record it after the fact
106
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0009-telemetry-off-the-call-path.md).
106
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0009-telemetry-off-the-call-path.md).
107
107
  * Omit it otherwise: with an explicit start time, the SDK measures the span by the wall clock, so pass the end time
108
108
  * to the handle too.
109
109
  */
@@ -112,14 +112,14 @@ interface SendInput {
112
112
  /**
113
113
  * Ends a send span. Only the first call counts; methods never throw.
114
114
  * Produced by the tracker only; methods may be added in minor releases
115
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
115
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
116
116
  */
117
117
  interface SendHandle {
118
118
  /**
119
119
  * The parent context with the send span set. Run the call that sends the transaction in it, e.g.
120
120
  * `await context.with(send.context, () => sendSomehow())`, so that spans of wallet, RPC or HTTP instrumentation
121
121
  * nest under the send span
122
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0015-send-span-as-active-context.md).
122
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0015-send-span-as-active-context.md).
123
123
  * Run only that call in it: a confirm span started in it becomes a child of the send span.
124
124
  */
125
125
  readonly context: Context;
@@ -182,7 +182,7 @@ interface ReceiptLike {
182
182
  /**
183
183
  * Hash of the mined transaction. When it differs from the awaited hash, the awaited transaction was replaced: its
184
184
  * confirm span ends as `replaced` and the receipt is recorded for this hash
185
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0008-replaced-transactions.md).
185
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0008-replaced-transactions.md).
186
186
  */
187
187
  transactionHash?: string | undefined;
188
188
  /** Replacement reason reported by the library, when {@link transactionHash} differs from the awaited hash. */
@@ -192,7 +192,7 @@ interface ReceiptLike {
192
192
  * One wait for a transaction's receipt, joined to the transaction's shared confirm span. Only the first call counts;
193
193
  * methods never throw.
194
194
  * Produced by the tracker only; methods may be added in minor releases
195
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
195
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
196
196
  */
197
197
  interface ConfirmHandle {
198
198
  /** Ends the shared confirm span with the receipt, for every handle of the transaction. */
@@ -216,7 +216,7 @@ interface ConfirmHandle {
216
216
  }
217
217
  /**
218
218
  * A payment the agent authorizes and another party settles on chain, e.g. an x402 facilitator
219
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md).
219
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md).
220
220
  * Values often come from a remote server: addresses, amounts and identifiers that are malformed are not recorded.
221
221
  */
222
222
  interface PaymentInput {
@@ -252,7 +252,10 @@ interface PaymentSettlement {
252
252
  hash?: string | undefined;
253
253
  /** Address that paid, when the settlement reports it; recorded instead of the input's. */
254
254
  payer?: string | undefined;
255
- /** Amount settled, when the settlement reports it; recorded instead of the input's. */
255
+ /**
256
+ * Amount settled, when the settlement reports it, recorded as `blockchain.payment.settled_amount`; also as
257
+ * `blockchain.payment.amount` when the input had none.
258
+ */
256
259
  amount?: bigint | string | undefined;
257
260
  /** Why a `failed` settlement failed, recorded as `error.type` if it is a short identifier, else `_OTHER`. */
258
261
  errorReason?: string | undefined;
@@ -260,7 +263,7 @@ interface PaymentSettlement {
260
263
  /**
261
264
  * Ends a payment span. Only the first call counts; methods never throw.
262
265
  * Produced by the tracker only; methods may be added in minor releases
263
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
266
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
264
267
  */
265
268
  interface PaymentHandle {
266
269
  /** Ends the payment span with its settlement. */
@@ -286,7 +289,7 @@ export declare const ATTR_GEN_AI_AGENT_NAME: "gen_ai.agent.name";
286
289
  /**
287
290
  * Attribute keys emitted by hashspan.
288
291
  *
289
- * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md for
292
+ * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md for
290
293
  * definitions and value types. These names are a public contract: changes follow the deprecation policy in AGENTS.md.
291
294
  */
292
295
  export declare const ATTR_BLOCKCHAIN_SYSTEM: "blockchain.system";
@@ -310,12 +313,12 @@ export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME: "blockchain.contrac
310
313
  export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR: "blockchain.contract.function.selector";
311
314
  /**
312
315
  * Opt-in: decoded call arguments as a JSON array. See
313
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0004-privacy-defaults.md.
316
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0004-privacy-defaults.md.
314
317
  */
315
318
  export declare const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS: "blockchain.contract.function.arguments";
316
319
  /**
317
320
  * Payments settled on chain by a party other than the agent, e.g. an x402 facilitator. See
318
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md.
321
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md.
319
322
  */
320
323
  export declare const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL: "blockchain.payment.protocol";
321
324
  export declare const ATTR_BLOCKCHAIN_PAYMENT_PAYER: "blockchain.payment.payer";
@@ -323,6 +326,8 @@ export declare const ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT: "blockchain.payment.reci
323
326
  export declare const ATTR_BLOCKCHAIN_PAYMENT_ASSET: "blockchain.payment.asset";
324
327
  export declare const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT: "blockchain.payment.amount";
325
328
  export declare const ATTR_BLOCKCHAIN_PAYMENT_STATUS: "blockchain.payment.status";
329
+ /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
330
+ export declare const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT: "blockchain.payment.settled_amount";
326
331
  /** x402's own payment fields. */
327
332
  export declare const ATTR_X402_SCHEME: "x402.scheme";
328
333
  export declare const ATTR_X402_RESOURCE: "x402.resource";
@@ -342,9 +347,9 @@ export declare const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED: "failed";
342
347
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS: "success";
343
348
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_REVERTED: "reverted";
344
349
  /**
345
- * @deprecated A confirm span that gave up waiting records `error.type` `timeout`; this value of
346
- * `blockchain.tx.status` stops being recorded in a later minor release and the constant is removed in 1.0. See
347
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
350
+ * @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
351
+ * `blockchain.tx.status`. The constant is removed in 1.0. See
352
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
348
353
  */
349
354
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT: "timeout";
350
355
  export declare const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED: "replaced";
@@ -361,7 +366,7 @@ export declare const ERROR_TYPE_VALUE_OTHER: "_OTHER";
361
366
  /**
362
367
  * Records transactions and payments as spans. Obtain one from {@link createTxTracker}: it is not meant to be
363
368
  * implemented, and members may be added to it and to its handles in minor releases
364
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0014-core-api-boundary.md).
369
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0014-core-api-boundary.md).
365
370
  */
366
371
  interface TxTracker {
367
372
  /**
@@ -379,7 +384,7 @@ interface TxTracker {
379
384
  /**
380
385
  * Starts a `payment` span as a child of `parent` (default: the active context), for a payment that another party
381
386
  * settles on chain
382
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md). Call
387
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md). Call
383
388
  * `end(settlement)` with the settlement, or `fail(error)`. A settlement with a hash links the transaction's confirm
384
389
  * span to this span, as a send span would.
385
390
  */
@@ -387,7 +392,7 @@ interface TxTracker {
387
392
  }
388
393
  /**
389
394
  * Creates a tracker that records transactions as `send` and `confirm` spans, and payments as `payment` spans, with
390
- * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md). It makes
395
+ * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md). It makes
391
396
  * no network calls; the caller passes hashes and receipts. Its methods and handles never throw: failures are logged
392
397
  * via `diag`, and a method that fails returns a handle that records nothing.
393
398
  */
package/dist/index.mjs CHANGED
@@ -5,7 +5,7 @@ const ATTR_GEN_AI_AGENT_NAME = "gen_ai.agent.name";
5
5
  /**
6
6
  * Agent identity as GenAI attributes. A field set in the static identity always wins; Baggage, which a remote caller
7
7
  * can set, only fills fields it leaves unset, and is not read at all with `fromBaggage` false
8
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0011-agent-identity-precedence.md).
8
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0011-agent-identity-precedence.md).
9
9
  */
10
10
  function agentAttributes(ctx, identity, fromBaggage = true) {
11
11
  const baggage = fromBaggage ? propagation.getBaggage(ctx) : void 0;
@@ -21,7 +21,7 @@ function agentAttributes(ctx, identity, fromBaggage = true) {
21
21
  /**
22
22
  * Attribute keys emitted by hashspan.
23
23
  *
24
- * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md for
24
+ * Stability: development. See https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md for
25
25
  * definitions and value types. These names are a public contract: changes follow the deprecation policy in AGENTS.md.
26
26
  */
27
27
  const ATTR_BLOCKCHAIN_SYSTEM = "blockchain.system";
@@ -45,12 +45,12 @@ const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_NAME = "blockchain.contract.function.nam
45
45
  const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_SELECTOR = "blockchain.contract.function.selector";
46
46
  /**
47
47
  * Opt-in: decoded call arguments as a JSON array. See
48
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0004-privacy-defaults.md.
48
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0004-privacy-defaults.md.
49
49
  */
50
50
  const ATTR_BLOCKCHAIN_CONTRACT_FUNCTION_ARGUMENTS = "blockchain.contract.function.arguments";
51
51
  /**
52
52
  * Payments settled on chain by a party other than the agent, e.g. an x402 facilitator. See
53
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0013-x402-payments.md.
53
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0013-x402-payments.md.
54
54
  */
55
55
  const ATTR_BLOCKCHAIN_PAYMENT_PROTOCOL = "blockchain.payment.protocol";
56
56
  const ATTR_BLOCKCHAIN_PAYMENT_PAYER = "blockchain.payment.payer";
@@ -58,6 +58,8 @@ const ATTR_BLOCKCHAIN_PAYMENT_RECIPIENT = "blockchain.payment.recipient";
58
58
  const ATTR_BLOCKCHAIN_PAYMENT_ASSET = "blockchain.payment.asset";
59
59
  const ATTR_BLOCKCHAIN_PAYMENT_AMOUNT = "blockchain.payment.amount";
60
60
  const ATTR_BLOCKCHAIN_PAYMENT_STATUS = "blockchain.payment.status";
61
+ /** The amount the settling party reports it settled, e.g. less than the authorized maximum with x402 `upto`. */
62
+ const ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT = "blockchain.payment.settled_amount";
61
63
  /** x402's own payment fields. */
62
64
  const ATTR_X402_SCHEME = "x402.scheme";
63
65
  const ATTR_X402_RESOURCE = "x402.resource";
@@ -77,9 +79,9 @@ const BLOCKCHAIN_PAYMENT_STATUS_VALUE_FAILED = "failed";
77
79
  const BLOCKCHAIN_TX_STATUS_VALUE_SUCCESS = "success";
78
80
  const BLOCKCHAIN_TX_STATUS_VALUE_REVERTED = "reverted";
79
81
  /**
80
- * @deprecated A confirm span that gave up waiting records `error.type` `timeout`; this value of
81
- * `blockchain.tx.status` stops being recorded in a later minor release and the constant is removed in 1.0. See
82
- * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
82
+ * @deprecated No longer recorded: a confirm span that gave up waiting records `error.type` `timeout` and no
83
+ * `blockchain.tx.status`. The constant is removed in 1.0. See
84
+ * https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0016-timeout-is-an-observer-outcome.md.
83
85
  */
84
86
  const BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT = "timeout";
85
87
  const BLOCKCHAIN_TX_STATUS_VALUE_REPLACED = "replaced";
@@ -377,7 +379,7 @@ function sanitizeResource(resource) {
377
379
  }
378
380
  //#endregion
379
381
  //#region src/version.ts
380
- const VERSION = "0.4.0";
382
+ const VERSION = "0.5.0";
381
383
  //#endregion
382
384
  //#region src/tracker.ts
383
385
  const INSTRUMENTATION_NAME = "@hashspan/core";
@@ -406,8 +408,8 @@ const TX_HASH = /^0x[0-9a-fA-F]{64}$/;
406
408
  const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
407
409
  /** A non-negative integer that fits in 256 bits. */
408
410
  const AMOUNT = /^(0|[1-9][0-9]{0,77})$/;
409
- /** `error.type` of a payment whose outcome was never learned, as for a confirmation that timed out. */
410
- const PAYMENT_TIMEOUT = "timeout";
411
+ /** `error.type` of a wait that gave up: a confirmation or a payment whose outcome was never learned. */
412
+ const OBSERVER_TIMEOUT = "timeout";
411
413
  const PAYMENT_STATUSES = /* @__PURE__ */ new Set([
412
414
  BLOCKCHAIN_PAYMENT_STATUS_VALUE_SETTLED,
413
415
  BLOCKCHAIN_PAYMENT_STATUS_VALUE_PENDING,
@@ -502,7 +504,7 @@ function reportedErrorType(error, options) {
502
504
  }
503
505
  /**
504
506
  * Creates a tracker that records transactions as `send` and `confirm` spans, and payments as `payment` spans, with
505
- * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/semconv.md). It makes
507
+ * `@opentelemetry/api` (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/semconv.md). It makes
506
508
  * no network calls; the caller passes hashes and receipts. Its methods and handles never throw: failures are logged
507
509
  * via `diag`, and a method that fails returns a handle that records nothing.
508
510
  */
@@ -542,7 +544,7 @@ function createTxTracker(options = {}) {
542
544
  /**
543
545
  * Exception event attributes for `error`, per the error message mode. The error object itself is never handed to
544
546
  * the SDK: its message and stack can carry addresses and calldata
545
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0006-error-privacy.md).
547
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0006-error-privacy.md).
546
548
  */
547
549
  const exceptionAttributes = (type, error) => {
548
550
  const attributes = { [ATTR_EXCEPTION_TYPE]: type };
@@ -690,10 +692,7 @@ function createTxTracker(options = {}) {
690
692
  span.setAttributes(redact(receiptAttributes(receipt)));
691
693
  if (receipt.status === "reverted") markError(span, BLOCKCHAIN_TX_STATUS_VALUE_REVERTED);
692
694
  }, endTime),
693
- timeout: (endTime) => finish("record confirmation timeout", () => {
694
- span.setAttributes(redact({ [ATTR_BLOCKCHAIN_TX_STATUS]: BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT }));
695
- markError(span, BLOCKCHAIN_TX_STATUS_VALUE_TIMEOUT);
696
- }, endTime),
695
+ timeout: (endTime) => finish("record confirmation timeout", () => markError(span, OBSERVER_TIMEOUT), endTime),
697
696
  fail: (error, endTime) => finish("record confirmation failure", () => markError(span, errorType(error), error), endTime),
698
697
  replaced: (hash, reason, endTime) => finish("record replacement", () => {
699
698
  const attributes = {
@@ -725,7 +724,7 @@ function createTxTracker(options = {}) {
725
724
  };
726
725
  /**
727
726
  * Ends `shared` with `receipt`, attributing it to the transaction that was mined
728
- * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.4.0/docs/adr/0008-replaced-transactions.md).
727
+ * (https://github.com/selimaytac/hashspan/blob/@hashspan/core@0.5.0/docs/adr/0008-replaced-transactions.md).
729
728
  */
730
729
  const endWithReceipt = (chainId, hash, shared, receipt, endTime) => {
731
730
  const mined = receipt.transactionHash;
@@ -831,8 +830,11 @@ function createTxTracker(options = {}) {
831
830
  settled[ATTR_BLOCKCHAIN_TX_HASH] = hash;
832
831
  }
833
832
  if (!knownPayer) setPaymentAddress(settled, ATTR_BLOCKCHAIN_PAYMENT_PAYER, settlement.payer);
834
- const settledAmount = paid === void 0 ? amount(settlement.amount) : void 0;
835
- if (settledAmount !== void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
833
+ const settledAmount = amount(settlement.amount);
834
+ if (settledAmount !== void 0) {
835
+ settled[ATTR_BLOCKCHAIN_PAYMENT_SETTLED_AMOUNT] = settledAmount;
836
+ if (paid === void 0) settled[ATTR_BLOCKCHAIN_PAYMENT_AMOUNT] = settledAmount;
837
+ }
836
838
  span.setAttributes(redact(settled));
837
839
  if (status === "failed") markError(span, identifier(settlement.errorReason) ?? "_OTHER");
838
840
  };
@@ -842,7 +844,7 @@ function createTxTracker(options = {}) {
842
844
  const read = handleOptions(options);
843
845
  finish("record payment failure", () => markError(span, reportedErrorType(error, read), error, errorType(error)), read.endTime);
844
846
  },
845
- timeout: (options) => finish("record payment timeout", () => markError(span, PAYMENT_TIMEOUT), handleOptions(options).endTime)
847
+ timeout: (options) => finish("record payment timeout", () => markError(span, OBSERVER_TIMEOUT), handleOptions(options).endTime)
846
848
  };
847
849
  };
848
850
  return {
@@ -852,4 +854,4 @@ function createTxTracker(options = {}) {
852
854
  };
853
855
  }
854
856
  //#endregion
855
- 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 };
857
+ 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_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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hashspan/core",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Transaction lifecycle tracing for on-chain actions of AI agents, built on OpenTelemetry.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "Selim Aytac",