Skip to content
BranchesTags

Repository files navigation

AgentGuard VerifyPay

Agent Control Plane

AgentGuard VerifyPay — policy-controlled commerce for autonomous AI agents.

Repository map: this is the generic AgentGuard foundation. For the ETHOnline 2026 Continuity submission, use ethonline-agentguard. Chain- and venue-specific implementations are linked from that submission's repository map.

Built for hackathons: make an Agent useful without making it unconstrained.

One Agent can hire another Agent or API. AgentGuard decides whether the quote and execution are still allowed — within explicit permissions, budgets, risk limits, deadlines, and verification rules.

CI Node 22 TypeScript Testnet first

Choose submission edition · BNB demo · Arbitrum demo · 3-minute demo · Submission kit · Why BNB + Arbitrum · Arbitrum evidence · BNB evidence

Agent Control Plane — policy-controlled execution for autonomous AI agents

Core invariant: an agent may act, but never beyond policy — and no payment or execution is accepted until the outcome is verified.

Why this exists

Agent demos usually stop at “the model called a tool.” Production systems need the missing control layer around that call:

  • Is this action permitted for this agent?
  • Is it still inside budget, target, time, and risk limits?
  • Did the execution produce the promised outcome?
  • If transport or verification fails, can funds and state be frozen safely?
  • Can a judge, operator, or auditor verify what happened later?

The execution lifecycle

flowchart LR
    A[Agent intent] --> B[Policy gate]
    B --> C[Risk checks]
    C --> D[Adapter execution]
    D --> E[Outcome verification]
    E --> I[Independent verifier attestation]
    I -->|verified| F[Release / settle]
    I -->|failed| G[Recover / freeze]
    F --> H[Signed receipt]
    G --> H
Loading

Capability surface

Layer Guarantees Examples
Policy permissions, budgets, targets, approvals, time windows “Only trade SOL on Devnet under 0.01 SOL”
Risk simulation, exposure, duplication, slippage, runtime drift block a changed quote or repeated action
Execution exchange, chain, payment, MCP, x402, workflow adapters OKX, Solana RPC, EVM, escrow, MCP
Verification accept only an outcome that satisfies the task validate an API result before release
Attestation independent signature bound to task, policy, evidence, chain and expiry EIP-712 Verifier Agent proof
Recovery cancel, refund, retry, freeze, circuit breaker freeze on transport or verification failure
Receipts auditable decisions, proofs, and execution history SHA-256 Merkle proofs and lifecycle receipts

Judge-first demos

Each reference app demonstrates a distinct winning moment and reuses the same control-plane lifecycle:

Demo What a judge sees
Safe Trade approved action, blocked action, and frozen outcome
Agent Commerce quote → escrow → verify → release or recover
API Procurement payment released only after result verification
OKX Trade exchange adapter with explicit policy and freeze paths
Treasury Guard allocation limits, risk thresholds, and circuit breakers
Solana Devnet resilient RPC, external signing, confirmation, and audit failure handling

The judge path

1. Hire SafeSwap Agent with a 50 USDT budget.
2. Show VERIFIED: result passes, payment releases, receipt is created.
3. Raise the budget above policy: BLOCKED before the adapter is called.
4. Return an out-of-policy fill: FROZEN with evidence and recovery state.
5. Open the live ERC-8004 / ERC-8183 evidence in the Marketplace.

The important distinction is not “an Agent called a tool.” It is that the same control plane proves what the Agent was allowed to do, what actually happened, and why funds were released or frozen.

Canonical Agent-to-Agent path

The winning path is one Buyer Agent hiring one Seller Agent — not four unrelated Agent demos:

Treasury Agent intent
  → discover YieldScout
  → compare quote (0.40 USDC)
  → enforce budget / asset / freshness policy
  → hold escrow
  → Seller Agent returns DeFiLlama evidence
  → independent verification
  → VERIFIED release, or BLOCKED / FROZEN recovery

Run the deterministic, offline-safe version:

npm run demo:agent-to-agent

It is builder-controlled demo evidence; the linked BNB and Arbitrum transactions are the separate testnet proof anchors.

One-command judge verification

For a fast repository review, run:

npm run judge:quick-check

Expected result: VERIFIED, BLOCKED, and FROZEN, followed by the Buyer → Seller VerifyPay trace and the Arbitrum judge bundle. For the TypeScript independent-verifier replay tests and security attack matrix, run their dedicated commands in a normal terminal. For live read-only proof, then run:

npm run demo:arbitrum:evidence
BNB_TX_HASH=0x5dc5469cfdb84c9758208b0bee796f775203dca6445bf9fc98a7f3becb82aa93 npm run demo:bnb:evidence

Use the network-specific BNB demo or Arbitrum demo when submitting; the root URL is only the edition selector.

The repository also keeps immutable submission snapshots: BNB bnb-v0.1.0 and Arbitrum arbitrum-v0.1.1.

