Architecture Overview

ENShell is a four-layer pipeline that intercepts AI agent actions before they reach the blockchain. Each layer adds a security guarantee, and together they ensure that no instruction executes without encryption, analysis, and (when needed) human approval.

The Four Layers

  Layer 1: SDK / CLI
  ┌─────────────────────────────────────────────┐
  │  protect() → encrypt instruction (ECIES)    │
  │  → store encrypted payload on relay          │
  │  → submit instructionHash on-chain           │
  └──────────────────┬──────────────────────────┘
                     │
  Layer 2: Smart Contract (AgentFirewall)
  ┌──────────────────┴──────────────────────────┐
  │  Policy checks (frozen? exists? owner?)      │
  │  Queue action → emit ActionSubmitted event   │
  └──────────────────┬──────────────────────────┘
                     │
  Layer 3: CRE Workflow (Chainlink)
  ┌──────────────────┴──────────────────────────┐
  │  Fetch encrypted payload from relay          │
  │  Decrypt inside CRE (ECDH + AES-256-GCM)    │
  │  Claude analysis via Confidential HTTP       │
  │  Write verdict on-chain via onReport()       │
  └──────────────────┬──────────────────────────┘
                     │
  Layer 4: Human-in-the-Loop
  ┌──────────────────┴──────────────────────────┐
  │  If ESCALATED: CLI/Ledger shows analysis     │
  │  Owner approves or rejects with wallet       │
  └─────────────────────────────────────────────┘

Action Lifecycle

Every protected action follows this exact flow:

1. Encrypt and Submit

The SDK's protect() method:

Hashes the instruction: instructionHash = keccak256(instruction)
Encrypts the instruction with the oracle's public key using ECIES (secp256k1 ECDH + AES-256-GCM)
Stores the encrypted payload on the relay at PUT /relay/{instructionHash}
Calls submitAction(agentId, target, value, data, instructionHash) on the contract

The instruction plaintext never touches the blockchain. Only its keccak256 hash appears in the ActionSubmitted event.

2. Queue and Emit

The smart contract:

Verifies the agent exists, is active, and has not exceeded max strikes
Verifies msg.sender is the agent's owner
Queues the action with decision = PENDING (0)
Emits ActionSubmitted(actionId, agentId, target, value, instructionHash)

3. Analyze

The CRE workflow (running as compiled WASM on oracle nodes):

Triggered by the ActionSubmitted event
Fetches the encrypted payload from the relay using the instructionHash
Decrypts using the oracle's private key (stored in Chainlink's Vault DON, threshold-encrypted)
Sends the plaintext instruction to Claude via Confidential HTTP
Claude returns a threat score (0-100,000) and decision
Posts the analysis to the relay for dashboard display
Writes the verdict on-chain via onReport() through the KeystoneForwarder

4. Resolve

Based on Claude's score:

Score Range	Decision	What Happens
0 - 29,999	APPROVED	Action resolves automatically. Threat score updated via EMA.
30,000 - 69,999	ESCALATED	Action paused. Owner must approve or reject.
70,000 - 100,000	BLOCKED	Action rejected automatically. Strike incremented.

For escalated actions, the CLI displays Claude's full analysis (score, reasoning, target, value) and prompts the owner for a decision. Ledger Live provides the same capability with hardware wallet signing.

Shared Ecosystem Model

ENShell uses a single firewall contract that anyone can register agents on. This is a deliberate design choice:

Access control is per-agent -- each agent has an owner field set to msg.sender during registration. Only the owner can submit actions, approve/reject escalations, or freeze/activate their agents.
Reputation is network-wide -- threat scores and strike counts are visible to all participants. An agent that consistently submits malicious instructions builds a bad reputation that the entire ecosystem can see.
Trust is composable -- any agent can check the trustworthiness of any other agent via checkTrust(). Trust events are recorded on-chain and visible through ENS text records.

This creates a network effect: the more agents participate, the more valuable the trust mesh becomes.

Data Flow: What Goes Where

Data	Location	Visibility
Instruction plaintext	CRE runtime only (during analysis)	Oracle nodes only, via Confidential HTTP
Encrypted instruction	Relay (24h TTL, in-memory)	Anyone with the hash (encrypted, useless without oracle key)
Instruction hash	On-chain (ActionSubmitted event)	Public
CRE analysis	Relay + on-chain (decision + score)	Public
Threat score	On-chain + ENS text records	Public
Agent metadata	On-chain + relay	Public

The critical insight: the instruction plaintext exists only inside the CRE workflow during the brief window of analysis. Before analysis, it's encrypted. After analysis, only the score and decision persist.

Key Addresses (Sepolia)

Contract	Address
AgentFirewall	`0x410f4D119EF857879E42625381DB131457db78A7`
KeystoneForwarder (Chainlink)	`0x15fC6ae953E024d975e77382eEeC56A9101f9F88`
ENS NameWrapper	`0x0635513f179D50A207757E05759CbD106d7dFcE8`
ENS Public Resolver	`0xE99638b40E4Fff0129D56f03b55b6bbC4BBE49b5`

Architecture Overview

#The Four Layers

#Action Lifecycle

#1. Encrypt and Submit

#2. Queue and Emit

#3. Analyze

#4. Resolve

#Shared Ecosystem Model

#Data Flow: What Goes Where

#Key Addresses (Sepolia)