9.5 KiB
Cred402 — Production Plan & System of Record
Cred402 is the Casper-rooted credit bureau for autonomous AI agents. Agents earn through x402, prove their work through on-chain receipts and RWA evidence, build reputation, and borrow working capital from DeFi pools — across every chain, with Casper as the canonical root of identity, reputation, receipts, and credit policy.
This document is the production plan: what the full product is, what is built, how it is operated, and the sequence to mainnet. It is the index that ties the design to running code.
The protocol was seeded by a series of design notes. Their substance now lives in the polished docs under
docs/(architecture, risk model, x402 flow, protocol/, whitepaper/) plus the real-integration phase docsdocs/p8.md(Casper Testnet),docs/p9.md(x402 + data + MCP), anddocs/p10.md(RealFi + cross-chain). Inline(pN §X)citations in source comments are provenance markers pointing back at those original notes.
1. Product surface (what a customer touches)
| Surface | Audience | Status |
|---|---|---|
Console (frontend/) |
LPs, operators, analysts | ✅ 19 tabs: Analytics, Onboard, Agents, RWA Jobs, Receipts, Credit Pool, Marketplace, Discovery, x402, Risk (incl. credit what-if simulator), Disputes, Governance, Multichain, RealFi, Trust, Compliance, Explorer, Developer, Ops + notification bell + Casper Wallet connect (real extension provider) |
Public REST API /v1 |
integrators | ✅ auth (scoped API keys), rate limiting, validation, idempotency, envelope; OpenAPI 3.1 (packages/openapi/cred402.v1.yaml) |
GraphQL API /graphql |
dashboards / typed clients | ✅ lib/graphql/ — typed query surface over the same read models |
MCP server (mcp/) |
AI agents | ✅ 54 tools — zero-dep stdio (mcp/server.ts) and official @modelcontextprotocol/sdk transport (mcp/server_sdk.ts, p9) for Claude Desktop / MCP Inspector |
| SDKs | developers | ✅ TypeScript (sdk/), Python (sdk/python/), Go (sdk/go/), Rust (sdk/rust/) |
| CLIs | developers / ops | ✅ cred402 in TS (cli/), Go, Rust |
| x402 paid endpoints | agent-to-agent commerce | ✅ real 402 → sign → 200 flow with real EIP-712 typed-data digests (@casper-ecosystem/casper-eip-712); optional real casper-x402 facilitator settlement (api/paid_evidence_server, lib/x402); Algorand USDC credit-score endpoint with Bazaar discovery, non-cacheable paid responses, public readiness status and integrity-digested release evidence |
| Risk service API | underwriting | ✅ Python risk-engine (services/risk-engine/) — PD model + fraud graph |
2. Protocol core (the canonical layer — Casper)
Implemented as 14 Odra (Rust→Wasm) contracts in contracts/, each with a
faithful in-memory mirror in lib/ledger/contracts/ (the transport seam):
AgentRegistry · AgentPassport · X402ReceiptRegistry · RWAAssetRegistry · RWAEvidenceRegistry · ReputationEngine · AgentCreditPool · RiskPolicyManager · DisputeCourt · SlashingVault · Governance · FiatReceiptRegistry · OperatorVerificationRegistry · RealFiAttestationRegistry.
Cross-chain (p3): standards (CAID/ABE/URE/UAID/EAE/CAN, crosschain/standards),
satellite contracts (contracts/{evm,solana,cosmos,move,bitcoin}), the
Casper-root relayer + Merkle proof-service (crosschain/), and the trust ladder
(crosschain/trust-ladder: multi-relayer + finality + proof-types).
3. Off-chain services
| Service | Lang | Path | Role |
|---|---|---|---|
| API gateway | TS | api/, lib/gateway/ |
/v1 + console /api + GraphQL; auth, rate limit, validation, idempotency, webhooks, structured logs |
| Durable persistence | TS | lib/gateway/persistence.ts |
append-only NDJSON event journal (system of record) + atomic snapshots |
| Event indexer | Go | services/event-indexer/ |
replays the journal → agent/pool/dispute projections (checkpointed) |
| Risk engine | Python | services/risk-engine/ |
logistic PD credit model + Tarjan-SCC fraud graph; advisory inputs to RiskPolicyManager |
| Compliance | TS | lib/compliance/ |
sanctions + jurisdiction + KYB + data-retention; gates underwriting |
| RealFi bridge | TS | lib/services/realfi_bridge.ts, lib/realfi/{stripe,plaid}.ts |
real Stripe test-mode webhooks (HMAC-verified) + Plaid sandbox → privacy-preserving on-chain envelopes (p10) |
| Casper transport | TS | lib/casper/ |
JSON-RPC reads + byte-exact casper-js-sdk deploy signer + WASM installer (p8) + Sidecar SSE event feed (casper-network/casper-sidecar); CRED402_CHAIN=sim|testnet switch |
4. Security model
- Secrets: env-driven, validated and fail-fast at boot (
lib/gateway/config.ts). The API refuses to start on testnet/mainnet without required secrets. - AuthN/Z: scoped API keys (read/write/admin), SHA-256 hashed at rest, constant-time verify (
lib/gateway/api_keys.ts). - Abuse: per-identity token-bucket rate limiting; idempotency keys on mutations.
- Boundary validation: every request body parsed by a typed schema (
lib/gateway/validation.ts) — no blind casts. - Privacy: no PII on-chain (p6) — fiat/identity data committed only as hashes (
lib/realfi/envelopes.ts); logs redact secret-like fields. - Webhooks: HMAC-signed with timestamped, replay-resistant signatures.
- On-chain invariants: replay protection on receipts/CANs, global exposure cap (cross-chain over-borrow guard), dispute-gated credit, slashing.
- Cross-chain trust: launch at Stage 1 (trusted relayer w/ public logs), designed through Stage 4 (zk) — proof types honestly reject unsupported verification.
5. Data & observability
- System of record: the event journal (NDJSON), consumed by the Go indexer into projections; a real DB writer implements the same
sink.Sinkinterface. - Logging: structured JSON, level-gated, request-scoped (
lib/gateway/logger.ts). - Health:
GET /v1/health(liveness/readiness);npm run casper:healthprobes the chain node. - Analytics: live read model (
lib/services/analytics.ts) — TVL, utilization, throughput, leaderboard, credit timeline.
6. Deployment
infra/: multi-stage non-root Dockerfile (healthchecked), docker-compose.yml
(api + indexer + postgres), Helm chart (helm lint clean), and a cloud-agnostic
Terraform module. All runtime config is environment-driven; state persists to a
CRED402_DATA_DIR volume.
7. Launch sequence (testnet → mainnet)
- Deploy contracts to Casper Testnet — ✅ real path built (p8):
scripts/deploy_testnet.tsinstalls the Odra WASM via the byte-exactcasper-js-sdksigner whenCRED402_CHAIN=testnet+ key are set, else prints the casper-client plan. Live reads verified againstnode.testnet.casper.network(Casper 2.0). Build WASM, fund a key, run it. - Stand up the indexer against the live journal / CSPR.cloud sidecar.
- Enable auth + webhooks; mint scoped keys; register integrator webhooks.
- Wire the risk engine as an advisory input to RiskPolicyManager (it already scores live agents).
- Compliance go-live — load the real sanctions/jurisdiction lists; require KYB for credit above a threshold.
- Cross-chain: Stage 1 trusted relayer → Stage 2 multi-relayer with bonds.
- Governance: timelock + launch multisig before mainnet credit; legal/operating model per the RealFi compliance boundary (
docs/p10.md) before real fiat flows.
8. Open seams (honest)
- Casper deploy signer — ✅ closed in p8: byte-exact
casper-js-sdksigner + WASM installer (lib/casper/sdk_signer.ts,install.ts), offline-tested intest/casper_sdk.test.ts. Remaining live-only step is funding a Testnet key and resolving installed contract hashes from account named keys. - DB-backed indexer sink — the Go
sink.Sinkinterface is ready; a Postgres writer is packaging. - Go relayer binaries — the relay→prove→anchor path is implemented and tested in TS; Go ports are deployment packaging, not new logic.
9. Design lineage → code coverage map
The protocol was seeded by design notes p1–p7 (now removed from the tree; their
substance is distilled into the polished docs/ and this file). p8–p10 are the
live "make it real" phase docs that replace simulation/mocks with real rails.
| Theme (origin) | Where it lives |
|---|---|
| the idea + demo loop (p1) | npm run demo, agents/, api/ |
| production protocol + services (p2) | contracts/, lib/, api/, mcp/, frontend/, lib/gateway/, lib/compliance/, services/, packages/openapi/ |
| omnichain, Casper-rooted (p3) | crosschain/, contracts/{evm,solana,cosmos,move,bitcoin}, packages/chain-adapters/ |
| fraud, marketplace, economics, trust ladder (p4) | lib/services/fraud_service.ts, marketplace.ts, lib/core/economics.ts, crosschain/trust-ladder/ |
| reason codes, Agent Finance (p5) | lib/core/reason_codes.ts, the credit decision path |
| RealFi Bridge (p6) | lib/realfi/, lib/services/realfi_bridge.ts, RealFi registries + EVM mirror |
| direct-use stack, attribution (p7) | THIRD_PARTY.md, npm run ship:check |
Real Casper Testnet (docs/p8.md) |
lib/casper/, scripts/deploy_testnet.ts, deploys.testnet.json |
Real x402 + data + MCP (docs/p9.md) |
lib/x402/facilitator.ts, api/rwa_data/, official MCP SDK in mcp/ |
Real RealFi + cross-chain (docs/p10.md) |
lib/services/realfi_bridge.ts, Stripe/Plaid adapters, Base Sepolia deploy + relayer |
See ROADMAP.md for the per-feature build ledger.