feat(x402): namespace the deferred scheme and add the v2 Discovery API

[JulioMCruz]

Implements the actionable findings from the protocol research (STACK-PROTOCOL-RESEARCH-2026-07-29.md).

Stacked on #144. Base branch is chore/drop-local-erc8004-registries, not main — both touch CLAUDE.md. Merge #144 first and this retargets cleanly.

R1 — Namespace the deferred scheme

x402 v2 standardizes exactly one scheme: exact. deferred, upto and batch-settlement are proposed, and since 2026-07-14 the namespace is governed by the x402 Foundation TSC under the Linux Foundation.

Stack was advertising a PerkOS-designed voucher scheme under the bare name deferred. If the TSC standardizes that string with different semantics, every client that negotiated it is speaking a different protocol than a compliant counterparty.

Backward-compatible migration, as agreed:

	Advertised	Accepted on input
perkos-deferred	yes	yes
deferred	no	yes, with X-x402-Deprecation on the response

Scheme handling is centralized in lib/utils/x402-schemes.ts and fails closed — canonicalizeScheme returns null for anything unrecognized rather than letting it fall through to a default handler.

One subtlety worth calling out: transactions written before the rename are stored as deferred. A filter matching only the new spelling would silently hide history, so schemeFilterValues() matches the whole family and the transactions query uses .in() instead of .eq().

R2 — x402 v2 Discovery API

Adds GET /api/discovery/resources — the spec-defined listing with limit/offset pagination and type filtering.

Stack already had /.well-known/x402-discovery.json, but that is PerkOS metadata about the facilitator (its own header comment says it "is not a core endpoint"), not a resource listing. The Discovery extension is how facilitators index each other, so without this Stack does not appear in that channel.

Vendor endpoints are read in one batched query per page rather than one per vendor.

R4, R6, R7 — Docs

• CLAUDE.md documented the v1 request shape — bare network names ("avalanche"), x402Version: 1, no accepted echo. The code has been fully v2 for a while; anyone onboarding from that doc wrote wrong clients. Now shows v2 with CAIP-2 and the echo rule.
• Protocol status table at the top, stating plainly that none of the four protocols is finalized, with the specific wording to avoid for each. Modeled on the discipline already in Docs/X401-STATUS-2026-07-22.md.
• Docs/PROTOCOL-PIN-REVIEW.md — monthly re-pin checklist for all four, with the specific things that would break us (a standardized deferred, an x401 0.3.0 wire redesign, the ERC-8004 Validation Registry shipping, a slimmed ERC8183WithAuthorization).

Two unrelated pre-existing fixes

Both were blocking verification of everything above.

main did not build. lib/utils/chains.ts imports megaeth from viem/chains, which does not export it — only megaethTestnet. package-lock.json is untracked, so any fresh install resolves ^2.44.1 and hits this.

I removed the mainnet entry rather than invent a chain ID. MegaETH mainnet launched 2026-02-09, but I could not confirm its chain ID in a primary source, and its payment token here was the zero-address placeholder — so it was never a working payment network. Re-add properly once viem ships it. The testnet (6342) is untouched.

npm test did not run. The script omitted --experimental-strip-types, so on Node 23.3 every suite failed with ERR_UNKNOWN_FILE_EXTENSION on its .ts imports. The whole suite was red, not just mine.

Verification

npx tsc --noEmit     clean (first time — was 1 error)
npm test             22/22 passing (was 0/22), 5 new scheme tests
npm run build        ✓ Compiled successfully
                     ƒ /api/discovery/resources registered

Not included

R5, the ERC-8183 → ERC-8004 reputation loop, is deliberately out of scope — it needs its own design (who signs the feedback, what value/decimals, idempotency) and is the strategically interesting piece rather than plumbing.

R3, @perkos/contracts-erc8004@1.0.1, cannot be fixed here: the package source is not in this repo or the workspace, and npm reports no repository.url. It is still published describing pre-v2 contracts, so external installers get stale definitions with no warning.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stack	Ready	Preview, Comment	Jul 29, 2026 2:30am