How shane2512/quota works
QUOTA is an anonymous, stake-backed rate-limit primitive for agent APIs and MCP tools. An operator enrolls and stakes an agent identity; the agent proves each request within its per-server epoch quota; middleware verifies the proof and tracks nullifiers; reuse can expose the agent secret and trigger a commit–reveal slash. The repo also includes reference MCP services, Scout’s quota-aware research workflow, wallet adapters, and web consoles. Contract sources are not present in the supplied tree, so contract behavior is shown only as a documented subsystem; some unsampled connections are omitted.
Main entry points: src/index.ts Request proof client · server.ts Protected MCP server · src/index.ts Quota verifier · main.ts Scout CLI
Components 34
Identity and proofs
- Quota registry contract
- Hashing and commitments
packages/core/src/hash.ts - Sparse Merkle tree
packages/core/src/tree.ts - Proof wire format
packages/core/src/proof.ts - Payload hashing
packages/core/src/payload.ts - Registry reads
packages/core/src/registry.ts - ZK artifacts
packages/core/src/artifacts.ts - Request proof client
packages/client/src/index.ts - Client helpers
packages/client/src/helpers.ts
Service verification
- Quota verifier
packages/server/src/index.ts - HTTP and MCP middleware
packages/server/src/http.ts - SQLite nullifier store
packages/server/src/sqlite.ts
Wallets and slashing
- Agent enrollment
packages/devtools/src/enroll.ts - Slash orchestration
packages/slasher/src/slasher.ts - Commit–reveal submitter
packages/slasher/src/submit.ts - Wallet adapter
packages/slasher/src/wallet.ts - Privy agent wallet
packages/wallets/src/privy.ts - Dynamic service wallet
packages/wallets/src/dynamic.ts - Dynamic SDK adapter
packages/wallets/src/dynamic-sdk.ts
Agent applications
- Protected MCP server
apps/demo-mcp/src/server.ts - Public status feed
apps/demo-mcp/src/feed.ts - Demo agent
apps/demo-mcp/src/agent.ts - Scout CLI
apps/scout/src/main.ts - Research planner loop
apps/scout/src/scout.ts - LLM planner
apps/scout/src/llm.ts - Quota-aware tools
apps/scout/src/tools.ts - Scout account
apps/scout/src/account.ts - Scripted planner
apps/scout/src/script.ts
Web consoles
- Landing page
apps/web/app/page.tsx - Operator console
apps/web/app/operator/page.tsx
Other components
- Human operator
- AI agent
- OpenAI-compatible model
- Protected MCP services
Connections 36
- Human operator → Agent enrollment: enrolls identity
README.md - Agent enrollment → Quota registry contract: stakes and registers
packages/devtools/src/enroll.ts - AI agent → Request proof client: requests proofs
README.md - Request proof client → Hashing and commitments: derives commitments
packages/client/src/index.ts - Request proof client → Proof wire format: encodes proofs
packages/client/src/index.ts - Request proof client → ZK artifacts: uses proof artifacts
- Hashing and commitments → Sparse Merkle tree: sets tree depth
packages/core/src/tree.ts - Registry reads → Sparse Merkle tree: tracks registry roots
packages/core/src/registry.ts - Request proof client → Client helpers: uses helpers
packages/client/src/helpers.ts - HTTP and MCP middleware → Quota verifier: verifies requests
packages/server/src/http.ts - Quota verifier → Payload hashing: checks payload hash
- Quota verifier → Quota registry contract: checks known roots
packages/server/src/index.ts - Quota verifier → SQLite nullifier store: records nullifiers
packages/server/src/sqlite.ts - Protected MCP server → Quota verifier: configures verifier
apps/demo-mcp/src/server.ts - Protected MCP server → HTTP and MCP middleware: protects HTTP route
apps/demo-mcp/src/server.ts - Protected MCP server → Public status feed: publishes results
apps/demo-mcp/src/server.ts - Protected MCP server → Slash orchestration: handles violations
README.md - Demo agent → Protected MCP server: calls MCP tools
README.md - Scout CLI → Scout account: loads account
apps/scout/src/main.ts - Scout CLI → Research planner loop: runs research
apps/scout/src/main.ts - Scout CLI → Privy agent wallet: loads wallet
- Scout CLI → LLM planner: configures planner
apps/scout/src/main.ts - Research planner loop → LLM planner: requests next step
apps/scout/src/scout.ts - Research planner loop → Quota-aware tools: dispatches tool calls
apps/scout/src/scout.ts - Research planner loop → Scripted planner: supports scripted plan
- Quota-aware tools → Scout account: checks quota and stakes
apps/scout/src/tools.ts - Quota-aware tools → Protected MCP services: calls protected tools
README.md - Scout account → Request proof client: creates request proofs
apps/scout/src/account.ts - Slash orchestration → Commit–reveal submitter: submits slash
packages/slasher/src/slasher.ts - Commit–reveal submitter → Wallet adapter: signs transactions
packages/slasher/src/submit.ts - Commit–reveal submitter → Quota registry contract: commits and reveals
packages/slasher/src/submit.ts - Privy agent wallet → Request proof client: signs agent messages
packages/wallets/src/privy.ts - Dynamic service wallet → Dynamic SDK adapter: uses SDK adapter
packages/wallets/src/dynamic.ts - Dynamic service wallet → Wallet adapter: adapts slasher wallet
packages/wallets/src/dynamic.ts - LLM planner → OpenAI-compatible model: sends tool requests
apps/scout/src/llm.ts - Landing page → Operator console: links operator view