Skip to content

README.md

Latest commit

 

History

History
198 lines (173 loc) · 7.96 KB

README.md

File metadata and controls

198 lines (173 loc) · 7.96 KB

Agent Bond Validator

Lean TypeScript validator service for Agent Bonds disputes.

This repository is intentionally focused on v1.1 essentials:

  • deterministic rules-first evaluation
  • manual review fallback for non-machine-checkable disputes
  • EIP-712 ValidatorCommitment signing
  • KMS-backed signing only (AWS KMS secp256k1)
  • task definition hash verification
  • evidence trust-level gating
  • queue-based ValidationRegistry request/response submission
  • signed audit export for public dispute traceability

What Is Implemented

  • Fastify API server with typed request validation (zod)
  • POST /v1/commitments/sign (EIP-712 signature generation)
  • POST /v1/utils/task-definition-hash
  • POST /v1/utils/request-hash
  • POST /v1/disputes/enqueue
  • GET /v1/disputes/:jobId
  • POST /v1/disputes/:jobId/manual-decision
  • POST /v1/disputes/:jobId/responded
  • POST /v1/disputes/:jobId/resolved
  • GET /v1/disputes/:jobId/audit-export
  • GET /v1/metrics/resolver
  • Deterministic evaluator with trust-aware checks
  • Postgres-backed dispute store (default and required runtime backend)
  • Queue worker with retry and deadline-aware escalation
  • Manual-review queue guardrails with optional pager webhook alerts
  • KMS-backed ValidationRegistry writer (VALIDATION_WRITER_ENABLED=true)
  • Automatic resolveDispute(taskId) keeper step after response submission
  • Canonical requestHash verification from structured request_context
  • Optional on-chain taskHash verification during dispute enqueue (DISPUTE_CHAIN_RPC_URL)
  • Authorization failures are marked blocked (no blind retries)
  • Response payloads include structured criterionOutcomes and evidenceSummary traces
  • Resolver metrics surface (resolved_count, resolve_failures, resolve_latency_ms)
  • Signed/public dispute audit export
  • Unit/integration tests via Vitest

Quick Start

npm install
npm run dev

Server defaults to http://0.0.0.0:8080.

Configuration

See config.example.env for supported variables.

Important:

  • JWT auth is required for all dispute, audit, metrics, and mutation endpoints. Configure API_AUTH_JWT_ALG, API_AUTH_JWT_ISSUER, and API_AUTH_JWT_AUDIENCE.
  • Configure one key source: API_AUTH_JWT_PUBLIC_KEY (static PEM) or API_AUTH_JWT_JWKS_URL (kid-based JWKS rotation). If both are set, JWKS is used.
  • In JWKS mode, validator fetches remote keys and supports rotation without restart; tune refresh behavior with API_AUTH_JWT_JWKS_COOLDOWN_MS and API_AUTH_JWT_JWKS_CACHE_MAX_AGE_MS.
  • Requests must pass Authorization: Bearer <jwt>; tokens are verified against the selected key source and checked for endpoint scopes.
  • Default required scopes are:
    • validator.utils.hash for POST /v1/utils/task-definition-hash and POST /v1/utils/request-hash
    • validator.commitment.sign for POST /v1/commitments/sign
    • validator.dispute.enqueue for POST /v1/disputes/enqueue
    • validator.dispute.read for GET /v1/disputes/:jobId
    • validator.dispute.audit_export for GET /v1/disputes/:jobId/audit-export
    • validator.dispute.manual_decision for POST /v1/disputes/:jobId/manual-decision
    • validator.dispute.responded for POST /v1/disputes/:jobId/responded
    • validator.dispute.resolved for POST /v1/disputes/:jobId/resolved
    • validator.metrics.read for GET /v1/metrics/resolver
    • Prefix wildcards (for example validator.dispute.* or validator.*) are accepted.
    • Global wildcard * is rejected.
  • AWS_REGION + AWS_KMS_KEY_ID are required (service is KMS-only)
  • optional AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN) can override credential resolution
  • signer/writer enforce boundary allowlists via ALLOWED_CHAIN_IDS, ALLOWED_BOND_MANAGER_ADDRESSES, ALLOWED_VALIDATION_REGISTRY_ADDRESSES
  • PUBLIC_RPC_URL is required only when nonce is not provided in POST /v1/commitments/sign.
  • NONCE_RESYNC_INTERVAL_MS controls periodic on-chain nonce re-sync to recover cursor drift
  • set DISPUTE_CHAIN_RPC_URL to verify task_definition_hash and request_context.task_hash against on-chain task data at enqueue-time (defaults to WRITER_RPC_URL, then PUBLIC_RPC_URL when unset)
  • DATABASE_URL is required (Postgres is the only runtime store backend)
  • enable writer with VALIDATION_WRITER_ENABLED=true and WRITER_RPC_URL
  • writer always uses the same KMS identity (AWS_REGION + AWS_KMS_KEY_ID)
  • writer is strict EIP-1559 (no legacy transaction fallback)
  • writer retries nonce-conflict submission errors with fresh pending nonce reads; for strict horizontal scale, run a single active writer or add an external nonce manager
  • queue guardrail thresholds can be tuned with MANUAL_QUEUE_* variables; set PAGER_WEBHOOK_URL for alert delivery
  • /v1/disputes/enqueue verifies request_hash against canonical request_context
  • AUTO_BINARY_SCORING defaults to false to avoid full-slash outcomes on partial-pass auto scores
  • task_definition.requiredEvidence supports optional minCount and minUniqueIssuers guards to prevent duplicate evidence from satisfying quantity/diversity requirements

