A capability-based delegation system built on ERC-7579 modular account abstraction. Each user instantiates a smart-contract account via SHFactory and grants scoped, time-bounded, rate-limited signing authority to ephemeral session keys — enabling an autonomous agent to construct and authorize transactions on the owner's behalf from natural-language instructions, without gaining custody of the owner's root private key. Session keys can be scoped to ERC20 primitives (transfer, approve) and DeFi primitives such as Uniswap/PancakeSwap V2 swaps and liquidity provisioning, with spend caps enforced in USD terms via Chainlink price feeds.
The protocol is composed of five layers: Solidity smart contracts, a Python blockchain interface, HashiCorp Vault (key custody), a LangChain AI agent, and a Telegram bot front end. It also integrates the ERC-8004 canonical on-chain agent identity and reputation registries.
┌─────────────────────────────────┐
│ User Interface │ ← User sends natural language messages
├─────────────────────────────────┤
│ LangChain AI Agent │ ← Claude LLM reasons and selects tools
├─────────────────────────────────┤
│ Blockchain Interface │ ← web3.py builds and submits UserOps
├─────────────────────────────────┤
│ ERC-7579 Smart Contracts │ ← SessionHandler (account) + SessionHandlerModule (session logic)
├─────────────────────────────────┤
│ HashiCorp Vault (Docker) │ ← Transit encrypt/decrypt for session keys
└─────────────────────────────────┘
Network support: Anvil (local), Ethereum mainnet fork, Sepolia fork, live Sepolia testnet, BSC (mainnet + fork, via PancakeSwap V2). Celo has partial Python-side scaffolding but no Solidity deployment path yet — see docs/app.md.
User (Telegram / CLI)
│ natural language
▼
LangChain AI Agent
│ signs UserOps with scoped session keys (via HashiCorp Vault)
▼
ERC-4337 EntryPoint
│ validateUserOp / preCheck+execute
▼
SessionHandler (per-user ERC-7579 smart account)
├─ delegates session-key logic ──▶ SessionHandlerModule (Validator + Hook)
│ ├─ reads config at runtime ──▶ SHRegistry
│ │ (fee, treasury, oracle, agentId, router, interpreter)
│ └─ USD computation ──────────▶ SHValueInterpreter → SHOracle (Chainlink)
├─ protocol fee ─────────────▶ SHTreasury (owns SHRegistry)
└─ identity / reputation ────▶ ERC-8004 Registries
SHFactory (deploys new SessionHandlers on demand, installs SessionHandlerModule as both Validator + Hook)
SHTreasury (protocol operator — owns SHRegistry)
└── SHRegistry (fee, treasury, oracle, agentId, router, interpreter)
├── SHOracle (Chainlink USD price feeds)
└── SHValueInterpreter (calldata → USD debit/credit)
SHFactory (user-facing factory)
└── SessionHandler (per-user ERC-7579 smart account, sequential walletId)
installs (Validator + Hook) ──▶ SessionHandlerModule
(all session-key state and USD enforcement)
reads ──▶ SHRegistry (via SessionHandlerModule, at execution time)
pays ──▶ SHTreasury (protocol fee per session-key execution)
- Foundry
- Docker Desktop — required for HashiCorp Vault
- Python 3.12+
- A Telegram bot token (from @BotFather)
- An Anthropic API key (or any LangChain-supported LLM provider)
- An Alchemy API key (required for live Sepolia, mainnet fork, and BSC fork)
git clone https://github.com/Conrad-sudo/sh-protocol.git
cd sh-protocol
# Foundry dependencies
forge install
# Python dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtNo Node/npm install step is required —
SHOracleuses Chainlink price feeds (lib/chainlink-brownie-contracts, installed viaforge install), not a JS-toolchain dependency.
| Document | Contents |
|---|---|
| docs/contracts.md | Smart contract architecture — all contracts, test suite, Foundry commands |
| docs/app.md | Python app layer — LangChain agent, blockchain interface, Telegram bot |
| docs/vault-security.md | Environment variables, Vault/Docker setup, session key security model |
| docs/setup.md | Local setup (Anvil, mainnet fork, Sepolia fork) and live Sepolia deployment |
| docs/reference.md | Makefile reference, full project structure, dependencies |