🛡️ Aegis Protocol

AI-Powered Autonomous DeFi Guardian Agent for BNB Chain

An autonomous AI agent — powered by LLM reasoning (Groq/OpenAI) + PancakeSwap on-chain data — that monitors your DeFi positions on BNB Chain 24/7, detects risks in real-time, and executes protective on-chain transactions before you lose money.

🌐 Live Dashboard · � Demo Video · �📜 Verified Contracts · 🧪 13 On-Chain TXs · 🤖 AI Build Log

Architecture · AI Engine · On-Chain Proof · Smart Contracts · Quick Start · AI Build Log

🎯 The Problem

DeFi users lose billions annually to rug pulls, flash loan attacks, liquidity drains, and price crashes. These losses happen when users aren't watching — overnight, during work, or because market conditions change faster than humans can react.

Pain Point	Status Quo	Aegis Solution
Monitoring	Manual, intermittent	AI-powered 24/7 autonomous monitoring
Threat Detection	Simple price alerts	5-vector heuristic + LLM reasoning + DEX data
Response Time	Minutes to hours	Sub-second autonomous execution
Custody	Surrender keys	Fully non-custodial (emergency exit always available)
Transparency	Black box	Every decision immutably logged on-chain with reasoning hash
Customization	One-size-fits-all	Per-user risk profiles (slippage, stop-loss, auto-actions)
Agent Identity	Anonymous bots	ERC-721 NFT agent identity with reputation scoring

💡 What Aegis Does

Aegis is a fully autonomous AI guardian agent that runs a continuous loop:

OBSERVE → ANALYZE → AI REASON → DEX VERIFY → DECIDE → EXECUTE

👁️ OBSERVE — Fetches live BNB price, volume, liquidity from CoinGecko + DeFiLlama
🧠 ANALYZE — 5-vector weighted risk scoring (price 30%, liquidity 25%, volume 15%, holders 15%, momentum 15%)
🤖 AI REASON — LLM-powered analysis via Groq (Llama 3.3 70B) or OpenAI (GPT-4o) with structured JSON output
📊 DEX VERIFY — Cross-references CoinGecko prices against PancakeSwap V2 on-chain reserves for price manipulation detection
⚡ DECIDE — Threat classification with confidence scoring; hashes both heuristic + LLM reasoning for on-chain attestation
🛡️ EXECUTE — Autonomous protective transactions (stop-loss, emergency withdrawal, rebalance) per user-defined risk profiles

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                         AEGIS PROTOCOL                               │
│                                                                      │
│   ┌────────────┐   ┌───────────────┐   ┌──────────────┐             │
│   │  OBSERVE   │──▶│   ANALYZE     │──▶│  AI REASON   │             │
│   │            │   │               │   │              │             │
│   │ CoinGecko  │   │ 5-Vector      │   │ Groq LLM    │             │
│   │ DeFiLlama  │   │ Risk Engine   │   │ (Llama 3.3  │             │
│   │ BSC RPC    │   │ (449 LOC)     │   │  70B) or     │             │
│   └────────────┘   └───────────────┘   │ OpenAI GPT-4o│             │
│                                         └──────┬───────┘             │
│   ┌────────────┐   ┌───────────────┐          │                     │
│   │ DEX VERIFY │──▶│    DECIDE     │◀─────────┘                     │
│   │            │   │               │                                │
│   │ PancakeSwap│   │ Threat        │   ┌──────────────┐             │
│   │ V2 Router  │   │ Detection +   │──▶│   EXECUTE    │             │
│   │ (On-chain) │   │ Confidence    │   │              │             │
│   └────────────┘   └───────────────┘   │ On-chain TXs │             │
│                                         └──────┬───────┘             │
│   ┌─────────────────────────────────────────────▼────────────────┐   │
│   │                    BNB CHAIN (BSC TESTNET)                   │   │
│   │                                                              │   │
│   │  ┌──────────────┐  ┌──────────────┐  ┌───────────────┐     │   │
│   │  │AegisRegistry │  │  AegisVault  │  │DecisionLogger │     │   │
│   │  │  (ERC-721)   │  │(Non-Custodial)│  │  (Immutable   │     │   │
│   │  │Agent Identity│  │  Protection  │  │  Audit Log)   │     │   │
│   │  │ + Reputation │  │ + Risk Profs │  │  + AI Hashes  │     │   │
│   │  └──────────────┘  └──────────────┘  └───────────────┘     │   │
│   └──────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘

Smart Contract Architecture (3 Contracts, 1,326 LOC)

Contract	LOC	Purpose	Key Features
AegisRegistry	415	Agent identity & reputation	ERC-721 NFTs, 4 tiers (Scout→Archon), 1-5 reputation scoring, performance tracking
AegisVault	573	Non-custodial asset protection	BNB/ERC20 deposits, per-user risk profiles, agent authorization, emergency withdrawal
DecisionLogger	338	On-chain decision audit trail	Immutable records, risk snapshots, reasoning hashes (keccak256 of AI analysis), 6 decision types

🤖 AI Reasoning Engine (LLM-Powered)

Not just heuristics — Aegis uses real LLM inference for threat analysis

The AI engine (agent/src/ai-engine.ts, 381 LOC) integrates with Groq (Llama 3.3 70B Versatile) or OpenAI (GPT-4o-mini) for natural language market reasoning:

How It Works

// Real LLM call with structured JSON output
const analysis = await aiEngine.analyzeMarket(marketData, riskSnapshot);

// Returns:
{
  reasoning: "BNB trading at $612.50 with +1.8% 24h movement...",
  riskScore: 22,          // AI-assessed risk (0-100)
  confidence: 92,         // AI confidence in assessment
  threats: [],            // Identified threat categories
  suggestedActions: ["continue_monitoring"],
  marketSentiment: "neutral",
  keyInsights: [
    "BNB stable at $612.50 with +1.8% 24h change",
    "Volume up 15% from baseline",
    "Liquidity: $4.20B (+0.5%)"
  ]
}

AI Capabilities

Capability	Method	Description
Market Analysis	`analyzeMarket()`	Full market snapshot analysis with structured risk assessment
Token Risk Scan	`analyzeToken()`	Per-token risk flags: rug pull, honeypot, wash trading, whale manipulation
Threat Reports	`generateThreatReport()`	Executive summary of active threats with trend context
Heuristic Fallback	Automatic	When no API key is configured, falls back to rule-based analysis (zero downtime)

On-Chain AI Attestation

Every AI decision is hashed and stored on-chain:

// Combines heuristic + LLM reasoning into a single attestation hash
const combinedReasoning = `${heuristicReasoning} | AI: ${llmAnalysis.reasoning}`;
const reasoningHash = keccak256(toUtf8Bytes(combinedReasoning));
// → Stored in DecisionLogger as immutable proof of AI reasoning

📊 PancakeSwap V2 On-Chain Integration

Real-time DEX price verification directly from PancakeSwap smart contracts

The PancakeSwap provider (agent/src/pancakeswap.ts, 300 LOC) reads on-chain reserve data from PancakeSwap V2 on BSC Mainnet:

Feature	Method	Description
Token Price (USD)	`getTokenPriceUSD()`	Routes through WBNB→BUSD via Router contract
BNB Price	`getBNBPrice()`	Direct BNB/BUSD on-chain price
Pair Data	`getPairData()`	Reserves, symbols, decimals, USD liquidity
Portfolio Tracking	`getPortfolioPrices()`	Multi-token price monitoring
Token Risk	`analyzeTokenRisk()`	Liquidity depth, concentration, red flags
DEX Depth	`getTotalPairs()`	Total PancakeSwap pair count

Price Oracle Cross-Verification

CoinGecko Price:   $612.50  (API)
PancakeSwap Price: $612.38  (On-chain Router)
Price Delta:        0.019%  → CONSISTENT ✓

If delta > 1%  → Potential price manipulation
If delta > 5%  → CRITICAL: Oracle attack likely

Supported BSC Tokens: WBNB, BUSD, USDT, CAKE, ETH, BTCB, USDC, XRP

🔍 On-Chain Proof (13 Verified Transactions)

All contracts deployed, verified, and battle-tested on BSC Testnet (Chain ID 97)

Contract Addresses

Contract	Address	Links
AegisRegistry	`0xac77139C2856788b7EEff767969353adF95D335e`	BSCScan · Sourcify
AegisVault	`0x73CE32Ece5d21836824C55c5EDB9d09b07F3a56E`	BSCScan · Sourcify
DecisionLogger	`0xEbfb45d0c075d8BdabD6421bdFB9A4b9570219ea`	BSCScan · Sourcify

Verified Transaction Log (Click to verify on BSCScan)

The comprehensive demo simulates a full threat lifecycle — from normal monitoring through threat escalation, protection triggering, and recovery:

#	Phase	Action	Risk Level	Confidence	TX Hash
1	Setup	Vault Deposit (0.005 tBNB)	—	—	`0x3602f8...216c7a`
2	Config	Risk Profile (0.5% slippage, 10% SL)	—	—	`0x4e2ddc...126989`
3	Normal	AI Market Analysis → All Clear	NONE	92%	`0xf0922a...65dbfb`
4	Normal	Risk Snapshot (overall: 15/100)	LOW	—	`0xcd7429...584618`
5	Escalation	Volatility Warning (-4.2% 6h)	LOW	78%	`0xeed6b6...2500ef`
6	Escalation	Risk Snapshot (overall: 38/100)	MEDIUM	—	`0x60e7f3...41ddf4`
7	Threat	Abnormal Volume (+350%, whale selling)	HIGH	88%	`0x8e8e1f...7d97d`
8	Defense	Risk Profile → Aggressive (0.3% slip, 5% SL)	—	—	`0x7b7546...0b6021`
9	Defense	Risk Snapshot (overall: 68/100)	HIGH	—	`0x2a8c0b...c402d3`
10	Protection	Stop-Loss Triggered (-15.3%, liquidity -28%)	CRITICAL	95%	`0xea98d4...28ae11`
11	Recovery	Market Stabilized, Recovery Detected	LOW	91%	`0xbbc362...d4912c`
12	Recovery	Risk Snapshot Normalized (overall: 18/100)	LOW	—	`0x530f57...5b3eb6`
13	Review	Position Review + AI Assessment	NONE	98%	`0x226c18...fdfbab`

Each decision includes a keccak256 hash of the AI reasoning text stored immutably on-chain.

🧪 Tests (54/54 Passing)

  AegisRegistry (20 tests)
    ✓ Deployment, Agent Registration (5), Agent Management (3)
    ✓ Reputation System (4), Agent Stats (4), Admin Functions (3)

  AegisVault (20 tests)
    ✓ Deployment, BNB Deposits (3), BNB Withdrawals (3)
    ✓ Agent Authorization (3), Risk Profile (3)
    ✓ Protection Execution (4), Emergency & Admin (3)

  DecisionLogger (14 tests)
    ✓ Deployment, Decision Logging (4), Risk Snapshots (3)
    ✓ View Functions (4), Admin Functions (2)

  54 passing

📂 Project Structure

aegis-protocol/
├── contracts/                           # Solidity smart contracts (1,326 LOC)
│   ├── AegisRegistry.sol                # ERC-721 agent identity & reputation (415 LOC)
│   ├── AegisVault.sol                   # Non-custodial vault & protection (573 LOC)
│   └── DecisionLogger.sol               # On-chain decision audit log (338 LOC)
│
├── agent/                               # AI Guardian Agent Engine
│   └── src/
│       ├── index.ts                     # Main loop: OBSERVE→ANALYZE→AI→DEX→DECIDE→EXECUTE (292 LOC)
│       ├── ai-engine.ts                 # 🧠 LLM-Powered AI reasoning — Groq/OpenAI (381 LOC)
│       ├── pancakeswap.ts               # 📊 PancakeSwap V2 on-chain price feeds (300 LOC)
│       ├── analyzer.ts                  # 5-vector weighted risk analysis engine (449 LOC)
│       ├── monitor.ts                   # Position & market data monitor (live+fallback)
│       ├── market-provider.ts           # CoinGecko + DeFiLlama live data feeds
│       ├── executor.ts                  # On-chain transaction executor
│       └── simulate.ts                  # Demo simulation (no blockchain required)
│
├── scripts/
│   ├── deploy.ts                        # Multi-contract BSC deployment
│   ├── demo-e2e.ts                      # 10-phase local Hardhat E2E demo
│   ├── demo-onchain.ts                  # 7-phase BSC Testnet demo (6 TXs)
│   └── demo-comprehensive.ts            # 🔥 15-phase BSC Testnet demo (full threat lifecycle)
│
├── test/                                # 54 comprehensive tests
│   ├── AegisRegistry.test.ts            # 20 tests
│   ├── AegisVault.test.ts               # 20 tests
│   └── DecisionLogger.test.ts           # 14 tests
│
├── frontend/                            # Next.js 14 Dashboard (Vercel-deployed)
│   └── src/
│       ├── app/
│       │   ├── page.tsx                 # Dashboard with live data + AI display + on-chain data
│       │   ├── layout.tsx               # OG meta tags, dark cyberpunk theme
│       │   └── globals.css              # Glassmorphism + animation CSS
│       ├── components/
│       │   └── AgentSimulation.tsx       # 🎮 Interactive 6-phase agent simulation (518 LOC)
│       └── lib/
│           ├── constants.ts             # Contract addresses & chain config
│           ├── useLiveMarket.ts         # 🔴 LIVE CoinGecko + PancakeSwap price hook
│           ├── useWallet.ts             # MetaMask wallet hook
│           ├── useContracts.ts          # Contract read/write hooks (+ public RPC)
│           └── abis.ts                  # Full contract ABIs
│
├── hardhat.config.ts                    # BSC Testnet + Sourcify verification
├── deployment.json                      # Deployed contract addresses
├── AI_BUILD_LOG.md                      # 🤖 Detailed AI usage documentation
└── README.md

🚀 Quick Start

Prerequisites

Node.js v18+
npm
MetaMask (for frontend interaction)

1. Clone & Install

git clone https://github.com/Tonyflam/rs.git
cd rs
npm install --legacy-peer-deps

2. Run Tests

npx hardhat test
# 54 passing ✓

3. Run the E2E Demo (Local Hardhat)

npx hardhat run scripts/demo-e2e.ts

4. Run Comprehensive Demo (BSC Testnet)

cp .env.example .env
# Add PRIVATE_KEY with tBNB balance
npx hardhat run scripts/demo-comprehensive.ts --network bscTestnet

15-phase threat lifecycle: normal → volatility warning → threat detected → protection triggered → recovery → review.

5. Start the AI Agent

cd agent && npm install

# Optional: Add LLM API key for AI reasoning
# export GROQ_API_KEY=your_key  (or OPENAI_API_KEY)

npx ts-node src/index.ts

6. Start the Frontend

cd frontend && npm install && npm run dev
# Open http://localhost:3000

7. Deploy to BSC Testnet

npx hardhat run scripts/deploy.ts --network bscTestnet

⛓️ Smart Contracts

Agent Tiers (ERC-721)

Tier	Name	Description
0	Scout	Default on registration
1	Guardian	Promoted by admin, basic operations
2	Sentinel	Higher authority, complex strategies
3	Archon	Maximum trust level, all capabilities

Risk Profile (Per User)

struct RiskProfile {
    uint256 maxSlippage;           // Max acceptable slippage (bps)
    uint256 stopLossThreshold;     // Stop-loss trigger (bps)
    uint256 maxSingleActionValue;  // Max value per action
    bool allowAutoWithdraw;        // Allow emergency withdrawals
    bool allowAutoSwap;            // Allow auto-rebalancing
}

5-Vector Risk Analysis

Vector	Weight	Description
Price Volatility	30%	24h price change magnitude and direction
Liquidity Health	25%	Pool liquidity changes and depth
Volume Analysis	15%	Trading volume anomalies and spike detection
Holder Concentration	15%	Whale ownership and centralization risk
Momentum Analysis	15%	Combined trend signals (price × volume × liquidity)

Threat Types

Threat	Trigger	Severity
Rug Pull	Simultaneous liquidity drain + price crash	CRITICAL
Flash Loan Attack	Extreme volume spikes (>1000%)	CRITICAL
Whale Movement	Top holder >70% concentration	HIGH
Price Crash	>20% decline in 24h	HIGH
Liquidity Drain	>25% liquidity decrease	MEDIUM
Abnormal Volume	>200% volume increase	LOW

📡 Data Sources

Provider	Data	Type
CoinGecko	BNB price, 24h change, volume	Free REST API
DeFiLlama	BSC chain TVL, liquidity	Free REST API
PancakeSwap V2	On-chain token prices, pair reserves, liquidity	On-chain (ethers.js)
Groq / OpenAI	LLM market reasoning, threat analysis	Optional API
BSC RPC	Gas price, block number, contract state	On-chain

🛠️ Tech Stack

Layer	Technology
Smart Contracts	Solidity 0.8.24, OpenZeppelin, Hardhat 2.22.17
AI Reasoning	Groq (Llama 3.3 70B) / OpenAI (GPT-4o-mini) with heuristic fallback
DEX Integration	PancakeSwap V2 Router + Factory (on-chain reads)
Risk Engine	5-vector weighted scoring, configurable thresholds
Live Data	CoinGecko (price/volume), DeFiLlama (TVL/liquidity)
Frontend	Next.js 14, Tailwind CSS, ethers.js v6, Vercel
Blockchain	BNB Smart Chain (BSC Testnet), Sourcify verification
Testing	Hardhat + Chai (54 tests) + 13-phase on-chain demo

🔒 Security

Non-Custodial: Users retain full control — emergency withdrawal always available
Agent Authorization: Users explicitly authorize which agents can act on their behalf
Risk Profiles: Per-user configurable limits (slippage, stop-loss, action value caps)
On-Chain Audit: Every AI decision permanently logged with reasoning hash attestation
ReentrancyGuard: All fund-moving functions protected
OpenZeppelin: Battle-tested contract libraries throughout
Dual-Source Verification: CoinGecko + PancakeSwap on-chain prices cross-referenced

🖥️ Frontend (Vercel-Deployed)

Live at: aegis-protocol-1.vercel.app

🎮 Interactive Agent Simulation: Click "Run Agent Cycle" to watch Aegis execute a full 6-phase guardian loop (OBSERVE → ANALYZE → AI REASON → DEX VERIFY → DECIDE → EXECUTE) with animated phase timeline, typewriter terminal output, and real market data — see exactly how the AI agent works
Live market data: Real-time BNB price from CoinGecko + PancakeSwap V2 on-chain price, auto-refreshing every 30s
Price oracle cross-verification: Shows live delta between API and DEX prices with status indicators
No-wallet mode: Reads on-chain data via public BSC RPC (no MetaMask required)
Wallet mode: Full interaction — deposit, authorize agent, set risk profile, withdraw
AI Analysis display: Real-time AI reasoning driven by live market data, sentiment, risk scores
13 TX evidence table: Every transaction clickable with BSCScan links
Auto-refresh: 30-second polling of on-chain state + market data
Contract verification: BSCScan links, Sourcify badges

📜 AI Build Log

Built with AI assistance as encouraged by the hackathon:

Competitive Analysis — Analyzed 40+ competitor submissions to identify unique positioning
3-Contract Architecture — Designed AegisRegistry + AegisVault + DecisionLogger system
1,326 LOC Solidity — 3 contracts with 54/54 test coverage
5-Vector Risk Engine — Weighted scoring with configurable thresholds
LLM AI Engine — Groq/OpenAI integration for natural language threat analysis (381 LOC)
PancakeSwap Integration — On-chain DEX price feeds for oracle cross-verification (300 LOC)
CoinGecko + DeFiLlama — Real-time market data with graceful fallback
13-Phase On-Chain Demo — Full threat lifecycle executed on BSC Testnet with clickable TX hashes
Next.js Dashboard — Cyberpunk glassmorphism UI with live contract hooks
Brutal Self-Audit — Identified and fixed 6 critical weaknesses mid-hackathon
BSC Testnet Deployment — 3 contracts verified via Sourcify, 13 confirmed transactions with clickable TX hashes
Vercel Deployment — Live dashboard with public RPC reads (no wallet needed)
Interactive Agent Simulation — Visual 6-phase agent loop with typewriter terminal, animated timeline, and live market data
AI Build Log — Comprehensive documentation of AI usage throughout development (see AI_BUILD_LOG.md)

Built with 🛡️ for BNB Chain · Good Vibes Only: OpenClaw Edition

Aegis Protocol — Your DeFi positions deserve a guardian that never sleeps.

Live Dashboard · BSCScan · GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
agent		agent
contracts		contracts
frontend		frontend
scripts		scripts
test		test
.env.example		.env.example
.gitignore		.gitignore
AI_BUILD_LOG.md		AI_BUILD_LOG.md
AMA_WIN_RECAP_ROADMAP.md		AMA_WIN_RECAP_ROADMAP.md
ARCHITECTURE.md		ARCHITECTURE.md
DORAHACKS_DESCRIPTION.md		DORAHACKS_DESCRIPTION.md
LICENSE		LICENSE
README.md		README.md
hardhat.config.ts		hardhat.config.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation