uvd-describe-sdk 0.1.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.
- package/LICENSE +21 -0
- package/README.md +612 -0
- package/dist/client-s3KrgrCt.d.mts +1537 -0
- package/dist/client-s3KrgrCt.d.ts +1537 -0
- package/dist/config-Y2VK_neB.d.mts +169 -0
- package/dist/config-Y2VK_neB.d.ts +169 -0
- package/dist/index.d.mts +488 -0
- package/dist/index.d.ts +488 -0
- package/dist/index.js +1082 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +1038 -0
- package/dist/index.mjs.map +1 -0
- package/dist/partner/index.d.mts +194 -0
- package/dist/partner/index.d.ts +194 -0
- package/dist/partner/index.js +77 -0
- package/dist/partner/index.js.map +1 -0
- package/dist/partner/index.mjs +71 -0
- package/dist/partner/index.mjs.map +1 -0
- package/dist/x402/index.d.mts +91 -0
- package/dist/x402/index.d.ts +91 -0
- package/dist/x402/index.js +29 -0
- package/dist/x402/index.js.map +1 -0
- package/dist/x402/index.mjs +26 -0
- package/dist/x402/index.mjs.map +1 -0
- package/package.json +97 -0
- package/src/caveats.ts +124 -0
- package/src/client.ts +953 -0
- package/src/config.ts +181 -0
- package/src/errors.ts +596 -0
- package/src/format.ts +67 -0
- package/src/hashes.ts +229 -0
- package/src/index.ts +192 -0
- package/src/jitter.ts +112 -0
- package/src/parse.ts +388 -0
- package/src/partner/index.ts +295 -0
- package/src/raters.ts +118 -0
- package/src/recovery.ts +254 -0
- package/src/types.ts +457 -0
- package/src/x402/index.ts +123 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,488 @@
|
|
|
1
|
+
import { D as DescribeErrorKind, P as PaymentEvidence, A as AgentReputation, I as IndexHealth, L as LeaderboardRow, W as WalletBreakdown, a as WalletReputation } from './client-s3KrgrCt.js';
|
|
2
|
+
export { b as Activity, C as CAVEAT_CODES, c as CAVEAT_SCOPE_FREE, d as CAVEAT_SCOPE_METERED, e as Caveat, f as CaveatCode, g as Concentration, h as Confidence, i as DescribeClient, j as DescribeClientConfig, k as DescribeError, l as DescribeFailure, m as DescribeHTTPError, n as DescribeMalformedHash, o as DescribeNotFound, p as DescribePartnerRejected, q as DescribePartnerUnsigned, r as DescribePaymentRefused, s as DescribePaymentRequired, t as DescribeTimeout, u as DescribeUnparseable, v as DescribeUnreachable, F as Facet, H as HealthChain, K as KnownCaveatCode, N as Network, O as Ownership, w as PartnerSigner, x as PaymentAttempt, R as Rating, S as Sealed, y as SelfRated, z as Snapshot, T as Timestamp, B as WalletChainRow, X as X402Challenge, E as X402Payer, G as failOpenCovers, J as failedAfterPaying, M as hasCaveat, Q as isKnownCaveatCode } from './client-s3KrgrCt.js';
|
|
3
|
+
export { D as DEFAULT_BASE_URL, a as DEFAULT_JITTER_MS, b as DEFAULT_SITE_URL, c as DEFAULT_TIMEOUT_MS, P as PARTNER_CHAIN_ID, d as PARTNER_KEY_ENV, S as SDK_NAME, e as SDK_VERSION, T as TREASURY_EVM, u as userAgent } from './config-Y2VK_neB.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* What to do INSTEAD โ the sentence `transient` cannot say.
|
|
7
|
+
*
|
|
8
|
+
* ## Where this came from, and it is not ours
|
|
9
|
+
*
|
|
10
|
+
* Contributed by **Execution Market** in `#agents` on **2026-08-30**, out of
|
|
11
|
+
* their own 502 body gaining `detail.code`, `detail.retryable` and
|
|
12
|
+
* `detail.recovery` with ten typed codes โ *"para que lo codifiquen de su
|
|
13
|
+
* lado"*. Their argument is the measurement that justifies this whole file:
|
|
14
|
+
*
|
|
15
|
+
* > *"SIETE de los diez son TERMINALES (`retryable: false`). Eso es lo que mรกs
|
|
16
|
+
* > les sirve: hoy su flota no puede distinguir 'reintenta' de 'no insistas', y
|
|
17
|
+
* > contra `AUTHORIZATION_EXPIRED` reintentar es quemar llamadas contra una
|
|
18
|
+
* > ventana cerrada hace **317 HORAS**."*
|
|
19
|
+
*
|
|
20
|
+
* 317 hours of retries against a door that closed is the cost of having only
|
|
21
|
+
* the boolean. Measured on our side the same day, before this file existed:
|
|
22
|
+
* `grep -rc recovery src/` was **0** in both SDKs, while `transient` and
|
|
23
|
+
* `serviceFault` were already on every error. So we had exactly half of it โ we
|
|
24
|
+
* could say whether retrying helps, and had no way at all to say what to do
|
|
25
|
+
* when it does not. A boolean that says "no" leaves the caller stuck; a
|
|
26
|
+
* sentence that names another door lets them keep going.
|
|
27
|
+
*
|
|
28
|
+
* ๐ด **What was deliberately NOT absorbed: their ten codes.**
|
|
29
|
+
* `AUTHORIZATION_EXPIRED`, escrow, release-to-worker, payout wallets โ that is
|
|
30
|
+
* Execution Market's API, and this SDK does not wrap it. It wraps describe.net,
|
|
31
|
+
* which holds no escrow and expires no authorization of its own. A consumer
|
|
32
|
+
* branching on `AUTHORIZATION_EXPIRED` against this index would be writing dead
|
|
33
|
+
* code against a domain we do not touch. The **pattern** is the contribution;
|
|
34
|
+
* the table below is ours and had to be re-derived failure by failure.
|
|
35
|
+
*
|
|
36
|
+
* ## Why a sentence, and not a second enum
|
|
37
|
+
*
|
|
38
|
+
* The machine-readable axis already exists and is `kind` โ plus `transient`
|
|
39
|
+
* ("would retrying help?") and `serviceFault` ("is this describe.net's
|
|
40
|
+
* fault?"). A `recoveryCode` enum would be a SECOND taxonomy over the same
|
|
41
|
+
* failures, kept in sync by hand, and consumers would start branching on it
|
|
42
|
+
* instead of on `kind`; the day the two disagree, the branch that fires is the
|
|
43
|
+
* wrong one. What was missing is not another thing to switch on, it is the
|
|
44
|
+
* paragraph a human (or an agent reading its own exception) needs in order to
|
|
45
|
+
* do something else.
|
|
46
|
+
*
|
|
47
|
+
* ๐ด So: **branch on `kind`, read `recovery`.** Never parse it, never match on
|
|
48
|
+
* it โ same contract the caveats carry, where `code` is frozen and the text is
|
|
49
|
+
* free to be re-written (`caveats.ts`, and describe.net's own rule: *"EL TEXTO
|
|
50
|
+
* puede cambiar sin aviso; EL CODE jamรกs"*). The stability a test needs comes
|
|
51
|
+
* from the strings living HERE, once, exported: pin `RECOVERY.payment_required`
|
|
52
|
+
* and the assertion cannot rot into a prose match.
|
|
53
|
+
*
|
|
54
|
+
* ## ๐ด The rule that keeps an empty one honest
|
|
55
|
+
*
|
|
56
|
+
* **A recovery that does not work is worse than no recovery**, because it sends
|
|
57
|
+
* the caller to do something useless with confidence โ which is the same shape
|
|
58
|
+
* as the 317 hours, one level up. So a `null` here is a decision that was made,
|
|
59
|
+
* not a field somebody forgot: `timeout` has one and its reasoning is written
|
|
60
|
+
* at the entry.
|
|
61
|
+
*
|
|
62
|
+
* And a recovery is never "retry" in other words โ `transient` already says
|
|
63
|
+
* that, and repeating it would be the second copy of a fact this package keeps
|
|
64
|
+
* in one place. Every entry names something ELSE: another route, another field,
|
|
65
|
+
* another mode, or the condition on the caller's side that has to be fixed.
|
|
66
|
+
*
|
|
67
|
+
* ## ๐ด Every string in this file is a literal, and that IS the redaction guard
|
|
68
|
+
*
|
|
69
|
+
* Execution Market's other warning of the same day: an unclassified error *"can
|
|
70
|
+
* carry an RPC URL with its API key inside"*, and they added a test with a fake
|
|
71
|
+
* secret that fails if it leaks. The service side of the house has had that
|
|
72
|
+
* guard for a while โ `describe-net/describenet/chain/rpc.py::_redact` replaces
|
|
73
|
+
* the endpoint with `<rpc-url>` in anything about to be logged or raised,
|
|
74
|
+
* because the key lives in the URL path.
|
|
75
|
+
*
|
|
76
|
+
* The SDK equivalent is structural rather than a filter: **this module holds
|
|
77
|
+
* nothing but frozen literals and interpolates nothing.** `recoveryFor()` picks
|
|
78
|
+
* one by key; no call site builds a recovery out of a message, a URL, a cause,
|
|
79
|
+
* or any other string that came from outside this file. A filter can be
|
|
80
|
+
* forgotten at one call site; a table has no call site to forget.
|
|
81
|
+
*
|
|
82
|
+
* That boundary is drawn where it is on purpose, and the neighbouring field is
|
|
83
|
+
* the contrast: `DescribeUnreachable`'s `message` DOES quote `String(error)`,
|
|
84
|
+
* because a transport failure with the cause stripped out is undebuggable. The
|
|
85
|
+
* message is forensic and belongs to whoever is reading the exception; the
|
|
86
|
+
* recovery is advice this package WROTE and is the string most likely to be
|
|
87
|
+
* copied into a log line, a ticket or a Slack message. `recovery.test.ts`
|
|
88
|
+
* mounts a fetch that throws a URL carrying a fake key and asserts the recovery
|
|
89
|
+
* comes back byte-identical to the table.
|
|
90
|
+
*
|
|
91
|
+
* ## ๐ด Parity: what a recovery text is allowed to name
|
|
92
|
+
*
|
|
93
|
+
* The Python SDK ships the same field with the same name and the SAME text, so
|
|
94
|
+
* a consumer who moves stacks does not read two different pieces of advice for
|
|
95
|
+
* one failure. That is only possible if a text names things BOTH SDKs share:
|
|
96
|
+
* HTTP routes, headers, wire fields, env vars, chain ids, and the numbers the
|
|
97
|
+
* service publishes. It may NOT name a language-specific spelling โ this
|
|
98
|
+
* package's `jitterMs` is the Python package's `jitter` and it is in SECONDS
|
|
99
|
+
* (see the README's parity note), so a text naming it would have to be either
|
|
100
|
+
* different or wrong. Options are therefore described by what they do, and the
|
|
101
|
+
* caller finds the spelling in their own SDK, one line away.
|
|
102
|
+
*/
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* The keys of the table.
|
|
106
|
+
*
|
|
107
|
+
* Every `kind`, plus `rate_limited` โ the one place where a kind is not fine
|
|
108
|
+
* enough. A 429 and a 422 are both `http_4xx`, and their recoveries are
|
|
109
|
+
* opposites: one says *this is your input, fix it*, the other says *this is not
|
|
110
|
+
* your request at all, spread your fleet*. Merging them would produce a
|
|
111
|
+
* paragraph that is wrong for both, which is exactly the mush this file exists
|
|
112
|
+
* to avoid. The split lives in `recoveryFor()`, on the same `status === 429`
|
|
113
|
+
* condition that already decides `transient` in `DescribeHTTPError`.
|
|
114
|
+
*/
|
|
115
|
+
type RecoveryKey = DescribeErrorKind | 'rate_limited';
|
|
116
|
+
/**
|
|
117
|
+
* The frozen table. One entry per {@link RecoveryKey}, `null` where there is
|
|
118
|
+
* honestly no other door.
|
|
119
|
+
*
|
|
120
|
+
* The `Record` annotation is half the guard: a `kind` added to the union
|
|
121
|
+
* without an entry here does not compile. The other half is
|
|
122
|
+
* `recovery.test.ts`, which walks every kind at runtime.
|
|
123
|
+
*/
|
|
124
|
+
declare const RECOVERY: Readonly<Record<RecoveryKey, string | null>>;
|
|
125
|
+
/**
|
|
126
|
+
* The recovery for one failure, or `null` when there honestly is none.
|
|
127
|
+
*
|
|
128
|
+
* Called from exactly one place โ the `DescribeError` constructor โ so every
|
|
129
|
+
* error in this package gets its recovery from the same table by construction,
|
|
130
|
+
* and a subclass cannot forget to pass one or invent one of its own.
|
|
131
|
+
*
|
|
132
|
+
* `status` is read for one case only: 429 is the single 4xx that is not the
|
|
133
|
+
* caller's bug, and it takes the `rate_limited` entry. Same condition that
|
|
134
|
+
* already decides `transient` one file over.
|
|
135
|
+
*/
|
|
136
|
+
declare function recoveryFor(kind: DescribeErrorKind, status?: number): string | null;
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* How a score is written down. One rule, ecosystem-wide.
|
|
140
|
+
*
|
|
141
|
+
* **Two decimals, trailing zeros trimmed.** `86.65`, `84.7`, `87` โ never `82.0`.
|
|
142
|
+
*
|
|
143
|
+
* Fixed on 2026-08-29 after the three consumers each rendered the SAME number
|
|
144
|
+
* differently (`86.653045`, `86.7`, `86` โ one field, three strings), and
|
|
145
|
+
* decided by measurement rather than taste: over 47 real distinct scores,
|
|
146
|
+
* rounding to 0 decimals merges 23 pairs of *different* agents into identical
|
|
147
|
+
* strings, 1 decimal merges 4, and 2 decimals merges 1. Trimming matters as
|
|
148
|
+
* much as the count โ two surfaces both "agreeing on 1 decimal" still printed
|
|
149
|
+
* `82.0` and `82` for the same agent.
|
|
150
|
+
*
|
|
151
|
+
* The canonical one-liner, byte-identical across the two languages
|
|
152
|
+
* (`docs.describe.net`, ยง"Displaying a score"):
|
|
153
|
+
*
|
|
154
|
+
* ```js
|
|
155
|
+
* String(parseFloat(x.toFixed(2))) // JavaScript
|
|
156
|
+
* ```
|
|
157
|
+
* ```python
|
|
158
|
+
* f"{round(x, 2):g}" # Python
|
|
159
|
+
* ```
|
|
160
|
+
*
|
|
161
|
+
* **Live witness case**: the agent scored `83.0` renders as `83` on all three
|
|
162
|
+
* surfaces โ where `toFixed(2)` alone prints `83.00` and `toFixed(1)` prints
|
|
163
|
+
* `83.0`. It is the one value that tells the three candidate rules apart, which
|
|
164
|
+
* is why `format.test.ts` tests it first.
|
|
165
|
+
*
|
|
166
|
+
* This is a DISPLAY convention. The API keeps serving the full-precision number
|
|
167
|
+
* (six decimals) and what you compute with is the number, never the string โ
|
|
168
|
+
* which is why the two functions below are separate and why `formatScore`
|
|
169
|
+
* returns a `string`. A helper that rounded the number in place would push a
|
|
170
|
+
* lossy value back into arithmetic, and averaging rounded members is how an
|
|
171
|
+
* aggregate ends up disagreeing with the members it aggregates.
|
|
172
|
+
*/
|
|
173
|
+
/**
|
|
174
|
+
* The canonical display string, or `null` when there is nothing to display.
|
|
175
|
+
*
|
|
176
|
+
* `null` in, `null` out โ never `"0"`, never `"โ"`. Choosing the placeholder
|
|
177
|
+
* for absence is the surface's job and it is a different decision per surface;
|
|
178
|
+
* inventing one here would put this package's taste into every consumer, and
|
|
179
|
+
* `"0"` in particular would publish "worst possible reputation" for "nobody has
|
|
180
|
+
* rated this yet" (invariante 7 of the index, and R1 of this SDK).
|
|
181
|
+
*
|
|
182
|
+
* A non-finite input (a `NaN` from a malformed payload) is also `null`: a
|
|
183
|
+
* number we cannot name is not a number we may put describe.net's name on.
|
|
184
|
+
*/
|
|
185
|
+
declare function formatScore(value: number | null | undefined): string | null;
|
|
186
|
+
/**
|
|
187
|
+
* The same rounding, kept as a `number`.
|
|
188
|
+
*
|
|
189
|
+
* For the one case where a number is what you need: MeshRelay rounds at the
|
|
190
|
+
* boundary where the value ENTERS the system rather than at each surface,
|
|
191
|
+
* because "the bug this closes is one number rendering differently in two
|
|
192
|
+
* places" (`describenet.js:204-208`). If you do that, use this โ and be aware
|
|
193
|
+
* you have made the value lossy on purpose. Everything else should carry the
|
|
194
|
+
* full-precision number and call `formatScore` at the pixel.
|
|
195
|
+
*/
|
|
196
|
+
declare function roundScore(value: number | null | undefined): number | null;
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* How many distinct counterparties are behind a wallet's reputation โ and the
|
|
200
|
+
* two ways of reconstructing that number that are both WRONG.
|
|
201
|
+
*
|
|
202
|
+
* Contributed by **MeshRelay**, `#agents` on MeshRelay, **2026-08-30**. The
|
|
203
|
+
* seven lines of the helper are not the contribution; the two measurements are,
|
|
204
|
+
* and they are the reason this file has a docstring longer than its code.
|
|
205
|
+
*/
|
|
206
|
+
/**
|
|
207
|
+
* The distinct-rater count of a wallet, or `null` when there is none to give.
|
|
208
|
+
*
|
|
209
|
+
* ## ๐ด Read this before you use the number
|
|
210
|
+
*
|
|
211
|
+
* `distinct_raters` at the top level of `GET /wallets/{wallet}/chains` is
|
|
212
|
+
* `COUNT(DISTINCT client)` across every chain AND every identity: one rater who
|
|
213
|
+
* reviewed on two chains counts **once**. There is no way to rebuild that from
|
|
214
|
+
* the per-chain rows, and MeshRelay measured both attempts on 2026-08-30:
|
|
215
|
+
*
|
|
216
|
+
* * **Summing the chains DOUBLE-COUNTS** whoever rated on more than one of
|
|
217
|
+
* them. Measured case: the karma-hello wallet reads **9** distinct raters
|
|
218
|
+
* globally while its per-chain figures add up to **11**.
|
|
219
|
+
* * **Taking the maximum UNDERESTIMATES.** Measured case: 3 raters on base and
|
|
220
|
+
* 4 *different* ones on avalanche is **7** real counterparties, and the
|
|
221
|
+
* maximum answers **4**.
|
|
222
|
+
*
|
|
223
|
+
* So the per-chain maximum is a **LOWER BOUND โ never the answer**, and summing
|
|
224
|
+
* is not a second-best either: it is wrong in the opposite direction. That pair
|
|
225
|
+
* of sentences is the contribution; without them this helper reads like a
|
|
226
|
+
* one-liner and gets used as the truth.
|
|
227
|
+
*
|
|
228
|
+
* **One live vector proves all three branches at once.** Verified against
|
|
229
|
+
* `api.describe.net` on 2026-08-30 (free route), wallet
|
|
230
|
+
* `0xcc28โฆ4821`: global `distinct_raters` **129**, per chain base **113** and
|
|
231
|
+
* ethereum **21**. The maximum answers 113 (**16 short**), the sum answers 134
|
|
232
|
+
* (**5 over**), and only the global figure is right. It is the fixture this
|
|
233
|
+
* file's test pins, because a vector where two wrong answers land on opposite
|
|
234
|
+
* sides of the true one cannot be passed by accident.
|
|
235
|
+
*
|
|
236
|
+
* ## ๐ด The fallback is a COMPATIBILITY path, not a normal one
|
|
237
|
+
*
|
|
238
|
+
* โ ๏ธ Corrected while writing this, and the correction matters more than the
|
|
239
|
+
* line it replaces: an earlier draft called the per-chain maximum a "fallback
|
|
240
|
+
* for when the global figure is not there", which invites a reader to treat the
|
|
241
|
+
* global field as optional. It is not. describe.net has served wallet-level
|
|
242
|
+
* `distinct_raters` since `b753c9c` โ *"el dato ya estaba y no lo leรญamos"*,
|
|
243
|
+
* committed **2026-08-28**, which MeshRelay's own note dates 08-29 (the day they
|
|
244
|
+
* read it; both are written here because a reader will find the other one and
|
|
245
|
+
* think one of us is wrong) โ and their comment says the maximum is kept *"only
|
|
246
|
+
* as a fallback for a cached response predating that deploy"*
|
|
247
|
+
* (`meshrelay/meshrelayserv/describenet.js:228-230`,
|
|
248
|
+
* read 2026-08-30). Confirmed live the same day: the free route serves
|
|
249
|
+
* `distinct_raters` at the top level on every wallet.
|
|
250
|
+
*
|
|
251
|
+
* So in a client written after that date the fallback branch is unreachable
|
|
252
|
+
* unless you cache responses and outlive one of their deploys โ which MeshRelay
|
|
253
|
+
* does, and is why the branch exists at all. It is kept for them and for anyone
|
|
254
|
+
* replaying a stored payload, not because the field might be missing today.
|
|
255
|
+
*
|
|
256
|
+
* ## What this function therefore does
|
|
257
|
+
*
|
|
258
|
+
* Prefers the global count whenever the object carries one; falls back to the
|
|
259
|
+
* per-chain maximum only when it does not. What comes back is exact in the first
|
|
260
|
+
* case and a lower bound in the second, and there is no third answer it could
|
|
261
|
+
* give. **It never sums, and neither should you.**
|
|
262
|
+
*
|
|
263
|
+
* ## ๐ด Why this is not called `maxDistinctRaters`
|
|
264
|
+
*
|
|
265
|
+
* Because MeshRelay, who wrote it under that name, asked for the rename when
|
|
266
|
+
* they handed it over (2026-08-30): *"ese nombre invita a creer que el mรกximo es
|
|
267
|
+
* la respuesta correcta, cuando es el รบltimo recurso. El mรญo estรก mal nombrado y
|
|
268
|
+
* lo arrastro de cuando el nivel wallet no existรญa."*
|
|
269
|
+
*
|
|
270
|
+
* That is worth keeping written down, because the old name is what a reader will
|
|
271
|
+
* search for and because it is the failure this whole file guards against
|
|
272
|
+
* arriving through the API surface: a function named after its fallback
|
|
273
|
+
* advertises the fallback, and the fallback is the wrong answer. Their name
|
|
274
|
+
* survives here, in the provenance, which is where it belongs.
|
|
275
|
+
*
|
|
276
|
+
* ## Two `null`s that are not zero
|
|
277
|
+
*
|
|
278
|
+
* * A wallet with no eligible rating anywhere serves `distinct_raters: null`
|
|
279
|
+
* with `chains: []` โ verified live 2026-08-30 against `0xdEaDโฆBEEF`. The
|
|
280
|
+
* answer is `null`, **never `0`**: "nobody has rated this" and "zero people
|
|
281
|
+
* rated this after we counted" are the same sentence, but `0` is a number a
|
|
282
|
+
* caller will divide by, average, or render as a bar of length zero next to
|
|
283
|
+
* wallets whose bar means something. `Math.max(...[])` is `-Infinity`, which
|
|
284
|
+
* is the concrete bug this branch exists to not have.
|
|
285
|
+
* * A `null` INPUT (the fail-open value of `wallet()`, i.e. "we could not ask
|
|
286
|
+
* describe.net") also gives `null`. Accepting it is deliberate: it lets a
|
|
287
|
+
* caller write `resolveDistinctRaters(await describe.wallet(w))` without a
|
|
288
|
+
* null-check that would only exist to satisfy the compiler, and it keeps the
|
|
289
|
+
* three absences of this package from collapsing โ an unreachable index and
|
|
290
|
+
* an unrated wallet both mean "no number", and neither means zero.
|
|
291
|
+
*
|
|
292
|
+
* Structurally typed rather than tied to `WalletReputation` so it also works on
|
|
293
|
+
* a payload you parsed yourself or pulled out of your own cache.
|
|
294
|
+
*/
|
|
295
|
+
declare function resolveDistinctRaters(wallet: {
|
|
296
|
+
distinctRaters: number | null;
|
|
297
|
+
chains: readonly {
|
|
298
|
+
distinctRaters: number;
|
|
299
|
+
}[];
|
|
300
|
+
} | null | undefined): number | null;
|
|
301
|
+
|
|
302
|
+
/**
|
|
303
|
+
* Shape validation for the hash fields โ *"el 200 sin tx"*, from KarmaKadabra.
|
|
304
|
+
*
|
|
305
|
+
* Pure: no network, no clock, no state. Strings in, booleans out.
|
|
306
|
+
*
|
|
307
|
+
* ## Where this comes from
|
|
308
|
+
*
|
|
309
|
+
* Contributed by **KarmaKadabra**, `#agents` on MeshRelay, **2026-08-30**. Their
|
|
310
|
+
* words:
|
|
311
|
+
*
|
|
312
|
+
* > *"Un 200 que no hizo la cosa es peor que un 503, porque el cliente lo toma
|
|
313
|
+
* > por bueno: si nosotros no chequeรกramos el tx, habrรญamos contado 14 ratings
|
|
314
|
+
* > que no existen. Nosotros lo cazamos con un sello que exige forma de hash โ
|
|
315
|
+
* > pero el contrato deberรญa decirlo, no cada cliente descubrirlo."*
|
|
316
|
+
*
|
|
317
|
+
* The second half is why this lives in the SDK: the check is a property of the
|
|
318
|
+
* CONTRACT, and three consumers each discovering it separately is three chances
|
|
319
|
+
* to get it wrong. Verified before writing a line: neither this SDK nor its
|
|
320
|
+
* Python twin validated the shape of any hash field on 2026-08-30.
|
|
321
|
+
*
|
|
322
|
+
* ## ๐ด Why `^0x[0-9a-f]{64}$` alone would have been a disaster
|
|
323
|
+
*
|
|
324
|
+
* The obvious version of this file โ one EVM regex โ would have flagged **every
|
|
325
|
+
* Solana rating in the index** as malformed. Two independent confirmations, both
|
|
326
|
+
* read 2026-08-30:
|
|
327
|
+
*
|
|
328
|
+
* * from the writer: `describe-net/describenet/solana_indexer.py:436` puts
|
|
329
|
+
* `firma["signature"]` โ a base58 signature โ into the `tx_hash` column of
|
|
330
|
+
* the INSERT at `indexer.py:153-157`, the same column the EVM indexer fills
|
|
331
|
+
* with `0xโฆ`. Solana writes to the same tables on purpose, so this is by
|
|
332
|
+
* construction and not an accident of one sample;
|
|
333
|
+
* * from the wire (measured by the Python twin against `GET /feed`): avalanche
|
|
334
|
+
* and celo serve 66-char `0x` + 64 hex, solana serves 87- and 88-char base58
|
|
335
|
+
* with no prefix.
|
|
336
|
+
*
|
|
337
|
+
* An alarm that screams about good data is worse than no alarm: people learn to
|
|
338
|
+
* ignore it, and then it is silent on the day it is right. So this validates the
|
|
339
|
+
* **union** of the legitimate shapes, never the intersection.
|
|
340
|
+
*
|
|
341
|
+
* The shapes the index emits today, each with its source:
|
|
342
|
+
*
|
|
343
|
+
* 1. **EVM hash** โ `0x` + 64 hex. `chain/decode.py:253` does `"0x" + โฆhex()`
|
|
344
|
+
* over a `bytes32` (`_NEW_FEEDBACK_TYPES:85`). This is `tx_hash`,
|
|
345
|
+
* `revoked_tx` and `feedback_hash` on the ten EVM chains.
|
|
346
|
+
* 2. **Solana signature** โ base58 (Bitcoin alphabet: no `0`, `O`, `I`, `l`),
|
|
347
|
+
* 86โ88 characters. 64 bytes in base58 is 87โ88; 86 is reachable with leading
|
|
348
|
+
* zero bytes. On Solana `feedback_hash` is **NULL on purpose**, so a hole
|
|
349
|
+
* there is correct and not a fault.
|
|
350
|
+
* 3. **Bare digest** โ 64 hex with **no** `0x`. That is `Snapshot.inputs_digest`,
|
|
351
|
+
* which comes out of `hashlib.sha256(...).hexdigest()` in `aggregate.py:1920`.
|
|
352
|
+
* Demanding the `0x` prefix would have marked every citable snapshot as
|
|
353
|
+
* malformed.
|
|
354
|
+
* 4. **The `pending` sentinel** โ only on the `X-Payment-Receipt` header, whose
|
|
355
|
+
* own OpenAPI declares it: the settlement hash *"or `pending` if settlement
|
|
356
|
+
* has not reported one"*. It is a LEGITIMATE value, which is why
|
|
357
|
+
* {@link looksLikeSettlementReceipt} exists separately: treating it as
|
|
358
|
+
* garbage would fire an alarm on the happy path of every fresh payment.
|
|
359
|
+
*
|
|
360
|
+
* ## ๐ด What is deliberately NOT validated: `build_sha`
|
|
361
|
+
*
|
|
362
|
+
* `IndexHealth.buildSha` looks like a hash and is not one, and the measurement
|
|
363
|
+
* that settles it is `describe-net/scripts/build_lambda_zip.py:64` (read
|
|
364
|
+
* 2026-08-30): `estampa = sha + ("-dirty" if sucio else "")`. A legitimate
|
|
365
|
+
* deploy can therefore publish `"<40 hex>-dirty"`, and a validator would scream
|
|
366
|
+
* about a perfectly good build โ forever, on every `/health` call. The general
|
|
367
|
+
* rule that falls out of it, and it is the one to apply to the next field:
|
|
368
|
+
* **validate the identifiers a caller will carry somewhere to verify (an
|
|
369
|
+
* explorer, a digest comparison); leave alone the strings that only describe a
|
|
370
|
+
* build.** Nobody looks up a `build_sha`; the service already refuses to publish
|
|
371
|
+
* its `unknown` default as if it were a SHA (`api.py:2439-2456`).
|
|
372
|
+
*
|
|
373
|
+
* ## The question this module answers โ and the one it does not
|
|
374
|
+
*
|
|
375
|
+
* It answers **"does this have the shape of an on-chain identifier?"**. It does
|
|
376
|
+
* NOT answer "does this transaction exist?" or "does it say what the index says
|
|
377
|
+
* it says": that is verified in an explorer, which is the entire point of the
|
|
378
|
+
* field (the service's own schema: *"go verify it in an explorer, which is the
|
|
379
|
+
* point"*). A shape check cannot prove existence and does not pretend to.
|
|
380
|
+
*
|
|
381
|
+
* What it does catch is what bit KarmaKadabra: the empty string, `"null"`,
|
|
382
|
+
* `"undefined"`, `"0x"`, `"0x0"`, a truncated hash, an error message parked in
|
|
383
|
+
* the field. Every one of those sails through an `if (rating.txHash)` today with
|
|
384
|
+
* nothing making a sound.
|
|
385
|
+
*
|
|
386
|
+
* ๐ด **And it deliberately does not validate per chain.** A `feedback_hash`
|
|
387
|
+
* shaped like a Solana signature is accepted even though Solana emits none
|
|
388
|
+
* today. Being strict per field would trade a cheap false negative (letting an
|
|
389
|
+
* odd-but-valid shape through) for an expensive false positive (screaming about
|
|
390
|
+
* good data the day the service extends a field), and that contradicts the
|
|
391
|
+
* passthrough rule this package is built on: type what is known, PRESERVE what
|
|
392
|
+
* is not.
|
|
393
|
+
*/
|
|
394
|
+
/**
|
|
395
|
+
* The one non-hash value the `X-Payment-Receipt` header declares legitimate.
|
|
396
|
+
*
|
|
397
|
+
* The live OpenAPI says it, not us: the settlement transaction hash *"or
|
|
398
|
+
* `pending` if settlement has not reported one"*.
|
|
399
|
+
*/
|
|
400
|
+
declare const SETTLEMENT_PENDING = "pending";
|
|
401
|
+
/**
|
|
402
|
+
* Does `value` have the shape of an on-chain identifier this index emits?
|
|
403
|
+
*
|
|
404
|
+
* The UNION of the three measured shapes (EVM hash, Solana signature, bare
|
|
405
|
+
* digest) โ never the intersection. See the module header for why an EVM-only
|
|
406
|
+
* regex would have marked every Solana rating as malformed.
|
|
407
|
+
*
|
|
408
|
+
* It does not prove the transaction exists. That is the explorer's job.
|
|
409
|
+
*/
|
|
410
|
+
declare function looksLikeOnchainId(value: string): boolean;
|
|
411
|
+
/**
|
|
412
|
+
* The same, plus the `pending` sentinel. For `X-Payment-Receipt` and nothing
|
|
413
|
+
* else.
|
|
414
|
+
*
|
|
415
|
+
* `pending` is not garbage: it is the seller saying *"I charged you and
|
|
416
|
+
* settlement has not reported the hash yet"*, and it is in their OpenAPI.
|
|
417
|
+
* Marking it malformed would turn the happy path of every freshly settled
|
|
418
|
+
* payment into an alarm.
|
|
419
|
+
*/
|
|
420
|
+
declare function looksLikeSettlementReceipt(value: string): boolean;
|
|
421
|
+
/** Anything that carries the marks of its own malformed hash fields. */
|
|
422
|
+
interface MalformedCarrier {
|
|
423
|
+
malformedHashes?: readonly string[];
|
|
424
|
+
}
|
|
425
|
+
/**
|
|
426
|
+
* Every malformed hash field of a result, located.
|
|
427
|
+
*
|
|
428
|
+
* Walks the places a hash can hide in a parsed result and returns qualified
|
|
429
|
+
* paths, in the order they appear:
|
|
430
|
+
*
|
|
431
|
+
* ```ts
|
|
432
|
+
* ['ratings[3].tx_hash', 'snapshot.inputs_digest', 'payment.receipt']
|
|
433
|
+
* ```
|
|
434
|
+
*
|
|
435
|
+
* Wire names (`tx_hash`), not ours (`txHash`), on purpose: this string is what
|
|
436
|
+
* ends up in a log line or a ticket to whoever runs the index, and it has to
|
|
437
|
+
* name the field the way the API does.
|
|
438
|
+
*
|
|
439
|
+
* An empty array is the normal case and means "no field arrived malformed" โ it
|
|
440
|
+
* says nothing about which fields arrived at all. An absent hash is legitimate
|
|
441
|
+
* and is not reported here.
|
|
442
|
+
*/
|
|
443
|
+
declare function malformedHashReport(result: {
|
|
444
|
+
ratings?: readonly MalformedCarrier[];
|
|
445
|
+
snapshot?: MalformedCarrier | null;
|
|
446
|
+
payment?: MalformedCarrier | null;
|
|
447
|
+
} | null | undefined): string[];
|
|
448
|
+
|
|
449
|
+
/**
|
|
450
|
+
* Wire JSON โ typed shape.
|
|
451
|
+
*
|
|
452
|
+
* Three rules, and each one is a bug that already happened somewhere:
|
|
453
|
+
*
|
|
454
|
+
* 1. **`null` survives.** `optNumber` returns `null` for `null` and NEVER `0`.
|
|
455
|
+
* Every `|| 0` in a parser is an invariant-7 violation waiting for its first
|
|
456
|
+
* unrated wallet.
|
|
457
|
+
* 2. **Unknown fields survive.** Every result keeps `raw`. The server may add a
|
|
458
|
+
* field tomorrow and a consumer must not wait for our release to read it.
|
|
459
|
+
* 3. **A body that is not the shape we asked for is `unparseable`, not
|
|
460
|
+
* garbage-in-silence.** The failure that has to be impossible here is a
|
|
461
|
+
* response that parses "successfully" into an object full of zeros.
|
|
462
|
+
* 4. **A hash field that is not a hash is dropped and MARKED, never passed
|
|
463
|
+
* through.** Added 2026-08-30 from KarmaKadabra's *"el 200 sin tx"*. The
|
|
464
|
+
* typed field goes `null` โ nobody builds an explorer link out of garbage โ
|
|
465
|
+
* and its wire name goes into the `malformedHashes` of the object that owns
|
|
466
|
+
* it, so that **absent** (`null`, list empty) stays distinguishable from
|
|
467
|
+
* **malformed** (`null`, name in the list). It is rule 1 one level down: the
|
|
468
|
+
* absence of a value and a value that is nonsense are different facts, and
|
|
469
|
+
* collapsing them is the failure this file exists to prevent. See
|
|
470
|
+
* `hashes.ts`, and `client.ts` for how the fact reaches the caller.
|
|
471
|
+
*/
|
|
472
|
+
|
|
473
|
+
/** `GET /wallets/{wallet}/chains`. Requires `wallet` โ everything else may be absent. */
|
|
474
|
+
declare function parseWalletReputation(payload: unknown): WalletReputation;
|
|
475
|
+
/** `GET /reputation/wallet/{wallet}` โ metered. */
|
|
476
|
+
declare function parseWalletBreakdown(payload: unknown, payment: PaymentEvidence | null): WalletBreakdown;
|
|
477
|
+
/** `GET /reputation/agent/{network}/{agent_id}` โ metered. */
|
|
478
|
+
declare function parseAgentReputation(payload: unknown, payment: PaymentEvidence | null): AgentReputation;
|
|
479
|
+
/**
|
|
480
|
+
* `GET /leaderboard` โ a bare JSON array (verified live 2026-08-30: 100 rows,
|
|
481
|
+
* no envelope). NOT `{rows: [...]}`, which is what a reader expecting a
|
|
482
|
+
* paginated shape would assume.
|
|
483
|
+
*/
|
|
484
|
+
declare function parseLeaderboard(payload: unknown): LeaderboardRow[];
|
|
485
|
+
/** `GET /health`. */
|
|
486
|
+
declare function parseHealth(payload: unknown): IndexHealth;
|
|
487
|
+
|
|
488
|
+
export { AgentReputation, DescribeErrorKind, IndexHealth, LeaderboardRow, PaymentEvidence, RECOVERY, type RecoveryKey, SETTLEMENT_PENDING, WalletBreakdown, WalletReputation, formatScore, looksLikeOnchainId, looksLikeSettlementReceipt, malformedHashReport, parseAgentReputation, parseHealth, parseLeaderboard, parseWalletBreakdown, parseWalletReputation, recoveryFor, resolveDistinctRaters, roundScore };
|