The canonical product story

AgentGuard's primary use case is a Treasury Agent hiring a Risk or Data Agent before moving treasury funds. The buyer Agent proposes a bounded task, the seller returns a quote and evidence, and Arbitrum holds the USDC budget until the evidence matches the policy. This is the product path; the BNB Agent profiles are compatibility examples built on the same control-plane contract.

The public Marketplace now has explicit network-specific judge entrances. Use the BNB Agent Studio Edition for ERC-8004 identity, ERC-8183 commerce, and Job 614. Use the Arbitrum Agentic AI Edition for PolicyEscrowV3 independent verification and VERIFIED/FROZEN/REFUNDED proof. The two views share this repository and control-plane core, but each page hides the other network's evidence so a judge sees one coherent submission at a time.

Read the dedicated BNB submission brief or Arbitrum submission brief when filing a form.

Run it in five minutes

Use Node.js 22 (the repository pins 22.23.2 in .nvmrc).

npm ci
npm run lint
npm run typecheck
npm test

Run the read-only Solana Devnet probe:

set -a; source .env; set +a
npm run demo:solana

Run the offline judge flow first:

npm run demo:judge

It shows VERIFIED, BLOCKED, and FROZEN outcomes with auditable receipts in one command. See the Judge Demo.

Run the Arbitrum Sepolia PolicyEscrow proof:

npm run demo:arbitrum:task
npm run demo:arbitrum:judge
npm run demo:verify-pay
npm run demo:arbitrum:evidence
npm run demo:treasury-agent
npm run demo:yield-scout:live
npm run demo:yield-scout:arbitrum
npm run demo:yield-scout:evidence
npm run demo:health-guard:live
npm run demo:rebalance-guard:live
npm run demo:safe-swap:live
npm run demo:pancakeswap:live
npm run demo:erc8004:discover
npm run demo:independent-verifier
npm run demo:arbitrum:v3:verification-artifact
npm run demo:arbitrum:v3:evidence
npm run security:attack-matrix
npm run impact:benchmark
npm run evidence:judge:bundle
npm run benchmark:agent-advantage

demo:arbitrum:evidence is a read-only RPC check. It independently verifies the deployed bytecode exists, Task 1 is VERIFIED, the policy and evidence hashes match the repository proof, and the settlement receipt succeeded.

demo:treasury-agent shows the canonical buyer flow: a Treasury Agent turns an objective into a bounded hire request, compares registered seller capabilities, checks the quote against budget, and fails closed before escrow when the request cannot be satisfied.

When the local Marketplace server is running, the same public, read-only plan is available at /api/treasury/plan for judge tooling and integrations.

YieldScout also has a real external data-source path. demo:yield-scout:live reads DeFiLlama pools, applies a TVL/APY/asset policy, ranks up to three candidates, and emits an evidence hash. It is read-only and fails closed when the source is unavailable. See YieldScout data source.

The full path has also been completed on Arbitrum Sepolia for Task 4: the live DeFiLlama snapshot produced the submitted evidence hash, and the task was verified on-chain. Run demo:yield-scout:evidence to independently check the contract, policy hash, evidence hash, source marker, and settlement receipt.

The other three BNB profiles expose the same evidence discipline through read-only public data paths: HealthGuard reads Venus market/account liquidity, RebalanceGuard combines BNB JSON-RPC balances with DeFiLlama prices, and SafeSwap reads both public pair data and PancakeSwap V2 Router quotes. Each adapter hashes the exact snapshot and fails closed when data is unavailable or outside policy. These probes do not execute swaps, repayments, or rebalances. See the Agent Advantage Report.

The Marketplace can also scan recent BNB Testnet ERC-8004 registrations or query arbitrary Agent IDs. It resolves identity owner, Agent wallet and registration metadata, then separates identity-only, hirable, endpoint proof and verified task history. See ERC-8004 discovery and the explainable reputation model.

The PancakeSwap-native SafeSwap path compares direct and multihop V2 Router quotes and applies a price-impact policy without approving tokens or sending a trade. See PancakeSwap SafeSwap.

The independent-verifier path produces an EIP-712 attestation bound to the task, policy, evidence, Arbitrum chain, settlement contract and expiry. The deployed PolicyEscrowV3 accepts only the configured verifier and rejects tampering or replay. Its owner and verifier are different addresses, and real Arbitrum Sepolia tasks prove both VERIFIED release and FROZEN recovery. See Independent verification, the attack matrix, and the Impact Dashboard.

PolicyEscrowV2 also exposes a testnet ERC-20 path. Set ARBITRUM_TEST_TOKEN_ADDRESS locally before running npm run demo:arbitrum:token-task; the command fails closed when no token is configured.

