Skip to content

arunabha003/RepSwarm

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

104 Commits
docs
docs
 
 
frontend
frontend
 
 
lib
lib
 
 
script
script
 
 
src
src
 
 
test
test
 
 
tools
tools
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
.gitmodules
.gitmodules
 
 
Readme.md
Readme.md
 
 
foundry.lock
foundry.lock
 
 
foundry.toml
foundry.toml
 
 

Repository files navigation

SwarmRep Protocol

MEV-Aware Swap Infrastructure on Uniswap v4 · Hook Agents · Flashloan Backruns · ERC-8004 Identity

Architecture · Local E2E Guide · Frontend Testing · Sepolia Deployment

What Is SwarmRep?

SwarmRep is a protocol that makes swaps safer and fairer by reducing MEV extraction and redistributing captured value back to liquidity providers. Instead of letting outside bots take most of the value created around large swaps, SwarmRep keeps protection and value routing inside the protocol itself. It is built on top of Uniswap v4 and continuously watches swap conditions so users get a more protected trading experience while LPs benefit from value that would normally leak out.

SwarmRep also introduces an agent-based execution model where specialized on-chain agents handle routing and market-response tasks, and ERC-8004 is used to give those agents verifiable identity and reputation. That means automation is not a black box: agents are registered, trackable, and accountable on-chain. The end result is a transparent system that aligns users, LPs, and executors by combining MEV-aware execution, value redistribution, and auditable agent performance in one protocol.

Architecture

SwarmRep Architecture

Contracts

Contract Path Purpose
SwarmHook src/hooks/SwarmHook.sol Uniswap v4 hook — delegates to agents, applies MEV accounting, accumulates LP value
AgentExecutor src/agents/AgentExecutor.sol Agent manager — stores/switches agents per type, supports backup failover + ERC-8004 scoring
ArbitrageAgent src/agents/ArbitrageAgent.sol Compares pool price vs oracle, recommends pre-swap value capture
DynamicFeeAgent src/agents/DynamicFeeAgent.sol Recommends dynamic fee override based on volatility/divergence
BackrunAgent src/agents/BackrunAgent.sol Detects post-swap price dislocations, signals backrun recording
FlashLoanBackrunner src/backrun/FlashLoanBackrunner.sol Stores opportunities, executes backruns (capital or Aave flashloan), splits profit 80/20
FlashBackrunExecutorAgent src/agents/FlashBackrunExecutorAgent.sol Permissionless executor — any caller triggers backrun and receives bounty
LPFeeAccumulator src/LPFeeAccumulator.sol Accumulates captured MEV value, donates to LPs via Uniswap v4 donate()
SwarmCoordinator src/SwarmCoordinator.sol Intent router — create/propose/execute swaps with optional ERC-8004 gating
SimpleRouteAgent src/erc8004/SimpleRouteAgent.sol Minimal on-chain route agent for intent proposals
SwarmAgentRegistry src/erc8004/SwarmAgentRegistry.sol Mints and links ERC-8004 identities for agent contracts
OracleRegistry src/oracles/OracleRegistry.sol Maps token pairs to Chainlink feeds, exposes getLatestPrice()

ERC-8004 Integration

ERC-8004 (Trustless Agents) provides the identity and reputation layer:

  • Identity — Each hook agent and route agent can be linked to an ERC-8004 identity (ERC-721 NFT with agent metadata).
  • Reputation — The coordinator writes +1 WAD feedback for winning route agents on successful execution. AgentExecutor can write feedback for hook agents during swaps.
  • Gating — The coordinator can enforce minimum reputation thresholds for route agent proposals.
  • Switching — Admin can configure reputation-based agent switching in AgentExecutor (always off-path, never inside swaps).

Live Sepolia Deployment

Deployed via script/DeploySwarmProtocol.s.sol on Ethereum Sepolia (chainId=11155111):

