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 ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-2025 Ultravioleta DAO
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,612 @@
1
+ # uvd-describe-sdk
2
+
3
+ Read reputation from [describe.net](https://describe.net) — the ERC-8004 reputation
4
+ index of Ultravioleta DAO, across 11 chains.
5
+
6
+ ```bash
7
+ npm install uvd-describe-sdk
8
+ ```
9
+
10
+ **Zero runtime dependencies.** The free routes need no package, no credential and
11
+ no account. The metered routes need one of two things, and both live behind
12
+ subpaths so a free-only consumer installs neither:
13
+
14
+ * **pay** the 402 through [`uvd-x402-sdk`](https://www.npmjs.com/package/uvd-x402-sdk)
15
+ (`uvd-describe-sdk/x402`), an *optional* peer;
16
+ * or **don't** — if your wallet is on describe.net's partner allowlist, sign
17
+ each request instead and read the metered routes for free
18
+ (`uvd-describe-sdk/partner`, see [the partner rail](#not-paying-the-partner-rail)).
19
+
20
+ ---
21
+
22
+ ## Sixty seconds
23
+
24
+ ```ts
25
+ import { DescribeClient, formatScore } from 'uvd-describe-sdk';
26
+
27
+ const describe = new DescribeClient({
28
+ product: 'my-app', // shows up in their logs
29
+ onFailure: (f) => console.warn('describe.net:', f.kind, f.path),
30
+ });
31
+
32
+ const rep = await describe.wallet('0x97cd97cfe21799bacbf39d0a53469e5f82f30996');
33
+
34
+ if (rep === null) {
35
+ // describe.net could not be reached. This is NOT "no reputation".
36
+ } else if (rep.globalScore === null) {
37
+ // No eligible rating. That IS the answer — never render it as 0.
38
+ } else {
39
+ console.log(formatScore(rep.globalScore)); // "100"
40
+ console.log(rep.policyVersion); // "equal-weight-per-chain@2"
41
+ console.log(rep.caveats); // [{ code, text }, ...]
42
+ }
43
+ ```
44
+
45
+ And the version with no JavaScript at all, which is most of what most pages need:
46
+
47
+ ```html
48
+ <img src="https://api.describe.net/badge/0x97cd…0996.svg" alt="describe.net reputation">
49
+ ```
50
+
51
+ ---
52
+
53
+ ## The API
54
+
55
+ | Method | Cost | Route | If describe.net is down |
56
+ |---|---|---|---|
57
+ | `wallet(address)` | **free** | `GET /wallets/{w}/chains` | `null` + `onFailure` |
58
+ | `leaderboard()` | **free** | `GET /leaderboard` | `null` + `onFailure` |
59
+ | `health()` | **free** | `GET /health` | `null` + `onFailure` |
60
+ | `badgeUrl(address)` | **no network** | builds a `/badge/{w}.svg` URL | cannot fail |
61
+ | `profileUrl(address)` | **no network** | builds a describe.net profile URL | cannot fail |
62
+ | `walletBreakdown(address)` | $0.01 — or **free** on the [partner rail](#not-paying-the-partner-rail) | `GET /reputation/wallet/{w}` | **throws, always** |
63
+ | `agent(network, agentId)` | $0.02 — or **free** on the [partner rail](#not-paying-the-partner-rail) | `GET /reputation/agent/{n}/{id}` | **throws, always** |
64
+
65
+ Prices are documentation with a date on them (2026-08-30). What gets paid is
66
+ what the live 402 challenge says — this package never types a price into a code
67
+ path.
68
+
69
+ 🔴 **The two metered methods return no `null` at all** — not for an outage, not
70
+ for a 404, and not even when you set `failOpen: true` yourself. See
71
+ [Failures](#failures): the line is not how many methods, it is whether there was
72
+ money in flight.
73
+
74
+ ---
75
+
76
+ ## The four things that will bite you
77
+
78
+ ### 1. `null` is never `0`
79
+
80
+ "There is no evidence" and "they were rated badly" are different facts and the
81
+ index refuses to collapse them. A wallet with no ERC-8004 identity answers
82
+ **HTTP 200** with `global_score: null` — verified live against `0xdEaD…BEEF`.
83
+
84
+ ```ts
85
+ const rep = await describe.wallet(unknownWallet);
86
+ rep.globalScore // null
87
+ formatScore(rep.globalScore) // null — never "0", never "—"
88
+ ```
89
+
90
+ Rendering that as `0` publishes "worst possible reputation" for "nobody has
91
+ rated this yet". Choosing what absence *looks* like is your job, per surface —
92
+ which is why `formatScore` hands you `null` instead of picking for you.
93
+
94
+ ### 2. Three different absences
95
+
96
+ ```ts
97
+ const rep = await describe.wallet(w);
98
+
99
+ rep === null // we could not ask (failOpen; onFailure fired)
100
+ rep.globalScore === null // they answered: no evidence
101
+ // a throw = your request was wrong, or a 402 arrived
102
+ ```
103
+
104
+ A fail-open that says nothing turns the first into the second. That is why
105
+ `onFailure` exists and why you should always pass it. The invariant, in one
106
+ line: **`onFailure` fires if and only if a method hands you `null` instead of an
107
+ answer.** On the metered routes it therefore never fires — they have no `null`.
108
+
109
+ ### 3. Branch on `caveat.code`, never on `caveat.text`
110
+
111
+ The index declares it: **the text may change without notice — the code never
112
+ will.** It already happened: a threshold was re-worded on 2026-08-25 and every
113
+ consumer matching on prose broke silently that day.
114
+
115
+ ```ts
116
+ import { hasCaveat, CAVEAT_CODES } from 'uvd-describe-sdk';
117
+
118
+ if (hasCaveat(rep, 'burn-address')) { /* nobody controls this address */ }
119
+ if (hasCaveat(rep, 'few-raters')) { /* thin evidence */ }
120
+ ```
121
+
122
+ The eight codes are exported and typed: `no-score`, `concentration-degraded`,
123
+ `single-rater`, `few-raters`, `top-client-share`, `campaign-per-rater`,
124
+ `self-rated`, `burn-address`. The union stays **open**, so a ninth code the
125
+ server adds tomorrow will not be a type error in code you already shipped.
126
+
127
+ ⚠️ On free routes `caveats: []` means *no **public-data** caveat*, not "clean" —
128
+ the evidence-quality cuts need the grain and ride the metered routes. Check
129
+ `rep.caveatScope` (`public-data-subset` vs `full`) before calling anything
130
+ clean.
131
+
132
+ ### 4. One display format, ecosystem-wide
133
+
134
+ **Two decimals, trailing zeros trimmed.** `86.65`, `84.7`, `87` — never `82.0`.
135
+
136
+ ```ts
137
+ formatScore(86.653045) // "86.65"
138
+ formatScore(83.0) // "83" <- the witness case
139
+ ```
140
+
141
+ Decided by measurement on 2026-08-29, after the three consumers rendered the
142
+ same number three ways (`86.653045`, `86.7`, `86`). Over 47 real scores,
143
+ rounding to 0 decimals merges 23 pairs of *different* agents into identical
144
+ strings. `83.0 → "83"` is the one value that tells the candidate rules apart —
145
+ `toFixed(2)` gives `"83.00"`, `toFixed(1)` gives `"83.0"`.
146
+
147
+ The API keeps serving full precision. Compute with the number, format at the
148
+ pixel.
149
+
150
+ ---
151
+
152
+ ## Failures
153
+
154
+ ```ts
155
+ const describe = new DescribeClient({
156
+ failOpen: true, // the default
157
+ onFailure: ({ kind, path, transient }) => metrics.increment(kind),
158
+ });
159
+ ```
160
+
161
+ `failOpen: true` (Saul, 2026-08-28: *"pon un fallback si es que describe está
162
+ caído"*) returns `null` for a **describe.net-side** failure on a **free route**
163
+ and announces it. It does **not** swallow your own bugs, and it does **not**
164
+ apply to the metered routes at all:
165
+
166
+ | `kind` | free routes | metered routes | `transient` | what it is |
167
+ |---|---|---|---|---|
168
+ | `timeout` | fail-open | **throws** | yes | their cold start (measured 15,2 s) or a slow index |
169
+ | `http_5xx` | fail-open | **throws** | yes | their fault |
170
+ | `unreachable` | fail-open | **throws** | yes | DNS, reset, offline, CORS |
171
+ | `unparseable` | fail-open | **throws** | no | they answered, unreadably. Retrying buys nothing |
172
+ | `http_4xx` | **throws** | **throws** | only 429 | **your** request. 422 `not_an_address` is the common one |
173
+ | `not_found` | `null`, announced | **throws** | no | absence. Free routes have a `null` to degrade into; metered ones do not |
174
+ | `payment_required` | — | **throws** | no | metered route, no `payer` configured. Carries the challenge |
175
+ | `payment_refused` | — | **throws** | no | `DO_NOT_PAY` — the challenge named a treasury that is not ours |
176
+ | `partner_unsigned` | **throws** | **throws** | no | partner mode on and the signature could not be produced. **Yours**, and it throws on the free routes too — an unsigned partner client is an anonymous client, and an anonymous client pays |
177
+ | `partner_rejected` | — | **throws** | no | you signed and were charged anyway: the free rail is off. Thrown *before* the payer, so nothing was spent |
178
+ | `malformed_hash` | announced | **announced** | no | a hash field was not a hash, so it was dropped. **Never thrown, on any route** — the read succeeded and the rest of it is good. See [Malformed hashes](#malformed-hashes-are-dropped-marked-and-announced) |
179
+
180
+ With `failOpen: false` the free routes throw instead. `not_found` on a free
181
+ route never throws either way: `failOpen` is about *their outage*, absence is a
182
+ different axis.
183
+
184
+ **`onFailure` announces everything this client swallowed and nothing it hands
185
+ you**: a `null` returned instead of an answer, and a field dropped because it
186
+ was not what it claimed to be. A failure that arrives as a throw is never
187
+ announced there — you are already holding it. If you only page on outages,
188
+ `malformed_hash` filters out in one line; it is `transient: false` and
189
+ `serviceFault: false`, so `failOpenCovers()` refuses it too.
190
+
191
+ ### `error.recovery` — what to do *instead*
192
+
193
+ Contributed by **Execution Market** (`#agents`, 2026-08-30), out of their own 502
194
+ gaining a typed `detail.recovery`:
195
+
196
+ > *"SIETE de los diez son TERMINALES (`retryable: false`). Eso es lo que más les
197
+ > sirve: hoy su flota no puede distinguir 'reintenta' de 'no insistas', y contra
198
+ > `AUTHORIZATION_EXPIRED` reintentar es quemar llamadas contra una ventana
199
+ > cerrada hace **317 HORAS**."*
200
+
201
+ `transient` says whether retrying helps and stops there — a `false` leaves you
202
+ holding a failure with no next move. Every `DescribeError` now also carries one
203
+ sentence naming **another** thing to do: another route (usually a free one),
204
+ another field, or the condition on your side that has to be fixed.
205
+
206
+ ```ts
207
+ try {
208
+ const breakdown = await describe.walletBreakdown(wallet);
209
+ } catch (e) {
210
+ if (e instanceof DescribeError) {
211
+ log.warn(e.kind, e.message);
212
+ if (e.recovery) log.warn('recovery:', e.recovery);
213
+ }
214
+ }
215
+ ```
216
+
217
+ * 🔴 **Branch on `kind`, read `recovery`.** It is prose, it is free to be
218
+ re-worded, and matching on it is the mistake the caveat `code`s exist to
219
+ prevent one level up.
220
+ * The texts are frozen literals in `RECOVERY`, which is exported: pin
221
+ `RECOVERY.payment_required` in your test instead of matching a sentence.
222
+ * A 402 with no payer points at the free door the challenge names itself
223
+ (`free_preview.endpoint`, and `see_also` for the rest); a `partner_rejected`
224
+ tells you to get the wallet allowlisted rather than to pay; a 429 tells you to
225
+ spread the fleet, because the limit is one shared bucket and the 429 is
226
+ usually somebody else. A 422 and a 429 are the same `kind` and get **opposite**
227
+ advice.
228
+ * **`timeout` is `null`, on purpose.** Its only two levers are retrying (which
229
+ `transient` already announces) and the client timeout, and raising that past
230
+ the default buys nothing an API Gateway that cuts at 29 s can deliver. A
231
+ recovery that does not work is worse than none, so the field stays empty and
232
+ says so.
233
+ * 🔴 It never quotes the exception it came from. A transport error can carry an
234
+ endpoint with an API key inside, and this is the string most likely to be
235
+ pasted into a ticket — the same guard describe.net runs server-side
236
+ (`chain/rpc.py::_redact`), enforced here by having no interpolation at all.
237
+ * **Python parity:** same field name, same text, because a consumer who changes
238
+ stacks must not read two different pieces of advice for one failure. That is
239
+ also why a text names only what both SDKs share — routes, headers, wire fields,
240
+ env vars — and never a `jitterMs`-style spelling, which is `jitter` and in
241
+ seconds over there.
242
+
243
+ ### 🔴 Why the metered routes never fail open
244
+
245
+ Because the line is **money**, not symmetry.
246
+
247
+ `walletBreakdown()` and `agent()` sign a payment and then wait for an answer. In
248
+ that window the USDC has already moved — describe.net's paywall settles *before*
249
+ it runs your query. Handing back `null` there tells you *"there was nothing to
250
+ fetch"* about a call that just spent your money, and nothing distinguishes the
251
+ two. That is not degrading gracefully; it is a spent credential with no receipt.
252
+
253
+ ⚠️ **This is a correction of what 0.1.0 shipped**, left written down because it
254
+ is the reason the rule exists: those two methods used to return `WalletBreakdown
255
+ | null` and swallow every service failure. Measured against a dead port on
256
+ 2026-08-30, a timeout on a metered route returned `null`.
257
+
258
+ A loud failure after paying is recoverable — retry, log, or claim. A silent
259
+ `null` is not. So no flag can buy the right to swallow it, `failOpen: true`
260
+ included: availability is your preference, a settled payment is a fact.
261
+
262
+ ```ts
263
+ import { failedAfterPaying } from 'uvd-describe-sdk';
264
+
265
+ try {
266
+ const detail = await describe.walletBreakdown(wallet);
267
+ } catch (err) {
268
+ if (failedAfterPaying(err)) {
269
+ // A signed envelope had already left. err.payment tells you how bad:
270
+ // settlement: 'settled' -> proof: err.payment.receipt is the tx hash
271
+ // settlement: 'unknown' -> the SDK cannot tell. Reconcile, do not assume
272
+ reconcile(err.payment.receipt, err.payment.amount, err.payment.token);
273
+ } else {
274
+ // Nothing was transmitted: a 402 with no payer, a DO_NOT_PAY, a 404, a
275
+ // payer that declined. You spent nothing — retry freely.
276
+ }
277
+ }
278
+ ```
279
+
280
+ `settlement` is never `'not settled'`, and that omission is deliberate: an
281
+ unhandled 500 is rendered above the paywall middleware and carries no receipt
282
+ even though the money moved, and `fetch` rejects identically whether the request
283
+ bytes were written or not. `'unknown'` means *ask the chain*, not *nothing
284
+ happened*.
285
+
286
+ ---
287
+
288
+ ## Paying
289
+
290
+ ```ts
291
+ import { DescribeClient } from 'uvd-describe-sdk';
292
+ import { payerFromX402Client } from 'uvd-describe-sdk/x402';
293
+ import { X402Client } from 'uvd-x402-sdk';
294
+
295
+ const x402 = new X402Client();
296
+ await x402.connectWithPrivateKey(process.env.PAYER_PRIVATE_KEY!, 'base');
297
+
298
+ const describe = new DescribeClient({
299
+ product: 'my-app',
300
+ payer: payerFromX402Client(x402),
301
+ });
302
+
303
+ const detail = await describe.walletBreakdown(wallet); // never null — it throws
304
+ detail.payment; // { receipt: 'rcpt_…', reused: false }
305
+ ```
306
+
307
+ 🔴 **The key comes from the environment.** Never a literal, not even "just for a
308
+ test" — bots scan public repos for `0x` + 64 hex and drain in minutes.
309
+
310
+ What happens under the hood, in order:
311
+
312
+ 1. Ask with no header. **Asking is free and is the intended first move.**
313
+ 2. Read the challenge (header first, then body).
314
+ 3. **Verify who we are about to pay.** The `payTo` of the top-level recipient
315
+ *and of every `accepts[]` entry* must be the pinned treasury. One stranger
316
+ anywhere in the list refuses the whole challenge and signs nothing.
317
+ 4. Hand the challenge to your payer. This SDK never signs, never builds an
318
+ EIP-3009 authorization, never touches a key.
319
+ 5. Replay the identical request with `X-PAYMENT`, and surface
320
+ `X-Payment-Receipt` / `X-Payment-Reused` as `result.payment`.
321
+
322
+ Step 4 is the line that changes what a failure means. Everything before it costs
323
+ nothing if it fails; everything after it may have cost real USDC, and those
324
+ failures carry `error.payment` so you never have to guess which side you landed
325
+ on.
326
+
327
+ Bring your own wallet with `payerFrom(challenge => Promise<string>)` — a browser
328
+ wallet, a custodial signer, a queue that asks a human. No `uvd-x402-sdk` needed.
329
+
330
+ **Free first.** The 402 challenge says it in its own words: *"si ahí no hay
331
+ nada, no hay nada que comprar"*. Call `wallet()` before you buy the
332
+ decomposition.
333
+
334
+ ---
335
+
336
+ ## Not paying: the partner rail
337
+
338
+ If your wallet is on describe.net's partner allowlist, the metered routes are
339
+ free for you. There is no token to hold and no secret for describe.net to lose:
340
+ **the allowlist is a list of public addresses**, and you prove you are one of
341
+ them by signing each request (ERC-8128 over RFC 9421) with a dedicated wallet
342
+ that holds no funds and does nothing but sign.
343
+
344
+ ```ts
345
+ import { DescribeClient } from 'uvd-describe-sdk';
346
+ import { partnerFromEnv } from 'uvd-describe-sdk/partner';
347
+
348
+ // DESCRIBE_PARTNER_PRIVATE_KEY lives in the environment. There is no argument
349
+ // to paste a key into — deliberately.
350
+ const describe = new DescribeClient({
351
+ product: 'meshrelay',
352
+ partner: partnerFromEnv(),
353
+ });
354
+
355
+ const detail = await describe.walletBreakdown(wallet); // metered route, $0.00
356
+ detail.payment; // null — nothing was paid
357
+ ```
358
+
359
+ Already have a signer? Hand it over and no key ever enters this package:
360
+
361
+ ```ts
362
+ import { partnerFromSigner } from 'uvd-describe-sdk/partner';
363
+
364
+ partner: partnerFromSigner({
365
+ address: await wallet.getAddress(),
366
+ signMessage: (base) => wallet.signMessage(base), // EIP-191 personal_sign
367
+ });
368
+ ```
369
+
370
+ This subpath is the one that needs `uvd-x402-sdk` installed: the signing is
371
+ entirely theirs. Nothing here reimplements a byte of it.
372
+
373
+ ### 🔴 A partner that cannot sign RAISES — it never quietly starts paying
374
+
375
+ This is the whole reason the rail is worth its code. Two failures are yours, not
376
+ describe.net's, and neither one degrades — not with `failOpen: true`, not on the
377
+ free routes, not ever:
378
+
379
+ | What happened | You get | What it cost |
380
+ |---|---|---|
381
+ | the signer threw (key unset, vault locked) | `DescribePartnerUnsigned` | nothing — the request was never sent |
382
+ | you signed and the route charged anyway | `DescribePartnerRejected` | **nothing** — thrown *before* your payer is called |
383
+
384
+ Losing the free rail is a configuration problem that costs one broken read.
385
+ Losing it *silently* is the same problem with a bill attached: identical
386
+ answers, identical latency, USDC leaving a wallet that budgeted none, and nobody
387
+ finds out until the invoice. So partner mode does not pay by default.
388
+
389
+ `DescribePartnerRejected` means the gate did not exempt you. In descending order
390
+ of likelihood: your address is not on the allowlist; your `baseUrl` is not
391
+ `https://api.describe.net`, so you signed an authority the gate pins and will
392
+ not accept; the keyid chain is not 8453; your clock is more than 30 s ahead, or
393
+ the signature took longer than 300 s to arrive. The challenge is attached
394
+ unpaid, so you can read what it *would* have cost.
395
+
396
+ To pay anyway when the rail is down, say so out loud:
397
+
398
+ ```ts
399
+ new DescribeClient({ partner, payer, partnerFallsBackToPaying: true });
400
+ ```
401
+
402
+ **Every request is signed, free routes included.** A table of "which routes are
403
+ metered" inside this package would be a second copy of the service's price list,
404
+ and it would start paying on its own the day a free route becomes metered. The
405
+ server already knows which is which. Measured cost of signing everything:
406
+ **0,67 ms** per signature (Node v23.11.0, 200 signatures, 2026-08-30) against a
407
+ 30 000 ms request timeout.
408
+
409
+ ---
410
+
411
+ ## Jitter, on by default
412
+
413
+ Every request waits a random `[0, 400)` ms first. **That is on unless you turn
414
+ it off**, and it is the one thing this package spends without being asked, so
415
+ here is the argument:
416
+
417
+ * The number is **KarmaKadabra's**, not ours — `random.uniform(0, 0.4)` before
418
+ every read, contributed 2026-08-30 with the measurement behind it: 27 agents
419
+ wake on one EventBridge schedule and hit a rate limit **shared** with every
420
+ other consumer. *"Sin jitter, un enjambre es un DDoS educado."*
421
+ * It defaults ON because **the cost of getting it wrong does not land on
422
+ whoever gets it wrong.** The shared limit has no per-partner bucket, so an
423
+ unjittered swarm is paid for by the other consumer, who gets the 429 and has
424
+ no lever. And opt-in is undiscoverable by construction: you find out you
425
+ needed jitter from somebody else's incident.
426
+ * At most 400 ms, ~200 ms on average, against a 30 000 ms timeout and a
427
+ provider cold start measured at 15,2 s.
428
+
429
+ ```ts
430
+ new DescribeClient({ jitterMs: 0 }); // off — do this in your unit tests
431
+ new DescribeClient({ jitterMs: 1200 }); // wider, for a bigger fleet
432
+ ```
433
+
434
+ It fires before **every** request, so a metered call — 402, pay, replay —
435
+ sleeps twice. Once per call would disperse the first arrival and let the rest
436
+ out in a pack, which is the problem it came to solve.
437
+
438
+ It is **not** backoff: jitter spreads a herd that has not asked for anything
439
+ yet, backoff yields to a service that already said no. This package has no
440
+ retry; build one on `error.transient` and give *that* the backoff.
441
+
442
+ > **Python parity.** `uvd-describe-sdk` for Python takes `jitter=0.4`, in
443
+ > **seconds**, because its `timeout` is in seconds while this one's is
444
+ > `timeoutMs`. Same value, same policy, different unit — each language keeps
445
+ > its own, rather than one of them carrying a lying name.
446
+
447
+ ---
448
+
449
+ ## Malformed hashes are dropped, marked, and announced
450
+
451
+ Contributed by **KarmaKadabra** from the finding they call *"el 200 sin tx"*:
452
+
453
+ > *"Un 200 que no hizo la cosa es peor que un 503, porque el cliente lo toma por
454
+ > bueno: si nosotros no chequeáramos el tx, habríamos contado 14 ratings que no
455
+ > existen."*
456
+
457
+ Every hash field is shape-checked — `tx_hash`, `feedback_hash`, `revoked_tx`,
458
+ `snapshot.inputs_digest`, and the `X-Payment-Receipt`. A value that is not
459
+ shaped like a hash is set to `null`, its name is recorded, and `onFailure` is
460
+ told. **It never throws**: one bad accessory field must not destroy an answer
461
+ you already paid for.
462
+
463
+ 🔴 **Absent and malformed are not the same thing.** The `null` is identical in
464
+ both cases and only the mark separates them:
465
+
466
+ ```ts
467
+ const agent = await describe.agent('base', 42);
468
+
469
+ agent.ratings[0].txHash; // null in BOTH cases
470
+ agent.ratings[0].malformedHashes; // [] → it did not come (normal:
471
+ // "null until the log scan
472
+ // reaches this entry")
473
+ // ['tx_hash'] → garbage came. THIS one.
474
+ ```
475
+
476
+ The value as served survives in `raw`, and the notice arrives on the channel you
477
+ already watch:
478
+
479
+ ```ts
480
+ onFailure: (f) => {
481
+ if (f.kind === 'malformed_hash') return report(f.error.fields); // not an outage
482
+ pageSomeone(f);
483
+ };
484
+ ```
485
+
486
+ The shape check is the **union** of what the index really emits — `0x` + 64 hex
487
+ on the EVM chains, **base58 on Solana**, a bare 64-hex digest for
488
+ `inputs_digest`, and the literal `pending` that the receipt header is documented
489
+ to carry. An EVM-only regex would have flagged every Solana rating in the index,
490
+ and an alarm that screams about good data is worse than no alarm.
491
+
492
+ `buildSha` is deliberately **not** checked: a legitimate deploy can stamp
493
+ `<sha>-dirty`, and validating it would scream forever about a good build.
494
+
495
+ ---
496
+
497
+ ## Counting distinct raters
498
+
499
+ ```ts
500
+ import { resolveDistinctRaters } from 'uvd-describe-sdk';
501
+
502
+ const raters = resolveDistinctRaters(await describe.wallet(address)); // number | null
503
+ ```
504
+
505
+ Contributed by **MeshRelay**, who also asked for the rename: *"`maxDistinctRaters`
506
+ invita a creer que el máximo es la respuesta correcta, cuando es el último
507
+ recurso."*
508
+
509
+ 🔴 **Do not rebuild this number from the per-chain rows.** Both ways are wrong,
510
+ in opposite directions, and both are measured — on the live wallet
511
+ `0xcc28cee3a1433493de119efe8cd218ff7c0e4821`, read 2026-08-30:
512
+
513
+ | | Value | |
514
+ |---|---|---|
515
+ | `distinct_raters` (global) | **129** | the answer |
516
+ | per-chain **maximum** (base 113, ethereum 21) | 113 | 16 short |
517
+ | per-chain **sum** | 134 | 5 over — it double-counts anyone who rated on two chains |
518
+
519
+ The global figure is `COUNT(DISTINCT client)` over every chain and every
520
+ identity. `resolveDistinctRaters` returns it when it is there and falls back to
521
+ the maximum only for a cached response predating 2026-08-28, when the field
522
+ started being served. `null` when there is nothing to count — **never `0`**.
523
+
524
+ ---
525
+
526
+ ## What this package deliberately does not do
527
+
528
+ **No `getScore(): number`.** Every result carries `policyVersion`, `caveats[]`
529
+ and its source. *Un score sin sus calificadores es un rumor* — a bare-number
530
+ helper would erase the reason the index exists. Take the number off the object
531
+ by hand; the friction is the point.
532
+
533
+ **No cache.** MeshRelay has one (a `Map`, 12-minute TTL) because its refresh
534
+ route is reachable from the internet and an uncached lookup would let a stranger
535
+ burn a rate limit that has no per-partner bucket. Execution Market and
536
+ KarmaKadabra have none. A TTL baked in here would hand you a staleness you did
537
+ not choose:
538
+
539
+ ```ts
540
+ // MeshRelay's shape, if you need it: async refresh, sync read, never both.
541
+ const cache = new Map<string, { rep: WalletReputation | null; at: number }>();
542
+ const key = (w: string) => (/^0x[a-fA-F0-9]{40}$/.test(w) ? w.toLowerCase() : w);
543
+ // EVM is case-insensitive, Solana base58 is NOT. Never lower() blindly.
544
+ ```
545
+
546
+ **No retry.** MeshRelay retries a transient failure at most *once*: "hammering a
547
+ permanent failure is how EM turned one error into a four-hour storm." Build the
548
+ policy you want on `error.transient`, which is a fact rather than a string
549
+ match.
550
+
551
+ **No writes.** This SDK reads. It never rates anyone, signs nothing on-chain and
552
+ holds no key.
553
+
554
+ ---
555
+
556
+ ## Configuration
557
+
558
+ | Option | Default | Why that value |
559
+ |---|---|---|
560
+ | `baseUrl` | `https://api.describe.net` | |
561
+ | `timeoutMs` | `30_000` | Above their 15,2 s cold start, above the 29 s API-Gateway ceiling, and deliberately ≠ the facilitator's 45 s so two clocks never race. An 8 s timeout already broke a real integration |
562
+ | `product` | — | Appended to the `User-Agent`. The rate limit is shared with no per-partner bucket, so the UA is what makes your share attributable. The limit itself is not repeated here — the `RateLimit-Policy` response header is the authority (it read `50;w=1;burst=40` on 2026-08-30) |
563
+ | `failOpen` | `true` | |
564
+ | `onFailure` | — | Pass it. See above |
565
+ | `jitterMs` | `400` | **On by default.** A random `[0, jitterMs)` pause before **every** request. KarmaKadabra's measurement on a fleet of 27: *"27 agentes despiertan al MISMO tiempo por EventBridge y pegan simultáneo contra su límite de rps COMPARTIDO"*. `0` turns it off; a garbage value falls back to this default, never to off. See [Jitter](#jitter-on-by-default) |
566
+ | `payer` | — | |
567
+ | `expectedPayTo` | the pinned treasury | Override only if you verified a rotation out of band |
568
+ | `partner` | — | The [partner rail](#not-paying-the-partner-rail). Signs every request; metered routes are free if your address is allowlisted |
569
+ | `partnerFallsBackToPaying` | `false` | With a partner configured, a 402 throws instead of paying. `true` is an explicit decision to spend USDC when the rail is down |
570
+
571
+ Never hardcode a threshold. `health()` publishes the live `readingPolicy` and
572
+ `confidenceThresholds` precisely so nobody re-types them.
573
+
574
+ ---
575
+
576
+ ## Types
577
+
578
+ Hand-written, and tied to the schema by two gates rather than by a generator:
579
+
580
+ - `npm test` — offline, compares the types against a pinned
581
+ `schema/openapi.snapshot.json`. Answers *did we drift?*
582
+ - `npm run schema:check` — re-fetches the live OpenAPI and diffs it. Answers
583
+ *did they move?*
584
+
585
+ Two failures, two gates. A generator collapses both into "the build broke" and
586
+ tells you neither — and cannot carry the one thing that matters most here, which
587
+ is *why* a `null` is a `null`. See the header of `src/types.ts`.
588
+
589
+ Every result also keeps `raw`: the exact payload as served. A field this SDK
590
+ version has not heard of is still there, so you are never blocked on our release
591
+ cycle.
592
+
593
+ ---
594
+
595
+ ## Development
596
+
597
+ ```bash
598
+ npm install
599
+ npm test # offline. 93 tests, no network
600
+ npm run typecheck
601
+ npm run lint
602
+ npm run build
603
+ npm run smoke # real call to the live API — FREE routes only
604
+ npm run schema:check # is the live schema still what we typed?
605
+ ```
606
+
607
+ `npm run smoke` never touches a metered route and has no flag to make it. The
608
+ safest way to not spend USDC by accident is to not write the code that could.
609
+
610
+ ## License
611
+
612
+ MIT © Ultravioleta DAO