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/src/hashes.ts
ADDED
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shape validation for the hash fields — *"el 200 sin tx"*, from KarmaKadabra.
|
|
3
|
+
*
|
|
4
|
+
* Pure: no network, no clock, no state. Strings in, booleans out.
|
|
5
|
+
*
|
|
6
|
+
* ## Where this comes from
|
|
7
|
+
*
|
|
8
|
+
* Contributed by **KarmaKadabra**, `#agents` on MeshRelay, **2026-08-30**. Their
|
|
9
|
+
* words:
|
|
10
|
+
*
|
|
11
|
+
* > *"Un 200 que no hizo la cosa es peor que un 503, porque el cliente lo toma
|
|
12
|
+
* > por bueno: si nosotros no chequeáramos el tx, habríamos contado 14 ratings
|
|
13
|
+
* > que no existen. Nosotros lo cazamos con un sello que exige forma de hash —
|
|
14
|
+
* > pero el contrato debería decirlo, no cada cliente descubrirlo."*
|
|
15
|
+
*
|
|
16
|
+
* The second half is why this lives in the SDK: the check is a property of the
|
|
17
|
+
* CONTRACT, and three consumers each discovering it separately is three chances
|
|
18
|
+
* to get it wrong. Verified before writing a line: neither this SDK nor its
|
|
19
|
+
* Python twin validated the shape of any hash field on 2026-08-30.
|
|
20
|
+
*
|
|
21
|
+
* ## 🔴 Why `^0x[0-9a-f]{64}$` alone would have been a disaster
|
|
22
|
+
*
|
|
23
|
+
* The obvious version of this file — one EVM regex — would have flagged **every
|
|
24
|
+
* Solana rating in the index** as malformed. Two independent confirmations, both
|
|
25
|
+
* read 2026-08-30:
|
|
26
|
+
*
|
|
27
|
+
* * from the writer: `describe-net/describenet/solana_indexer.py:436` puts
|
|
28
|
+
* `firma["signature"]` — a base58 signature — into the `tx_hash` column of
|
|
29
|
+
* the INSERT at `indexer.py:153-157`, the same column the EVM indexer fills
|
|
30
|
+
* with `0x…`. Solana writes to the same tables on purpose, so this is by
|
|
31
|
+
* construction and not an accident of one sample;
|
|
32
|
+
* * from the wire (measured by the Python twin against `GET /feed`): avalanche
|
|
33
|
+
* and celo serve 66-char `0x` + 64 hex, solana serves 87- and 88-char base58
|
|
34
|
+
* with no prefix.
|
|
35
|
+
*
|
|
36
|
+
* An alarm that screams about good data is worse than no alarm: people learn to
|
|
37
|
+
* ignore it, and then it is silent on the day it is right. So this validates the
|
|
38
|
+
* **union** of the legitimate shapes, never the intersection.
|
|
39
|
+
*
|
|
40
|
+
* The shapes the index emits today, each with its source:
|
|
41
|
+
*
|
|
42
|
+
* 1. **EVM hash** — `0x` + 64 hex. `chain/decode.py:253` does `"0x" + …hex()`
|
|
43
|
+
* over a `bytes32` (`_NEW_FEEDBACK_TYPES:85`). This is `tx_hash`,
|
|
44
|
+
* `revoked_tx` and `feedback_hash` on the ten EVM chains.
|
|
45
|
+
* 2. **Solana signature** — base58 (Bitcoin alphabet: no `0`, `O`, `I`, `l`),
|
|
46
|
+
* 86–88 characters. 64 bytes in base58 is 87–88; 86 is reachable with leading
|
|
47
|
+
* zero bytes. On Solana `feedback_hash` is **NULL on purpose**, so a hole
|
|
48
|
+
* there is correct and not a fault.
|
|
49
|
+
* 3. **Bare digest** — 64 hex with **no** `0x`. That is `Snapshot.inputs_digest`,
|
|
50
|
+
* which comes out of `hashlib.sha256(...).hexdigest()` in `aggregate.py:1920`.
|
|
51
|
+
* Demanding the `0x` prefix would have marked every citable snapshot as
|
|
52
|
+
* malformed.
|
|
53
|
+
* 4. **The `pending` sentinel** — only on the `X-Payment-Receipt` header, whose
|
|
54
|
+
* own OpenAPI declares it: the settlement hash *"or `pending` if settlement
|
|
55
|
+
* has not reported one"*. It is a LEGITIMATE value, which is why
|
|
56
|
+
* {@link looksLikeSettlementReceipt} exists separately: treating it as
|
|
57
|
+
* garbage would fire an alarm on the happy path of every fresh payment.
|
|
58
|
+
*
|
|
59
|
+
* ## 🔴 What is deliberately NOT validated: `build_sha`
|
|
60
|
+
*
|
|
61
|
+
* `IndexHealth.buildSha` looks like a hash and is not one, and the measurement
|
|
62
|
+
* that settles it is `describe-net/scripts/build_lambda_zip.py:64` (read
|
|
63
|
+
* 2026-08-30): `estampa = sha + ("-dirty" if sucio else "")`. A legitimate
|
|
64
|
+
* deploy can therefore publish `"<40 hex>-dirty"`, and a validator would scream
|
|
65
|
+
* about a perfectly good build — forever, on every `/health` call. The general
|
|
66
|
+
* rule that falls out of it, and it is the one to apply to the next field:
|
|
67
|
+
* **validate the identifiers a caller will carry somewhere to verify (an
|
|
68
|
+
* explorer, a digest comparison); leave alone the strings that only describe a
|
|
69
|
+
* build.** Nobody looks up a `build_sha`; the service already refuses to publish
|
|
70
|
+
* its `unknown` default as if it were a SHA (`api.py:2439-2456`).
|
|
71
|
+
*
|
|
72
|
+
* ## The question this module answers — and the one it does not
|
|
73
|
+
*
|
|
74
|
+
* It answers **"does this have the shape of an on-chain identifier?"**. It does
|
|
75
|
+
* NOT answer "does this transaction exist?" or "does it say what the index says
|
|
76
|
+
* it says": that is verified in an explorer, which is the entire point of the
|
|
77
|
+
* field (the service's own schema: *"go verify it in an explorer, which is the
|
|
78
|
+
* point"*). A shape check cannot prove existence and does not pretend to.
|
|
79
|
+
*
|
|
80
|
+
* What it does catch is what bit KarmaKadabra: the empty string, `"null"`,
|
|
81
|
+
* `"undefined"`, `"0x"`, `"0x0"`, a truncated hash, an error message parked in
|
|
82
|
+
* the field. Every one of those sails through an `if (rating.txHash)` today with
|
|
83
|
+
* nothing making a sound.
|
|
84
|
+
*
|
|
85
|
+
* 🔴 **And it deliberately does not validate per chain.** A `feedback_hash`
|
|
86
|
+
* shaped like a Solana signature is accepted even though Solana emits none
|
|
87
|
+
* today. Being strict per field would trade a cheap false negative (letting an
|
|
88
|
+
* odd-but-valid shape through) for an expensive false positive (screaming about
|
|
89
|
+
* good data the day the service extends a field), and that contradicts the
|
|
90
|
+
* passthrough rule this package is built on: type what is known, PRESERVE what
|
|
91
|
+
* is not.
|
|
92
|
+
*/
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* `0x` + 64 hex. Case-insensitive: the index serves lowercase, but a hash
|
|
96
|
+
* written in mixed case is the same hash and flagging it would be a false
|
|
97
|
+
* positive.
|
|
98
|
+
*/
|
|
99
|
+
const EVM_HASH = /^0x[0-9a-fA-F]{64}$/;
|
|
100
|
+
|
|
101
|
+
/** 64 hex with NO prefix — a `sha256(...).hexdigest()`, i.e. `inputs_digest`. */
|
|
102
|
+
const BARE_DIGEST = /^[0-9a-fA-F]{64}$/;
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Base58, Bitcoin alphabet (no `0`, `O`, `I`, `l`), 86–88 characters: a Solana
|
|
106
|
+
* transaction signature. Both high lengths measured live on 2026-08-30.
|
|
107
|
+
*/
|
|
108
|
+
const BASE58_SIGNATURE = /^[1-9A-HJ-NP-Za-km-z]{86,88}$/;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* The one non-hash value the `X-Payment-Receipt` header declares legitimate.
|
|
112
|
+
*
|
|
113
|
+
* The live OpenAPI says it, not us: the settlement transaction hash *"or
|
|
114
|
+
* `pending` if settlement has not reported one"*.
|
|
115
|
+
*/
|
|
116
|
+
export const SETTLEMENT_PENDING = 'pending';
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Does `value` have the shape of an on-chain identifier this index emits?
|
|
120
|
+
*
|
|
121
|
+
* The UNION of the three measured shapes (EVM hash, Solana signature, bare
|
|
122
|
+
* digest) — never the intersection. See the module header for why an EVM-only
|
|
123
|
+
* regex would have marked every Solana rating as malformed.
|
|
124
|
+
*
|
|
125
|
+
* It does not prove the transaction exists. That is the explorer's job.
|
|
126
|
+
*/
|
|
127
|
+
export function looksLikeOnchainId(value: string): boolean {
|
|
128
|
+
return EVM_HASH.test(value) || BASE58_SIGNATURE.test(value) || BARE_DIGEST.test(value);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* The same, plus the `pending` sentinel. For `X-Payment-Receipt` and nothing
|
|
133
|
+
* else.
|
|
134
|
+
*
|
|
135
|
+
* `pending` is not garbage: it is the seller saying *"I charged you and
|
|
136
|
+
* settlement has not reported the hash yet"*, and it is in their OpenAPI.
|
|
137
|
+
* Marking it malformed would turn the happy path of every freshly settled
|
|
138
|
+
* payment into an alarm.
|
|
139
|
+
*/
|
|
140
|
+
export function looksLikeSettlementReceipt(value: string): boolean {
|
|
141
|
+
return value === SETTLEMENT_PENDING || looksLikeOnchainId(value);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Read one hash field off a wire object: keep it if it has the shape of a hash,
|
|
146
|
+
* otherwise `null` **and a mark**.
|
|
147
|
+
*
|
|
148
|
+
* 🔴 **Absent and malformed are not the same thing** (R1, applied one level
|
|
149
|
+
* below where it usually lives) and this function is where the distinction is
|
|
150
|
+
* made, so read the two cases carefully:
|
|
151
|
+
*
|
|
152
|
+
* ```
|
|
153
|
+
* did not come → null, and `key` does NOT enter `malformed`. This is normal
|
|
154
|
+
* and documented: the schema itself says tx_hash is "null
|
|
155
|
+
* until the log scan reaches this entry, not null forever",
|
|
156
|
+
* and Solana writes feedback_hash NULL on purpose.
|
|
157
|
+
* came garbage → null AND `key` in `malformed`. THIS is the one that shouts.
|
|
158
|
+
* ```
|
|
159
|
+
*
|
|
160
|
+
* A caller therefore branches on the list, never on `field === null`.
|
|
161
|
+
*
|
|
162
|
+
* Why the value is dropped rather than passed through: the field exists so
|
|
163
|
+
* somebody can build an explorer link out of it, and a link built from garbage
|
|
164
|
+
* is the "200 that did not do the thing" arriving one layer later. Why it does
|
|
165
|
+
* not throw: the rest of the response is very likely useful, and killing a whole
|
|
166
|
+
* reputation breakdown over an accessory field would be worse than the bug being
|
|
167
|
+
* hunted. The original value is not lost — it stays in the result's `raw`, which
|
|
168
|
+
* is where it gets investigated.
|
|
169
|
+
*
|
|
170
|
+
* A non-string that is not `null`/`undefined` (a number, an object) counts as
|
|
171
|
+
* garbage, not as absence: the wire said something and it was not a hash.
|
|
172
|
+
*/
|
|
173
|
+
export function hashField(
|
|
174
|
+
row: Record<string, unknown>,
|
|
175
|
+
key: string,
|
|
176
|
+
malformed: string[],
|
|
177
|
+
ok: (value: string) => boolean = looksLikeOnchainId,
|
|
178
|
+
): string | null {
|
|
179
|
+
const value = row[key];
|
|
180
|
+
if (value === null || value === undefined) return null;
|
|
181
|
+
if (typeof value === 'string' && ok(value)) return value;
|
|
182
|
+
malformed.push(key);
|
|
183
|
+
return null;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** Anything that carries the marks of its own malformed hash fields. */
|
|
187
|
+
interface MalformedCarrier {
|
|
188
|
+
malformedHashes?: readonly string[];
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* Every malformed hash field of a result, located.
|
|
193
|
+
*
|
|
194
|
+
* Walks the places a hash can hide in a parsed result and returns qualified
|
|
195
|
+
* paths, in the order they appear:
|
|
196
|
+
*
|
|
197
|
+
* ```ts
|
|
198
|
+
* ['ratings[3].tx_hash', 'snapshot.inputs_digest', 'payment.receipt']
|
|
199
|
+
* ```
|
|
200
|
+
*
|
|
201
|
+
* Wire names (`tx_hash`), not ours (`txHash`), on purpose: this string is what
|
|
202
|
+
* ends up in a log line or a ticket to whoever runs the index, and it has to
|
|
203
|
+
* name the field the way the API does.
|
|
204
|
+
*
|
|
205
|
+
* An empty array is the normal case and means "no field arrived malformed" — it
|
|
206
|
+
* says nothing about which fields arrived at all. An absent hash is legitimate
|
|
207
|
+
* and is not reported here.
|
|
208
|
+
*/
|
|
209
|
+
export function malformedHashReport(
|
|
210
|
+
result:
|
|
211
|
+
| {
|
|
212
|
+
ratings?: readonly MalformedCarrier[];
|
|
213
|
+
snapshot?: MalformedCarrier | null;
|
|
214
|
+
payment?: MalformedCarrier | null;
|
|
215
|
+
}
|
|
216
|
+
| null
|
|
217
|
+
| undefined,
|
|
218
|
+
): string[] {
|
|
219
|
+
if (!result) return [];
|
|
220
|
+
const fields: string[] = [];
|
|
221
|
+
(result.ratings ?? []).forEach((rating, i) => {
|
|
222
|
+
for (const name of rating.malformedHashes ?? []) fields.push(`ratings[${i}].${name}`);
|
|
223
|
+
});
|
|
224
|
+
for (const attr of ['snapshot', 'payment'] as const) {
|
|
225
|
+
const part = result[attr];
|
|
226
|
+
if (part) for (const name of part.malformedHashes ?? []) fields.push(`${attr}.${name}`);
|
|
227
|
+
}
|
|
228
|
+
return fields;
|
|
229
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* uvd-describe-sdk — read reputation from describe.net.
|
|
3
|
+
*
|
|
4
|
+
* The ERC-8004 reputation index of Ultravioleta DAO, across 11 chains. Free
|
|
5
|
+
* lookups need no dependency and no credential; metered lookups pay their 402
|
|
6
|
+
* through `uvd-x402-sdk`, which lives behind the `uvd-describe-sdk/x402`
|
|
7
|
+
* subpath so a free-only consumer installs nothing.
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { DescribeClient, formatScore } from 'uvd-describe-sdk';
|
|
11
|
+
*
|
|
12
|
+
* const describe = new DescribeClient({
|
|
13
|
+
* product: 'my-app',
|
|
14
|
+
* onFailure: (f) => console.warn('describe.net:', f.kind, f.path),
|
|
15
|
+
* });
|
|
16
|
+
*
|
|
17
|
+
* const rep = await describe.wallet('0x97cd…0996');
|
|
18
|
+
* if (rep === null) {
|
|
19
|
+
* // describe.net could not be reached. NOT "this wallet has no reputation".
|
|
20
|
+
* } else if (rep.globalScore === null) {
|
|
21
|
+
* // No eligible rating. That IS the answer — never render it as 0.
|
|
22
|
+
* } else {
|
|
23
|
+
* console.log(formatScore(rep.globalScore), rep.policyVersion, rep.caveats);
|
|
24
|
+
* }
|
|
25
|
+
* ```
|
|
26
|
+
*
|
|
27
|
+
* ## Three ways in, and only one of them costs anything
|
|
28
|
+
*
|
|
29
|
+
* Free routes need nothing. Metered routes are paid through `uvd-x402-sdk` via
|
|
30
|
+
* `uvd-describe-sdk/x402`, or read for FREE through `uvd-describe-sdk/partner`
|
|
31
|
+
* if your wallet is on describe.net's partner allowlist — a signature per
|
|
32
|
+
* request, no token, no secret held by the service. See `PartnerSigner`.
|
|
33
|
+
*
|
|
34
|
+
* ## The free routes degrade, the paid routes do not
|
|
35
|
+
*
|
|
36
|
+
* `wallet()`, `leaderboard()` and `health()` return `null` when describe.net
|
|
37
|
+
* cannot be reached (that is `failOpen`, on by default, always announced
|
|
38
|
+
* through `onFailure`). `walletBreakdown()` and `agent()` return no `null` at
|
|
39
|
+
* all and throw instead — including with `failOpen: true` — because between
|
|
40
|
+
* signing a payment and reading the answer there is a window where the USDC has
|
|
41
|
+
* already moved, and a `null` there hides a spend from the caller. Use
|
|
42
|
+
* `failedAfterPaying(error)` to tell "it broke before I paid" from "it broke
|
|
43
|
+
* after".
|
|
44
|
+
*
|
|
45
|
+
* ## Note on the public surface
|
|
46
|
+
*
|
|
47
|
+
* There is no function here that returns a bare score. `formatScore` takes a
|
|
48
|
+
* number you already pulled off a sealed result, and every result carries
|
|
49
|
+
* `policyVersion` and `caveats[]`. That is deliberate: *un score sin sus
|
|
50
|
+
* calificadores es un rumor*, and a `getScore(): number` would erase the reason
|
|
51
|
+
* the index exists. Reach into the object by hand — the friction is the point.
|
|
52
|
+
*/
|
|
53
|
+
|
|
54
|
+
export { DescribeClient } from './client';
|
|
55
|
+
export type {
|
|
56
|
+
DescribeClientConfig,
|
|
57
|
+
DescribeFailure,
|
|
58
|
+
PartnerSigner,
|
|
59
|
+
X402Payer,
|
|
60
|
+
} from './client';
|
|
61
|
+
|
|
62
|
+
export {
|
|
63
|
+
DescribeError,
|
|
64
|
+
DescribeHTTPError,
|
|
65
|
+
/**
|
|
66
|
+
* 🔴 Exported to be RECOGNISED, never to be caught: it is never thrown. It
|
|
67
|
+
* arrives as the `error` of an `onFailure` notice whose `kind` is
|
|
68
|
+
* `malformed_hash`, saying a hash field was dropped because it was not a hash.
|
|
69
|
+
*/
|
|
70
|
+
DescribeMalformedHash,
|
|
71
|
+
/**
|
|
72
|
+
* ⚠️ Exported since 2026-08-30 and it used to be deliberately absent: with the
|
|
73
|
+
* metered methods no longer nullable, a 404 on `walletBreakdown()` / `agent()`
|
|
74
|
+
* DOES reach the caller as a throw, so `instanceof` has to be possible. On the
|
|
75
|
+
* free routes it still never does.
|
|
76
|
+
*/
|
|
77
|
+
DescribeNotFound,
|
|
78
|
+
/**
|
|
79
|
+
* The two partner-rail failures. Both are exported because both are meant to
|
|
80
|
+
* be caught by `instanceof`: `DescribePartnerUnsigned` is "fix your config",
|
|
81
|
+
* `DescribePartnerRejected` is "your free rail is off and we did NOT pay for
|
|
82
|
+
* you". Neither is ever swallowed by `failOpen`.
|
|
83
|
+
*/
|
|
84
|
+
DescribePartnerRejected,
|
|
85
|
+
DescribePartnerUnsigned,
|
|
86
|
+
DescribePaymentRefused,
|
|
87
|
+
DescribePaymentRequired,
|
|
88
|
+
DescribeTimeout,
|
|
89
|
+
DescribeUnparseable,
|
|
90
|
+
DescribeUnreachable,
|
|
91
|
+
failedAfterPaying,
|
|
92
|
+
failOpenCovers,
|
|
93
|
+
} from './errors';
|
|
94
|
+
export type { DescribeErrorKind, PaymentAttempt, X402Challenge } from './errors';
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* The recovery table — what to do INSTEAD of the failure you are holding.
|
|
98
|
+
*
|
|
99
|
+
* Absorbed from **Execution Market** (`#agents`, 2026-08-30). Every
|
|
100
|
+
* `DescribeError` already carries its own text in `error.recovery`; the table
|
|
101
|
+
* is exported so a test can pin one without matching on prose, and so a router
|
|
102
|
+
* that has not failed yet can read the advice up front. `recoveryFor()` is the
|
|
103
|
+
* same lookup for a `kind` you hold without an instance.
|
|
104
|
+
*
|
|
105
|
+
* 🔴 Read it, never branch on it: `kind` is the enum.
|
|
106
|
+
*/
|
|
107
|
+
export { RECOVERY, recoveryFor } from './recovery';
|
|
108
|
+
export type { RecoveryKey } from './recovery';
|
|
109
|
+
|
|
110
|
+
export {
|
|
111
|
+
CAVEAT_CODES,
|
|
112
|
+
CAVEAT_SCOPE_FREE,
|
|
113
|
+
CAVEAT_SCOPE_METERED,
|
|
114
|
+
hasCaveat,
|
|
115
|
+
isKnownCaveatCode,
|
|
116
|
+
} from './caveats';
|
|
117
|
+
export type { Caveat, CaveatCode, KnownCaveatCode } from './caveats';
|
|
118
|
+
|
|
119
|
+
export { formatScore, roundScore } from './format';
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* The distinct-rater helper, from MeshRelay. Read its docstring before using the
|
|
123
|
+
* number: summing the per-chain counts double-counts and taking the maximum
|
|
124
|
+
* underestimates, both measured, and this function does neither.
|
|
125
|
+
*/
|
|
126
|
+
export { resolveDistinctRaters } from './raters';
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* The hash-shape contract, from KarmaKadabra's *"el 200 sin tx"*.
|
|
130
|
+
*
|
|
131
|
+
* Exported because the check belongs to the CONTRACT and not to each consumer —
|
|
132
|
+
* that was their whole point. `malformedHashReport` locates what a parsed result
|
|
133
|
+
* dropped; the two predicates are there for a payload you validate yourself.
|
|
134
|
+
*/
|
|
135
|
+
export {
|
|
136
|
+
looksLikeOnchainId,
|
|
137
|
+
looksLikeSettlementReceipt,
|
|
138
|
+
malformedHashReport,
|
|
139
|
+
SETTLEMENT_PENDING,
|
|
140
|
+
} from './hashes';
|
|
141
|
+
|
|
142
|
+
export {
|
|
143
|
+
DEFAULT_BASE_URL,
|
|
144
|
+
DEFAULT_JITTER_MS,
|
|
145
|
+
DEFAULT_SITE_URL,
|
|
146
|
+
DEFAULT_TIMEOUT_MS,
|
|
147
|
+
PARTNER_CHAIN_ID,
|
|
148
|
+
PARTNER_KEY_ENV,
|
|
149
|
+
SDK_NAME,
|
|
150
|
+
SDK_VERSION,
|
|
151
|
+
TREASURY_EVM,
|
|
152
|
+
userAgent,
|
|
153
|
+
} from './config';
|
|
154
|
+
|
|
155
|
+
export type {
|
|
156
|
+
Activity,
|
|
157
|
+
AgentReputation,
|
|
158
|
+
Concentration,
|
|
159
|
+
Confidence,
|
|
160
|
+
Facet,
|
|
161
|
+
HealthChain,
|
|
162
|
+
IndexHealth,
|
|
163
|
+
LeaderboardRow,
|
|
164
|
+
Network,
|
|
165
|
+
Ownership,
|
|
166
|
+
PaymentEvidence,
|
|
167
|
+
Rating,
|
|
168
|
+
Sealed,
|
|
169
|
+
SelfRated,
|
|
170
|
+
Snapshot,
|
|
171
|
+
Timestamp,
|
|
172
|
+
WalletBreakdown,
|
|
173
|
+
WalletChainRow,
|
|
174
|
+
WalletReputation,
|
|
175
|
+
} from './types';
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The parsers, exported for one reason: a consumer who already has a describe
|
|
179
|
+
* payload (from the MCP tools, the A2A gate, or a snapshot in their own
|
|
180
|
+
* database) can get the same typed shape without a second HTTP call.
|
|
181
|
+
*
|
|
182
|
+
* EM stores a snapshot in its own table and MeshRelay caches raw JSON — both
|
|
183
|
+
* re-derive shapes from stored payloads today. This is the seam that lets them
|
|
184
|
+
* stop.
|
|
185
|
+
*/
|
|
186
|
+
export {
|
|
187
|
+
parseAgentReputation,
|
|
188
|
+
parseHealth,
|
|
189
|
+
parseLeaderboard,
|
|
190
|
+
parseWalletBreakdown,
|
|
191
|
+
parseWalletReputation,
|
|
192
|
+
} from './parse';
|
package/src/jitter.ts
ADDED
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A short random pause before a read, so a fleet does not arrive as one spike.
|
|
3
|
+
*
|
|
4
|
+
* ## Where this comes from, and what not having it cost
|
|
5
|
+
*
|
|
6
|
+
* Contributed by **KarmaKadabra**, `#agents` on MeshRelay, **2026-08-30**. They
|
|
7
|
+
* operate the largest fleet against this index — 27 agents — and their sentence
|
|
8
|
+
* is the whole specification:
|
|
9
|
+
*
|
|
10
|
+
* > *"27 agentes despiertan al MISMO tiempo por EventBridge y pegan simultáneo
|
|
11
|
+
* > contra su límite de rps COMPARTIDO con los otros consumidores. Sin jitter,
|
|
12
|
+
* > un enjambre es un DDoS educado."*
|
|
13
|
+
*
|
|
14
|
+
* They sleep `random.uniform(0, 0.4)` before every read
|
|
15
|
+
* (`karmakadabra/lib/reputation_scan.py:123`). Verified before writing a line:
|
|
16
|
+
* `grep -riE 'jitter|random|sleep' src/` in **both** SDKs returned zero hits on
|
|
17
|
+
* 2026-08-30. Neither of us had it.
|
|
18
|
+
*
|
|
19
|
+
* Two halves of what follows are theirs and two are ours, and the line matters
|
|
20
|
+
* because provenance is the reason to trust a number: **measured at
|
|
21
|
+
* KarmaKadabra** are the 0.4 s and the non-cryptographic uniform draw.
|
|
22
|
+
* **Designed here** are everything about it being a parameter at all — the
|
|
23
|
+
* default being ON, `0` switching it off, and a garbage value falling back to
|
|
24
|
+
* the default rather than to off. KarmaKadabra has no jitter option; they have
|
|
25
|
+
* a literal.
|
|
26
|
+
*
|
|
27
|
+
* The word that makes it the library's problem and not the fleet's is
|
|
28
|
+
* **COMPARTIDO**. describe.net's rate limit has no per-partner bucket (already
|
|
29
|
+
* written down in `config.ts`), so the agent that pays for an unjittered swarm
|
|
30
|
+
* is not the swarm's owner — it is the other consumer whose read gets the 429,
|
|
31
|
+
* and who has no lever to fix it. That is the shape of an externality, and a
|
|
32
|
+
* default that leaves the cost on someone with no lever is the wrong default.
|
|
33
|
+
*
|
|
34
|
+
* ## 🔴 Jitter is NOT backoff, and the day someone adds a retry this matters
|
|
35
|
+
*
|
|
36
|
+
* They look alike (both sleep) and they answer opposite questions. **Jitter
|
|
37
|
+
* disperses a herd that has not asked for anything yet**; it goes before a
|
|
38
|
+
* request and its size is about how many of us there are. **Backoff yields to a
|
|
39
|
+
* service that has already said no**; it goes before a RETRY and its size is
|
|
40
|
+
* about how hard it just refused. So a retry — this package has none,
|
|
41
|
+
* deliberately, see `client.ts` — takes backoff, never this.
|
|
42
|
+
*
|
|
43
|
+
* ## 🔴 It goes before EVERY request, not once per public call
|
|
44
|
+
*
|
|
45
|
+
* ⚠️ **This is a correction of the rule this file was first written with, and
|
|
46
|
+
* the old one is left here because it is the intuitive reading and the next
|
|
47
|
+
* person to touch this will want to "optimise" back to it.** The first version
|
|
48
|
+
* said *"once per public call, before the FIRST request"*. It sounds
|
|
49
|
+
* equivalent. It is not: a call that fires N requests would disperse one and
|
|
50
|
+
* let the other N−1 out in a pack — the exact problem this contribution came to
|
|
51
|
+
* fix, reintroduced through the back door.
|
|
52
|
+
*
|
|
53
|
+
* KarmaKadabra's own call site settles it, and it was read rather than assumed
|
|
54
|
+
* (2026-08-30): the sleep lives INSIDE `_scan_describenet()`, the function that
|
|
55
|
+
* performs the GET (`reputation_scan.py:123`), and that function runs **twice**
|
|
56
|
+
* on the real path — `:242` for the EVM address, `:245` for the Solana one. So
|
|
57
|
+
* their jitter is per REQUEST, and the reason they wrote next to it
|
|
58
|
+
* (`:121-122`) is per-PROCESS: it is anti-thundering-herd between agents that
|
|
59
|
+
* wake together against a shared ceiling, not a spacer inside one call.
|
|
60
|
+
*
|
|
61
|
+
* The paid replay sleeps too, and that is the same correction. It was going to
|
|
62
|
+
* be the one exception here, on the argument that delaying a signed envelope
|
|
63
|
+
* widens the window in which a crash loses a receipt. Measured against the
|
|
64
|
+
* numbers, that argument does not hold: the challenge this client answers
|
|
65
|
+
* carries `maxTimeoutSeconds: 120`, so 400 ms is a third of a percent of the
|
|
66
|
+
* envelope's own validity, while the herd argument applies to the replay in
|
|
67
|
+
* full — 27 agents that get their 402 in the same second replay in the same
|
|
68
|
+
* second. One rule with no exception, and nothing in the money path is
|
|
69
|
+
* measurably worse for it.
|
|
70
|
+
*
|
|
71
|
+
* ## 🔴 `Math.random`, and never `crypto.getRandomValues`
|
|
72
|
+
*
|
|
73
|
+
* This is dispersion, not a secret. Nothing about the delay needs to be
|
|
74
|
+
* unguessable: an adversary who predicts that this process will wait 213 ms
|
|
75
|
+
* learns nothing worth knowing, and cannot use it. Reaching for a CSPRNG here
|
|
76
|
+
* would be worse than useless — it tells the next reader that unpredictability
|
|
77
|
+
* is a security property of this value, which invites them to "harden" a
|
|
78
|
+
* sleep. `Math.random` is uniform enough for spreading arrivals, is available
|
|
79
|
+
* in every runtime this package targets (browser included), and costs nothing.
|
|
80
|
+
*/
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* How long to wait, in milliseconds: a uniform draw from `[0, maxMs)`.
|
|
84
|
+
*
|
|
85
|
+
* Pure, so it is tested exhaustively without a clock. `random` is injectable for
|
|
86
|
+
* exactly that reason and for no other — production always passes `Math.random`.
|
|
87
|
+
*
|
|
88
|
+
* Garbage in gives the caller's own configured default nothing to stand on, so
|
|
89
|
+
* this function's contract is narrow: it clamps rather than throws. A `maxMs`
|
|
90
|
+
* that is not a finite positive number yields `0`, because a library that dies
|
|
91
|
+
* at read time over a mistyped option is worse than one that does not sleep.
|
|
92
|
+
* The decision about what a garbage OPTION means (fall back to the default, not
|
|
93
|
+
* to off) belongs one level up, in `DescribeClient` — see `jitterMs` there.
|
|
94
|
+
*/
|
|
95
|
+
export function jitterDelayMs(maxMs: number, random: () => number = Math.random): number {
|
|
96
|
+
if (!Number.isFinite(maxMs) || maxMs <= 0) return 0;
|
|
97
|
+
const draw = random();
|
|
98
|
+
if (!Number.isFinite(draw) || draw < 0) return 0;
|
|
99
|
+
return Math.min(draw, 1) * maxMs;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* The only timer in this package.
|
|
104
|
+
*
|
|
105
|
+
* `setTimeout` and not a busy loop, obviously — but also not `unref()`d: a
|
|
106
|
+
* process that exits while a read is pending would have dropped that read
|
|
107
|
+
* anyway, and `unref` is Node-only, which would break the browser target this
|
|
108
|
+
* package keeps.
|
|
109
|
+
*/
|
|
110
|
+
export function sleep(ms: number): Promise<void> {
|
|
111
|
+
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
112
|
+
}
|