Reachability Watchtower

Standalone service that runs weekly and checks whether Agent0 web, A2A, and MCP endpoints are reachable. If reachable, it posts a public, on-chain ERC-8004 feedback message advertising reachability.

This is designed to be low-maintenance and deployed as AWS Lambda + EventBridge schedule, with CloudWatch observability and DynamoDB idempotency.

This repo is multi-role: Reachability is implemented today, and additional watchtowers (e.g. domain verification) can be deployed as separate Lambda functions from the same watchtower/ codebase/bundle.

---

Product scope & goal

Goal

• Weekly, for each configured chain:
  • Load agents from the chain’s Agent0 subgraph (SDK defaults).
  • Extract each agent’s registrationFile.webEndpoint, registrationFile.a2aEndpoint, and registrationFile.mcpEndpoint.
  • Probe reachability (HTTP-level).
  • If reachable, post ERC-8004 feedback on-chain:
    • agentId = the agent being checked (chainId:agentId)
    • clientAddress = the watchtower wallet address
    • tag1 = reachable
    • tag2 = web or a2a or mcp
    • value = 1
    • valueDecimals = 0
    • endpoint = full normalized URL (e.g. https://endpoint.com/path)

Non-goals (current)

• Horizontal scaling / fan-out (single scheduled Lambda invocation is intended).
• Protocol-level “deep” A2A/MCP handshakes (optional future improvement).

---

Features

Per-endpoint, on-chain reachability attestations

For each reachable endpoint, the watchtower posts a feedback entry. Consumers can search for these tags in the subgraph to validate “reachable” endpoints publicly.

STAR-gated scanning (optional allowlist mode)

If enabled, the watchtower only scans agents that have already received feedback satisfying:

• tag1 = "STAR"
• clientAddress = <STAR_REVIEWER_ADDRESS>
• isRevoked = false

This lets you curate which agents are scanned without maintaining a separate allowlist file.

DynamoDB idempotency (anti-spam by design)

The watchtower stores a record keyed by:

• (roleId, chainId, agentId, endpointType, hostname)

If a success was recorded within the last IDEMPOTENCY_WINDOW_DAYS (default 7), the watchtower skips posting again.

---

Software architecture

Components

• Controller/engine (src/runtime/engine.ts + role plugins under src/roles/)

  • Loops over configured chains
  • Optional STAR allowlist query (per chain)
  • Fetch agents + endpoints from subgraph
  • Runs reachability checks with bounded concurrency
  • Posts feedback and writes idempotency records

• Subgraph ingestion (src/subgraph/agents.ts)

  • Uses a direct GraphQL query to fetch agents { id registrationFile { webEndpoint mcpEndpoint a2aEndpoint } }
  • Uses a direct GraphQL query for STAR gating (exact tag1="STAR" match)

• Reachability probe (src/checks/reachability.ts)

  • Normalizes URL (defaults scheme to https:// if missing)
  • Uses HEAD then GET fallback
  • Treats 2xx/3xx/401/403 as reachable (server is alive, even if auth required)

• Feedback posting (src/feedback/post.ts)

  • Uses the agent0-sdk TypeScript SDK to prepare and submit feedback on-chain

• Idempotency store (src/storage/idempotency.ts)

  • DynamoDB get/put for last success time and last tx reference

Data flow

flowchart TD
  eventBridge[EventBridgeSchedule] --> controller[WatchtowerController]
  controller --> subgraph[Agent0SubgraphGraphQL]
  controller --> endpoints[AgentEndpoints_HTTP]
  controller --> rpc[RPC_provider]
  rpc --> chain[ReputationRegistry_giveFeedback]
  controller --> db[DynamoDB_idempotency]

Loading

---

Deployment (AWS Lambda + EventBridge)

Runtime

• Node.js 20.x Lambda runtime recommended.

AWS resources

• Lambda function (scheduled weekly by EventBridge)
• EventBridge rule (cron schedule)
• DynamoDB table for idempotency
• Secrets Manager secret containing the watchtower private key
• CloudWatch logs + CloudWatch alarms
• SNS topic + email subscription (or SES) for notifications

This repo includes CloudFormation/SAM templates under watchtower/deploy/ (see that folder once built).

Alarms / notifications

watchtower/deploy/alarms.yaml provisions:

• an SNS topic with an email subscription
• alarms on:
  • Lambda Errors
  • Lambda Duration
  • custom EMF metric FeedbackFailed (namespace Agent0/Watchtower)

---

Configuration

All configuration is via environment variables.

Required env vars

• CHAINS: Comma-separated chain IDs to scan (e.g. 11155111,84532)
• RPC_URL_<chainId>: RPC URL per chain (e.g. RPC_URL_11155111, RPC_URL_84532)
• WATCHTOWER_PRIVATE_KEY_SECRET_ID: Secrets Manager secret id/arn with the private key
• DDB_TABLE_NAME: DynamoDB idempotency table name

Optional env vars

• STAR_MODE_ENABLED: true|false (default false)
• STAR_REVIEWER_ADDRESS: required if STAR mode is enabled
• IDEMPOTENCY_WINDOW_DAYS: default 7
• MAX_CONCURRENCY: default 10
• REQUEST_TIMEOUT_MS: default 8000
• PROBE_RETRIES: default 1

Secrets Manager formats

Supported secret value formats:

• Plaintext:
  • 0xabc123... or abc123...
• JSON:
  • { "privateKey": "0xabc123..." }

---

Local development

From watchtower/:

npm install
npm run build
node dist/index.js

For Lambda, the handler entrypoint is:

• dist/reachability.js (export: handler) ✅ recommended
• dist/domainVerification.js (export: handler) (currently safe no-op)
• dist/lambda/handler.js (export: handler) (backwards-compatible default)