the3rdweblabs/cosign

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.