Contract Address
Deployer / Treasury 0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814
PoolManager 0x8C4BcBE6b9eF47855f97E675296FA3F6fafa5F1A
SwarmHook 0x653557bE812E70CD5B9Abc0f4Ee8f5f4604e00cc
SwarmCoordinator 0x5be7B30051264fECf6a248551bd408b98eCfd5d2
AgentExecutor 0xAC8B64ee8DF2dcdcCbF471B9E2a4a281d14b03FF
LPFeeAccumulator 0xe7D6cDe8f3Af7088D1999F1969F877ebe0d78517
OracleRegistry 0x42b598ff76b62A0fd273560F691896102c5a3A4A
FlashLoanBackrunner 0xAf26D906b2AE22276D8d07183aEc66609035F196
FlashBackrunExecutorAgent 0xD6D9473EA9f155F25f9D15CE896171075961A2a4
SimpleRouteAgent 0xDf1cb317Fff7CC63100682e9E3ea0eAce8D514d4 · 8004Scan
SwarmAgentRegistry 0x048b0819f3942e1B548579004a486b6029217d13
ArbitrageAgent 0xFA1591069f7f1e48e8758179014f19F65fF44b26 · 8004Scan
DynamicFeeAgent 0x6Be9E7Db2335fe26fB0741D9E1fC8c581FCBfBDd · 8004Scan
BackrunAgent 0xe2B466898D45f6Ae73Ca20b5e85eA584d0589216 · 8004Scan

Tokens (Sepolia):

Deployment TxIDs

Contract Creation TxID
OracleRegistry 0xc3b7ab20a35d3040ccb5b0a7350e107adea96faaa29020d4c58de15461b8cacf
LPFeeAccumulator 0xf237035d3ae113773188cd68855ed60ddbdcb599c1912aa908f5b99737ac68cb
AgentExecutor 0xc626fa8cb24a23ba3be6cb62ac7a6ec2312051e726c6ed4a0e6e8ef2073dadae
SwarmHook 0x4d9edd58ca542bebf8906aa7e257ef30f41e670891b3843a63d5beb3475f6a4c
SwarmCoordinator 0xec5f9a96731b7493c5801b5e0551b01f639e55af8c2c1de63fb19fc0ef2b939f
FlashLoanBackrunner 0x52db0e939f556df016032bb2d137087a1291106de34209a333e85116f8166
SimpleRouteAgent 0x096eaaecd3273548f5256b32f1af26d006c537965de036309fb07c537965de036
FlashBackrunExecutorAgent 0x52db0e939f556df016032bb2d137087a1291106de34fc38e5f5b66cb7e542ffb
SwarmAgentRegistry 0xe440c3ca1d834c46023e28b310e5e5cf62684273
ArbitrageAgent 0xa16ad0502561af77e2e5d55f280bdfaf74fb5c9df6bb79d4f9a7e18ac357d97a
DynamicFeeAgent 0xe86a6e59b14f12c476e287689af9c34762ef5be8768da7c47265fb5a526746a6
BackrunAgent 0xc73e82c0d812b04e0a5340544947d56429430a

Quick Start (Local Sepolia Fork)

Full guide: docs/ANVIL_SEPOLIA_E2E.md

Prerequisites

  • Foundry (forge, cast, anvil)
  • Node.js ≥ 18 + pnpm
  • Python 3 (for the DAI funding helper)

1. Start Anvil

anvil --fork-url https://eth-sepolia.g.alchemy.com/v2/<YOUR_KEY> \
  --chain-id 31337 --auto-impersonate

2. Fund DAI

python3 tools/anvil_set_erc20_balance.py \
  --rpc http://127.0.0.1:8545 \
  --token 0xFF34B3d4Aee8ddCd6F9AFFFB6Fe49bD371b8a357 \
  --account 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
  --amount 5000000000000000000000000

3. Deploy

PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
SEED_AAVE_LIQUIDITY=true \
SEED_AAVE_DAI=false \
forge script script/DeployAnvilSepoliaFork.s.sol:DeployAnvilSepoliaFork \
  --rpc-url http://127.0.0.1:8545 --broadcast -vvv

4. Run Frontend

cd frontend
cp .env.example .env   # fill with addresses from deploy output
pnpm install && pnpm dev

5. Test the Flow

  1. Connect MetaMask → RPC http://127.0.0.1:8545, Chain ID 31337
  2. Import deployer key: 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
  3. Quick Intent → Approve → Create Intent
  4. Intent Desk → Load intent → Auto Propose + Execute via Router
  5. Backrun → Load → Execute (Executor Agent)
  6. LP Donations → Load → Donate To LPs

