# the3rdweblabs/cosign architecture

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

- Interactive diagram: https://gitdiagram.com/the3rdweblabs/cosign
- Repository: https://github.com/the3rdweblabs/cosign

## Overview

#### Purpose and topology
Cosign is a BOT Chain payment-control system for autonomous agents. It separates policy/state on-chain, transaction facilitation and sponsorship off-chain, human approval in a browser console, and reusable client integrations. BOT Chain testnet (968) and mainnet (677) are selected through `BOT_NETWORK` and network-specific environment variables.

#### On-chain policy boundary
`AgentRegistry` maps agents to guardians and spending policy; `ConsentGateway` decides whether an action may auto-settle, must await guardian consent, or is rejected. The contracts hold policy/state rather than user funds. Deployment creates and wires both contracts.
- `contracts/src/AgentRegistry.sol`
- `contracts/src/ConsentGateway.sol`
- `contracts/script/Deploy.s.sol`

#### Facilitator: payment execution boundary
The Node/TypeScript facilitator is the operational payment service. It adapts x402 payment requests to BOT Chain execution, assesses sponsorship policy, and sends transactions. It first attempts BOT Chain native EOA paymaster sponsorship, then guarantees a self-pay fallback when sponsorship is unavailable.
- `facilitator/src/server.ts`
- `facilitator/src/x402-adapter.ts`
- `facilitator/src/paymaster.ts`
- `facilitator/src/selfpay-fallback.ts`
- `facilitator/src/policy.ts`

#### Transaction and chain services
The facilitator encapsulates RPC/network selection, fee calculations, and transaction bundling, insulating x402 callers from BOT Chain-specific paymaster RPC methods (`pm_isSponsorable`) and raw transaction submission. Sponsor credentials and deployed contract addresses are runtime configuration.
- `facilitator/src/chain.ts`
- `facilitator/src/bundler.ts`
- `facilitator/src/fee.ts`

#### SDK integration layer
The workspace SDK exposes reusable primitives for consent-aware payment clients, wallet sourcing, middleware, x402 protocol handling, and network configuration. Adapter packages provide fetch interception, guardian-oriented use, and MCP servers/CLIs for agent/tool integrations.
- `facilitator/sdk/packages/core/src/consent-client.ts`
- `facilitator/sdk/packages/core/src/middleware.ts`
- `facilitator/sdk/packages/fetch/src/index.ts`
- `facilitator/sdk/packages/guardian/src/index.ts`
- `facilitator/sdk/packages/mcp/src/agent-server.ts`

#### x402 reference flow
A resource server exposes paid endpoints and returns HTTP 402 until payment settles. An agent uses wallet, reasoning, and consent client code to request resources through the x402 flow. The primary control path is: agent request → 402 payment terms → facilitator/payment execution → resource server serves protected response; policy-sensitive calls route through the consent contracts.
- `examples/resource-server/src/server.ts`
- `examples/resource-server/src/routes/x402.ts`
- `examples/resource-server/src/routes/hubot-task.ts`
- `examples/agent/src/agent.ts`
- `examples/agent/src/consent-client.ts`

#### Guardian console
The Vite/React console is the human-facing boundary. It connects a wallet, registers agents, reads consent state, presents pending approvals, and displays activity; guardian signatures/transactions resolve paused actions on-chain.
- `console/src/main.tsx`
- `console/src/App.tsx`
- `console/src/ApprovalQueue.tsx`
- `console/src/hooks/useConsent.ts`
- `console/src/chain.ts`

#### Runtimes and infrastructure
Solidity contracts use Foundry; services, SDK, examples, and console use Node.js/TypeScript. The console runs as a Vite browser application. External dependencies are BOT Chain RPC endpoints, its explorer/faucet, native paymaster RPC, deployed registry/gateway addresses, agent/guardian wallets, and x402-compatible resource endpoints.

