EthersFlow — Trust Gate for AI Agents

EthersFlow — Agent Action Verification Layer (KYAA)

EthersFlow MCP is the action-verification layer for AI Agents (KYAA — Know Your Agent's Action). An adversarial council of independent models examines what your agent is about to do — and returns a signed, independently checkable verdict before execution.

Overview

KYA establishes who your agent is and what it's allowed to do. KYAA (Know Your Agent's Action) verifies what it's actually doing — one signed action at a time. Identity gets your agent through the door. Verification decides what leaves with it.

EthersFlow is an action gate: it decides whether an agent's next action should execute — and notarizes its own decision with signed, independently verifiable evidence. Calls from unverified identities are refused by default; read-only probes get a rate-capped look, and every decision — including every refusal — is a signed receipt. Enforcement without proof is a black box; proof without enforcement is just an audit log after the damage is done. EthersFlow is the checkpoint that does both.

The Agent Governance Stack

+-------------------+      +-------------------+      +-------------------------+      +-------------------+

| 1. IDENTITY (KYA) | ---> | 2. AUTHORIZATION | ---> | 3. ACTION VERIFICATION | ---> | 4. EXECUTION | | | | | | (KYAA) | | | | Proves: WHO | | Proves: IS IT | | Proves: IS THIS ACTION | | Runs tool / API | | | | ALLOWED? | | LEGITIMATE? | | | | Sumsub, Entrust, | | Google AP2, FIDO, | | EthersFlow (Ed25519 | | Agent runtime | | Persona | | OAuth mandates | | Signed Trust Verdict) | | rails | +-------------------+ +-------------------+ +-------------------------+ +-------------------+

Identity answers *who*. Authorization answers *is it allowed*. EthersFlow answers: *is this specific action legitimate?*

   +-------------------------------------------------------------+

| Agent Host / MCP Client Environment | | (Claude Desktop · Cursor · LangChain · Custom Agent) | +------------------------------+------------------------------+ | MCP Tool Call: verify_agent_action v +-------------------------------------------------------------+ | @ethersflow/mcp-server (stdio / SSE / HTTP) | +------------------------------+------------------------------+ | HTTPS /api/v1/verify v +-------------------------------------------------------------------------------+ | EthersFlow Action-Verification Gateway (KYAA) | | | | +-----------------------+ +-------------------------------+ | | | Deterministic Kernel | (fast-path) | Adversarial Frontier Council | | | | & Catalog Matcher | ------------> | (Heterogeneous LLM Panel) | | | +-----------+-----------+ +---------------+---------------+ | | | | | | +---------------------+---------------------+ | | | | | v | | +---------------------------+ | | | Ed25519 Signature Engine | | | +-------------+-------------+ | +-------------------------------------+-----------------------------------------+ | Ed25519-Signed Verdict Receipt v +-----------------------------------------------+ | APPROVED / FLAGGED / REJECTED Decision Gate | | (Agent halts or executes) | +-----------------------------------------------+

Latency Profile & Performance Benchmarks

EthersFlow operates a dual-lane execution engine balancing rapid determinism with multi-model adversarial deliberation:

Structuring Defense & Automatic Escalation: To prevent autonomous agents from splitting large operations into multiple micro-transactions to bypass policy controls, requests that exceed safety thresholds or exhibit anomalous frequency automatically escalate from the deterministic Fast Path to the multi-model Consensus lane for thorough deliberation.

Policy-Driven Thresholds: Fast-path ceilings (e.g. low-risk micro-expenses <$100), approved vendors, and ticket anchor requirements (e.g. Jira, ServiceNow, Ops tickets) are enforced via policy profiles (such as finops_default_v1), ensuring deterministic speed for routine actions and multi-model defense for high-stakes edge cases.

Retention Architecture & Audit Logging

EthersFlow unifies audit compliance with strict data privacy through a receipt-persist + payload-discard model:

• Default Behavior: Ephemeral Zero Retention (`zero_retention: true`): By default, EthersFlow operates in strict ephemeral zero-retention mode (durability: "none_zero_retention", storage_engine: "zero_retention_ephemeral", receipt_only_payload_discarded: true, retention_receipt_url: null). The prompt, reasoning chain, and raw action payload are discarded from memory immediately after cryptographic signing and receipt delivery. No action text is stored anywhere.

• Opt-In Durable Audit Vault (`retention_mode: "durable"` or `zero_retention: false`): When durable audit logging is explicitly requested for enterprise compliance, callers pass retention_mode: "durable" or zero_retention: false:

  {

"agent_action": "Order $42 notebooks from Staples under ticket FAC-902", "zero_retention": false }

  This persists the cryptographic receipt to the durable audit vault (`durability: "durable_audit_log"`, `storage_engine: "firestore_durable"`, `retention_receipt_url: "/api/v1/receipts/{request_id}"`).

• Cryptographic Action Hash Binding (Zero Payload Leakage): Strict Privacy Invariant: In both ephemeral and durable modes, EthersFlow binds ONLY the SHA-256 action hash (action_hash: sha256(agent_action)). Raw prompt and action text are never persisted to the database vault. An auditor can verify the Ed25519 signature on the decision without exposing sensitive business prompts to storage breaches. Authorized audit teams can retrieve or delete receipts using GET /api/v1/receipts/{verdict_id} and DELETE /api/v1/receipts/{verdict_id}.

Canonical Policy IDs

Every EthersFlow decision receipt binds a canonical policy_id across both top-level metadata (receipt.policy_id) and the signed configuration tuple (receipt.receipt_v2.config_tuple.policy_id):

Enforcement vs. Advisory Positioning

EthersFlow provides a hybrid enforcement and advisory architecture:

1. Deterministic Enforcement Gates (Fail-Closed by Default):

• High-risk operations, prompt injections, and grounding contradictions receive an unconditional REJECTED or FLAGGED_HUMAN_REVIEW verdict with approval_blocked: true.
• Gate wrappers like cloudflareVerifyGate in @ethersflow/sdk or execution bindings (POST /api/v1/binding/confirm) strictly halt agent execution unless an active, cryptographically signed approval receipt exists.
• Strict Fail-Closed Guarantee: If an internal gateway error, network partition, or upstream timeout occurs, EthersFlow always fails closed (returning verdict: "REJECTED", approval_blocked: true, status 502/503). The gateway never approves without cryptographic verification.

1. Advisory Multi-Model Consensus:

• For subjective or borderline decisions, the gateway provides rich multidimensional telemetry: consensus_score, risk_index, and signed individual perspectives across heterogeneous models.
• Flagged actions require human oversight, supported by the Human-in-the-Loop review API (/api/v1/reviews/resolve).

What's Included

This repository contains the official client surfaces and developer tools for the EthersFlow ecosystem:

*Note: The core Federated Adversarial Consensus engine operates with default receipt-only persistence and payload discard (verdicts, reason codes, action hashes, and Ed25519 signatures retained; raw action payloads discarded immediately after signing). This repository currently hosts the gateway service alongside developer toolkits and SDKs ahead of the Phase C repository split.*

5-Minute Quickstart

1. cURL API Call (Fastest Proof)

curl -X POST "https://www.ethersflow.com/api/v1/verify" \

-H "Authorization: Bearer $ETHERSFLOW_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent_action": "Transfer 5000 USDC to wallet 0x9f for smart contract audit", "persona_preset": "financial_compliance", "agent_count": 3 }'

2. Python SDK & Zero-Dependency Ver