# shane2512/quota architecture

> Architecture diagram of the GitHub repository shane2512/quota, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shane2512/quota
- Repository: https://github.com/shane2512/quota

## Overview

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: [`packages/client/src/index.ts`](https://github.com/shane2512/quota/blob/main/packages/client/src/index.ts) (Request proof client), [`apps/demo-mcp/src/server.ts`](https://github.com/shane2512/quota/blob/main/apps/demo-mcp/src/server.ts) (Protected MCP server), [`packages/server/src/index.ts`](https://github.com/shane2512/quota/blob/main/packages/server/src/index.ts) (Quota verifier), [`apps/scout/src/main.ts`](https://github.com/shane2512/quota/blob/main/apps/scout/src/main.ts) (Scout CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and proofs"]
  node_registry["Quota registry contract"]
  node_core_hash["Hashing and commitments<br/>[hash.ts]"]
  node_merkle_tree["Sparse Merkle tree<br/>[tree.ts]"]
  node_proof_format["Proof wire format<br/>[proof.ts]"]
  node_payload["Payload hashing<br/>[payload.ts]"]
  node_registry_reads["Registry reads<br/>[registry.ts]"]
  node_artifacts["ZK artifacts<br/>[artifacts.ts]"]
  node_client["Request proof client<br/>[index.ts]"]
  node_client_helpers["Client helpers<br/>[helpers.ts]"]
end

subgraph group_middleware["Service verification"]
  node_verifier["Quota verifier<br/>[index.ts]"]
  node_http_middleware["HTTP and MCP middleware<br/>[http.ts]"]
  node_nullifier_db[("SQLite nullifier store<br/>[sqlite.ts]")]
end

subgraph group_operations["Wallets and slashing"]
  node_enrollment["Agent enrollment<br/>[enroll.ts]"]
  node_slasher["Slash orchestration<br/>[slasher.ts]"]
  node_slash_submit["Commit–reveal submitter<br/>[submit.ts]"]
  node_slash_wallet["Wallet adapter<br/>[wallet.ts]"]
  node_privy_wallet["Privy agent wallet<br/>[privy.ts]"]
  node_dynamic_wallet["Dynamic service wallet<br/>[dynamic.ts]"]
  node_dynamic_sdk["Dynamic SDK adapter<br/>[dynamic-sdk.ts]"]
end

subgraph group_apps["Agent applications"]
  node_mcp_server["Protected MCP server<br/>[server.ts]"]
  node_feed["Public status feed<br/>[feed.ts]"]
  node_demo_agent["Demo agent<br/>[agent.ts]"]
  node_scout_cli["Scout CLI<br/>[main.ts]"]
  node_scout_loop["Research planner loop<br/>[scout.ts]"]
  node_llm["LLM planner<br/>[llm.ts]"]
  node_scout_tools["Quota-aware tools<br/>[tools.ts]"]
  node_scout_account["Scout account<br/>[account.ts]"]
  node_scout_script["Scripted planner<br/>[script.ts]"]
end

subgraph group_web["Web consoles"]
  node_web_home["Landing page<br/>[page.tsx]"]
  node_operator_console["Operator console<br/>[page.tsx]"]
end

node_operator(("Human operator"))
node_agent(("AI agent"))
node_llm_service["OpenAI-compatible model"]
node_mcp_services["Protected MCP services"]

node_operator -->|"enrolls identity"| node_enrollment
node_enrollment -->|"stakes and registers"| node_registry
node_agent -->|"requests proofs"| node_client
node_client -->|"derives commitments"| node_core_hash
node_client -->|"encodes proofs"| node_proof_format
node_client -.->|"uses proof artifacts"| node_artifacts
node_core_hash -->|"sets tree depth"| node_merkle_tree
node_registry_reads -->|"tracks registry roots"| node_merkle_tree
node_client -->|"uses helpers"| node_client_helpers
node_http_middleware -->|"verifies requests"| node_verifier
node_verifier -->|"checks payload hash"| node_payload
node_verifier -->|"checks known roots"| node_registry
node_verifier -.->|"records nullifiers"| node_nullifier_db
node_mcp_server -->|"configures verifier"| node_verifier
node_mcp_server -->|"protects HTTP route"| node_http_middleware
node_mcp_server -->|"publishes results"| node_feed
node_mcp_server -->|"handles violations"| node_slasher
node_demo_agent -->|"calls MCP tools"| node_mcp_server
node_scout_cli -->|"loads account"| node_scout_account
node_scout_cli -->|"runs research"| node_scout_loop
node_scout_cli -.->|"loads wallet"| node_privy_wallet
node_scout_cli -->|"configures planner"| node_llm
node_scout_loop -->|"requests next step"| node_llm
node_scout_loop -->|"dispatches tool calls"| node_scout_tools
node_scout_loop -.->|"supports scripted plan"| node_scout_script
node_scout_tools -->|"checks quota and stakes"| node_scout_account
node_scout_tools -->|"calls protected tools"| node_mcp_services
node_scout_account -->|"creates request proofs"| node_client
node_slasher -->|"submits slash"| node_slash_submit
node_slash_submit -->|"signs transactions"| node_slash_wallet
node_slash_submit -->|"commits and reveals"| node_registry
node_privy_wallet -->|"signs agent messages"| node_client
node_dynamic_wallet -->|"uses SDK adapter"| node_dynamic_sdk
node_dynamic_wallet -->|"adapts slasher wallet"| node_slash_wallet
node_llm -->|"sends tool requests"| node_llm_service
node_web_home -.->|"links operator view"| node_operator_console

click node_core_hash "https://github.com/shane2512/quota/blob/main/packages/core/src/hash.ts"
click node_merkle_tree "https://github.com/shane2512/quota/blob/main/packages/core/src/tree.ts"
click node_proof_format "https://github.com/shane2512/quota/blob/main/packages/core/src/proof.ts"
click node_payload "https://github.com/shane2512/quota/blob/main/packages/core/src/payload.ts"
click node_registry_reads "https://github.com/shane2512/quota/blob/main/packages/core/src/registry.ts"
click node_artifacts "https://github.com/shane2512/quota/blob/main/packages/core/src/artifacts.ts"
click node_client "https://github.com/shane2512/quota/blob/main/packages/client/src/index.ts"
click node_client_helpers "https://github.com/shane2512/quota/blob/main/packages/client/src/helpers.ts"
click node_verifier "https://github.com/shane2512/quota/blob/main/packages/server/src/index.ts"
click node_http_middleware "https://github.com/shane2512/quota/blob/main/packages/server/src/http.ts"
click node_nullifier_db "https://github.com/shane2512/quota/blob/main/packages/server/src/sqlite.ts"
click node_mcp_server "https://github.com/shane2512/quota/blob/main/apps/demo-mcp/src/server.ts"
click node_feed "https://github.com/shane2512/quota/blob/main/apps/demo-mcp/src/feed.ts"
click node_demo_agent "https://github.com/shane2512/quota/blob/main/apps/demo-mcp/src/agent.ts"
click node_scout_cli "https://github.com/shane2512/quota/blob/main/apps/scout/src/main.ts"
click node_scout_loop "https://github.com/shane2512/quota/blob/main/apps/scout/src/scout.ts"
click node_llm "https://github.com/shane2512/quota/blob/main/apps/scout/src/llm.ts"
click node_scout_tools "https://github.com/shane2512/quota/blob/main/apps/scout/src/tools.ts"
click node_scout_account "https://github.com/shane2512/quota/blob/main/apps/scout/src/account.ts"
click node_scout_script "https://github.com/shane2512/quota/blob/main/apps/scout/src/script.ts"
click node_enrollment "https://github.com/shane2512/quota/blob/main/packages/devtools/src/enroll.ts"
click node_slasher "https://github.com/shane2512/quota/blob/main/packages/slasher/src/slasher.ts"
click node_slash_submit "https://github.com/shane2512/quota/blob/main/packages/slasher/src/submit.ts"
click node_slash_wallet "https://github.com/shane2512/quota/blob/main/packages/slasher/src/wallet.ts"
click node_privy_wallet "https://github.com/shane2512/quota/blob/main/packages/wallets/src/privy.ts"
click node_dynamic_wallet "https://github.com/shane2512/quota/blob/main/packages/wallets/src/dynamic.ts"
click node_dynamic_sdk "https://github.com/shane2512/quota/blob/main/packages/wallets/src/dynamic-sdk.ts"
click node_web_home "https://github.com/shane2512/quota/blob/main/apps/web/app/page.tsx"
click node_operator_console "https://github.com/shane2512/quota/blob/main/apps/web/app/operator/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registry,node_core_hash,node_merkle_tree,node_proof_format,node_payload,node_registry_reads,node_artifacts,node_client,node_client_helpers toneBlue
class node_verifier,node_http_middleware,node_nullifier_db toneAmber
class node_enrollment,node_slasher,node_slash_submit,node_slash_wallet,node_privy_wallet,node_dynamic_wallet,node_dynamic_sdk toneMint
class node_mcp_server,node_feed,node_demo_agent,node_scout_cli,node_scout_loop,node_llm,node_scout_tools,node_scout_account,node_scout_script toneRose
class node_web_home,node_operator_console,node_operator,node_agent,node_llm_service,node_mcp_services toneIndigo
```

## Components

### Identity and proofs

- **Quota registry contract**
- [Hashing and commitments](https://github.com/shane2512/quota/blob/main/packages/core/src/hash.ts): `packages/core/src/hash.ts`
- [Sparse Merkle tree](https://github.com/shane2512/quota/blob/main/packages/core/src/tree.ts): `packages/core/src/tree.ts`
- [Proof wire format](https://github.com/shane2512/quota/blob/main/packages/core/src/proof.ts): `packages/core/src/proof.ts`
- [Payload hashing](https://github.com/shane2512/quota/blob/main/packages/core/src/payload.ts): `packages/core/src/payload.ts`
- [Registry reads](https://github.com/shane2512/quota/blob/main/packages/core/src/registry.ts): `packages/core/src/registry.ts`
- [ZK artifacts](https://github.com/shane2512/quota/blob/main/packages/core/src/artifacts.ts): `packages/core/src/artifacts.ts`
- [Request proof client](https://github.com/shane2512/quota/blob/main/packages/client/src/index.ts): `packages/client/src/index.ts`
- [Client helpers](https://github.com/shane2512/quota/blob/main/packages/client/src/helpers.ts): `packages/client/src/helpers.ts`

### Service verification

- [Quota verifier](https://github.com/shane2512/quota/blob/main/packages/server/src/index.ts): `packages/server/src/index.ts`
- [HTTP and MCP middleware](https://github.com/shane2512/quota/blob/main/packages/server/src/http.ts): `packages/server/src/http.ts`
- [SQLite nullifier store](https://github.com/shane2512/quota/blob/main/packages/server/src/sqlite.ts): `packages/server/src/sqlite.ts`

### Wallets and slashing

- [Agent enrollment](https://github.com/shane2512/quota/blob/main/packages/devtools/src/enroll.ts): `packages/devtools/src/enroll.ts`
- [Slash orchestration](https://github.com/shane2512/quota/blob/main/packages/slasher/src/slasher.ts): `packages/slasher/src/slasher.ts`
- [Commit–reveal submitter](https://github.com/shane2512/quota/blob/main/packages/slasher/src/submit.ts): `packages/slasher/src/submit.ts`
- [Wallet adapter](https://github.com/shane2512/quota/blob/main/packages/slasher/src/wallet.ts): `packages/slasher/src/wallet.ts`
- [Privy agent wallet](https://github.com/shane2512/quota/blob/main/packages/wallets/src/privy.ts): `packages/wallets/src/privy.ts`
- [Dynamic service wallet](https://github.com/shane2512/quota/blob/main/packages/wallets/src/dynamic.ts): `packages/wallets/src/dynamic.ts`
- [Dynamic SDK adapter](https://github.com/shane2512/quota/blob/main/packages/wallets/src/dynamic-sdk.ts): `packages/wallets/src/dynamic-sdk.ts`

### Agent applications

- [Protected MCP server](https://github.com/shane2512/quota/blob/main/apps/demo-mcp/src/server.ts): `apps/demo-mcp/src/server.ts`
- [Public status feed](https://github.com/shane2512/quota/blob/main/apps/demo-mcp/src/feed.ts): `apps/demo-mcp/src/feed.ts`
- [Demo agent](https://github.com/shane2512/quota/blob/main/apps/demo-mcp/src/agent.ts): `apps/demo-mcp/src/agent.ts`
- [Scout CLI](https://github.com/shane2512/quota/blob/main/apps/scout/src/main.ts): `apps/scout/src/main.ts`
- [Research planner loop](https://github.com/shane2512/quota/blob/main/apps/scout/src/scout.ts): `apps/scout/src/scout.ts`
- [LLM planner](https://github.com/shane2512/quota/blob/main/apps/scout/src/llm.ts): `apps/scout/src/llm.ts`
- [Quota-aware tools](https://github.com/shane2512/quota/blob/main/apps/scout/src/tools.ts): `apps/scout/src/tools.ts`
- [Scout account](https://github.com/shane2512/quota/blob/main/apps/scout/src/account.ts): `apps/scout/src/account.ts`
- [Scripted planner](https://github.com/shane2512/quota/blob/main/apps/scout/src/script.ts): `apps/scout/src/script.ts`

### Web consoles

- [Landing page](https://github.com/shane2512/quota/blob/main/apps/web/app/page.tsx): `apps/web/app/page.tsx`
- [Operator console](https://github.com/shane2512/quota/blob/main/apps/web/app/operator/page.tsx): `apps/web/app/operator/page.tsx`

### Other components

- **Human operator**
- **AI agent**
- **OpenAI-compatible model**
- **Protected MCP services**

## Connections

- Human operator → Agent enrollment: enrolls identity (evidence: `README.md`)
- Agent enrollment → Quota registry contract: stakes and registers (evidence: `packages/devtools/src/enroll.ts`)
- AI agent → Request proof client: requests proofs (evidence: `README.md`)
- Request proof client → Hashing and commitments: derives commitments (evidence: `packages/client/src/index.ts`)
- Request proof client → Proof wire format: encodes proofs (evidence: `packages/client/src/index.ts`)
- Request proof client → ZK artifacts: uses proof artifacts
- Hashing and commitments → Sparse Merkle tree: sets tree depth (evidence: `packages/core/src/tree.ts`)
- Registry reads → Sparse Merkle tree: tracks registry roots (evidence: `packages/core/src/registry.ts`)
- Request proof client → Client helpers: uses helpers (evidence: `packages/client/src/helpers.ts`)
- HTTP and MCP middleware → Quota verifier: verifies requests (evidence: `packages/server/src/http.ts`)
- Quota verifier → Payload hashing: checks payload hash
- Quota verifier → Quota registry contract: checks known roots (evidence: `packages/server/src/index.ts`)
- Quota verifier → SQLite nullifier store: records nullifiers (evidence: `packages/server/src/sqlite.ts`)
- Protected MCP server → Quota verifier: configures verifier (evidence: `apps/demo-mcp/src/server.ts`)
- Protected MCP server → HTTP and MCP middleware: protects HTTP route (evidence: `apps/demo-mcp/src/server.ts`)
- Protected MCP server → Public status feed: publishes results (evidence: `apps/demo-mcp/src/server.ts`)
- Protected MCP server → Slash orchestration: handles violations (evidence: `README.md`)
- Demo agent → Protected MCP server: calls MCP tools (evidence: `README.md`)
- Scout CLI → Scout account: loads account (evidence: `apps/scout/src/main.ts`)
- Scout CLI → Research planner loop: runs research (evidence: `apps/scout/src/main.ts`)
- Scout CLI → Privy agent wallet: loads wallet
- Scout CLI → LLM planner: configures planner (evidence: `apps/scout/src/main.ts`)
- Research planner loop → LLM planner: requests next step (evidence: `apps/scout/src/scout.ts`)
- Research planner loop → Quota-aware tools: dispatches tool calls (evidence: `apps/scout/src/scout.ts`)
- Research planner loop → Scripted planner: supports scripted plan
- Quota-aware tools → Scout account: checks quota and stakes (evidence: `apps/scout/src/tools.ts`)
- Quota-aware tools → Protected MCP services: calls protected tools (evidence: `README.md`)
- Scout account → Request proof client: creates request proofs (evidence: `apps/scout/src/account.ts`)
- Slash orchestration → Commit–reveal submitter: submits slash (evidence: `packages/slasher/src/slasher.ts`)
- Commit–reveal submitter → Wallet adapter: signs transactions (evidence: `packages/slasher/src/submit.ts`)
- Commit–reveal submitter → Quota registry contract: commits and reveals (evidence: `packages/slasher/src/submit.ts`)
- Privy agent wallet → Request proof client: signs agent messages (evidence: `packages/wallets/src/privy.ts`)
- Dynamic service wallet → Dynamic SDK adapter: uses SDK adapter (evidence: `packages/wallets/src/dynamic.ts`)
- Dynamic service wallet → Wallet adapter: adapts slasher wallet (evidence: `packages/wallets/src/dynamic.ts`)
- LLM planner → OpenAI-compatible model: sends tool requests (evidence: `apps/scout/src/llm.ts`)
- Landing page → Operator console: links operator view