Main entry points: [`contracts/src/ConsentGateway.sol`](https://github.com/the3rdweblabs/cosign/blob/main/contracts/src/ConsentGateway.sol) (Consent Gateway), [`facilitator/src/chain.ts`](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/chain.ts) (Chain execution), [`facilitator/sdk/packages/core/src/consent-client.ts`](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/core/src/consent-client.ts) (Consent client & middleware), [`facilitator/src/policy.ts`](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/policy.ts) (Sponsorship policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onchain["On-chain policy"]
  node_registry[("Agent Registry<br/>Solidity contract<br/>[AgentRegistry.sol]")]
  node_gateway{{"Consent Gateway<br/>Solidity contract<br/>[ConsentGateway.sol]"}}
  node_deployment["Contract deployment<br/>Foundry script<br/>[Deploy.s.sol]"]
end

subgraph group_facilitator["Payment facilitator"]
  node_facilitator_server["Facilitator API<br/>Node service<br/>[server.ts]"]
  node_x402_adapter["x402 adapter<br/>Protocol adapter<br/>[x402-adapter.ts]"]
  node_sponsorship_policy["Sponsorship policy<br/>Policy module<br/>[policy.ts]"]
  node_paymaster["Native paymaster<br/>Sponsorship client<br/>[paymaster.ts]"]
  node_self_pay["Self-pay fallback<br/>Transaction fallback"]
  node_chain_execution["Chain execution<br/>Chain service<br/>[chain.ts]"]
  node_bundler["Transaction bundler<br/>Transaction service<br/>[bundler.ts]"]
end

subgraph group_sdk["SDK integrations"]
  node_sdk_core["Consent client &amp; middleware<br/>SDK core<br/>[consent-client.ts]"]
  node_fetch_adapter["Fetch adapter<br/>SDK adapter<br/>[index.ts]"]
  node_guardian_sdk["Guardian adapter<br/>SDK adapter<br/>[index.ts]"]
  node_mcp_server["MCP agent server<br/>MCP integration<br/>[agent-server.ts]"]
end

subgraph group_examples["x402 reference flow"]
  node_agent["Autonomous agent<br/>Example client<br/>[agent.ts]"]
  node_resource_server["Protected resource server<br/>Example service<br/>[server.ts]"]
  node_x402_routes["Paid endpoint routes<br/>x402 routes<br/>[x402.ts]"]
end

subgraph group_console["Guardian console"]
  node_guardian_console["Guardian console<br/>React application<br/>[App.tsx]"]
  node_approval_queue["Approval queue<br/>Console view<br/>[ApprovalQueue.tsx]"]
  node_consent_hook["Consent state hook<br/>Console chain hook<br/>[useConsent.ts]"]
end

node_bot_chain[("BOT Chain<br/>External blockchain")]
node_paymaster_rpc["Paymaster RPC<br/>External RPC"]

node_deployment -->|"deploys"| node_registry
node_deployment -->|"wires"| node_gateway
node_gateway -->|"checks agent policy"| node_registry
node_registry -->|"stores policy on"| node_bot_chain
node_gateway -->|"records consent state on"| node_bot_chain
node_agent -->|"requests through"| node_fetch_adapter
node_fetch_adapter -->|"uses"| node_sdk_core
node_sdk_core -->|"submits payment"| node_facilitator_server
node_agent -->|"requests protected resource"| node_resource_server
node_resource_server -.->|"returns 402 terms"| node_agent
node_resource_server -->|"serves"| node_x402_routes
node_facilitator_server -->|"adapts request"| node_x402_adapter
node_x402_adapter -->|"evaluates"| node_sponsorship_policy
node_sponsorship_policy -->|"sponsorable"| node_paymaster
node_sponsorship_policy -.->|"not sponsored"| node_self_pay
node_paymaster -->|"checks sponsorship"| node_paymaster_rpc
node_paymaster -->|"sponsored transaction"| node_chain_execution
node_self_pay -->|"self-paid transaction"| node_chain_execution
node_chain_execution -->|"builds bundle"| node_bundler
node_bundler -->|"submits transaction"| node_bot_chain
node_chain_execution -->|"invokes consent policy"| node_gateway
node_guardian_console -->|"presents"| node_approval_queue
node_approval_queue -->|"uses"| node_consent_hook
node_consent_hook -->|"reads and resolves consent"| node_gateway
node_guardian_sdk -->|"builds on"| node_sdk_core
node_mcp_server -->|"builds on"| node_sdk_core

click node_registry "https://github.com/the3rdweblabs/cosign/blob/main/contracts/src/AgentRegistry.sol"
click node_gateway "https://github.com/the3rdweblabs/cosign/blob/main/contracts/src/ConsentGateway.sol"
click node_deployment "https://github.com/the3rdweblabs/cosign/blob/main/contracts/script/Deploy.s.sol"
click node_facilitator_server "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/server.ts"
click node_x402_adapter "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/x402-adapter.ts"
click node_sponsorship_policy "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/policy.ts"
click node_paymaster "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/paymaster.ts"
click node_self_pay "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/selfpay-fallback.ts"
click node_chain_execution "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/chain.ts"
click node_bundler "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/bundler.ts"
click node_sdk_core "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/core/src/consent-client.ts"
click node_fetch_adapter "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/fetch/src/index.ts"
click node_guardian_sdk "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/guardian/src/index.ts"
click node_mcp_server "https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/mcp/src/agent-server.ts"
click node_agent "https://github.com/the3rdweblabs/cosign/blob/main/examples/agent/src/agent.ts"
click node_resource_server "https://github.com/the3rdweblabs/cosign/blob/main/examples/resource-server/src/server.ts"
click node_x402_routes "https://github.com/the3rdweblabs/cosign/blob/main/examples/resource-server/src/routes/x402.ts"
click node_guardian_console "https://github.com/the3rdweblabs/cosign/blob/main/console/src/App.tsx"
click node_approval_queue "https://github.com/the3rdweblabs/cosign/blob/main/console/src/ApprovalQueue.tsx"
click node_consent_hook "https://github.com/the3rdweblabs/cosign/blob/main/console/src/hooks/useConsent.ts"

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_gateway,node_deployment toneBlue
class node_facilitator_server,node_x402_adapter,node_sponsorship_policy,node_paymaster,node_self_pay,node_chain_execution,node_bundler toneAmber
class node_sdk_core,node_fetch_adapter,node_guardian_sdk,node_mcp_server toneMint
class node_agent,node_resource_server,node_x402_routes toneRose
class node_guardian_console,node_approval_queue,node_consent_hook toneIndigo
class node_bot_chain,node_paymaster_rpc toneNeutral
```

## Components

### On-chain policy

Foundry contracts on BOT Chain.

- [Agent Registry](https://github.com/the3rdweblabs/cosign/blob/main/contracts/src/AgentRegistry.sol): Solidity contract · Maps agents to guardians and spending policy. · `contracts/src/AgentRegistry.sol`
- [Consent Gateway](https://github.com/the3rdweblabs/cosign/blob/main/contracts/src/ConsentGateway.sol): Solidity contract · Routes actions to auto-settlement, consent, or rejection. · `contracts/src/ConsentGateway.sol`
- [Contract deployment](https://github.com/the3rdweblabs/cosign/blob/main/contracts/script/Deploy.s.sol): Foundry script · Deploys and wires registry and gateway. · `contracts/script/Deploy.s.sol`

### Payment facilitator

Node service executing x402 payments.

- [Facilitator API](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/server.ts): Node service · Operational boundary for payment execution. · `facilitator/src/server.ts`
- [x402 adapter](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/x402-adapter.ts): Protocol adapter · Converts x402 payment requests into BOT Chain execution. · `facilitator/src/x402-adapter.ts`
- [Sponsorship policy](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/policy.ts): Policy module · Assesses whether a payment can be sponsored. · `facilitator/src/policy.ts`
- [Native paymaster](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/paymaster.ts): Sponsorship client · Attempts native EOA paymaster sponsorship first. · `facilitator/src/paymaster.ts`
- [Self-pay fallback](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/selfpay-fallback.ts): Transaction fallback · Guarantees execution when sponsorship is unavailable. · `facilitator/src/selfpay-fallback.ts`
- [Chain execution](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/chain.ts): Chain service · Selects network and submits BOT Chain transactions. · `facilitator/src/chain.ts`
- [Transaction bundler](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/src/bundler.ts): Transaction service · Builds execution bundles. · `facilitator/src/bundler.ts`

### SDK integrations

Reusable TypeScript client packages.

- [Consent client & middleware](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/core/src/consent-client.ts): SDK core · Consent-aware client primitives and middleware. · `facilitator/sdk/packages/core/src/consent-client.ts`
- [Fetch adapter](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/fetch/src/index.ts): SDK adapter · Intercepts fetch requests for x402 handling. · `facilitator/sdk/packages/fetch/src/index.ts`
- [Guardian adapter](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/guardian/src/index.ts): SDK adapter · Guardian-oriented integration primitives. · `facilitator/sdk/packages/guardian/src/index.ts`
- [MCP agent server](https://github.com/the3rdweblabs/cosign/blob/main/facilitator/sdk/packages/mcp/src/agent-server.ts): MCP integration · Exposes agent and tool integration endpoints. · `facilitator/sdk/packages/mcp/src/agent-server.ts`

### x402 reference flow

Agent and protected resource examples.

- [Autonomous agent](https://github.com/the3rdweblabs/cosign/blob/main/examples/agent/src/agent.ts): Example client · Requests paid resources using wallet and consent code. · `examples/agent/src/agent.ts`
- [Protected resource server](https://github.com/the3rdweblabs/cosign/blob/main/examples/resource-server/src/server.ts): Example service · Returns 402 terms until payment settles. · `examples/resource-server/src/server.ts`
- [Paid endpoint routes](https://github.com/the3rdweblabs/cosign/blob/main/examples/resource-server/src/routes/x402.ts): x402 routes · Defines protected x402 and task endpoints. · `examples/resource-server/src/routes/x402.ts`

### Guardian console

Vite browser application for human approvals.

- [Guardian console](https://github.com/the3rdweblabs/cosign/blob/main/console/src/App.tsx): React application · Wallet-connected interface for agent and consent management. · `console/src/App.tsx`
- [Approval queue](https://github.com/the3rdweblabs/cosign/blob/main/console/src/ApprovalQueue.tsx): Console view · Shows pending guardian approvals and activity. · `console/src/ApprovalQueue.tsx`
- [Consent state hook](https://github.com/the3rdweblabs/cosign/blob/main/console/src/hooks/useConsent.ts): Console chain hook · Reads consent state and resolves approvals. · `console/src/hooks/useConsent.ts`

### Other components

- **BOT Chain**: External blockchain · Testnet 968 or mainnet 677 selected at runtime.
- **Paymaster RPC**: External RPC · Provides pm_isSponsorable for native sponsorship.

## Connections

- Contract deployment → Agent Registry: deploys
- Contract deployment → Consent Gateway: wires
- Consent Gateway → Agent Registry: checks agent policy
- Agent Registry → BOT Chain: stores policy on
- Consent Gateway → BOT Chain: records consent state on
- Autonomous agent → Fetch adapter: requests through
- Fetch adapter → Consent client & middleware: uses
- Consent client & middleware → Facilitator API: submits payment
- Autonomous agent → Protected resource server: requests protected resource
- Protected resource server → Autonomous agent: returns 402 terms
- Protected resource server → Paid endpoint routes: serves
- Facilitator API → x402 adapter: adapts request
- x402 adapter → Sponsorship policy: evaluates
- Sponsorship policy → Native paymaster: sponsorable
- Sponsorship policy → Self-pay fallback: not sponsored
- Native paymaster → Paymaster RPC: checks sponsorship
- Native paymaster → Chain execution: sponsored transaction
- Self-pay fallback → Chain execution: self-paid transaction
- Chain execution → Transaction bundler: builds bundle
- Transaction bundler → BOT Chain: submits transaction
- Chain execution → Consent Gateway: invokes consent policy
- Guardian console → Approval queue: presents
- Approval queue → Consent state hook: uses
- Consent state hook → Consent Gateway: reads and resolves consent
- Guardian adapter → Consent client & middleware: builds on
- MCP agent server → Consent client & middleware: builds on