@decdn/client is a TypeScript client for Node.js 20.19+ and evergreen browsers. It speaks HTTP to a decdn gateway. The gateway pays for every pull and verifies it. The SDK hashes the bytes again with BLAKE3 wherever it holds a whole blob named by its hash. It has no native code and needs no wallet library.
Which gateway
The gateway’s HTTP contract is in appendix-gateway.
@decdn/client 0.1 works with any loopback gateway from Node.js. Browser pages and public gateways need a gateway release that answers every origin (cross-origin reads): decdn v0.3.0 or later.
Fetch from a public gateway
decdn:<hash>/<path> URI names one file of a bundle. The SDK reads the bundle manifest once per client, checks the manifest’s own hash, and hashes the file against the entry the manifest gives.
A byte window of a file that declares its size comes back as 206:
Use the local gateway from Node.js
A loopback gateway pays with a capability that a pool owner issues to one of the gateway’s delegate keys (ADR 003). Mint the delegate, have the pool owner assign it, then register the capability for the host your requests name:PAYMENT_REQUIRED. client.loopback.capabilities() lists the capabilities the gateway holds.
The SDK does not start the gateway. Run decdn gateway yourself, or the decdn/decdn Docker image. open() treats a localhost, 127.0.0.1 or ::1 URL as a loopback gateway, so a public gateway you run locally needs another host name, such as decdn.localhost.
Pages on a site origin
A bundle opened as a website has its own origin,https://<hash32>.decdn.link/ or, on a loopback gateway, http://<hash32>.localhost:8484/. A page there opens the client without a URL. Its own paths and other content both verify:
https://<ns>.decdn.link/, serves whatever bundle its pointer names. A page there opens the client with the gateway URL, DecdnClient.open({ gatewayUrl: "https://decdn.link" }). Its own paths are not verified, and client.manifest() needs a hash.
What the SDK verifies
verified: true names the check, not its result. Chunks reach you before the last one is hashed, so act on the bytes only once the stream ends with done, or once bytes(), text() or json() resolves.
A site rewrites HTML and CSS as it serves them, so the SDK fetches those files by their own hash and verifies them too: on the gateway’s bare host from a public or loopback client, or under /_decdn/ on the page’s own origin from a site client. Pass verify: true to refuse anything that cannot be verified: such a request fails with CONFIG.
When the gateway does not pay
A public gateway answers402 when its allowance is spent and 503 when its pool cannot pay. They reach your code as a DecdnError with code PAYMENT_REQUIRED or POOL_UNFUNDED, and with retryAfterSecs and fallbackUri, the canonical decdn: URI. Fetch that URI with a paying client of your own (decdn get), or wait and retry. The SDK retries nothing on its own. get(uri, { retry: true }) waits out one Retry-After and tries once more.
Point a namespace
The owner of a namespace on thePublisherRegistry points it at a bundle. The public gateway then serves that bundle at https://<ns>.decdn.link/:
pointerTypedData gives the typed data to a wallet that signs it. The chain id and registry are the deployment the gateway verifies against. The gateway stores a pointer only when its signer owns the namespace and its sequence number is above the last one from that signer.
The package README has more examples and every error code: decdn/sdk-typescript.