Skip to content

Commit 4c37b9c

Browse files
zachyozachyo
authored
Merge pull request #4 from zachyo/readme
readme
2 parents efd63e3 + d454964 commit 4c37b9c

1 file changed

Lines changed: 138 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 138 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,165 @@
1-
## Foundry
1+
# VeiledBatch Hook 🦄🔒
22

3-
**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
3+
> **"The CoW Swap you can’t front-run — fully encrypted, restaked batch auctions on Uniswap v4"**
44
5-
Foundry consists of:
5+
![License](https://img.shields.io/badge/license-MIT-blue.svg)
6+
![Status](https://img.shields.io/badge/status-MVP-green.svg)
7+
![Fhenix](https://img.shields.io/badge/FHE-Fhenix-purple)
8+
![EigenLayer](https://img.shields.io/badge/AVS-EigenLayer-blue)
9+
![Uniswap](https://img.shields.io/badge/Hook-Uniswap%20v4-pink)
610

7-
- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
8-
- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
9-
- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
10-
- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
11+
## 📖 Vision
1112

12-
## Documentation
13+
**VeiledBatch** is a Uniswap v4 hook that enables **confidential intent-based batch auctions**. It allows traders to submit fully encrypted intents (size, direction, max slippage) which remain hidden from the public mempool, preventing toxic MEV and sandwich attacks.
1314

14-
https://book.getfoundry.sh/
15+
Every ~15–30 seconds, these intents are batched and sent to a custom **EigenLayer AVS** that runs a uniform-price auction entirely under **FHE (Fully Homomorphic Encryption)** using **Fhenix**. Only the final matched trades are selectively decrypted and settled on-chain. Unfilled volume automatically falls back to UniswapX or standard v4 pools.
1516

16-
## Usage
17+
The result: **Zero toxic MEV, full order privacy, and verifiable fair execution.**
1718

18-
### Build
19+
---
1920

20-
```shell
21-
$ forge build
22-
```
21+
## 🤝 Partner Integrations
2322

24-
### Test
23+
This project leverages cutting-edge infrastructure from the following partners:
2524

26-
```shell
27-
$ forge test
28-
```
25+
### 🟣 Fhenix (FHE)
2926

30-
### Format
27+
We utilize **Fhenix** to bring Fully Homomorphic Encryption to the EVM.
3128

32-
```shell
33-
$ forge fmt
34-
```
29+
- **Usage:** All user intents (amount, direction, slippage) are encrypted using the Fhenix JS SDK before submission.
30+
- **On-Chain:** The `VeiledBatchHook.sol` stores these `euint` (encrypted uint) values.
31+
- **Decryption:** Selective decryption is performed only after the AVS has computed the optimal batch clearing price and matches.
32+
- **Location:** `src/VeiledBatchHook.sol`, `src/avs/VeiledBatchAVSOperator.sol`
33+
34+
### 🌐 EigenLayer (AVS)
35+
36+
We deploy a custom **Actively Validated Service (AVS)** on EigenLayer to handle the heavy lifting of batch matching off-chain but trustlessly.
37+
38+
- **Usage:** Operators stake ETH to register for the VeiledBatch AVS. They listen for finalized batches from the hook.
39+
- **Computation:** Operators perform the batch auction logic (matching orders, calculating clearing price) on the encrypted data.
40+
- **Verification:** Results are signed and verified on-chain before settlement.
41+
- **Location:** `src/avs/VeiledBatchAVS.sol`, `src/avs/VeiledBatchAVSOperator.sol`
42+
43+
---
3544

36-
### Gas Snapshots
45+
## ✨ Key Features
3746

38-
```shell
39-
$ forge snapshot
47+
- **🔒 True FHE Privacy:** Orders are encrypted from wallet to settlement. No one, not even the solvers, can see your exact trade details until the batch is closed.
48+
- **🛡️ Zero MEV Exposure:** Since intents are hidden, sandwich bots cannot front-run your trades.
49+
- **🤖 Automatic Batching:** Intents are collected and batched automatically based on time (30s) or size (100 intents).
50+
- **🔄 Hybrid Execution:**
51+
- **Primary:** Encrypted Batch Auction (Uniform Clearing Price).
52+
- **Fallback:** Unmatched intents are automatically routed to Uniswap v4 pools or UniswapX fillers.
53+
- **🔐 Restaked Security:** Leveraging EigenLayer's pooled security for the off-chain matching engine.
54+
55+
---
56+
57+
## 🏗️ Architecture
58+
59+
```mermaid
60+
graph TD
61+
User[User / Wallet] -->|Encrypts Intent| Relayer
62+
Relayer -->|Submits Batch| Hook[VeiledBatch Hook]
63+
Hook -->|Emits Event| AVS[EigenLayer AVS Operators]
64+
AVS -->|FHE Computation| AVS
65+
AVS -->|Submit Result + Proof| Hook
66+
Hook -->|Verify & Decrypt| Settlement[Settlement Logic]
67+
Settlement -->|Match| Pool[Uniswap v4 Pool]
68+
Settlement -->|Unmatched| Fallback[Standard Swap / UniswapX]
4069
```
4170

42-
### Anvil
71+
### Detailed Flow
72+
73+
1. **Submission:** User encrypts intent (amount, direction, slippage) via Fhenix SDK and submits to the hook via `beforeSwap`.
74+
2. **Batching:** The hook collects encrypted intents. Once the batch is full or times out, it emits a `BatchFinalized` event.
75+
3. **Execution (AVS):** EigenLayer operators pick up the batch, perform the auction matching algorithm on encrypted data, and calculate the clearing price.
76+
4. **Verification:** Operators submit the result and a signature to the hook. The hook verifies the quorum.
77+
5. **Settlement:** The hook selectively decrypts the matched amounts and executes the swaps against the Uniswap v4 pool manager.
78+
6. **Fallback:** Any unmatched volume is executed as a standard swap ensuring no user is left behind.
79+
80+
---
81+
82+
## 📂 Repository Structure
4383

44-
```shell
45-
$ anvil
4684
```
85+
VeiledBatch/
86+
├── src/
87+
│ ├── BatchAuctionHook.sol # Core Hook Logic (Week 1-2)
88+
│ ├── VeiledBatchHook.sol # Production Hook with FHE (Week 3)
89+
│ ├── IntentBridge.sol # Intent Management
90+
│ ├── avs/
91+
│ │ ├── VeiledBatchAVS.sol # EigenLayer Service Manager
92+
│ │ ├── VeiledBatchAVSOperator.sol # Operator Logic
93+
│ │ └── interfaces/ # Interfaces
94+
│ └── mocks/
95+
│ └── MockAVS.sol # Simulation for local testing
96+
├── script/
97+
│ ├── Deploy.s.sol # Deployment Scripts
98+
│ └── DeployProduction.s.sol # Fhenix Deployment
99+
├── test/
100+
│ └── BatchAuction.t.sol # Foundry Tests
101+
└── docs/ # Documentation & Assets
102+
```
103+
104+
---
47105

48-
### Deploy
106+
## 🚀 Getting Started
49107

50-
```shell
51-
$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
108+
### Prerequisites
109+
110+
- [Foundry](https://book.getfoundry.sh/getting-started/installation)
111+
- [Node.js](https://nodejs.org/) (for frontend/SDK)
112+
113+
### Installation
114+
115+
```bash
116+
git clone https://github.com/your-username/VeiledBatch.git
117+
cd VeiledBatch
118+
forge install
52119
```
53120

54-
### Cast
121+
### Build
55122

56-
```shell
57-
$ cast <subcommand>
123+
```bash
124+
# Build contracts (via-ir enabled for stack optimization)
125+
forge build
58126
```
59127

60-
### Help
128+
### Test
129+
130+
```bash
131+
# Run all tests
132+
forge test
61133

62-
```shell
63-
$ forge --help
64-
$ anvil --help
65-
$ cast --help
134+
# Run with verbosity for debugging
135+
forge test -vv
66136
```
137+
138+
_Note: Local tests use `MockAVS.sol` to simulate the FHE and AVS layers. For full FHE functionality, deployment to Fhenix testnet is required._
139+
140+
---
141+
142+
## ✅ Implementation Status
143+
144+
| Feature | Status | Description |
145+
| :------------------ | :----: | :------------------------------------------------------------- |
146+
| **Hook Core** | ✅ | Intent storage, batch management, event emission |
147+
| **Settlement** | ✅ | Clearing price logic, swap execution, fallback mechanism |
148+
| **FHE Integration** | ✅ | `euint` types, encrypted submission, permissioned decryption |
149+
| **AVS Integration** | ✅ | Operator registration, task submission, signature verification |
150+
| **Frontend** | 🚧 | React UI for encrypted intent submission (In Progress) |
151+
| **Deployment** | 🔄 | Ready for Fhenix Helium Testnet |
152+
153+
---
154+
155+
## 🏆 Hackathon Tracks
156+
157+
- **Uniswap Hook Incubator (UHI):** Innovative use of v4 hooks to solve MEV.
158+
- **Fhenix:** Core privacy architecture using FHE.
159+
- **EigenLayer:** Decentralized off-chain computation for batch matching.
160+
161+
---
162+
163+
## 📄 License
164+
165+
MIT

0 commit comments

Comments
 (0)