Quality Checks

npm run check

This runs:

  • eslint
  • typecheck
  • tests
  • tests use a Postgres-backed harness; set TEST_DATABASE_URL if your local Postgres is not postgresql://127.0.0.1:5432/postgres

Example Payloads

Sign commitment

POST /v1/commitments/sign

{
  "chain_id": 84532,
  "bond_manager": "0x0000000000000000000000000000000000000001",
  "agent_id": "77",
  "client": "0x0000000000000000000000000000000000000002",
  "task_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "fee_amount": "1000000",
  "deadline": "1738800000",
  "nonce": "1"
}

Enqueue dispute

POST /v1/disputes/enqueue

{
  "chain_id": 84532,
  "task_id": "123",
  "agent_id": "77",
  "bond_manager_address": "0x0000000000000000000000000000000000000001",
  "task_type": "api_integration",
  "ruleset_id": "api-integration-core",
  "ruleset_version": "1.0.0",
  "validator_address": "0x0000000000000000000000000000000000000009",
  "validation_registry_address": "0x000000000000000000000000000000000000000A",
  "request_hash": "0x67802f22aa0d69c66a1206c4f49c7b602f736009f9bebc7263c636d8cfbf89e0",
  "request_context": {
    "client": "0x0000000000000000000000000000000000000005",
    "agent_recipient": "0x0000000000000000000000000000000000000006",
    "client_recipient": "0x0000000000000000000000000000000000000007",
    "payment": "0",
    "task_hash": "0x3333333333333333333333333333333333333333333333333333333333333333"
  },
  "task_definition_uri": "ipfs://task-definition-cid",
  "task_definition_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "task_definition": {
    "taskType": "api_integration",
    "rulesetId": "api-integration-core",
    "rulesetVersion": "1.0.0",
    "acceptanceCriteria": [
      {
        "id": "ac-1",
        "description": "All required endpoints return HTTP 200",
        "weightBps": 10000
      }
    ],
    "requiredEvidence": [
      {
        "type": "api_test_results",
        "required": true,
        "minTrustLevel": "third_party",
        "minCount": 2,
        "minUniqueIssuers": 2
      }
    ]
  },
  "evidence_items": [
    {
      "type": "api_test_results",
      "uri": "ipfs://evidence-cid",
      "sha256": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "trustLevel": "third_party",
      "issuer": "qa-lab-alpha"
    },
    {
      "type": "api_test_results",
      "uri": "ipfs://evidence-cid-2",
      "sha256": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
      "trustLevel": "third_party",
      "issuer": "qa-lab-beta"
    }
  ],
  "criterion_results": [
    {
      "criterionId": "ac-1",
      "passed": true,
      "evidenceTypes": ["api_test_results"]
    }
  ]
}

Next Steps

  • integrate durable object storage for large request/response evidence payloads
  • add worker metrics and Prometheus-compatible telemetry export
  • add multi-reviewer assignment policy and SLA dashboards