Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(brownout): serve the degradation proofs and the upstream baseline publicly
nirholas0fe4721764bd
diff --git a/api/brownout.js b/api/brownout.jsnew file mode 100644index 000000000..127218d79--- /dev/null+++ b/api/brownout.js@@ -0,0 +1,89 @@+// GET /api/brownout — the platform's degradation posture, as data.+//+// Two things, and the second is the one that matters:+//+// contracts what this platform promises to do when a given upstream fails+// proofs the last time each of those promises was executed for real,+// with the upstream actually broken, and what came back+//+// Anyone can claim a fallback. The proof block is a receipt from a run where+// the named provider was made to fail inside the real request path, so a reader+// can check the claim rather than take it. `not_exercised` is reported as+// plainly as a failure, because a proof that did not run is not a pass.+import { readFileSync } from 'node:fs';+import { join } from 'node:path';+import { cors, json, method, wrap, error } from './_lib/http.js';+import { limits, clientIp, rateLimited } from './_lib/rate-limit.js';++const ROOT = process.cwd();+let _cached = null;++// Both files are baked into the image at build time, so this is a disk read+// once per process, not per request.+function load() {+ if (_cached) return _cached;+ const registry = JSON.parse(readFileSync(join(ROOT, 'data/brownout.json'), 'utf8'));+ let proofs = null;+ try {+ proofs = JSON.parse(readFileSync(join(ROOT, 'public/brownout.json'), 'utf8'));+ } catch {+ // A build that has never run the prover is a real state, and saying so is+ // better than implying the contracts are unverified when they are simply+ // unrun in this image.+ proofs = null;+ }+ const byId = new Map((proofs?.results || []).map((r) => [r.id, r]));+ _cached = {+ updated: registry.updated,+ summary: registry.summary,+ proven: proofs?.proven ?? 0,+ total: registry.contracts.length,+ last_proof_at: proofs?.generated_at ?? null,+ contracts: registry.contracts.map((c) => {+ const proof = byId.get(c.id) || null;+ return {+ id: c.id,+ title: c.title,+ surface: c.surface ?? null,+ endpoint: c.endpoint,+ breaks: c.break,+ expect: c.expect,+ why: c.why ?? null,+ proof: proof+ ? {+ verdict: proof.verdict,+ status: proof.observed?.status ?? null,+ tier: proof.observed?.tier ?? null,+ degraded: proof.observed?.degraded ?? null,+ failed_sources: proof.observed?.failedSources ?? 0,+ trace: proof.observed?.trace ?? [],+ ms: proof.ms ?? null,+ problems: proof.problems ?? [],+ }+ : null,+ };+ }),+ };+ return _cached;+}++export default wrap(async (req, res) => {+ if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;+ if (!method(req, res, ['GET'])) return;++ const rl = await limits.publicIp(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ let payload;+ try {+ payload = load();+ } catch (err) {+ return error(res, 503, 'registry_unavailable', `the brownout registry could not be read: ${err?.message || err}`);+ }++ return json(res, 200, payload, {+ // The registry changes with a deploy and the proofs with a prover run, so+ // a short shared cache is right and a long one would hide a fresh proof.+ 'cache-control': 'public, max-age=60, s-maxage=300, stale-while-revalidate=600',+ });+});diff --git a/data/upstream-baseline.json b/data/upstream-baseline.jsonnew file mode 100644index 000000000..bd5164334--- /dev/null+++ b/data/upstream-baseline.json@@ -0,0 +1,167 @@+{+ "generated": "scripts/audit-upstreams.mjs",+ "summary": {+ "total": 183,+ "grades": {+ "A": 0,+ "B": 46,+ "C": 84,+ "D": 53,+ "F": 0+ },+ "protections": {+ "deadline": 183,+ "retry": 88,+ "failover": 42,+ "lastGood": 4,+ "breaker": 79+ }+ },+ "sites": {+ "api/_lib/agent-tools.js::api.duckduckgo.com::fetchUpstreamJson": "C",+ "api/_lib/alerts.js::api.telegram.org::fetchUpstream": "C",+ "api/_lib/blockchair.js::api.blockchair.com__expr__::fetch": "C",+ "api/_lib/changelog-push.js::api.telegram.org::fetchUpstream": "C",+ "api/_lib/coinbase-onramp.js::api.developer.coinbase.com::fetch": "D",+ "api/_lib/companion/lanes/telegram.js::api.telegram.org::fetch": "D",+ "api/_lib/elevenlabs.js::api.elevenlabs.io::fetchUpstream": "C",+ "api/_lib/embeddings.js::integrate.api.nvidia.com::fetch": "D",+ "api/_lib/embeddings.js::api.openai.com::fetch": "D",+ "api/_lib/esplora.js::blockstream.info::fetch": "C",+ "api/_lib/gcp-auth.js::metadata.google.internal::fetchUpstream": "C",+ "api/_lib/gcp-auth.js::oauth2.googleapis.com::fetchUpstream": "C",+ "api/_lib/gcp-billing.js::bigquery.googleapis.com::fetch": "D",+ "api/_lib/github-api.js::api.github.com__expr__::fetchUpstream": "C",+ "api/_lib/github-api.js::api.github.com::fetchUpstream": "C",+ "api/_lib/gmgn-feed.js::api.dexscreener.com::fetch": "D",+ "api/_lib/hyperliquid.js::api.hyperliquid.xyz::fetchUpstreamJson": "B",+ "api/_lib/indexnow.js::api.indexnow.org::fetch": "D",+ "api/_lib/ipfs-pin.js::api.pinata.cloud::fetchUpstream": "C",+ "api/_lib/ipfs-pin.js::api.web3.storage::fetchUpstream": "C",+ "api/_lib/openrouter-free.js::openrouter.ai::fetch": "D",+ "api/_lib/oracle/alerts.js::api.telegram.org::fetchUpstream": "C",+ "api/_lib/persona-wallet.js::sns-api.bonfida.com::fetchUpstreamJson": "C",+ "api/_lib/privy.js::auth.privy.io::fetchUpstream": "C",+ "api/_lib/publish-safety.js::integrate.api.nvidia.com::fetch": "D",+ "api/_lib/pump-go.js::livestream-api.pump.fun__expr__::fetchUpstream": "C",+ "api/_lib/pump-launch.js::pump.fun::fetchUpstream": "C",+ "api/_lib/rerank.js::ai.api.nvidia.com::fetch": "D",+ "api/_lib/rugcheck.js::api.rugcheck.xyz::fetchUpstreamJson": "C",+ "api/_lib/sketchfab.js::api.sketchfab.com::fetch": "D",+ "api/_lib/sniper/notify.js::api.telegram.org::fetchUpstream": "C",+ "api/_lib/sol-price.js::api.coingecko.com::fetchFirst": "B",+ "api/_lib/sol-price.js::lite-api.jup.ag::fetchFirst": "B",+ "api/_lib/sol-price.js::api.kraken.com::fetchFirst": "B",+ "api/_lib/sol-price.js::api.coinbase.com::fetchFirst": "B",+ "api/_lib/sol-price.js::coins.llama.fi::fetchFirst": "B",+ "api/_lib/sol-price.js::api.diadata.org::fetchFirst": "B",+ "api/_lib/sol-price.js::api-pub.bitfinex.com::fetchFirst": "B",+ "api/_lib/token-market.js::api.dexscreener.com::fetchUpstreamJson": "B",+ "api/_lib/tokens-xyz.js::api.tokens.xyz::fetch": "D",+ "api/_lib/tts-edge.js::speech.platform.bing.com::fetch": "D",+ "api/_lib/watsonx.js::openrouter.ai::fetch": "D",+ "api/_lib/x-post.js::api.twitter.com::fetchUpstream": "C",+ "api/_lib/x-post.js::api.x.com::fetchUpstream": "C",+ "api/_mcp/tools/garments.js::storage.googleapis.com::fetchUpstream": "C",+ "api/_providers/meshy.js::api.meshy.ai__expr__::fetchUpstream": "C",+ "api/_providers/nvidia-cosmos.js::api.nvcf.nvidia.com::fetch": "D",+ "api/_providers/nvidia.js::ai.api.nvidia.com::fetch": "D",+ "api/_providers/nvidia.js::api.nvcf.nvidia.com::fetch": "D",+ "api/_providers/replicate.js::api.replicate.com::fetchUpstream": "C",+ "api/_providers/rodin.js::api.hyper3d.com::fetchUpstream": "C",+ "api/_providers/stability.js::api.stability.ai::fetchUpstream": "C",+ "api/_providers/tripo.js::api.tripo3d.ai::fetchUpstream": "C",+ "api/agents/[id]/memory-seed-x.js::api.twitter.com::fetchUpstream": "C",+ "api/agents/alpha.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",+ "api/agents/alpha.js::api.dexscreener.com::fetchUpstreamJson": "C",+ "api/agents/register/[action].js::api.web3.storage::fetchUpstream": "C",+ "api/agents/register/[action].js::api.pinata.cloud::fetchUpstream": "C",+ "api/agents/sns.js::sns-api.bonfida.com__expr__::fetchUpstreamJson": "C",+ "api/agents/wallet-intents.js::api.anthropic.com::fetch": "D",+ "api/agents/wallet-intents.js::openrouter.ai::fetch": "D",+ "api/auth/github/[action].js::github.com::fetchUpstream": "C",+ "api/auth/github/[action].js::api.github.com::fetchUpstream": "C",+ "api/auth/x/[action].js::api.twitter.com::fetchUpstream": "C",+ "api/avatars/_actions.js::api.anthropic.com::fetchUpstream": "C",+ "api/chat/proxy.js::openrouter.ai::fetch": "D",+ "api/coin/fear-greed.js::api.alternative.me::fetchUpstreamJson": "C",+ "api/coin/fear-greed.js::pro-api.coinmarketcap.com::fetchUpstreamJson": "C",+ "api/coin/global.js::api.alternative.me::fetchUpstreamJson": "C",+ "api/coin/trending.js::api.geckoterminal.com::fetch": "D",+ "api/cron/[name].js::api.twitter.com::fetchUpstream": "C",+ "api/cron/copy-fanout.js::api.telegram.org::fetch": "D",+ "api/cron/gmgn-seed.js::raw.githubusercontent.com::fetch": "D",+ "api/cron/oracle-digest.js::api.telegram.org::fetchUpstream": "C",+ "api/cron/quota-check.js::api.upstash.com::fetch": "D",+ "api/cron/quota-check.js::qstash.upstash.io::fetch": "D",+ "api/crypto/portfolio.js::api.dexscreener.com::fetchUpstreamJson": "B",+ "api/defi/chains.js::api.llama.fi::fetchUpstream": "C",+ "api/defi/dex-volumes.js::api.llama.fi::fetchUpstream": "C",+ "api/defi/hacks.js::api.llama.fi::fetchUpstream": "C",+ "api/defi/protocols.js::api.llama.fi::fetchUpstream": "C",+ "api/defi/stablecoins.js::stablecoins.llama.fi::fetchUpstream": "C",+ "api/defi/yields.js::yields.llama.fi::fetchUpstream": "C",+ "api/demo-economy.js::api.geckoterminal.com::fetchUpstreamJson": "B",+ "api/erc8004/[action].js::api.web3.storage::fetchUpstream": "C",+ "api/erc8004/[action].js::api.nft.storage::fetchUpstream": "C",+ "api/healthz.js::api.resend.com::fetch": "D",+ "api/oracle-share.js::api.dexscreener.com::fetchUpstreamJson": "C",+ "api/oracle-share.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",+ "api/oracle/og.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",+ "api/oracle/test-alert.js::api.telegram.org::fetchUpstream": "C",+ "api/pinning/[action].js::api.pinata.cloud::fetch": "D",+ "api/pinning/[action].js::api.web3.storage::fetch": "D",+ "api/portfolio/[action].js::coins.llama.fi::fetchFirstOrNull": "B",+ "api/pump-fun-mcp.js::publish.twitter.com::fetch": "D",+ "api/pump/[action].js::api.github.com::fetch": "D",+ "api/pump/dex-trades.js::api.geckoterminal.com::fetch": "D",+ "api/pump/launch-detail.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",+ "api/pump/launch-detail.js::swap-api.pump.fun::pumpFetchJson": "C",+ "api/pump/launch-og.js::frontend-api-v3.pump.fun::pumpFetchJson": "C",+ "api/tts/eleven.js::api.elevenlabs.io::fetch": "D",+ "api/tts/eleven/library.js::api.elevenlabs.io::fetch": "D",+ "api/tts/speak.js::api.openai.com::fetch": "D",+ "api/tx/explain.js::api.helius.xyz::fetchUpstream": "C",+ "api/x402/crypto-intel.js::api.coingecko.com::fetch": "D",+ "api/x402/crypto-intel.js::api.exchange.coinbase.com::fetch": "D",+ "api/x402/defi-radar.js::api.llama.fi__expr__::fetchUpstream": "C",+ "api/x402/hack-check.js::api.llama.fi::fetchUpstream": "C",+ "api/x402/market-heatmap.js::api.coinpaprika.com::fetch": "D",+ "api/x402/market-mood.js::api.alternative.me::fetchUpstream": "C",+ "api/x402/market-mood.js::www.deribit.com::fetchUpstream": "C",+ "api/x402/stablecoin-health.js::stablecoins.llama.fi::fetchUpstream": "C",+ "api/x402/telegram-health.js::api.telegram.org::fetch": "D",+ "api/x402/yield-scan.js::yields.llama.fi::fetchUpstream": "C",+ "mcp-server/src/tools/_studio-core.js::api.replicate.com::fetch": "D",+ "public/studio/fees-panel.js::api.github.com::fetch": "D",+ "src/artifact/entry.js::esm.sh::loadModule": "B",+ "src/auth/walletconnect-bridge.js::esm.sh::loadModule": "B",+ "src/character.js::api.dexscreener.com::fetchFirstOrNull": "B",+ "src/character.js::api.geckoterminal.com::fetchFirstOrNull": "B",+ "src/character.js::lite-api.jup.ag::fetchFirstOrNull": "B",+ "src/coin3d/main.js::api.geckoterminal.com::fetchFirstOrNull": "B",+ "src/coin3d/main.js::api.dexscreener.com::fetchFirstOrNull": "B",+ "src/coin3d/main.js::lite-api.jup.ag::fetchFirstOrNull": "B",+ "src/home-bento.js::lite-api.jup.ag::fetch": "D",+ "src/kol/kolscan-live.js::kolscan.io::fetch": "D",+ "src/pinning/pinata.js::api.pinata.cloud::fetch": "C",+ "src/privy-login.js::auth.privy.io::fetch": "D",+ "src/shared/leaflet-loader.js::esm.sh::loadModule": "B",+ "src/shared/leaflet-loader.js::nominatim.openstreetmap.org::fetchFirstOrNull": "B",+ "src/shared/leaflet-loader.js::photon.komoot.io::fetchFirstOrNull": "B",+ "src/shared/leaflet-loader.js::api.bigdatacloud.net::fetchFirstOrNull": "B",+ "src/shared/usd-price.js::lite-api.jup.ag::fetchFirst": "B",+ "src/shared/usd-price.js::api.coingecko.com::fetchFirst": "B",+ "src/shared/usd-price.js::api.coinbase.com::fetchFirst": "B",+ "src/shared/usd-price.js::coins.llama.fi::fetchFirst": "B",+ "src/shared/usd-price.js::api.kraken.com::fetchFirst": "B",+ "src/solana/jupiter-swap.js::lite-api.jup.ag::fetchFirst": "B",+ "src/solana/jupiter-swap.js::tokens.jup.ag::fetchFirst": "B",+ "src/solana/jupiter-swap.js::raw.githubusercontent.com::fetchFirst": "B",+ "src/solana/sns.js::sns-api.bonfida.com__expr__::fetch": "D",+ "src/swap-jupiter.js::lite-api.jup.ag::fetch": "D",+ "workers/agent-sniper/intel/learn.js::frontend-api-v3.pump.fun::fetch": "D",+ "workers/agent-sniper/llm-judge.js::openrouter.ai::fetch": "D",+ "workers/okx-chat-bot/state.js::storage.googleapis.com::fetch": "D"+ }+}diff --git a/docs/resilience.md b/docs/resilience.mdnew file mode 100644index 000000000..04896c43a--- /dev/null+++ b/docs/resilience.md@@ -0,0 +1,144 @@+<!-- GENERATED by scripts/audit-upstreams.mjs. Run `npm run audit:upstreams -- --map`. -->+# Upstream resilience map++Every third-party service this platform calls, and what happens to a user when+that service is down. Generated from the source by an AST pass, so it cannot+drift from the code the way a hand-written list does.++## How a call site is graded++| Grade | Meaning |+|---|---|+| A | Bounded, and survives the upstream being down (a second source, plus a remembered value or a retry) |+| B | Bounded, with one way to survive: either another source or a remembered value |+| C | Bounded, retries or trips a breaker, but has no second source |+| D | Bounded only: a deadline and nothing behind it |+| F | Unbounded: one stalled socket can outlive the request that opened it |++A deadline is the floor rather than one grade among five, because without one+no other protection ever gets a turn.++## Totals++183 outbound call sites across 72 upstreams.++| A | B | C | D | F |+|---|---|---|---|---|+| 0 | 46 | 84 | 53 | 0 |++## Weakest upstreams++These carry at least one call site with no second source behind it. They are+the list to work down, worst first.++| Upstream | Call sites | Worst grade |+|---|---|---|+| `api.telegram.org` | 10 | D |+| `lite-api.jup.ag` | 9 | D |+| `api.dexscreener.com` | 8 | D |+| `api.github.com` | 7 | D |+| `api.coingecko.com` | 6 | D |+| `frontend-api-v3.pump.fun` | 6 | D |+| `openrouter.ai` | 5 | D |+| `api.geckoterminal.com` | 5 | D |+| `api.elevenlabs.io` | 4 | D |+| `api.pinata.cloud` | 4 | D |+| `api.web3.storage` | 4 | D |+| `api.replicate.com` | 4 | D |+| `integrate.api.nvidia.com` | 2 | D |+| `api.openai.com` | 2 | D |+| `auth.privy.io` | 2 | D |+| `ai.api.nvidia.com` | 2 | D |+| `api.sketchfab.com` | 2 | D |+| `storage.googleapis.com` | 2 | D |+| `api.nvcf.nvidia.com` | 2 | D |+| `sns-api.bonfida.com__expr__` | 2 | D |+| `api.anthropic.com` | 2 | D |+| `raw.githubusercontent.com` | 2 | D |+| `api.developer.coinbase.com` | 1 | D |+| `bigquery.googleapis.com` | 1 | D |+| `api.indexnow.org` | 1 | D |++## Every upstream++| Upstream | Call sites | Worst grade | A | B | C | D | F |+|---|---|---|---|---|---|---|---|+| `api.telegram.org` | 10 | D | 0 | 0 | 7 | 3 | 0 |+| `lite-api.jup.ag` | 9 | D | 0 | 5 | 0 | 4 | 0 |+| `api.dexscreener.com` | 8 | D | 0 | 4 | 2 | 2 | 0 |+| `api.github.com` | 7 | D | 0 | 0 | 5 | 2 | 0 |+| `api.coingecko.com` | 6 | D | 0 | 5 | 0 | 1 | 0 |+| `frontend-api-v3.pump.fun` | 6 | D | 0 | 0 | 5 | 1 | 0 |+| `openrouter.ai` | 5 | D | 0 | 0 | 0 | 5 | 0 |+| `api.geckoterminal.com` | 5 | D | 0 | 3 | 0 | 2 | 0 |+| `api.elevenlabs.io` | 4 | D | 0 | 0 | 2 | 2 | 0 |+| `api.pinata.cloud` | 4 | D | 0 | 0 | 3 | 1 | 0 |+| `api.web3.storage` | 4 | D | 0 | 0 | 3 | 1 | 0 |+| `api.replicate.com` | 4 | D | 0 | 0 | 2 | 2 | 0 |+| `integrate.api.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |+| `api.openai.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |+| `auth.privy.io` | 2 | D | 0 | 0 | 1 | 1 | 0 |+| `ai.api.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |+| `api.sketchfab.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |+| `storage.googleapis.com` | 2 | D | 0 | 0 | 1 | 1 | 0 |+| `api.nvcf.nvidia.com` | 2 | D | 0 | 0 | 0 | 2 | 0 |+| `sns-api.bonfida.com__expr__` | 2 | D | 0 | 0 | 1 | 1 | 0 |+| `api.anthropic.com` | 2 | D | 0 | 0 | 1 | 1 | 0 |+| `raw.githubusercontent.com` | 2 | D | 0 | 1 | 0 | 1 | 0 |+| `api.developer.coinbase.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `bigquery.googleapis.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `api.indexnow.org` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `api.tokens.xyz` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `speech.platform.bing.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `api.upstash.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `qstash.upstash.io` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `api.resend.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `publish.twitter.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `api.exchange.coinbase.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `api.coinpaprika.com` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `kolscan.io` | 1 | D | 0 | 0 | 0 | 1 | 0 |+| `api.twitter.com` | 8 | C | 0 | 0 | 8 | 0 | 0 |+| `api.llama.fi` | 5 | C | 0 | 0 | 5 | 0 | 0 |+| `api.x.com` | 4 | C | 0 | 0 | 4 | 0 | 0 |+| `api.hyper3d.com` | 3 | C | 0 | 0 | 3 | 0 | 0 |+| `api.tripo3d.ai` | 3 | C | 0 | 0 | 3 | 0 | 0 |+| `api.alternative.me` | 3 | C | 0 | 0 | 3 | 0 | 0 |+| `yields.llama.fi` | 3 | C | 0 | 0 | 3 | 0 | 0 |+| `api.meshy.ai__expr__` | 2 | C | 0 | 0 | 2 | 0 | 0 |+| `stablecoins.llama.fi` | 2 | C | 0 | 0 | 2 | 0 | 0 |+| `api.duckduckgo.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `api.blockchair.com__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `blockstream.info` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `metadata.google.internal` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `oauth2.googleapis.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `api.github.com__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `sns-api.bonfida.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `livestream-api.pump.fun__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `pump.fun` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `api.rugcheck.xyz` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `api.stability.ai` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `github.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `pro-api.coinmarketcap.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `api.nft.storage` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `swap-api.pump.fun` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `api.helius.xyz` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `api.llama.fi__expr__` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `www.deribit.com` | 1 | C | 0 | 0 | 1 | 0 | 0 |+| `coins.llama.fi` | 6 | B | 0 | 6 | 0 | 0 | 0 |+| `esm.sh` | 5 | B | 0 | 5 | 0 | 0 | 0 |+| `api.kraken.com` | 4 | B | 0 | 4 | 0 | 0 | 0 |+| `api.coinbase.com` | 4 | B | 0 | 4 | 0 | 0 | 0 |+| `nominatim.openstreetmap.org` | 2 | B | 0 | 2 | 0 | 0 | 0 |+| `photon.komoot.io` | 2 | B | 0 | 2 | 0 | 0 | 0 |+| `api.hyperliquid.xyz` | 1 | B | 0 | 1 | 0 | 0 | 0 |+| `api.diadata.org` | 1 | B | 0 | 1 | 0 | 0 | 0 |+| `api-pub.bitfinex.com` | 1 | B | 0 | 1 | 0 | 0 | 0 |+| `api.bigdatacloud.net` | 1 | B | 0 | 1 | 0 | 0 | 0 |+| `tokens.jup.ag` | 1 | B | 0 | 1 | 0 | 0 | 0 |++## Keeping this true++`npm run audit:upstreams` fails when a call site regresses below the grade+recorded in `data/upstream-baseline.json`, or when a new unbounded call appears.+Improving a call site lowers the baseline automatically; raising it back needs an+explicit `--accept`, which is a reviewable line in the diff.diff --git a/scripts/resilience/README.md b/scripts/resilience/README.mdnew file mode 100644index 000000000..19ad30791--- /dev/null+++ b/scripts/resilience/README.md@@ -0,0 +1,126 @@+# Upstream resilience toolkit++Three parts, each answering a question the previous one cannot.++| Part | Question it answers | Entry point |+|---|---|---|+| [`analyze.mjs`](analyze.mjs) | Where do we call other people's services, and what protects each call? | `npm run audit:upstreams` |+| [`contracts.mjs`](contracts.mjs) | When a service is down, what is an endpoint allowed to say? | `tests/upstream-degradation.test.js` |+| The baseline | Can this get worse without anyone noticing? | `data/upstream-baseline.json` |++## Why this exists++Adding a fallback is easy. Knowing whether it made things better is not.++In one week this repo added deadlines, retries, provider ladders and last-good+caches across 147 modules, and shipped four bugs in the process. Every one came+from the same mistake: serving a remembered value on a path where a remembered+value is the wrong answer.++- The post-402 payment retry re-signed the exact blockhash the facilitator had+ just refused. Same payer, same payee, same amount, same hash: byte-identical+ bytes, refused again for the same reason.+- `/api/v1/token/security` assembled a live `200` out of remembered on-chain+ state. Mint authority and holder concentration *are* the verdict, so that was+ a clean bill of health for a chain nobody could read.+- An access gate answered from a cached verdict.+- `/api/ca2x402/resolve` told callers a real token did not exist, because on a+ cold instance the remembered payload it was supposed to fall back to did not+ exist yet.++All four passed review. All four had fallbacks. What none of them had was a+written answer to a different question, and that question is what this toolkit+makes mechanical.++## Part 1: the audit++`npm run audit:upstreams` parses every runtime module and records, per call+site, which of five protections are present: `deadline`, `retry`, `failover`,+`lastGood`, `breaker`.++It is an AST pass, not a grep, because the property being measured is not+visible on the line the call is written on. The options object may be built+three statements earlier, the deadline may arrive through a wrapper, and a+`signal,` shorthand looks nothing like `signal:`. An earlier regex sweep of this+same repo reported one unguarded call and was wrong in both directions: it+missed real findings and invented 507 others, nearly all of them same-origin+calls it could not tell from third-party ones.++Two passes run. The first collects every module-level string constant, because+base URLs here are almost always `export const PUMP_FRONTEND_BASE = '...'` in+one module and imported everywhere else; without it the majority of call sites+cannot be attributed to the host they actually talk to. The second grades each+call site with those constants resolved.++Grades:++| Grade | Meaning |+|---|---|+| A | Bounded, and survives the upstream being down |+| B | Bounded, with one way to survive |+| C | Bounded, retries or trips a breaker, but has no second source |+| D | Bounded only |+| F | Unbounded: one stalled socket can outlive the request that opened it |++A deadline is the floor rather than one grade among five, because without one no+other protection ever gets a turn.++This complements [`scripts/check-fetch-timeouts.mjs`](../check-fetch-timeouts.mjs),+which enforces that floor as a binary rule. The audit measures everything above+it and is the tool to reach for when the question is "what happens to users when+this provider goes down", not "did someone forget a signal".++`--map` regenerates [`docs/resilience.md`](../../docs/resilience.md).+`--json` emits the full table for other tooling.++## Part 2: degradation contracts++Every endpoint can declare what it is allowed to say during a total outage:++```js+import { CONTRACT } from '../scripts/resilience/contracts.mjs';++CONTRACT.MAY_SERVE_STALE // a remembered value beats an error, and it is marked as remembered+CONTRACT.MUST_REFUSE // no honest answer exists without a live read+CONTRACT.MUST_NOT_SERVE_STALE // acting on a stale answer costs money or grants access+```++`tests/upstream-degradation.test.js` then makes it true rather than taking it on+trust: it replaces `fetch` with one that fails the way a dead host fails, calls+the real handler, and judges the real response. Two failure shapes are injected,+because a refused connection and a socket that accepts and never answers are+different bugs and have caught different ones here.++`MAY_SERVE_STALE` requires the response to *say* it is stale (`stale: true`, an+`as_of` stamp, or an `x-*-stale` header). Degrading silently is how a remembered+answer gets mistaken for a current one, so an unmarked `200` fails the contract+even though it looks like a success.++Adding an endpoint is one entry in the `ENDPOINTS` table. The harness found a+real bug on its first run: `/api/ca2x402/resolve` answered `404 token_not_found`+on a cold instance during an outage, denying tokens that plainly existed.++## Part 3: the ratchet++`data/upstream-baseline.json` records the grade of every known call site.++- A **new unbounded call** fails the audit.+- A **call site that gets worse** fails the audit, naming the file, the host and+ the transition (`D -> F`).+- A call site that gets **better** lowers the baseline automatically, so nobody+ has to remember to re-record a fix and the floor only ever rises.+- Raising the floor back needs `--accept`, which is one reviewable line in a diff+ rather than a silent drift.++This shape matters because the tail is long and the fix is not always today's+job. A threshold ("no more than N unguarded calls") gets rounded up until it+means nothing. A baseline lets the existing tail be paid down at its own pace+while making it impossible to add to it by accident.++## Adding a new shared helper++The analyzer resolves protections by helper name. A new wrapper needs one entry+in `GUARDS` in [`analyze.mjs`](analyze.mjs) naming what it provides by+construction, otherwise every call site using it will be graded as if it were a+bare `fetch`. That is the toolkit's one maintenance cost, and it is deliberate:+it is also the list of blessed ways to call an upstream.