Project Structure

src/
├── hooks/SwarmHook.sol              # Uniswap v4 hook
├── agents/
│   ├── AgentExecutor.sol            # Agent manager + failover + scoring
│   ├── ArbitrageAgent.sol           # Pre-swap oracle arbitrage capture
│   ├── DynamicFeeAgent.sol          # Dynamic fee recommendations
│   ├── BackrunAgent.sol             # Post-swap backrun detection
│   └── FlashBackrunExecutorAgent.sol # Permissionless backrun executor
├── backrun/FlashLoanBackrunner.sol  # Backrun storage + execution + Aave flashloans
├── LPFeeAccumulator.sol             # MEV value accumulation + LP donation
├── SwarmCoordinator.sol             # Intent router with ERC-8004 enforcement
├── oracles/OracleRegistry.sol       # Chainlink feed registry
├── erc8004/
│   ├── SimpleRouteAgent.sol         # Minimal on-chain route agent
│   └── SwarmAgentRegistry.sol       # ERC-8004 identity minting + linking
├── interfaces/                      # Contract interfaces
└── libraries/                       # Shared types and helpers

script/
├── DeployAnvilSepoliaFork.s.sol     # Local fork deployment (pools + liquidity + agents)
├── DeploySwarmProtocol.s.sol        # Live Sepolia deployment
└── SeedAaveLiquidityAnvilSepoliaFork.s.sol  # Aave liquidity seeding

frontend/                            # React + Vite + ethers.js frontend
test/                                # Foundry test suites
tools/                               # Helper scripts (ERC20 balance injection)
docs/                                # Architecture + deployment + E2E guides

Tests

# All tests
forge test -vvv

# Sepolia fork E2E (real integrations)
forge test --match-contract E2ESepoliaTest -vvv

# Mainnet fork E2E
RUN_MAINNET_E2E=true forge test --match-contract E2EMainnetTest -vvv
Suite File Coverage
Unit test/SwarmUnit.t.sol Core hook + agent logic
Agent Integration test/AgentIntegration.t.sol Multi-agent swap pipeline
Failover test/AgentExecutorFailover.t.sol Backup agent switching
MEV test/MevIntegration.t.sol Backrun detection + execution + profit split
ERC-8004 test/ERC8004Integration.t.sol Identity + reputation + coordinator gating
Reputation Switch test/AgentExecutorReputationSwitch_Sepolia.t.sol Reputation threshold switching
E2E Sepolia test/E2E_Sepolia.t.sol Full flow on Sepolia fork

Integrations (No Mocks)

All integrations use real Sepolia deployments — zero mocked contracts in src/:

Protocol Usage Sepolia Address
Uniswap v4 Pool creation, swaps, dynamic fees, donate() 0x8C4BcBE6b9eF47855f97E675296FA3F6fafa5F1A
Chainlink ETH/USD oracle feed for price divergence detection 0x694AA1769357215DE4FAC081bf1f309aDC325306
Aave v3 Flashloan source for backrun execution 0x6Ae43d3271ff6888e7Fc43Fd7321a503ff738951
ERC-8004 Agent identity, reputation, and validation registries Spec

Documentation

Document Description
Architecture System design, contract roles, data flows, agent switching model
Local E2E Guide Anvil fork setup → deploy → configure → test
Frontend E2E Guide UI-driven test flows for every protocol feature
Sepolia Deployment Live Sepolia deployment guide + verification
Pitch Deck Protocol overview and key features

Built With

Notes

  • Live Sepolia Limitation: Sepolia testnet has minimal liquidity. Live swaps on Sepolia may fail or execute with poor pricing. Use local Anvil fork testing (see ANVIL_SEPOLIA_E2E.md) for full protocol testing — Anvil forks have deterministic liquidity and oracle feeds from the real Sepolia state.
  • Oracle pricing uses Chainlink ETH/USD as a proxy for WETH/DAI (assumes DAI ≈ USD). Production deployments should use pair-specific feeds.
  • This repo is not audited. It is a hackathon prototype demonstrating MEV redistribution via hook agents.

Built at ETHGlobal HackMoney

About

rep-swarm.vercel.app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages