# MODL: Modular On-Chain Dynamic Logic
## 🏆 Winner of UHI7 Hookathon ($500 Prize)
## Overview
MODL is a Uniswap v4 hook aggregator that lets a single pool coordinate multiple pieces of custom logic. Instead of writing a monolithic hook, developers compose reusable modules that implement the `IMODLModule` interface. The aggregator enforces ordering, error handling, and hook-data routing so each module stays isolated.
## Live Demo & Documentation
- **[Documentation](https://migarci2.github.io/modl/)**: Comprehensive guides, architecture overview, and API references.
- **[Interactive Demo](https://migarci2.github.io/modl/demo/)**: A live dApp to configure, mine, and deploy hooks composed of multiple configurable modules.
- **[Pitch Deck](https://migarci2.github.io/modl/deck/)**: High-level presentation of the project vision and features.
## Architecture
### MODLAggregator.sol
Extends `BaseHook` and fans out every lifecycle callback to registered modules. Each module declares which hooks it cares about plus a per-module gas budget, failure policy (`critical`), and priority. Hook data is ABI-encoded as `IMODLModule.ModuleCallData[]`, allowing callers to send per-module payloads in a single bytes blob. The aggregator also exposes a deterministic routing table that forwards arbitrary function selectors (like `placeOrder`) through its fallback to one or more modules.
### IMODLModule Interface
Shared interface covering every pool lifecycle callback plus return-value structs for hooks that produce deltas or fee overrides. Modules receive the `IPoolManager`, the hook caller, and hook-specific data.
## Core Modules
### WhitelistModule
Reusable access control for swaps, liquidity updates, and donations. Owners manage the whitelist and can toggle enforcement per action.
### DynamicFeeModule
Computes a dynamic LP fee override based on configurable volatility parameters or per-swap instructions embedded in hook data.
## Fhenix Integration (Privacy-Preserving Hooks)
MODL includes modules that leverage [Fhenix](https://www.fhenix.io/) Fully Homomorphic Encryption (FHE) for privacy-preserving hook logic:
- **FhenixCredentialsModule**: Abstract base for modules that validate user credentials using encrypted data. Callers submit encrypted credentials which are verified without revealing the underlying values.
- **FhenixWhitelistModule**: Production-ready allow-list that defers credential validation to an off-chain Fhenix verifier. The module gates swaps, liquidity updates, and donations based on privacy-preserving proofs.
- **FhenixAsyncModule**: Base helper for modules that outsource private computation to a Fhenix co-processor.
## EigenLayer Integration
MODL provides modules that integrate with [EigenLayer](https://www.eigenlayer.xyz/) Actively Validated Services (AVS) and oracles:
- **EigenOracleModule**: Lightweight helper to consume EigenLayer-backed oracles with built-in freshness checks.
- **EigenDynamicFeeModule**: Dynamic-fee calculator that pulls a volatility index from an EigenLayer oracle and adjusts LP fees within configurable bounds.
- **EigenTaskModule**: Base helper for modules that dispatch async work to an EigenLayer AVS.
## MODL CLI
Generate modules and tests from templates:
```bash
npm install -g @modl-dev/cli
modl init # writes modl.config.json
modl template:list # discover available templates
modl module:new MyModule # uses default template (basic)
modl module:new EigenDynamicFee -t eigen-oracle
modl module:new FhenixWhitelist -t fhenix-credentials
```
## Usage
1. **Install dependencies and compile**: `forge build`
2. **Run the full test suite**: `forge test`
3. **Add new modules**: Implement `IMODLModule`, deploy, and register through `MODLAggregator.setModules`
4. **Hook data format**: Encode as `abi.encode(IMODLModule.ModuleCallData[] memory)`
5. **Function routing**: Configure via `setRoute(bytes4 selector, uint16[] moduleIndices, ExecMode mode)`
## Project Layout
```
src/
MODLAggregator.sol # Core hook aggregator
interfaces/IMODLModule.sol # Shared module interface
modules/
DynamicFeeModule.sol
WhitelistModule.sol
fhenix/
FhenixAsyncModule.sol
FhenixCredentialsModule.sol
FhenixWhitelistModule.sol
eigen/
EigenOracleModule.sol
EigenDynamicFeeModule.sol
EigenTaskModule.sol
```
## Tech Stack
Solidity, Foundry, Uniswap v4 Hooks, Fhenix FHE, EigenLayer AVS, TypeScript CLI
---
*MODL enables composable, modular hook development for Uniswap v4 - build once, use everywhere.*