The V2 and V3 deployment and task evidence are recorded in deployments/arbitrum-sepolia-policy-escrow-v2.json and deployments/arbitrum-sepolia-policy-escrow-v3.json. To deploy a fresh testnet instance, run npm run demo:arbitrum:deploy with a local Keychain wallet or an ignored ARBITRUM_PRIVATE_KEY environment variable. npm run demo:arbitrum:v3:task sends new testnet transactions and should not be used as a read-only judge command.

Run the BNB AgentGuard Marketplace vertical slice:

npm run demo:bnb

Open the judge-facing Marketplace UI:

cd apps/marketplace
npm start

See the Arbitrum hackathon build guide for the Agentic AI submission path. The BNB hackathon build guide documents the existing cross-chain evidence.

The optional signing probe sends only a tiny self-transfer on Devnet:

npm run demo:solana:transfer

Repository map

packages/   domain-neutral control-plane contracts and receipt logic
adapters/   exchange, chain, payment, MCP, x402, and workflow integrations
examples/   hackathon-ready reference applications
apps/       human-facing policy and receipt dashboards
docs/       architecture, safety rules, migration notes, and judging guide

What is real vs. simulated

Surface Status
ERC-8004 identities Real BNB Testnet registrations, Agent IDs 1898, 1902, 1903, and 1904
ERC-8183 task Real BNB Testnet Job 614, funded, submitted, settled, and COMPLETED
Arbitrum settlement Real Arbitrum Sepolia PolicyEscrowV2 deployment, verified source, and VERIFIED task
Arbitrum evidence check Read-only RPC verification of contract, task state, hashes, and settlement receipt
YieldScout live proof DeFiLlama snapshot → evidence hash → Arbitrum Sepolia Task 4 VERIFIED
Independent verifier Real Arbitrum Sepolia V3 deployment with a separate verifier address, VERIFIED release, FROZEN decision, and refund proof
Agent-to-Agent task Real Arbitrum Sepolia Task 3: Treasury Agent → YieldScout, named in policy/evidence metadata, VERIFIED and released
Impact benchmark 20 builder-controlled scenarios with explicit VERIFIED/BLOCKED/FROZEN/EXPIRED labels
Marketplace Public GitHub Pages deployment
Judge lifecycle Deterministic, offline-safe reference scenarios
Mainnet execution Disabled by design
Production database / auth Roadmap, not claimed as deployed

Latest BNB Testnet proof

SafeSwap completed a real ERC-8183 task on BNB Testnet. The settlement receipt was independently verified by the BNB receipt adapter.

  • Job: 614
  • Status: COMPLETED
  • Budget: 1 U
  • Settlement: View on BscScan
  • Settlement transaction hash: 0x5dc5469cfdb84c9758208b0bee796f775203dca6445bf9fc98a7f3becb82aa93
  • Receipt evidence hash: 5c9bd98ffd7de6fa5a1d2ff26cec2f0fb2e951ef8b608d9444ffb811bf512f5b
  • Public Marketplace: Open the live demo

Latest Arbitrum Sepolia proof

PolicyEscrowV3 — independent verifier live proof

PolicyEscrowV3 is deployed with a verifier address that is separate from the owner. The verifier signs EIP-712 decisions off-chain; the contract binds the signature to the task, policy, evidence, chain, contract, issue time, and expiry before releasing or freezing funds.

PolicyEscrowV2 — verified source and ERC-20 proof

The AgentGuard PolicyEscrowV2 contract is deployed on Arbitrum Sepolia and has completed a real funded VerifyPay task with a deadline, policy decision hash, evidence-backed verification, and native ETH settlement.

Real ERC-20 / USDC proof

Task 3 completed a real 0.1 USDC VerifyPay lifecycle on Arbitrum Sepolia:

Real Buyer → Seller task

Task 3 is a real Arbitrum Sepolia PolicyEscrowV3 task whose public policy and evidence metadata name both participants:

This is real Arbitrum Sepolia testnet evidence. The task budget is testnet ETH; no mainnet execution or external-user traction is claimed.

Verified Contract

Visual assets

The reusable launch graphics are versioned with the evidence they describe:

Safety boundary

  • Demo defaults are simulated or testnet-only.
  • Signing stays outside the dependency-free control-plane adapter.
  • Runtime credentials belong in the local OKX profile or ignored .env, never in Git.
  • Failed transport and verification paths produce frozen, auditable outcomes.
  • See SECURITY.md and local development safety.

Verification

The current reference implementation is validated with:

73 tests passing (10 Node + 63 TypeScript) · lint passing · typecheck passing · security preflight passing

More detail:

About

Policy-controlled execution layer for autonomous AI agents: permissions, budgets, risk gates, verification, recovery, and audit receipts.

github.com/0xCaptain888/agent-control-plane#readme

Topics

agent-infrastructureagent-safetyai-agentsautonomous-agentshackathonmcpokxpaymentspolicy-enginesolanatypescriptx402

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages