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 issues cryptographically signed, independently verifiable trust verdicts for AI agent actions before execution, providing dual-control verification and cryptographic audit trails.

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 (~20-30x speedup) with multi-model adversarial deliberation:

Execution Lane	p50 Latency	p95 Latency	Mechanism	Guarantee & Finality
Policy Fast Path	0.45 s	2.4 s	Deterministic safety kernel & catalog matcher (<$100, allowlisted vendor, operational ticket, pre-fast-path intent screen).	`POLICY_FAST_PATH_APPROVAL`
Idempotent Replay	3.2 ms	4.5 ms	Sub-millisecond deduplication on repeated `idempotency_key` and action hash.	`replayed: true`
Adversarial Consensus	11.2 s	28.6 s	Live multi-model debate across heterogeneous frontier models (Qwen, Llama, Gemini) with cryptographic node attestations.	`POLICY_SUPERMAJORITY_APPROVAL` / `POLICY_FINAL_BLOCK`

Velocity Capping & Preconditions: Operational tickets (e.g. FAC-101) have an automated allowance of 5 fast-path approvals per 24 hours ($500 cap). The velocity cap counts attempts (stateful), requiring a proper 5-purchase precondition on a fresh ticket for verification. When this threshold is reached, subsequent requests automatically fall back to the live multi-model consensus lane to prevent micro-expense structuring attacks. Full empirical data is published in docs/calibration-benchmark.md.

Launch Architecture Principle: "The deterministic fast path plus signed receipt is the provable core; consensus is escalation telemetry whose semantic detection is confirmed (3/3 on kernel-invisible attacks) but conditionally reachable — under measurement, published."

Retention Architecture & Audit Logging

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

Default Behavior (Receipt-Only Persistence): By default, EthersFlow persists the receipt artifact only (verdict, normalized hashes, Ed25519 cryptographic signature, reason codes, request ID — NO raw action text). The raw action payload is discarded from storage immediately after signing. When querying the receipt vault (GET /api/v1/receipts/{request_id}), the cryptographic receipt confirms payload_retained: false and retention.policy: "receipt_only_payload_discarded". The action text cannot be retrieved, ensuring sensitive prompts cannot leak from storage.
Explicit Opt-In Audit Retention (zero_retention: false): If full action payload retention is strictly required for compliance audit logs, clients must explicitly opt in per call:
```
{
  "agent_action": "Order $42 notebooks from Staples under ticket FAC-902",
  "zero_retention": false
}
```
This creates an audit record logged in the receipt (retention.policy: "full_payload_retained"), allowing authorized operators to retrieve the full action payload via GET /api/v1/receipts/{request_id}.
Ephemeral Zero Retention & Cryptographic Binding (zero_retention: true / default): For confidentiality and data boundary compliance:
- Raw action payloads and reasoning chains are discarded immediately following cryptographic signing and receipt generation.
- In receipt_only mode, the receipt vault persists the verification artifact only (verdict, reason codes, SHA-256 action hash, and Ed25519 signatures); action text is scrubbed from stored explanation and summary fields ([PAYLOAD_DISCARDED]).
- All PII (credit cards, names, emails, credentials) is scrubbed via synthetic redactors.
- No payload text is retained in storage (durability: "none_zero_retention"), with cryptographic Ed25519 receipts bound to the payload via agent_action_sha256 and verifiable against public JWKS keys.

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):

Policy ID	Description	Default Rules & Thresholds
`finops_default_v1`	Default Enterprise FinOps Safety Policy	Dual-lane evaluation: Micro-expense fast-path (<$100, approved catalog vendor, ticket anchor, 5 approvals/24hr window) and multi-model consensus fallback.
`tripwire_circuit_breaker_v1`	High-Assurance Circuit Breaker Policy	Immediate fail-closed tripping on anomalous wire transfers, credential exfiltration, prompt injection patterns, or authority bypasses.

Enforcement vs. Advisory Positioning

EthersFlow provides a hybrid enforcement and advisory architecture:

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.
- If an internal gateway error occurs, EthersFlow fails closed by default (verdict: REJECTED, status: 500/503) unless fail_mode: "fail-open" is explicitly opted into by the caller.
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:

Surface	Path	Description
MCP Server	`/mcp-server`	Model Context Protocol server for Claude Desktop, Cursor, and MCP clients
Python Demo & Verifier	`efverify.py`	Zero-dependency pure-Python client and Ed25519 signature validator
Python SDK	`/sdk/python`	Native Python package & LangChain tool wrapper
TypeScript SDK	`/sdk/typescript`	TypeScript SDK + Cloudflare Worker middleware helper
Postman Collection	`/postman`	11-request Postman collection + environment variables

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 Verifier

Install via pip:

pip install ethersflow

Or run the included zero-dependency reference script:

python efverify.py verify "Transfer 5000 USDC to wallet 0x9f for smart contract audit"

3. Model Context Protocol (MCP) Server

Option A: Via NPX (Recommended)

npx -y @ethersflow/mcp-server --api-key=YOUR_API_KEY

Option B: Remote HTTP / SSE Gateway (Zero Local Dependencies)

Connect your MCP client directly to EthersFlow's production endpoint with connection-level authentication:

Endpoint: https://www.ethersflow.com/api/mcp
Connection Header: Authorization: Bearer YOUR_API_KEY
RFC 9728 / OAuth Resource Metadata: In accordance with RFC 9728, unauthenticated requests return HTTP 401 with WWW-Authenticate: Bearer realm="ethersflow-gateway", resource_metadata="/.well-known/oauth-protected-resource". Tool calls without authorization cleanly emit structured JSON-RPC -32000 (MISSING_AUTHORIZATION) errors with preserved request IDs.
Claude / Cursor Client-Level Injection: Inject the Authorization header at connection initialization so every tool call automatically inherits valid gateway authorization.

Option C: Claude Desktop Configuration

{
  "mcpServers": {
    "ethersflow": {
      "command": "npx",
      "args": ["-y", "@ethersflow/mcp-server"],
      "env": {
        "ETHERSFLOW_TOKEN": "YOUR_API_KEY",
        "ETHERSFLOW_BASE_URL": "https://www.ethersflow.com"
      }
    }
  }
}

Option D: From source

git clone https://github.com/Ethersflow/EthersFlow.git
cd EthersFlow/mcp-server
npm install
npm start

Fast-Path Diagnostics & Anchor Remediation (Naive-Phrasing UX)

EthersFlow evaluates requests across two primary execution lanes:

FAST_PATH (<1s, ~470ms server): Deterministic, synchronous policy verification for low-risk micro-expenses (under $100) anchored by verified operational artifacts.
CONSENSUS (~11–14s): Multi-model adversarial cross-examination across independent LLM nodes.

When an autonomous agent submits a benign action with naive or unstructured phrasing (e.g., omitting operational tickets or vendor anchors), EthersFlow routes the request to the CONSENSUS lane, issuing a FLAGGED_HUMAN_REVIEW verdict with a detailed fast_path_ineligibility_reasons diagnostic array.

Worked Example: Diagnosing and Remediating a Naive Request

Step 1: The Naive Benign Request

A developer or agent submits an unanchored micro-expense:

POST /api/v1/verify
{
  "agent_action": "Order pens and paper for the team"
}

Step 2: The Diagnostic Response

Because the request lacks structured anchors, it cannot be fast-pathed and is flagged for review:

{
  "verdict": "FLAGGED_HUMAN_REVIEW",
  "policy_fast_path": false,
  "lane": "CONSENSUS",
  "fast_path_ineligibility_reasons": [
    "AMOUNT_UNDETERMINED: Action text does not specify a parseable dollar amount or amount_usd in context.",
    "TICKET_MISSING: Operational ticket anchor (e.g. FAC-*, OPS-*, JIRA-*) missing from context and action.",
    "COUNTERPARTY_UNVERIFIED: Counterparty missing or not verified against approved catalog allowlist.",
    "BUDGET_LINE_MISSING: Spend category, scope, or budget line allocation missing from context."
  ]
}

Step 3: Reading the Diagnostic Reasons & Supplying Missing Anchors

The developer or agent loop inspects fast_path_ineligibility_reasons and supplies the four missing operational anchors:

Amount: Provide dollar amount in action text ("$10 of pens") or in context.amount_usd: 10.00.
Ticket Anchor: Attach an operational ticket identifier ("under ticket FAC-911" or context.ticket: "FAC-911").
Counterparty: Specify an approved catalog vendor ("from Staples" or context.vendor: "Staples").
Scope / Budget Allocation: Define the procurement scope (context.scope: "routine_office_supplies" or context.budget_line: "office_supplies_q3").

Step 4: The Remediated Fast-Path Request

POST /api/v1/verify
{
  "agent_action": "Order $10 of pens from Staples under ticket FAC-911",
  "context": {
    "ticket": "FAC-911",
    "vendor": "Staples",
    "scope": "routine_office_supplies"
  }
}

Step 5: Immediate Sub-Second Fast-Path Approval

{
  "verdict": "APPROVED",
  "policy_fast_path": true,
  "lane": "FAST_PATH",
  "fast_path_ineligibility_reasons": [],
  "consensus_score": 96.8,
  "risk_index": 1.5,
  "latency_ms": 472,
  "attestation": {
    "status": "VERIFIED_ED25519_SIG",
    "key_id": "ef_attest_v3"
  }
}

Idempotency & Replay Semantics (B3 Dedup Surface)

EthersFlow implements opt-in deduplication at the verification boundary to support both high-throughput distributed agent swarms and explicit, intentional re-verifications:

1. Default Behavior: Fresh Execution (Dedup is Opt-In)

When duplicate actions are submitted without an idempotency_key:

EthersFlow evaluates each request freshly through the verification engine.
Every invocation generates a new cryptographic signature and unique request_id.
Response indicates replayed: false and c2_replayed: false.

2. Opt-In Deduplication (`idempotency_key`)

To prevent duplicate financial disbursements, API calls, or ticket mutations across retrying agents, include an idempotency_key (via JSON body idempotency_key or HTTP header Idempotency-Key / X-Idempotency-Key):

Initial Verification: Evaluates the action, generates the Ed25519 attestation, commits the receipt, and caches the result (replayed: false, replay_index: 0).
Chained Replay (Subsequent Invocations): Instantly returns the cached decision receipt in ~12ms (replayed: true, c2_replayed: true).
Chained Replay Index: Each replayed call increments replay_index (1, 2, ...), creates a distinct audit transaction ID, while preserving the reference to original_request_id and the immutable action_hash.

# First Call (Fresh Verification ~470ms Fast-Path or ~14s Consensus)
curl -X POST https://www.ethersflow.com/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: agent-step-uuid-101" \
  -d '{"agent_action": "Order $10 of pens from Staples under ticket FAC-911"}'
# Response: {"request_id": "req_a1b2...", "replayed": false, "replay_index": 0, ...}

# Second Call (Instant Replay ~12ms)
curl -X POST https://www.ethersflow.com/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: agent-step-uuid-101" \
  -d '{"agent_action": "Order $10 of pens from Staples under ticket FAC-911"}'
# Response: {"request_id": "req_c3d4...", "original_request_id": "req_a1b2...", "replayed": true, "replay_index": 1, ...}

Retention Architecture & Derived Fields Policy (N2 & N4)

EthersFlow strictly distinguishes between raw unparsed action payloads and derived operational audit metadata:

Derived Fields are Non-Payload Audit Metadata (N2)

Derived Fields: Attributes deterministically extracted by policy rules (e.g. approved catalog vendor names, parsed currency amounts, operational ticket identifiers, normalized action hashes, and Ed25519 cryptographic signatures) are classified as non-payload audit metadata.
Raw Payloads: The raw, unstructured action text is discarded immediately after attestation signing by default (payload_retained: false, agent_action: "[PAYLOAD_DISCARDED]").
Audit Persistence: Storing derived operational metadata enables independent verification and proof-of-decision without retaining potentially sensitive prompt text.

Retention Honesty per Decision State (N4)

Fast-Path Approvals: Default receipt-only persistence (retention.policy: "receipt_only_payload_discarded", perspectives_retained: false).
Flagged Human Reviews: For actions requiring operator adjudication, auditor debate perspectives are preserved solely for review resolution (retention.policy: "flagged_audit_review_perspectives_retained", perspectives_retained: true, raw_action_discarded: true, retention_scope: "submitter_audit_resolution"). Neither path retains raw action payloads.

Status & Known Limitations

Ed25519-Signed Audit Trail: Every audit node output is signed using Ed25519-EdDSA. Signatures can be verified independently against /.well-known/jwks.json with zero trust required in EthersFlow's servers.
Probabilistic, Not Deterministic: Borderline or ambiguous actions (e.g., high-value wire transfers or missing compliance records) evaluate near decision thresholds (APPROVED <-> FLAGGED_HUMAN_REVIEW). We strongly recommend routing any FLAGGED_HUMAN_REVIEW verdict directly to human operators for sign-off.
Live Model Engine: Powered by heterogeneous inference nodes across independent providers (Llama 3.3 70B Instruct via Groq, Qwen 3.6 27B / Qwen 3.8 27B, and Gemini 3.7 Flash) with active pipeline routing and automated failover. Multi-provider custom BYOK model routing is under continuous expansion.
Gateway Architecture & Repository Evolution: The core Federated Adversarial Consensus backend operates as a secure API service with default receipt-only persistence and payload discard (verdicts, reason codes, action hashes, and Ed25519 signatures retained; raw action payloads discarded immediately after signing). Currently, this repository hosts the gateway service alongside developer toolkits and SDKs; backend engine code will be segregated into a dedicated repository in Phase C.

Key Features

Multi-Model Consensus: Eliminates single-model bias by forcing heterogeneous models into adversarial debate.
Ed25519 Attestation: Every debate node output is signed with an Ed25519 cryptographic key. Public key set available at /.well-known/jwks.json.
Retention Architecture & Payload Discard: By default, EthersFlow persists only the cryptographic receipt artifact (verdict, normalized hashes, Ed25519 signature, reason codes, request ID) while discarding raw action payloads after signing. Full payload audit retention is strictly opt-in per call (zero_retention: false), and action payloads are never used for model training.
OpenAI & Anthropic Drop-In Proxies: Use /v1/chat/completions or /v1/messages as a drop-in replacement for existing agent pipelines.
Specialized Personas:
- financial_compliance (FINRA/SEC, wire limits, KYC, sanctions)
- clinical_safety (ISMP high-alert meds, dosage bounds, FDA)
- cybersecurity_auditor (NIST SP 800-53, privilege escalation, SOC 2)
- legal_citation (FCPA, evidentiary privilege, contract breach)
- general_adversarial (Cross-domain safety & logic verification)

Framework Integrations

LangChain (Python)

import os
from ethersflow import EthersFlowLangChainTool

verifier_tool = EthersFlowLangChainTool(api_key=os.getenv("ETHERSFLOW_API_KEY", "your_api_key"))

# Add to your LangChain agent tools
tools = [verifier_tool]

Cloudflare Workers / Agents SDK (TypeScript)

import { cloudflareVerifyGate } from '@ethersflow/sdk';

export default {
  async fetch(request: Request, env: { ETHERSFLOW_API_KEY: string }) {
    const isSafe = await cloudflareVerifyGate(
      "Transfer 5000 USDC to wallet 0x9f",
      "Vendor audit payment",
      env.ETHERSFLOW_API_KEY
    );

    if (!isSafe) {
      return new Response("Action blocked by EthersFlow Consensus Gate", { status: 403 });
    }

    // Proceed with execution
  }
};

Security & Ed25519 Attestation

EthersFlow publishes its public key set in JSON Web Key Set (JWKS) format:

JWKS Endpoint: GET /.well-known/jwks.json
Attestation Manifest: GET /.well-known/attestation.json
Verification Endpoint: POST /api/v1/verify-attestation

You can verify signatures locally or through the API to prove that every audit node's perspective originated directly from the EthersFlow signing authority.

Held-Out Adversarial Evaluation & Calibration Anti-Circularity

To ensure empirical rigor and prevent circular evaluation (testing against samples seen during development), EthersFlow maintains an independently developed held-out test battery:

Author: Independent Red Team & AI Safety Consortium.
Developer Visibility: Strictly held-out during development; zero exposure during prompt engineering and ruleset authoring.
Independent Acceptance QA: Independent acceptance QA in progress.

Postman Collection

Import postman/ethersflow.postman_collection.json and postman/ethersflow.postman_environment.json into Postman to test all 11 core endpoints instantly.

Links & Community

MCP Listings

Official MCP Registry: https://registry.modelcontextprotocol.io (search "Ethersflow")
Smithery: https://smithery.ai/servers/ethersflow-dev/ethersflow
Glama: https://glama.ai/mcp/servers/Ethersflow/EthersFlow

License

Code & SDK wrappers licensed under MIT License. Hosted EthersFlow API services subject to Terms of Service.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
mcp-server		mcp-server
postman		postman
public		public
sdk		sdk
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
efverify.py		efverify.py
llms-install.md		llms-install.md
server.json		server.json
smithery.yaml		smithery.yaml

Latest commit

History

Folders and files

Repository files navigation