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/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
|