cred402/docs/ACTIVATION_CHECKLIST.md
caelum0x 52c5c87a1f fix: point frontend config comment at the canonical Render service
frontend/src/lib/config.ts told operators to set VITE_API_BASE to
cred402.onrender.com (no -1) — a stale duplicate Render deploy still
running an old pre-Algorand build. Every other reference in the repo
(render.yaml, README, vercel.json rewrites, docs, examples) already
points at the canonical cred402-1.onrender.com. Fixed the comment and
documented the duplicate-service cleanup (owner-gated, no Render API
token available here) in docs/ACTIVATION_CHECKLIST.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-15 16:34:17 +03:00

142 lines
7.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Cred402 — Paid Endpoint Activation Checklist (owner-gated)
The one product Cred402 sells is the pay-per-call Credit Score API:
```
GET /v1/x402/credit-score/:agentId → 0.01 USDC over x402 on Algorand
```
On the current deploy this endpoint returns **HTTP 503 `algorand_x402_not_configured`**
because the paid path is deliberately **fail-closed**: it never becomes free and never
advertises a placeholder receiver. `GET /v1/x402/algorand/status` reports
`{"configured": false, ...}` until every required variable below is set. The pricing and
docs pages are now **status-aware** — they read that probe and render "activating" instead
of a live-price CTA while `configured:false`, so the site never sells a dead endpoint.
This checklist is the exact set of environment variables the owner must set (in the Render
service and mirrored in `.env`) to flip the probe to `configured:true`. Setting them is
owner-gated; nothing here deploys on its own.
**Known duplicate service (owner-gated cleanup):** the Render account currently has two
live services — the canonical one from this repo's [`render.yaml`](../render.yaml), reachable
at `https://cred402-1.onrender.com` (used by every doc, script, and the Vercel rewrites in
this repo), and a second, older zombie deploy at `https://cred402.onrender.com` (no `-1`)
still serving a stale pre-Algorand build (Casper-simulation `/api/state`, no `/v1/health` or
`/v1/x402/*` routes). There is no Render API token in this environment to delete it via API;
delete or suspend `cred402.onrender.com` from the Render dashboard to stop it answering
stale responses under a confusingly similar hostname.
---
## 1. Required to turn the paid endpoint ON (testnet)
| Variable | Required | Example / default | Notes |
|---|---|---|---|
| `CRED402_ALGORAND_PAY_TO` | **yes** | `<58-char Algorand address>` | USDC receiver. Must be a valid Algorand address, opted into the USDC ASA. No default — its absence is the current 503 reason. |
| `CRED402_ALGORAND_NETWORK` | no | `testnet` (default) | `testnet` \| `mainnet` \| a supported Algorand CAIP-2 id. |
| `CRED402_ALGORAND_PRICE_MICRO_USDC` | no | `10000` (0.01 USDC) | Positive integer, micro-USDC. |
| `CRED402_ALGORAND_FACILITATOR_URL` | no | `https://facilitator.goplausible.xyz` | HTTP(S), no credentials/query/fragment. HTTPS required on mainnet/prod. |
| `CRED402_ALGORAND_FACILITATOR_TIMEOUT_MS` | no | `10000` | Integer 1–60000. |
| `CRED402_ALGORAND_INDEXER_URL` | no | `https://testnet-idx.algonode.cloud` | Used to independently confirm USDC finality. HTTPS required on mainnet/prod. |
| `CRED402_ALGORAND_INDEXER_TOKEN` | no | *(empty)* | Only if your Indexer needs an API token. |
| `CRED402_ALGORAND_INDEXER_TIMEOUT_MS` | no | `5000` | Integer 250–30000. |
| `CRED402_ALGORAND_MIN_FINALITY_ROUNDS` | no | `4` | Integer 1–1000. |
| `CRED402_ALGORAND_MISSING_TX_THRESHOLD` | no | `3` | Integer 2–100. |
| `CRED402_ALGORAND_RECONCILE_INTERVAL_MS` | no | `15000` | Integer 1000–3600000. |
| `CRED402_ALGORAND_MISSING_TX_GRACE_MS` | no | `120000` | Integer 30000–86400000. |
USDC ASA ids are selected automatically by network: testnet `10458941`, mainnet `31566704`.
**Minimum viable testnet activation** is a single variable:
```bash
export CRED402_ALGORAND_PAY_TO=<funded, USDC-opted-in testnet address>
# defaults cover network=testnet, price=10000, GoPlausible facilitator, algonode indexer
```
Then verify:
```bash
curl -sS https://cred402-1.onrender.com/v1/x402/algorand/status # → "configured": true
npm run x402:algorand:check # scripted readiness probe
```
When `configured:true`, `/pricing` and `/docs` automatically switch to the live state
(testnet banner + real price/network/receiver pulled from the probe).
---
## 2. Durable persistence (disqualifying if skipped)
The ledger, API keys, rate-limit buckets, and x402 payment-replay barrier are **in-memory
per instance**. On Render free tier the instance sleeps/restarts, so without a data dir a
credit bureau forgets its entire history — unacceptable for a credit product.
| Variable | Required | Example | Notes |
|---|---|---|---|
| `CRED402_DATA_DIR` | **strongly** (required on mainnet/prod) | `/var/data` | Persists the append-only ledger journal, durable external-receipt proofs, and the Algorand payment-attempt store (exactly-once replay protection). |
On Render, back this with a **persistent disk** mounted at the same path (not the ephemeral
container filesystem). `loadAlgorandX402Config` refuses to enable the paid path on
mainnet/prod unless `CRED402_DATA_DIR` is set, precisely to prevent replay-protection loss.
Verify persistence survives a restart:
```bash
# 1. record an external receipt / run a paid attempt
# 2. restart the service
# 3. GET the same /v1/x402/external-receipts/<id> and /api/state — history is still present
```
---
## 3. Mainnet (real USDC) — extra gates
Mainnet is intentionally hard to enable by accident. All of the following are required
**together** or the endpoint stays 503:
| Variable | Value |
|---|---|
| `CRED402_ALGORAND_NETWORK` | `mainnet` |
| `CRED402_ENV` | `mainnet` (must match the network) |
| `CRED402_ALGORAND_MAINNET_RELEASE_ACK` | `I_ACKNOWLEDGE_REAL_USDC_MAINNET_PAYMENTS` |
| `CRED402_PUBLIC_URL` | pinned **HTTPS** origin (e.g. `https://cred402-1.onrender.com`) |
| `CRED402_DATA_DIR` | set (durable disk) |
| facilitator + indexer URLs | must be **HTTPS** |
Mainnet is also the Global x402 Challenge environment. Keep the receiver address stable
once set — discovery, dashboards, receipts, and leaderboard rankings all key on it — and
verify attribution after the first payment with `npm run x402:algorand:challenge-check`.
Submission requirements and the ordered activation runbook:
[`X402_GLOBAL_CHALLENGE.md`](./X402_GLOBAL_CHALLENGE.md).
`CRED402_PUBLIC_URL` is also recommended on testnet so Bazaar discovery + receipt URLs use
the canonical origin instead of a request host.
---
## 4. REST auth (separate from the x402 paid path)
REST reads under `/v1/*` are open and free by default in development
(`CRED402_ENV=development` → `authRequired=false`). To gate them, set:
| Variable | Notes |
|---|---|
| `CRED402_AUTH_REQUIRED` | `true` to require an API key on mutating routes. |
| `CRED402_ADMIN_API_KEY` | required whenever auth is enabled; used to mint scoped keys via `POST /v1/admin/api-keys`. |
| `CRED402_RATE_WINDOW_MS` / `CRED402_RATE_MAX` | per-key rate limit (default 60000ms / 120). |
Note: API keys and rate-limit buckets are in-memory today, so they also depend on
`CRED402_DATA_DIR` semantics for durability across restarts. The x402 paid endpoint does
**not** use API keys — the payment is the authorization.
---
## Quick reference — probe outcomes
| `/v1/x402/algorand/status` | Meaning | Site behavior |
|---|---|---|
| `configured: false` + `reason` | paid path off (missing/invalid config) | pricing/docs show "activating", CTA points to docs |
| `configured: true`, `release_tier: testnet` | live on testnet USDC | pricing/docs show live testnet banner + real price |
| `configured: true`, `release_tier: mainnet` | live on real USDC | pricing/docs show live mainnet state |