Direction for durable viem-chain freshness in x402 SDKs

[ryanRfox]

Background

#1971 closed via #2054 which is a different layer than the options @cryptomotifs sketched. Reopening as a fresh issue since the close didn't address this design layer.

The dependencies bug

The visible symptom was Mezo (eip155:31611) missing from published bundles. The real bug surfaced by @cryptomotifs:
x402 can't distinguish "chain exists in viem ≥ N but we're pinned on < N"
(freshness gap; throws Unsupported chain ID when the chain is in fact
supported) from "chain truly doesn't exist" (correct error).

A lockfile bump postpones the first case until the next new chain. A runtime registry fixes the distinction.

Three options (per @cryptomotifs, ordered by effort vs. robustness)

1. Runtime fetch + minimal local fallback — small x402-chains package lazy-fetches chain metadata from a CDN JSON endpoint, with compiled-in fallback for the offline-must-work subset. Decouples downstream SDKs from viem's release cadence entirely, but introduces infrastructure requirements.
2. defineChain by ID, per-chain literals committed here — viem for types only. Scoped variant I floated:
   paywall sources from x402's existing per-chain registries (e.g. DEFAULT_STABLECOINS in @x402/evm).
3. Weekly Dependabot lockfile refresh — drafted as chore: add scoped viem dependabot updates for /typescript #2002 which narrows the freshness gap but doesn't fix the UX distinction.

Status

• chore: bump viem floor to ^2.48.11 across monorepo + refresh lockfiles #2242 shipped in v2.12.0 which stops pnpm from re-resolving downward when sub-packages land with looser pins.
• chore: add scoped viem dependabot updates for /typescript #2002 (option 3) ready to land; doesn't foreclose options 1 or 2 as follow-ups.
• Option 2's pattern is partially implemented in chore(e2e): make the harness portable to any EVM chain in DEFAULT_STABLECOINS #2250 (e2e harness scope only) via resolveViemChain(caip2) walking viem's chain DB with defineChain fallback, sourced from DEFAULT_STABLECOINS. SDK-runtime application would be a separate step. Adjacent design notes with @phdargen on a related pattern in PR #2238.

Ask

@phdargen — looking for guidance on which of options 1 or 2 is the direction we should consider for a robust fix, as I don't have context to pick between them. Merging #2002 seems to be a fine mitigation step in the meantime.

[danielnorkin]

Thanks @ryanRfox for the clear write-up, and @cryptomotifs for naming the actual bug ("chain is in viem but we're on an older version" vs "chain doesn't exist"). That distinction made it click for us when we hit the same problem internally.

Sharing something we built that might help, plus an offer.

We had the same problem inside our pipeline. We watch x402 settlements on Base, Polygon, Optimism, Arbitrum, and Solana, and we need correct chain info no matter which viem version we're pinned to. Our fix looks a lot like option 1: a small JSON endpoint that returns per-network info on demand.

What it returns per network:

• CAIP-2 identifier
• USDC contract address + decimals
• Permit2 proxy (where it applies)
• Confirmation depth
• EIP-3009 AuthorizationUsed and Transfer event topics
• latest_block_observed and last_event_at (proves the registry is fresh)

Five chains today. We built it for our own chain-watching work, and we'd be happy to grow it if the Foundation thinks it's useful. That could mean contributing the shape and code upstream as a starting point, or taking on more of the maintenance work as a community contributor. Either way we'd like to help.

(The offline fallback for Base / Base Sepolia / Ethereum still belongs inside the SDK no matter which option wins.)

Picking between option 1 and option 2 is a maintainer call, and figuring out neutral hosting comes first. Happy to chat offline.

[ryanRfox]

Hey @phdargen, wondering if you feel @danielnorkin's offer above warrants pulling the rest of the maintainer team in to weigh in on the direction between options 1, 2, or something else. Option 3 #2002 remains a viable stopgap in the meantime.