Ledger Integration

ENShell integrates with Ledger at two levels: an ERC-7730 clear-signing descriptor that makes firewall transactions human-readable on-device, and a Ledger Live app for agent management directly inside Ledger Live.

ERC-7730 Clear Signing

ERC-7730 defines a standard for describing smart contract calldata in human-readable form. ENShell provides a clear-signing descriptor that Ledger devices use to display meaningful transaction details instead of raw hex data.

The descriptor lives at erc7730/calldata-AgentFirewall.json in the contract repository and passes erc7730 lint validation.

Supported Functions

Function Intent Label Displayed Fields
registerAgentSimple "Register AI Agent" Agent ID, Agent Wallet, Spend Limit (ETH)
submitAction "Submit Action for Analysis" Agent, Target, Value (ETH)
approveAction "Approve Escalated Action" Action ID
rejectAction "Reject Escalated Action" Action ID
deactivateAgent "Freeze Agent" Agent ID
reactivateAgent "Reactivate Agent" Agent ID

When a user signs any of these transactions with a Ledger device, the device screen shows the human-readable intent and field values instead of raw calldata. This is especially important for approveAction and rejectAction, where the user is making a security decision.

Example: On-Device Display

When approving an escalated action:

Approve Escalated Action
Action ID: 42

When registering an agent:

Register AI Agent
Agent ID: my-trader
Agent Wallet: 0x7a25...488D
Spend Limit: 1.0 ETH

Ledger Live App

The ENShell Ledger Live app is a Next.js application that runs inside Ledger Live Desktop, providing agent management through the Ledger Wallet API.

Stack: Next.js + React + TypeScript + Ledger Wallet API

Features

  • Agent list -- Displays all agents registered by the connected Ledger wallet (filtered by owner field)
  • Freeze / Activate -- Toggle agent status with hardware wallet signing
  • Register Agent -- Create new agents with spend limits and wallet addresses
  • Empty state -- Clean message when no agents are associated with the connected wallet

All transactions are signed on the Ledger device itself. Combined with the ERC-7730 descriptor, users see exactly what they're approving.

How to Test

  1. Enable Developer Mode in Ledger Live Desktop:

    • Settings > About > click the version number 10 times
    • Go to the Developer tab that appears

  2. Add the local app:

    • Click "Add a local app"
    • Browse to public/manifest.json in the enshell-ledger-live repository

  3. Run the dev server:

cd ~/www/enshell-ledger-live
npm run dev  # Port 3000
  1. Open ENShell in Ledger Live and connect an Ethereum account

Wallet API Integration

The app uses the Ledger Wallet API to:

  • Get connected accounts -- reads the active Ethereum account from the Ledger device
  • Sign transactions -- routes transaction signing through the physical device
  • Filter agents -- matches the connected account address against agent owner fields on-chain

Architecture Note

The Ledger Live app connects to the same AgentFirewall contract on Sepolia. When a user freezes or activates an agent through Ledger Live, it's the same deactivateAgent() / reactivateAgent() contract call that the CLI uses -- just signed via the Ledger device instead of WalletConnect or an environment private key.

The app manifest (public/manifest.json) configures Ledger Live to load the app from http://localhost:3000 during development. For production, this would point to a hosted URL.

Using Ledger with the CLI

If your Ledger is connected via WalletConnect (through Ledger Live's WalletConnect support or MetaMask with a Ledger hardware wallet), the CLI works seamlessly:

enshell connect  # Scan QR with Ledger-connected wallet
enshell protect --id my-agent --target 0x... --value 0.05 --instruction "..."

The CLI shows "approve in your wallet" during transaction signing. The Ledger device displays the ERC-7730 clear-signed transaction details for review.

For escalated actions, the full flow is:

  1. CLI displays Claude's analysis
  2. User types y to approve
  3. CLI sends approveAction() transaction
  4. Ledger device shows "Approve Escalated Action - Action ID: 42"
  5. User confirms on-device
  6. Transaction is broadcast

This provides a complete security chain: AI analysis (Claude) + human review (CLI display) + hardware attestation (Ledger signing).