diff --git a/.gitignore b/.gitignore index 9722eeec3..a46de7620 100644 --- a/.gitignore +++ b/.gitignore @@ -109,7 +109,9 @@ desktop.ini # Project-Specific Documentation (Internal Use) # ============================================================================= AGENTS.md +CLAUDE.md CREATE_PROTOCOL_PR.md +NOTES.md QWEN.md TODO.md diff --git a/CLAUDE.md b/CLAUDE.md index 50b706421..8e1214d45 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,3 @@ - - - - # GitHub The branch we will be psuhing to ins uhi7 diff --git a/README.md b/README.md index a4dee7c2b..f6d01d6c1 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@
- Solidity- + Solidity- TypeScript React Vite @@ -15,12 +15,11 @@ Description

- - ## Table of Contents - [Hook Bazaar Monorepo](#hook-bazaar-monorepo) - [Table of Contents](#table-of-contents) - [Problem Description](#problem-description) + - [Demo](#demo) - [Solution Overview](#solution-overview) - [Architecture](#architecture) - [Setup](#setup) @@ -44,6 +43,14 @@ Hook Bazaar solves **9 critical market failures** in the Uniswap v4 ecosystem: ๐Ÿ“– **[Read the full Problem Description](docs/problem-description/PROBLEM_DESCRIPTION.md)** for detailed analysis of each market failure and how Hook Bazaar solves them. +--- + +## Demo + + + +--- + ## Solution Overview Hook Bazaar is a **decentralized marketplace and infrastructure layer** for Uniswap v4 hooks that: @@ -52,66 +59,143 @@ Hook Bazaar is a **decentralized marketplace and infrastructure layer** for Unis - **For Protocols**: Instant deployment (minutes vs weeks), lower costs ($100s vs $10k+), pre-audited hooks, multi-hook composition - **For Ecosystem**: Self-sustaining economic model, quality through competition, accelerated v4 adoption +Hook Bazaar enables trustless monetization of Uniswap V4 hooks through: -# Setup +- **Centralized Discovery Layer**: Connects hook supply with protocol demand +- **Ready-Made Hooks**: Reduces deployment time from weeks to minutes +- **Direct Monetization**: Fixed-price, revenue-share, or hybrid licensing models +- **Mathematical Specifications**: Hook Specification Format for objective behavior verification +- **MasterHook Diamond**: Safe multi-hook composition with selector-level routing +- **Fhenix CoFHE Integration**: Encrypted implementations protecting developer IP +- **EigenLayer AVS**: Cryptoeconomic guarantees with slashing for false attestations -Minimal setup to run the frontend and indexer locally. +**Value Delivery:** +- Hook developers: IP protection, monetization, reputation building +- Protocol designers: Instant deployment, lower costs, pre-verified hooks +- Ecosystem: Self-sustaining economics, quality improvement through competition -## Prerequisites +[Full Documentation](docs/README.md) -- Node.js v18+ -- Foundry +--- -## Quick Start +## Architecture +### System Context -### 1. Install Dependencies +```mermaid +flowchart TB + subgraph HookBazaar["Hook Bazaar System"] + ProtocolPkg["protocol-pkg"] + HooksOperatorAVS["hooks-operator-avs"] + HookPkg["hook-pkg"] + MasterHookPkg["master-hook-pkg"] + end -```bash -npm install -forge install + ProtocolAdmin["Protocol Admin"] -->|"create_protocol\ncreate_pool"| ProtocolPkg + HookDeveloper["Hook Developer"] -->|"commitToHookSpec"| HookPkg + AVSOperator["AVS Operator"] -->|"respondToTask"| HooksOperatorAVS + + ProtocolPkg -->|"initialize"| UniswapV4["Uniswap V4"] + HooksOperatorAVS -->|"register/slash"| EigenLayer["EigenLayer"] + HookPkg -->|"fetch spec"| IPFS["IPFS"] + HookPkg -.->|"encrypted"| Fhenix["Fhenix CoFHE"] ``` -### 2. Frontend +**Goal**: Define environment boundary between Hook Bazaar and external systems (Uniswap V4, EigenLayer, IPFS, Fhenix). -Start the frontend development server: +[Full Context Diagram](docs/context-diagram.md) -```bash -npm run dev -``` +### Package Structure + +| Package | Purpose | +|---------|---------| +| `protocol-pkg` | Protocol lifecycle management for pool administration | +| `hooks-operator-avs` | EigenLayer AVS for hook specification attestation | +| `hook-pkg` | Hook development, marketplace, and IP protection | +| `master-hook-pkg` | Diamond-pattern multi-hook composition | +| `operator/` | Off-chain attestation task processing runtime | + +[Package Documentation](docs/README.md#package-documentation) + +### Bonded Hooks Comparison + +| Dimension | Bonded Hooks | Hook Bazaar | +|-----------|-------------|-------------| +| Primary Focus | Low-code composition | IP-protected marketplace | +| Target User | Pool admins | Hook developers | +| Verification | Centralized AVS | Decentralized EigenLayer AVS | +| IP Model | Open source | Encrypted implementations | -Frontend runs on: **http://localhost:3000** +**Key Differentiator**: Hook Bazaar provides mathematical specification verification with cryptoeconomic guarantees (slashing). -### 3. HookAttestationAVS Operator +[Full Comparison](docs/hook-pkg/architecture/bonded-hooks-comparison.md) | [Operator EigenLayer Integration](operator/README.md) -The operator verifies hook implementations match their specifications without accessing source code. +--- + +## Setup + +### Prerequisites + +- Node.js v18+ +- Foundry + +### Build ```bash -cd operator npm install +forge install +forge build ``` -**Run tests:** +### Test + ```bash -npm test +forge test +cd operator && npm test ``` -**Run operator in dry-run mode:** +### Deploy + ```bash +# Frontend +npm run dev +# Frontend runs on: http://localhost:3000 + +# Operator (dry-run mode) +cd operator cp .env.example .env -anvil // on separate terminal +anvil # on separate terminal npm start ``` -**Constraints:** +**Operator Constraints:** - Dry-run mode only (on-chain contracts not yet deployed) - Uses mock state sampler (real IHookStateView pending) - BLS signatures and multi-operator consensus pending EigenLayer integration -See `operator/INTEGRATION_ROADMAP.md` for full integration requirements. +See [operator/README.md](operator/README.md) for full documentation. + +--- + +## References + +### Documentation + +- [Full Documentation Index](docs/README.md) +- [Mission Statement (JSON)](docs/mission-statement.json) +- [Function Refinement Tree (JSON)](docs/function-refinement-tree.json) +- [Context Diagram](docs/context-diagram.md) + +### Package Specifications -### 4. Contracts -- `forge build` - Compile contracts -- `forge test` - Run tests +- [protocol-pkg](docs/protocol-pkg/solutionSpec.md) +- [hooks-operator-avs](docs/hook-attestation-pkg/solutionSpec.md) +- [hook-pkg/development](docs/hook-pkg/development/solutionSpec.md) +- [hook-pkg/market](docs/hook-pkg/market/solutionSpec.md) +- [hook-pkg/cofhe-haas](docs/hook-pkg/cofhe-haas/solutionSpec.md) +### Architecture +- [AVS Verification System](docs/hook-pkg/architecture/avs-verification-system.md) +- [Bonded Hooks Comparison](docs/hook-pkg/architecture/bonded-hooks-comparison.md) +- [Market Structure](docs/hook-market-pkg/market_structure_docs.md) diff --git a/client2/CREATE_PROTOCOL_PR.md b/client2/CREATE_PROTOCOL_PR.md deleted file mode 100644 index 4690d6eee..000000000 --- a/client2/CREATE_PROTOCOL_PR.md +++ /dev/null @@ -1,46 +0,0 @@ -## Craete Protocol Flow (Partially Completed) - -- Once a transaction fails or it is canceled it needs to close the create protocol pop up but not affect subsequente create protocol creations. - -If a create_protocol transaction succeeds, then what follows is - -- After success confetti is shown in the whole screen -- The dashboar MUST only be shown to the logged in address with the PROTOCOLS this address has created - - -- A @ProtocolDesginerDashboard ProtocolDetailsFromat is instantiated with the - -- This seems to be done on an indexer, meaioning hearing the event -ProtocolCreated and from the data fill the ProtocolDetailsFormat - -The add website on prtocol detials is a permissioned (only protocol creator) call to setTokenURI only allowed to the protocol creator OR the protocol_admin_manager - -The creater pool on protocolDetails is a permissioned (only protocol creator) call to create_pool only allowed to the protocol creator OR the protocol_admin_manager - -- The fee recipient remains empty until pool creation. On pool creation allowed callers can specify a fee recipant address compliant with a Vault, trasurey interface. Thjis function also emits an event - - - - -- Socials are stored in a centralized database using the protocol token ID and protocol caller as keys. -``` -{ - socials { - "admin": "address", - "protocol_id": "uint256", - "X": "hyperlink", - "farcaster": "handle", \\ "@..." - "zora": "handle", \\ "@..." - } -} -``` - - - - -projetc ID, alchemy API key, PRIVATE_Kye must be secret - - - - -The roles are a call to edit a governance contract on the Protocol diff --git a/client2/TODO.md b/client2/TODO.md deleted file mode 100644 index 203a9e246..000000000 --- a/client2/TODO.md +++ /dev/null @@ -1,68 +0,0 @@ -- Create Protocol FLow - -``` -get started -| -I am a protocol designer -| -create protocol -| - -User calls createProtocol() โ†’ mints tokenId - โ†“ -``` -The ERC1155 facet is the ProtocolRegistry component - -- Each tokenId is a protocol instance - -``` -// Example tokenId allocation -tokenId = 1 โ†’ Protocol "DeFi Protocol Alpha" -tokenId = 2 โ†’ Protocol "Liquidity Hub Beta" -tokenId = 3 โ†’ Protocol "Yield Farm Gamma" -// etc. -``` - -Balance = 1: Protocol exists -Balance = 0: Protocol doesn't exist or was burned - - - - -------Pool Creation - -- For pool creation the user needs to specify the entry point for -protocol fee, its receipiant and possibly its model - -Once this is specified in the UI, it is passed to the "PoolBuilder," which is an operator created when a protocol is deployed. The PoolBuilder acts as the intermediary between the UI and the PoolManager for pool initialization. This is necessary because it handles the requirements for protocol fee management. - - - -- For each protocol ERC-5169 enables executable scripts attached to tokens. For protocols, this enables: - -> From now the one of our interest is ... - -``` -- Pool connection rules -// ... -``` - - - - -Pool Structure - -``` - -{ - id: string; // NOTE: This matches PoolId bytes32 on PoolManager - protocolId: string; // Links pool to protocol (tokenId) - feeRevenueReceiver: string; // Pool-specific fee recipient - tokenPair: string; - feeTier: string; - // ... other pool data -} - -``` - - diff --git a/contracts/TODO.md b/contracts/TODO.md index d4c523a41..51ab49eeb 100644 --- a/contracts/TODO.md +++ b/contracts/TODO.md @@ -1,78 +1,21 @@ -- uhi7 branch integration ci/cd - - This needs to be tested against current code base and other branche +# Documentation +- Create documentation agent guideline +- Generate documentation for protocol-pkg following guidelines +- Organize + -The following follows + - Fhenix integration goes on docs/hook-ip-protection + - EigenLayer integration goes on docs/hook-attestation-pkg +- Document all contracts -Create a temp branch on upstream to test this CI workflow works agains current uhi7 state and test against other branches MAKE sure to output a sepearet dir ci-testing/ the findgindgs and next steps +- Update README following table of contents (Make sure the AGENT referecenes documentation) +# Slides +- See slides bes practices from Mark (Bonded Hooks) +# Video -- ProtocolAdminRegistry: - - INITIALIZATION - - MUST be initialized once - - MUST set the caller as upgradeAdmin - - MUST set the implementation as ProtocolAdminManager - - - -- create protocol - - The creator is set by a protocolAdminManager which MUST be the caller of createProtocol initially - - - The protocolAdminManager MUST implement IERC1155Receiver - - - Once, the creator is set it MUST have permission to add governance - - - The tokenURI is set concatenating with the /loggedIn?=protocolDashboard/protocolId?=tokenURI - - - - Since protocolAdmin 1----->* tokenId 1----> 1 protocolAdminManager - - -- ProtocolAdminManager returns to the client the initialization of the protocol and then the client asks the -panel to unclock functionality to caller - - - Then ProtocolAdminManager can only MANAGE (CUD) pools associated with (protocolAdmin, tokenId) - - The initial only caller of protocolAdminManager is the protocolAdmin, but we can provide access control to other accounts or governance mechanisms - - What are the advantages of doing in this way instead of directly on the AdminClient - - - Let's explore the adminClient case : - protocolAdmin ---> client.createPool - --> isValidCreator - --> attach masterHook - --> attach treassury - -- ProtocolAdminClient.fork.t.sol - - createPool flow with masterHook and protocolHookMaster - - Ensure the only entry point to initialize a pool with HookMatter attached to it is through the client - -- Study possible EigenLayer integration - - BondedHooks reference - - EigenLayerDocumentation - -- Connect Figma MCP and frontend system prompt and tooling to Claude -- Make github system prompt -- Make indexer system prompt - - -- Revenue MultiAsset Vault (Eahc Vault is a dedicated pool revenue vault) -- Revennue PoolVault - -- Connect to HookDB, both at contract level queris and frontend - -- Create staking mechaincs both for ProtocolDevelopers and HookDevelopers - -- hooks querys (smart contracts) -- view details, set protocol website -- protocol treassury (smart contract, frontned) -- pool treassury (smart contract, frontend) -- eigenLayer integration - - reverse ing BondedHooks - - own intgration checking - - -The gitmodules must reference the Compose dendendcies at the already specidfied commit and the nested Compose dependecies muts comply with this = - -Openeppeling version in 0.5.1. - -This must be consistent and protected for all new code integrations \ No newline at end of file +- See video best practices from Mark +- User story for protocol developer and for Hook Developer submitting a spec +(MOCK DATA IS TO BE ENTERED AND PREPARED) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..e05e8fa30 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,243 @@ +# Hook Bazaar Documentation + +## Solution Overview + +Hook Bazaar solves critical market failures in the Uniswap V4 hooks ecosystem: + +- **Missing Marketplace**: Connects hook supply (developers) with demand (protocol designers) through a centralized discovery layer +- **High Barriers to Entry**: Reduces time-to-deployment from weeks to minutes with pre-verified, ready-made hooks +- **No Developer Incentives**: Enables direct monetization via fixed-price, revenue-share, or hybrid licensing models +- **Lack of Standardization**: Enforces mathematical specifications (Hook Specification Format) for objective behavior verification +- **No Composition Mechanism**: Provides MasterHook Diamond pattern for safe multi-hook execution with selector-level routing +- **No IP Protection**: Integrates Fhenix CoFHE for encrypted implementations that cannot be decompiled +- **No Trust Mechanism**: Delivers cryptoeconomic guarantees through EigenLayer AVS with slashing for false attestations + +**Value Delivery:** +- Hook developers: IP protection, monetization, reputation building +- Protocol designers: Instant deployment, lower costs, pre-verified hooks +- Ecosystem: Self-sustaining economics, quality improvement through competition + +Reference: [problem-description.md](./problem-description.md) + +## Architecture + +### System Context + +The following diagram establishes the system boundary and identifies external actors that jointly achieve Hook Bazaar's mission: + +```mermaid +flowchart TB + subgraph Environment["Hook Bazaar Environment"] + subgraph HookBazaar["Hook Bazaar System"] + ProtocolPkg["protocol-pkg"] + HooksOperatorAVS["hooks-operator-avs"] + HookPkg["hook-pkg"] + MasterHookPkg["master-hook-pkg"] + end + end + + ProtocolAdmin["Protocol Admin"] + HookDeveloper["Hook Developer"] + AVSOperator["AVS Operator"] + Trader["Trader/LP"] + + UniswapV4["Uniswap V4 PoolManager"] + EigenLayer["EigenLayer AVSDirectory"] + IPFS["IPFS (Specifications)"] + Fhenix["Fhenix CoFHE"] + + ProtocolAdmin -->|"create_protocol\ncreate_pool"| ProtocolPkg + HookDeveloper -->|"commitToHookSpec\npost implementation"| HookPkg + AVSOperator -->|"acceptBondedEngagement\nrespondToTask"| HooksOperatorAVS + Trader -->|"swap\naddLiquidity"| UniswapV4 + + ProtocolPkg -->|"initialize pool"| UniswapV4 + HooksOperatorAVS -->|"registerOperator\nslash"| EigenLayer + HookPkg -->|"fetch spec"| IPFS + HookPkg -.->|"encrypted code"| Fhenix + MasterHookPkg -->|"hook callbacks"| UniswapV4 + + ProtocolPkg --> MasterHookPkg + HooksOperatorAVS --> HookPkg + HookPkg --> MasterHookPkg +``` + +**Goal**: Define environment boundary and communication channels between Hook Bazaar and external systems required to achieve composite system goals. + +### On-Chain / Off-Chain Boundary + +```mermaid +flowchart LR + subgraph OnChain["On-Chain"] + ProtocolAdminClient + HookAttestationTaskManager + AttestationRegistry + HaaSVendorManagement + ClearingHouse + EscrowCoordinator + HaaSFacet + end + + subgraph OffChain["Off-Chain"] + OperatorRuntime["Operator Runtime (TypeScript)"] + IPFSGateway["IPFS Gateway"] + end + + OperatorRuntime -->|"event listener"| HookAttestationTaskManager + OperatorRuntime -->|"state sampling"| HaaSFacet + OperatorRuntime -->|"spec fetch"| IPFSGateway + OperatorRuntime -->|"submit response"| HookAttestationTaskManager +``` + +**Goal**: Separate concerns between immutable on-chain contracts and upgradeable off-chain verification logic. + +### Data Flow Summary + +Primary flows that realize system responsibilities: + +1. **Protocol Creation**: `ProtocolAdmin` -> `ProtocolAdminClient` -> `ProtocolAdminRegistry` -> `ProtocolAdminManager` +2. **Pool Creation**: `ProtocolAdmin` -> `ProtocolAdminClient` -> `ProtocolHookMediator` -> `UniswapV4.initialize` +3. **Hook Registration**: `HookDeveloper` -> `HaaSVendorManagement.commitToHookSpec` -> `HookLicense NFT` +4. **Attestation Flow**: `createAttestationTask` -> `OperatorRuntime` -> `respondToAttestationTask` -> `AttestationRegistry` +5. **Bonded Engagement**: `HookDeveloper` -> `EscrowCoordinator.postBond` -> `ClearingHouse.acceptBondedEngagement` + +Reference: [context-diagram.md](./context-diagram.md) + +### Bonded Hooks Comparison + +Hook Bazaar and Bonded Hooks are complementary solutions for different market segments: + +| Dimension | Bonded Hooks | Hook Bazaar | +|-----------|-------------|-------------| +| Primary Focus | Low-code hook composition | IP-protected hook marketplace | +| Target User | Pool admins, non-developers | Hook developers, integrators | +| Verification | Centralized AVS operator | Decentralized EigenLayer AVS | +| IP Model | Open source commands | Encrypted implementations | +| Composability | Native command chaining | Diamond facet routing | + +**Key Differentiator**: Hook Bazaar provides mathematical specification verification with cryptoeconomic guarantees (slashing), while Bonded Hooks prioritizes ease of use through pre-built command blocks. + +**Integration Potential**: Hook Bazaar verified hooks could be wrapped as Bonded Hooks commands, combining IP protection with composability. + +Reference: [bonded-hooks-comparison.md](./hook-pkg/architecture/bonded-hooks-comparison.md) + +**EigenLayer Integration**: The off-chain operator runtime implements the verification workflow with planned BLS signature aggregation for multi-operator consensus. See [operator/README.md](../operator/README.md) for implementation details and EigenLayer component dependencies. + +--- + +## System-Level Documents + +| Document | Description | +|----------|-------------| +| [mission-statement.json](./mission-statement.json) | System purpose, responsibilities, exclusions (JSON schema) | +| [function-refinement-tree.json](./function-refinement-tree.json) | Hierarchical service decomposition (JSON schema) | +| [context-diagram.md](./context-diagram.md) | System boundary and external actor interactions | +| [problem-description.md](./problem-description.md) | Market failures and value propositions | + +## Package Documentation + +### protocol-pkg + +Protocol lifecycle management for Uniswap V4 pool administration. + +| Document | Description | +|----------|-------------| +| [solutionSpec.md](./protocol-pkg/solutionSpec.md) | Context diagram, workflow, state transitions | +| [roadmap.md](./protocol-pkg/roadmap.md) | Implementation status and TODOs | + +**Key Contracts:** +- `ProtocolAdminClient` - Entry point for protocol/pool creation +- `ProtocolAdminManager` - Per-protocol access control + +### hooks-operator-avs (Hook Attestation) + +EigenLayer AVS for hook specification verification. + +| Document | Description | +|----------|-------------| +| [solutionSpec.md](./hook-attestation-pkg/solutionSpec.md) | Attestation flow, challenge mechanism, bonded engagement | +| [roadmap.md](./hook-attestation-pkg/roadmap.md) | Contract and operator implementation status | + +**Key Contracts:** +- `HookAttestationTaskManager` - Task creation and response handling +- `AttestationRegistry` - Attestation storage and validity +- `HaaSVendorManagement` - HookLicense NFT issuance +- `ClearingHouse` / `EscrowCoordinator` - Bonded engagement + +**Off-Chain:** +- [operator/README.md](../operator/README.md) - Operator runtime with EigenLayer integration roadmap +- `operator/src/HookAttestationAVS.ts` - Main runtime +- `operator/src/processor.ts` - Task processing pipeline + +### hook-pkg + +Hook development, marketplace, and IP protection. + +#### hook-pkg/development + +Base contracts for HaaS-compliant hook implementation. + +| Document | Description | +|----------|-------------| +| [solutionSpec.md](./hook-pkg/development/solutionSpec.md) | HaaSMod storage, HaaSFacet callbacks, authorization | +| [roadmap.md](./hook-pkg/development/roadmap.md) | Implementation status | + +**Key Contracts:** +- `HaaSMod` - Diamond-compatible base storage +- `HaaSFacet` - IHooks implementation template + +#### hook-pkg/market + +Hook discovery, licensing, and revenue distribution. + +| Document | Description | +|----------|-------------| +| [solutionSpec.md](./hook-pkg/market/solutionSpec.md) | Pricing models, Splits integration, license lifecycle | +| [roadmap.md](./hook-pkg/market/roadmap.md) | Marketplace implementation status | + +**Key Interfaces:** +- `IHaaSMarket` - Marketplace operations +- `IHookLicenseIssuer` - License management + +#### hook-pkg/cofhe-haas + +Fhenix CoFHE integration for IP-protected hooks. + +| Document | Description | +|----------|-------------| +| [solutionSpec.md](./hook-pkg/cofhe-haas/solutionSpec.md) | Encryption architecture, callback flow, security | +| [roadmap.md](./hook-pkg/cofhe-haas/roadmap.md) | CoFHE implementation status | + +**Key Contracts:** +- `CoFHEHook` - IHooks wrapper with encryption boundary +- `ICoFHEHookMod` - Encrypted callback interface + +### hook-market-pkg + +Extended marketplace documentation. + +| Document | Description | +|----------|-------------| +| [market_structure_docs.md](./hook-market-pkg/market_structure_docs.md) | Trading mechanisms analysis | +| [integrations.md](./hook-market-pkg/integrations.md) | Splits protocol integration | + +## Architecture References + +Located in `docs/hook-pkg/architecture/`: + +| Document | Description | +|----------|-------------| +| [mission-statement.md](./hook-pkg/architecture/mission-statement.md) | Strategic foundation (Markdown) | +| [avs-verification-system.md](./hook-pkg/architecture/avs-verification-system.md) | AVS technical specification | +| [bonded-hooks-comparison.md](./hook-pkg/architecture/bonded-hooks-comparison.md) | Comparison with Bonded Hooks | +| [function-refinement-tree.md](./hook-pkg/architecture/function-refinement-tree.md) | Detailed function decomposition | + +## Documentation Standards + +Per [requirements-specification-agent-system-prompt.md](../agents/requirements-specification-agent-system-prompt.md): + +- All diagrams use Mermaid syntax +- JSON schemas for Mission Statement and Function Refinement Tree +- Per-package `solutionSpec.md` and `roadmap.md` required +- Code hyperlinks mandatory for traceability +- No emojis in technical documentation diff --git a/docs/diagrams.md b/docs/diagrams.md new file mode 100644 index 000000000..6578d0c43 --- /dev/null +++ b/docs/diagrams.md @@ -0,0 +1,96 @@ +# Hook Bazaar: System Context Diagram + +## Context Diagram + +```mermaid +flowchart TB + subgraph Environment["Hook Bazaar Environment"] + subgraph HookBazaar["Hook Bazaar System"] + ProtocolPkg["protocol-pkg"] + HooksOperatorAVS["hooks-operator-avs"] + HookPkg["hook-pkg"] + MasterHookPkg["master-hook-pkg"] + end + end + + %% External Actors + ProtocolAdmin["Protocol Admin"] + HookDeveloper["Hook Developer"] + AVSOperator["AVS Operator"] + Trader["Trader/LP"] + + %% External Systems + UniswapV4["Uniswap V4 PoolManager"] + EigenLayer["EigenLayer AVSDirectory"] + IPFS["IPFS (Specifications)"] + Fhenix["Fhenix CoFHE"] + + %% Actor -> System flows + ProtocolAdmin -->|"create_protocol\ncreate_pool"| ProtocolPkg + HookDeveloper -->|"commitToHookSpec\npost implementation"| HookPkg + AVSOperator -->|"acceptBondedEngagement\nrespondToTask"| HooksOperatorAVS + Trader -->|"swap\naddLiquidity"| UniswapV4 + + %% System -> External flows + ProtocolPkg -->|"initialize pool"| UniswapV4 + HooksOperatorAVS -->|"registerOperator\nslash"| EigenLayer + HookPkg -->|"fetch spec"| IPFS + HookPkg -.->|"encrypted code (future)"| Fhenix + MasterHookPkg -->|"hook callbacks"| UniswapV4 + + %% Internal flows + ProtocolPkg --> MasterHookPkg + HooksOperatorAVS --> HookPkg + HookPkg --> MasterHookPkg +``` + +## Actor Descriptions + +| Actor | Role | Primary Interactions | +|-------|------|---------------------| +| **Protocol Admin** | Creates protocols and pools | `create_protocol`, `create_pool`, `delegatePoolCreatorRole` | +| **Hook Developer** | Builds and monetizes hooks | `commitToHookSpec`, deploy `HaaSFacet` implementations | +| **AVS Operator** | Verifies hook compliance | `acceptBondedEngagement`, `respondToAttestationTask` | +| **Trader/LP** | End user of pools | Swaps and liquidity operations via Uniswap V4 | + +## External System Boundaries + +| System | Interface Type | Purpose | +|--------|---------------|---------| +| **Uniswap V4 PoolManager** | Smart Contract | Pool initialization, swap execution, hook callbacks | +| **EigenLayer AVSDirectory** | Smart Contract | Operator registration, stake management, slashing | +| **IPFS** | Storage | Hook specification documents (JSON/YAML) | +| **Fhenix CoFHE** | Encryption | IP-protected hook implementations (future) | + +## Communication Channels + +```mermaid +flowchart LR + subgraph OnChain["On-Chain"] + ProtocolAdminClient + HookAttestationTaskManager + AttestationRegistry + HaaSVendorManagement + ClearingHouse + EscrowCoordinator + HaaSFacet + end + + subgraph OffChain["Off-Chain"] + OperatorRuntime["Operator Runtime (TypeScript)"] + IPFSGateway["IPFS Gateway"] + end + + OperatorRuntime -->|"event listener"| HookAttestationTaskManager + OperatorRuntime -->|"state sampling"| HaaSFacet + OperatorRuntime -->|"spec fetch"| IPFSGateway + OperatorRuntime -->|"submit response"| HookAttestationTaskManager +``` + +## Data Flow Summary + +1. **Protocol Creation**: `ProtocolAdmin` -> `ProtocolAdminClient` -> `ProtocolAdminRegistry` -> `ProtocolAdminManager` +2. **Pool Creation**: `ProtocolAdmin` -> `ProtocolAdminClient` -> `ProtocolHookMediator` -> `UniswapV4.initialize` +3. **Hook Registration**: `HookDeveloper` -> `HaaSVendorManagement.commitToHookSpec` -> `HookLicense NFT` +4. **Attestation Flow**: `createAttestationTask` -> `OperatorRuntime` -> `respondToAttestationTask` -> `AttestationRegistry` +5. **Bonded Engagement**: `HookDeveloper` -> `EscrowCoordinator.postBond` -> `ClearingHouse.acceptBondedEngagement` diff --git a/docs/function-refinement-tree.json b/docs/function-refinement-tree.json new file mode 100644 index 000000000..cd52ab369 --- /dev/null +++ b/docs/function-refinement-tree.json @@ -0,0 +1,71 @@ +{ + "root": "HookBazaar Mission Statement", + "functions": [ + { + "name": "Protocol Administration", + "services": [ + "create_protocol: Initialize protocol with admin manager and NFT ownership", + "create_pool: Deploy Uniswap V4 pool through hook mediator with access control", + "delegatePoolCreatorRole: Grant pool creation permissions to accounts", + "setURI: Configure protocol metadata (ZORA, website, social links)" + ] + }, + { + "name": "Hook Attestation", + "services": [ + "createAttestationTask: Submit hook for specification verification with pools and callbacks", + "respondToAttestationTask: Record operator consensus on specification compliance", + "challengeFalsePositive: Contest incorrect compliant attestation with counter-sample", + "challengeFalseNegative: Contest incorrect non-compliant attestation with compliance samples", + "recordAttestation: Store verified attestation with expiration", + "revokeAttestation: Invalidate attestation on successful challenge", + "renewAttestation: Extend attestation validity after re-verification" + ] + }, + { + "name": "Vendor Management", + "services": [ + "commitToHookSpec: Register hook developer with specification URI and receive license NFT", + "getHookLicense: Retrieve license details and strategies", + "revokeLicense: Invalidate developer license", + "getHaaSEngagementParams: Retrieve quorum and pubkey params for bonded engagement" + ] + }, + { + "name": "Bonded Engagement", + "services": [ + "acceptBondedEngagement: Register operator with clearing coordinator for license", + "terminateBondedEngagement: Deregister operator and end engagement", + "postBond: Deposit collateral for license engagement", + "releaseBond: Return collateral after lock period", + "slashBond: Penalize collateral for non-compliance" + ] + }, + { + "name": "Operator Verification (Off-chain)", + "services": [ + "processAttestationTask: Execute spec-parsing, state-sampling, compliance-checking workflow", + "sampleStatesForTask: Collect pre/post state transitions across pools and callbacks", + "checkCompliance: Verify sampled states against specification invariants", + "submitResponse: Aggregate results and submit on-chain (BLS signature pending)" + ] + }, + { + "name": "Hook Development", + "services": [ + "HaaSFacet callbacks: beforeSwap, afterSwap, beforeAddLiquidity, afterAddLiquidity, etc.", + "setAuthorization: Grant developer permissions on hook facet", + "HookStateLens: Read hook state for external verification" + ] + }, + { + "name": "Service Management", + "services": [ + "registerOperatorToAVS: Onboard operator with stake", + "deregisterOperatorFromAVS: Remove operator from service", + "slashOperator: Penalize operator stake for offenses", + "getOperatorStake: Query operator collateral" + ] + } + ] +} diff --git a/docs/avs-integration/ECDSAStakeRegistry.md b/docs/hook-attestation-pkg/ECDSAStakeRegistry.md similarity index 100% rename from docs/avs-integration/ECDSAStakeRegistry.md rename to docs/hook-attestation-pkg/ECDSAStakeRegistry.md diff --git a/docs/avs-integration/Quorums.md b/docs/hook-attestation-pkg/Quorums.md similarity index 100% rename from docs/avs-integration/Quorums.md rename to docs/hook-attestation-pkg/Quorums.md diff --git a/docs/avs-integration/RegistryCoordinator.md b/docs/hook-attestation-pkg/RegistryCoordinator.md similarity index 100% rename from docs/avs-integration/RegistryCoordinator.md rename to docs/hook-attestation-pkg/RegistryCoordinator.md diff --git a/docs/avs-integration/StakeRegistry.md b/docs/hook-attestation-pkg/StakeRegistry.md similarity index 100% rename from docs/avs-integration/StakeRegistry.md rename to docs/hook-attestation-pkg/StakeRegistry.md diff --git a/docs/hook-attestation-pkg/roadmap.md b/docs/hook-attestation-pkg/roadmap.md new file mode 100644 index 000000000..34010b670 --- /dev/null +++ b/docs/hook-attestation-pkg/roadmap.md @@ -0,0 +1,49 @@ +# hooks-operator-avs: Roadmap + +## Contracts + +| Status | Feature | Test Reference | +|--------|---------|----------------| +| TODO | createAttestationTask event emission | [HookAttestationTaskManager.t.sol:27](../../contracts/test/hooks-operator-avs/HookAttestationTaskManager.t.sol) | +| TODO | createTask revert for zero hook address | [HookAttestationTaskManager.t.sol:42](../../contracts/test/hooks-operator-avs/HookAttestationTaskManager.t.sol) | +| TODO | createTask revert for empty specURI | [HookAttestationTaskManager.t.sol:53](../../contracts/test/hooks-operator-avs/HookAttestationTaskManager.t.sol) | +| TODO | createTask revert for empty poolIds | [HookAttestationTaskManager.t.sol:64](../../contracts/test/hooks-operator-avs/HookAttestationTaskManager.t.sol) | +| TODO | createTask store correct task data | [HookAttestationTaskManager.t.sol:75](../../contracts/test/hooks-operator-avs/HookAttestationTaskManager.t.sol) | +| TODO | respondToAttestationTask with valid signature | Requires BLS infrastructure | +| TODO | respondToAttestationTask window enforcement | Response after window should revert | +| TODO | challengeFalsePositive verification | Counter-sample validation logic | +| TODO | challengeFalseNegative verification | Compliance samples validation logic | +| TODO | AttestationRegistry recordAttestation | [AttestationRegistry.t.sol](../../contracts/test/hooks-operator-avs/AttestationRegistry.t.sol) | +| TODO | AttestationRegistry revokeAttestation | Challenge-triggered revocation | +| TODO | AttestationRegistry renewAttestation | Re-verification flow | +| TODO | HaaSVendorManagement commitToHookSpec | [HaaSVendorManagement.t.sol](../../contracts/test/hooks-operator-avs/HaaSVendorManagement.t.sol) | +| TODO | HaaSVendorManagement license NFT minting | ERC721 integration | +| TODO | ClearingHouse acceptBondedEngagement | [ClearingHouseEscrow.t.sol](../../contracts/test/hooks-operator-avs/ClearingHouseEscrow.t.sol) | +| TODO | ClearingHouse terminateBondedEngagement | Deregistration flow | +| TODO | EscrowCoordinator postBond | Bond deposit with strategy | +| TODO | EscrowCoordinator releaseBond | Post-lock release | +| TODO | EscrowCoordinator slashBond | Penalty execution | +| TODO | HookStateSampler getHookState | [HookStateSampler.t.sol](../../contracts/test/hooks-operator-avs/HookStateSampler.t.sol) | + +## Operator Runtime + +| Status | Feature | Test Reference | +|--------|---------|----------------| +| Implemented | Event listener setup | [HookAttestationAVS.ts:205](../../operator/src/HookAttestationAVS.ts) | +| Implemented | Task processing pipeline | [processor.ts:71](../../operator/src/processor.ts) | +| Implemented | Specification parsing | [specParser.ts](../../operator/src/specParser.ts) | +| Implemented | Compliance checking | [complianceChecker.ts](../../operator/src/complianceChecker.ts) | +| Implemented | State sampling | [stateSampler.ts](../../operator/src/stateSampler.ts) | +| TODO | BLS signature aggregation | Response signing infrastructure | +| TODO | On-chain response submission | Awaiting BLS setup | +| TODO | Multi-operator coordination | Quorum formation | + +## EigenLayer Integration + +| Status | Feature | Notes | +|--------|---------|-------| +| Scaffolded | AVSDirectory registration | Interface defined, awaiting deployment | +| Scaffolded | StakeRegistry integration | Operator stake tracking | +| TODO | BLSSignatureChecker | Full signature verification | +| TODO | AllocationManager slashing | Economic penalty execution | +| TODO | RewardsCoordinator | Operator reward distribution | diff --git a/docs/hook-attestation-pkg/solutionSpec.md b/docs/hook-attestation-pkg/solutionSpec.md new file mode 100644 index 000000000..f3bcc4d4b --- /dev/null +++ b/docs/hook-attestation-pkg/solutionSpec.md @@ -0,0 +1,286 @@ +# hooks-operator-avs: Solution Specification + +## Problem Description + +Hook integrators need trustless guarantees that hook implementations conform to advertised specifications. Traditional audits are: +- Point-in-time (don't catch runtime violations) +- Expensive (prohibitive for small hooks) +- Opaque (integrators must trust auditor reputation) + +The system requires: +- Continuous behavioral verification against specifications +- Economic accountability via staked collateral +- Challenge mechanisms for false attestations +- Decentralized operator network for sampling + +## Solution Overview + +The `hooks-operator-avs` package implements an EigenLayer AVS for hook specification verification: + +```mermaid +flowchart TB + subgraph Context["hooks-operator-avs Context"] + HookAttestationTaskManager["HookAttestationTaskManager
(Task Coordination)"] + HookAttestationServiceManager["HookAttestationServiceManager
(Operator Management)"] + AttestationRegistry["AttestationRegistry
(Attestation Storage)"] + HaaSVendorManagement["HaaSVendorManagement
(License NFTs)"] + ClearingHouse["ClearingHouse
(Bonded Engagement)"] + EscrowCoordinator["EscrowCoordinator
(Bond Management)"] + HookStateSampler["HookStateSampler
(On-chain Sampling)"] + end + + subgraph OffChain["Off-Chain Components"] + OperatorRuntime["Operator Runtime
(TypeScript)"] + SpecParser["Spec Parser"] + ComplianceChecker["Compliance Checker"] + StateSampler["State Sampler"] + end + + HookDeveloper["Hook Developer"] -->|"commitToHookSpec"| HaaSVendorManagement + HookDeveloper -->|"postBond"| EscrowCoordinator + HookDeveloper -->|"acceptBondedEngagement"| ClearingHouse + + Requester["Attestation Requester"] -->|"createAttestationTask"| HookAttestationTaskManager + + OperatorRuntime -->|"listen events"| HookAttestationTaskManager + OperatorRuntime -->|"fetch spec"| IPFS["IPFS"] + OperatorRuntime -->|"sample state"| HookStateSampler + OperatorRuntime -->|"respondToAttestationTask"| HookAttestationTaskManager + + HookAttestationTaskManager -->|"recordAttestation"| AttestationRegistry + HookAttestationTaskManager -->|"slashOperator"| HookAttestationServiceManager + + HookAttestationServiceManager -->|"register/deregister"| EigenLayer["EigenLayer AVSDirectory"] + ClearingHouse -->|"register"| RegistryCoordinator["RegistryCoordinator"] + EscrowCoordinator -->|"deposit"| StrategyManager["StrategyManager"] +``` + +## Component Responsibilities + +| Contract | Source | Responsibility | +|----------|--------|----------------| +| `HookAttestationTaskManager` | [src/hooks-operator-avs/HookAttestationTaskManager.sol](../../contracts/src/hooks-operator-avs/HookAttestationTaskManager.sol) | Task creation, response handling, challenge processing | +| `HookAttestationServiceManager` | [src/hooks-operator-avs/HookAttestationServiceManager.sol](../../contracts/src/hooks-operator-avs/HookAttestationServiceManager.sol) | Operator registration, stake management, slashing | +| `AttestationRegistry` | [src/hooks-operator-avs/AttestationRegistry.sol](../../contracts/src/hooks-operator-avs/AttestationRegistry.sol) | Attestation storage, validity, revocation | +| `HaaSVendorManagement` | [src/hooks-operator-avs/HaaSVendorManagement.sol](../../contracts/src/hooks-operator-avs/HaaSVendorManagement.sol) | HookLicense NFT minting, developer registration | +| `ClearingHouse` | [src/hooks-operator-avs/ClearingHouse.sol](../../contracts/src/hooks-operator-avs/ClearingHouse.sol) | Bonded engagement acceptance/termination | +| `EscrowCoordinator` | [src/hooks-operator-avs/EscrowCoordinator.sol](../../contracts/src/hooks-operator-avs/EscrowCoordinator.sol) | Bond posting, release, slashing | +| `HookStateSampler` | [src/hooks-operator-avs/HookStateSampler.sol](../../contracts/src/hooks-operator-avs/HookStateSampler.sol) | On-chain state sampling for hooks | + +## Off-Chain Operator Components + +| Module | Source | Responsibility | +|--------|--------|----------------| +| `HookAttestationAVS` | [operator/src/HookAttestationAVS.ts](../../operator/src/HookAttestationAVS.ts) | Main runtime, event listener, response submission | +| `processor` | [operator/src/processor.ts](../../operator/src/processor.ts) | Task processing orchestration | +| `specParser` | [operator/src/specParser.ts](../../operator/src/specParser.ts) | Specification fetching and parsing | +| `complianceChecker` | [operator/src/complianceChecker.ts](../../operator/src/complianceChecker.ts) | State sample verification against spec | +| `stateSampler` | [operator/src/stateSampler.ts](../../operator/src/stateSampler.ts) | State collection from hooks | + +## Attestation Task Workflow + +```mermaid +sequenceDiagram + participant Requester + participant TaskManager as HookAttestationTaskManager + participant Operator as Operator Runtime + participant Hook as Hook Contract + participant Spec as IPFS (Specification) + participant Registry as AttestationRegistry + + %% Task Creation + Requester->>TaskManager: createAttestationTask(hook, specURI, poolIds, callbacks, sampleCount) + TaskManager-->>TaskManager: store task, emit AttestationTaskCreated + + %% Operator Processing + Operator->>TaskManager: listen AttestationTaskCreated + TaskManager-->>Operator: task details + + Operator->>Spec: fetch specification + Spec-->>Operator: HookSpecification JSON + + loop For each pool x callback + Operator->>Hook: sample pre-state + Hook-->>Operator: state variables + Note over Operator: Execute callback (simulated) + Operator->>Hook: sample post-state + Hook-->>Operator: state variables + Operator-->>Operator: verify against spec invariants + end + + %% Response Submission + alt All samples compliant + Operator->>TaskManager: respondToAttestationTask(task, response{specCompliant: true}, signature) + TaskManager->>Registry: recordAttestation(hook, specURI, taskIndex, responseHash) + Registry-->>Registry: store attestation with 30-day expiry + TaskManager-->>Requester: TaskCompleted(taskIndex, true) + else Non-compliant samples found + Operator->>TaskManager: respondToAttestationTask(task, response{specCompliant: false}, signature) + TaskManager-->>Requester: TaskCompleted(taskIndex, false) + end +``` + +## Challenge Mechanism + +```mermaid +sequenceDiagram + participant Challenger + participant TaskManager as HookAttestationTaskManager + participant Registry as AttestationRegistry + participant ServiceManager as HookAttestationServiceManager + + %% False Positive Challenge + alt Challenge False Positive (hook attested but non-compliant) + Challenger->>TaskManager: challengeFalsePositive(task, response, counterSample) + TaskManager-->>TaskManager: verify counterSample proves non-compliance + alt Challenge successful + TaskManager->>Registry: revokeAttestation(hook, "Challenge successful") + TaskManager->>ServiceManager: slashOperator(operator, FALSE_POSITIVE, evidence) + TaskManager-->>Challenger: AttestationChallenged(taskIndex, challenger, true) + else Challenge failed + TaskManager-->>Challenger: AttestationChallenged(taskIndex, challenger, false) + end + end + + %% False Negative Challenge + alt Challenge False Negative (hook rejected but compliant) + Challenger->>TaskManager: challengeFalseNegative(task, response, complianceSamples) + TaskManager-->>TaskManager: verify samples prove compliance + alt Challenge successful + TaskManager->>Registry: recordAttestation(hook, specURI, taskIndex, hash) + TaskManager->>ServiceManager: slashOperator(operator, FALSE_NEGATIVE, evidence) + TaskManager-->>Challenger: AttestationChallenged(taskIndex, challenger, true) + else Challenge failed + TaskManager-->>Challenger: AttestationChallenged(taskIndex, challenger, false) + end + end +``` + +## State Transition Diagram: Attestation Lifecycle + +```mermaid +stateDiagram-v2 + [*] --> NoAttestation: Hook deployed + + NoAttestation --> TaskPending: createAttestationTask() + + TaskPending --> TaskResponded: respondToAttestationTask() + TaskPending --> TaskExpired: TASK_RESPONSE_WINDOW_BLOCK exceeded + + TaskResponded --> Attested: specCompliant = true + TaskResponded --> NotAttested: specCompliant = false + + Attested --> ChallengePeriod: within TASK_CHALLENGE_WINDOW_BLOCK + ChallengePeriod --> AttestationValid: no successful challenge + ChallengePeriod --> AttestationRevoked: challengeFalsePositive() succeeds + + AttestationValid --> AttestationExpired: 30 days elapsed + AttestationExpired --> TaskPending: renewAttestation() requested + + NotAttested --> TaskPending: challengeFalseNegative() succeeds +``` + +## Slashing Conditions + +| Offense | Slash Percentage | Condition | +|---------|-----------------|-----------| +| `OPERATOR_COLLUSION` | 100% | Multiple operators coordinate false attestations | +| `FALSE_POSITIVE` | 50% | Attested non-compliant hook as compliant | +| `FALSE_NEGATIVE` | 30% | Rejected compliant hook as non-compliant | +| `SAMPLE_MANIPULATION` | 20% | Tampered with state sampling | + +## Bonded Engagement Flow + +```mermaid +sequenceDiagram + participant Developer as Hook Developer + participant Vendor as HaaSVendorManagement + participant Escrow as EscrowCoordinator + participant Clearing as ClearingHouse + participant Registry as RegistryCoordinator + + %% Developer Registration + Developer->>Vendor: commitToHookSpec(specURI, signature, operatorAccount) + Vendor-->>Developer: licenseId (NFT minted) + + %% Bond Posting + Developer->>Escrow: postBond(licenseId) + Note over Escrow: Transfer tokens, deposit to strategy + Escrow-->>Developer: BondPosted event + + %% Engagement Acceptance + Developer->>Clearing: acceptBondedEngagement(signature, licenseId) + Clearing->>Vendor: validate license, get params + Clearing->>Registry: registerOperator(quorumNumbers, socket, params) + Clearing-->>Developer: BondedEngagementAccepted event + + %% Service Delivery + Note over Developer: Provide HaaS services + + %% Termination + alt Successful completion + Developer->>Clearing: terminateBondedEngagement(licenseId, reason) + Clearing->>Registry: deregisterOperator(quorumNumbers) + Note over Escrow: Bond locked for 7 days + Developer->>Escrow: releaseBond(licenseId) + Escrow-->>Developer: Bond returned + else Non-compliance + Note over Escrow: Owner calls slashBond + Escrow-->>Developer: Partial/full bond slashed + end +``` + +## Data Structures + +```solidity +// AttestationTask +struct AttestationTask { + address hook; + string specificationURI; + bytes32[] poolIds; + bytes4[] callbacks; + uint32 sampleCount; + uint32 taskCreatedBlock; + bytes quorumNumbers; + uint32 quorumThresholdPercentage; +} + +// Attestation +struct Attestation { + bytes32 attestationId; + address hook; + string specificationURI; + bool isValid; + uint256 attestedAt; + uint256 expiresAt; + uint32 taskIndex; + bytes32 responsesHash; +} + +// HookLicense +struct HookLicense { + uint256 licenseId; + StrategyParams[] haasStrategies; + address socketManager; +} + +// BondDetails +struct BondDetails { + IERC20 paymentToken; + uint256 bondAmount; + uint256 depositedAmount; + address depositor; + uint256 lockedUntil; + bool isActive; +} +``` + +## Constants + +| Constant | Value | Contract | +|----------|-------|----------| +| `TASK_RESPONSE_WINDOW_BLOCK` | 100 blocks | HookAttestationTaskManager | +| `TASK_CHALLENGE_WINDOW_BLOCK` | 200 blocks | HookAttestationTaskManager | +| `COMPLIANCE_TOLERANCE` | 100 bps (1%) | HookAttestationTaskManager | +| `ATTESTATION_VALIDITY_PERIOD` | 30 days | AttestationRegistry | +| `BOND_LOCK_PERIOD` | 7 days | EscrowCoordinator | diff --git a/documentation/integrations.md b/docs/hook-market-pkg/integrations.md similarity index 100% rename from documentation/integrations.md rename to docs/hook-market-pkg/integrations.md diff --git a/documentation/market_structure_docs.md b/docs/hook-market-pkg/market_structure_docs.md similarity index 100% rename from documentation/market_structure_docs.md rename to docs/hook-market-pkg/market_structure_docs.md diff --git a/docs/hook-pkg/cofhe-haas/roadmap.md b/docs/hook-pkg/cofhe-haas/roadmap.md new file mode 100644 index 000000000..a75236c2b --- /dev/null +++ b/docs/hook-pkg/cofhe-haas/roadmap.md @@ -0,0 +1,19 @@ +# hook-pkg/cofhe-haas: Roadmap + +| Status | Feature | Source Reference | +|--------|---------|------------------| +| Implemented | CoFHEHook IHooks wrapper | [CoFHEHook.sol:19](../../../contracts/src/hook-pkg/CoFHEHook.sol) | +| Implemented | Encryption helpers (all types) | [CoFHEHook.sol:103-168](../../../contracts/src/hook-pkg/CoFHEHook.sol) | +| Implemented | Decryption helpers | [CoFHEHook.sol:174-191](../../../contracts/src/hook-pkg/CoFHEHook.sol) | +| Implemented | ICoFHEHookMod interface | [interfaces/ICoFHEHookMod.sol](../../../contracts/src/hook-pkg/interfaces/ICoFHEHookMod.sol) | +| Implemented | ICoFHETypes definitions | [interfaces/ICoFHETypes.sol](../../../contracts/src/hook-pkg/interfaces/ICoFHETypes.sol) | +| Implemented | setHookMod admin | [CoFHEHook.sol:88](../../../contracts/src/hook-pkg/CoFHEHook.sol) | +| Implemented | setVerifierAuthorization | [CoFHEHook.sol:94](../../../contracts/src/hook-pkg/CoFHEHook.sol) | +| Implemented | beforeSwap encrypted flow | [CoFHEHook.sol:304-324](../../../contracts/src/hook-pkg/CoFHEHook.sol) | +| Implemented | afterSwap encrypted flow | [CoFHEHook.sol:326-344](../../../contracts/src/hook-pkg/CoFHEHook.sol) | +| TODO | CoFHEHookMod base implementation | Encrypted computation template | +| TODO | MockCoFHECounterHookMod completion | [mocks/MockCoFHECounterHookMod.sol](../../../contracts/src/hook-pkg/mocks/MockCoFHECounterHookMod.sol) | +| TODO | Gas benchmarking suite | Measure encryption overhead | +| TODO | Fhenix mainnet deployment | Production-ready encryption | +| TODO | State exposure for AVS | Encrypted state sampling interface | +| TODO | Fallback mode (non-encrypted) | Graceful degradation | diff --git a/docs/hook-pkg/cofhe-haas/solutionSpec.md b/docs/hook-pkg/cofhe-haas/solutionSpec.md new file mode 100644 index 000000000..b9bca6586 --- /dev/null +++ b/docs/hook-pkg/cofhe-haas/solutionSpec.md @@ -0,0 +1,226 @@ +# hook-pkg/cofhe-haas: CoFHE IP Protection Solution Specification + +## Problem Description + +Hook developers face IP theft risk because: +- Deployed bytecode is publicly readable +- Decompilation reveals algorithmic logic +- Competitors can copy and redeploy without compensation +- Premium algorithms (MEV protection, IL mitigation) lose competitive advantage + +## Solution Overview + +The CoFHE (Confidential FHE) subsystem provides IP protection through Fhenix encryption: + +```mermaid +flowchart TB + subgraph Context["CoFHE HaaS Context"] + CoFHEHook["CoFHEHook
(IHooks Wrapper)"] + CoFHEHookMod["CoFHEHookMod
(Encrypted Logic)"] + EncryptedState["Encrypted State
(euint256, eaddress, etc.)"] + end + + PoolManager["Uniswap V4 PoolManager"] -->|"plaintext params"| CoFHEHook + CoFHEHook -->|"encrypted params"| CoFHEHookMod + CoFHEHookMod -->|"encrypted state"| EncryptedState + CoFHEHookMod -->|"encrypted result"| CoFHEHook + CoFHEHook -->|"decrypted result"| PoolManager + + Developer["Hook Developer"] -->|"setHookMod"| CoFHEHook + Developer -->|"setVerifierAuthorization"| CoFHEHook + AVSVerifier["AVS Verifier"] -->|"authorized access"| CoFHEHook +``` + +## Component Responsibilities + +| Contract | Source | Responsibility | +|----------|--------|----------------| +| `CoFHEHook` | [src/hook-pkg/CoFHEHook.sol](../../../contracts/src/hook-pkg/CoFHEHook.sol) | IHooks interface, encryption/decryption boundary | +| `ICoFHEHookMod` | [src/hook-pkg/interfaces/ICoFHEHookMod.sol](../../../contracts/src/hook-pkg/interfaces/ICoFHEHookMod.sol) | Encrypted callback interface | +| `ICoFHETypes` | [src/hook-pkg/interfaces/ICoFHETypes.sol](../../../contracts/src/hook-pkg/interfaces/ICoFHETypes.sol) | Encrypted type definitions | + +## Encryption Architecture + +```mermaid +flowchart LR + subgraph Plaintext["Plaintext Layer"] + PoolKey["PoolKey"] + SwapParams["SwapParams"] + BalanceDelta["BalanceDelta"] + end + + subgraph Encrypted["Encrypted Layer (Fhenix)"] + EPoolKey["EPoolKey"] + ESwapParams["ESwapParams"] + EBalanceDelta["EBalanceDelta"] + end + + subgraph FHETypes["Fhenix Types"] + euint32["euint32"] + euint128["euint128"] + euint256["euint256"] + eaddress["eaddress"] + ebool["ebool"] + end + + PoolKey -->|"_encryptPoolKey"| EPoolKey + SwapParams -->|"_encryptSwapParams"| ESwapParams + BalanceDelta -->|"_encryptBalanceDelta"| EBalanceDelta + + EPoolKey --> euint32 & eaddress + ESwapParams --> ebool & euint256 + EBalanceDelta --> euint128 +``` + +## Encrypted Type Definitions + +```solidity +// Encrypted PoolKey +struct EPoolKey { + eaddress currency0; + eaddress currency1; + euint32 fee; // uint24 -> euint32 + euint32 tickSpacing; // int24 -> euint32 + eaddress hooks; +} + +// Encrypted SwapParams +struct ESwapParams { + ebool zeroForOne; + euint256 amountSpecified; // int256 stored as magnitude + euint256 sqrtPriceLimitX96; +} + +// Encrypted ModifyLiquidityParams +struct EModifyLiquidityParams { + euint32 tickLower; + euint32 tickUpper; + euint256 liquidityDelta; + euint256 salt; +} + +// Encrypted BalanceDelta +struct EBalanceDelta { + euint128 amount0; + euint128 amount1; +} + +// Encrypted BeforeSwapDelta +struct EBeforeSwapDelta { + euint128 deltaSpecified; + euint128 deltaUnspecified; +} +``` + +## Callback Flow + +```mermaid +sequenceDiagram + participant PM as PoolManager + participant Hook as CoFHEHook + participant Mod as CoFHEHookMod + participant FHE as Fhenix FHE + + PM->>Hook: beforeSwap(sender, key, params, data) + + Note over Hook: Encryption Phase + Hook->>FHE: FHE.asEaddress(sender) + FHE-->>Hook: eaddress sender + Hook->>FHE: _encryptPoolKey(key) + FHE-->>Hook: EPoolKey + Hook->>FHE: _encryptSwapParams(params) + FHE-->>Hook: ESwapParams + + Hook->>Mod: beforeSwap(eSender, eKey, eParams, data) + Note over Mod: Encrypted computation
(logic hidden) + Mod-->>Hook: (selector, EBeforeSwapDelta, euint32 fee) + + Note over Hook: Decryption Phase + Hook->>FHE: FHE.decrypt(eDelta) + FHE-->>Hook: BeforeSwapDelta + Hook->>FHE: FHE.decrypt(eFee) + FHE-->>Hook: uint24 fee + + Hook-->>PM: (selector, delta, fee) +``` + +## Authorization Model + +```mermaid +flowchart TB + subgraph Access["Access Control"] + Developer["developer
(immutable)"] + Verifiers["authorizedVerifiers
(mapping)"] + end + + subgraph Actions["Authorized Actions"] + SetMod["setHookMod()"] + SetAuth["setVerifierAuthorization()"] + StateAccess["Decrypt state access"] + end + + Developer -->|"onlyDeveloper"| SetMod + Developer -->|"onlyDeveloper"| SetAuth + Developer -->|"onlyAuthorized"| StateAccess + Verifiers -->|"onlyAuthorized"| StateAccess +``` + +## State Transition Diagram + +```mermaid +stateDiagram-v2 + [*] --> Deployed: constructor(poolManager, developer) + + Deployed --> ModSet: setHookMod(mod) + ModSet --> Ready: hookMod != address(0) + + Ready --> Processing: PoolManager callback + Processing --> Encrypting: receive plaintext + Encrypting --> Computing: call hookMod + Computing --> Decrypting: receive encrypted result + Decrypting --> Ready: return plaintext + + Ready --> ModSet: setHookMod(newMod) +``` + +## Security Considerations + +| Consideration | Mitigation | +|---------------|------------| +| Developer key compromise | Immutable developer address | +| Verifier collusion | Limited verifier set, slashing via AVS | +| Decryption oracle attacks | onlyAuthorized modifier | +| Gas cost overhead | Batch operations where possible | +| Fhenix availability | Fallback to non-encrypted mode (future) | + +## Integration with AVS Verification + +```mermaid +flowchart TB + subgraph Verification["AVS Verification Layer"] + Operator["AVS Operator"] + TaskManager["HookAttestationTaskManager"] + end + + subgraph CoFHE["CoFHE Hook"] + Hook["CoFHEHook"] + Auth["authorizedVerifiers"] + end + + Developer["Developer"] -->|"setVerifierAuthorization"| Auth + Operator -->|"authorized"| Auth + Auth -->|"allows"| Hook + Operator -->|"sample encrypted state"| Hook + Operator -->|"verify against spec"| TaskManager +``` + +## Gas Considerations + +| Operation | Estimated Overhead | +|-----------|-------------------| +| Encryption (per param) | ~10-50k gas | +| Decryption (per return) | ~10-50k gas | +| Encrypted computation | ~2-10x plaintext | +| beforeSwap total | ~100-300k gas (vs ~20-50k plaintext) | + +Note: Gas costs depend on Fhenix network conditions and encryption complexity. diff --git a/docs/hook-pkg/development/roadmap.md b/docs/hook-pkg/development/roadmap.md new file mode 100644 index 000000000..bc43a47b9 --- /dev/null +++ b/docs/hook-pkg/development/roadmap.md @@ -0,0 +1,15 @@ +# hook-pkg/development: Roadmap + +| Status | Feature | Source Reference | +|--------|---------|------------------| +| Implemented | HaaSMod base storage pattern | [HaaSMod.sol:40](../../../contracts/src/hook-pkg/HaaSMod.sol) | +| Implemented | onlyPoolManager modifier | [HaaSMod.sol:62](../../../contracts/src/hook-pkg/HaaSMod.sol) | +| Implemented | onlyDeveloper modifier | [HaaSMod.sol:68](../../../contracts/src/hook-pkg/HaaSMod.sol) | +| Implemented | onlyAuthorized modifier | [HaaSMod.sol:74](../../../contracts/src/hook-pkg/HaaSMod.sol) | +| Implemented | HaaSFacet IHooks callbacks | [HaaSFacet.sol:60-154](../../../contracts/src/hook-pkg/HaaSFacet.sol) | +| Implemented | setAuthorization admin | [HaaSFacet.sol:160](../../../contracts/src/hook-pkg/HaaSFacet.sol) | +| Implemented | ERC165 supportsInterface | [HaaSFacet.sol:43](../../../contracts/src/hook-pkg/HaaSFacet.sol) | +| TODO | HookStateLens interface | State exposure for AVS sampling | +| TODO | Diamond facet integration tests | Multi-facet hook composition | +| TODO | Hook upgrade patterns | Safe facet replacement | +| TODO | Gas optimization benchmarks | Callback overhead measurement | diff --git a/docs/hook-pkg/development/solutionSpec.md b/docs/hook-pkg/development/solutionSpec.md new file mode 100644 index 000000000..529a90483 --- /dev/null +++ b/docs/hook-pkg/development/solutionSpec.md @@ -0,0 +1,163 @@ +# hook-pkg/development: Hook Development Solution Specification + +## Problem Description + +Hook developers need: +- Standardized base contracts for Uniswap V4 hook implementation +- Diamond-pattern compatible storage to avoid collisions +- Built-in authorization for developer access control +- State exposure interfaces for AVS verification + +## Solution Overview + +The development subsystem provides base contracts and patterns for building HaaS-compliant hooks: + +```mermaid +flowchart TB + subgraph Context["Hook Development Context"] + HaaSMod["HaaSMod
(Base Storage)"] + HaaSFacet["HaaSFacet
(IHooks Implementation)"] + HookStateLens["HookStateLens
(State Exposure)"] + end + + HookDeveloper["Hook Developer"] -->|"extends"| HaaSFacet + HaaSFacet -->|"inherits"| HaaSMod + + PoolManager["Uniswap V4 PoolManager"] -->|"callbacks"| HaaSFacet + AVSOperator["AVS Operator"] -->|"sample state"| HookStateLens +``` + +## Component Responsibilities + +| Contract | Source | Responsibility | +|----------|--------|----------------| +| `HaaSMod` | [src/hook-pkg/HaaSMod.sol](../../../contracts/src/hook-pkg/HaaSMod.sol) | Diamond-compatible storage, authorization modifiers | +| `HaaSFacet` | [src/hook-pkg/HaaSFacet.sol](../../../contracts/src/hook-pkg/HaaSFacet.sol) | IHooks interface with default implementations | +| `HookStateLens` | [src/hook-pkg/HookStateLens.sol](../../../contracts/src/hook-pkg/HookStateLens.sol) | Read-only state access for verification | + +## HaaSMod Storage Layout + +```solidity +bytes32 constant HAAS_STORAGE_POSITION = keccak256("hook-bazaar.haas.storage"); + +struct HaaSStorage { + IPoolManager poolManager; + IHaaSMarket hooksMarket; + IHookStateLens hookStateViewer; + IHookLicenseIssuer hookLicenseIssuer; + address developer; + mapping(address => bool) authorizedAccounts; +} +``` + +## Authorization Model + +```mermaid +flowchart TB + subgraph Modifiers["HaaSMod Modifiers"] + onlyPoolManager["onlyPoolManager
(Uniswap V4 callbacks)"] + onlyDeveloper["onlyDeveloper
(Admin functions)"] + onlyAuthorized["onlyAuthorized
(Developer + authorized)"] + end + + PoolManager["PoolManager"] -->|"beforeSwap, afterSwap, etc."| onlyPoolManager + Developer["Hook Developer"] -->|"setAuthorization"| onlyDeveloper + Verifier["AVS Verifier"] -->|"state access"| onlyAuthorized +``` + +## Hook Development Workflow + +```mermaid +sequenceDiagram + participant Dev as Hook Developer + participant Facet as Custom HaaSFacet + participant Diamond as MasterHook Diamond + participant PM as PoolManager + participant Lens as HookStateLens + + %% Development + Dev->>Facet: implement custom beforeSwap() + Dev->>Facet: implement custom afterSwap() + Dev->>Diamond: deploy facet + Dev->>Diamond: add facet to diamond + + %% Runtime + PM->>Diamond: beforeSwap(key, params) + Diamond->>Facet: delegate to facet + Facet-->>Facet: execute custom logic + Facet-->>Diamond: return (selector, delta, fee) + Diamond-->>PM: forward result + + %% Verification + Note over Lens: AVS Operator samples state + Lens->>Facet: getHookState(poolId) + Facet-->>Lens: state variables +``` + +## HaaSFacet Callback Interface + +All callbacks return their selector on success, enabling composition detection: + +| Callback | Returns | Purpose | +|----------|---------|---------| +| `beforeInitialize` | `bytes4` | Pre-pool setup | +| `afterInitialize` | `bytes4` | Post-pool setup | +| `beforeAddLiquidity` | `bytes4` | Pre-liquidity validation | +| `afterAddLiquidity` | `(bytes4, BalanceDelta)` | Post-liquidity processing | +| `beforeRemoveLiquidity` | `bytes4` | Pre-removal validation | +| `afterRemoveLiquidity` | `(bytes4, BalanceDelta)` | Post-removal processing | +| `beforeSwap` | `(bytes4, BeforeSwapDelta, uint24)` | Pre-swap modification | +| `afterSwap` | `(bytes4, int128)` | Post-swap processing | +| `beforeDonate` | `bytes4` | Pre-donation validation | +| `afterDonate` | `bytes4` | Post-donation processing | + +## Integration with HookStateLens + +```mermaid +flowchart LR + subgraph Hook["Hook Contract"] + Storage["Internal State"] + Lens["IHookStateLens"] + end + + subgraph Verification["Verification Layer"] + Operator["AVS Operator"] + Sampler["HookStateSampler"] + end + + Operator -->|"sample"| Sampler + Sampler -->|"call"| Lens + Lens -->|"read"| Storage + Storage -->|"return"| Sampler +``` + +## Example: Custom Hook Implementation + +```solidity +contract MyCustomHook is HaaSFacet { + bytes32 constant MY_STORAGE = keccak256("my.hook.storage"); + + struct MyStorage { + uint256 swapCount; + mapping(PoolId => uint256) poolSwaps; + } + + function _getMyStorage() internal pure returns (MyStorage storage $) { + bytes32 position = MY_STORAGE; + assembly { $.slot := position } + } + + function beforeSwap( + address sender, + PoolKey calldata key, + SwapParams calldata params, + bytes calldata hookData + ) external override onlyPoolManager returns (bytes4, BeforeSwapDelta, uint24) { + MyStorage storage $ = _getMyStorage(); + $.swapCount++; + $.poolSwaps[key.toId()]++; + + return (IHooks.beforeSwap.selector, BeforeSwapDeltaLibrary.ZERO_DELTA, 0); + } +} +``` diff --git a/docs/hook-pkg/market/roadmap.md b/docs/hook-pkg/market/roadmap.md new file mode 100644 index 000000000..74cdda2db --- /dev/null +++ b/docs/hook-pkg/market/roadmap.md @@ -0,0 +1,53 @@ +# hook-pkg/market: Roadmap + +## Core Marketplace + +| Status | Feature | Reference | +|--------|---------|-----------| +| Designed | IHaaSMarket interface | [HaaSMod.sol:19](../../../contracts/src/hook-pkg/HaaSMod.sol) | +| Designed | IHookLicenseIssuer interface | [HaaSMod.sol:17](../../../contracts/src/hook-pkg/HaaSMod.sol) | +| Designed | Fixed-price licensing | [market_structure_docs.md](../../hook-market-pkg/market_structure_docs.md) | +| Designed | Revenue-share licensing | [market_structure_docs.md](../../hook-market-pkg/market_structure_docs.md) | +| Designed | Hybrid pricing model | [market_structure_docs.md](../../hook-market-pkg/market_structure_docs.md) | +| TODO | HooksMarket contract implementation | Full marketplace logic | +| TODO | Hook Registry contract | Hook template storage | +| TODO | License NFT minting | ERC721 license tokens | +| TODO | Clone deployment logic | Parametric hook clones | + +## Splits Integration + +| Status | Feature | Reference | +|--------|---------|-----------| +| Designed | 0xSplits architecture | [integrations.md](../../hook-market-pkg/integrations.md) | +| TODO | SplitMain integration | Factory for split contracts | +| TODO | Per-license split creation | Automated split deployment | +| TODO | Fee distribution flow | afterSwap -> Warehouse -> Split | +| TODO | Revenue share cap enforcement | Max 30% developer share | + +## Discovery System + +| Status | Feature | Notes | +|--------|---------|-------| +| TODO | Hook metadata schema | Name, description, category, capabilities | +| TODO | Category taxonomy | Swap, liquidity, oracle, fee hooks | +| TODO | Search and filter API | By price, attestation, developer | +| TODO | Usage statistics tracking | Deployment count, TVL, revenue | +| TODO | Developer reputation system | History, attestation rate | + +## Pricing Engine + +| Status | Feature | Notes | +|--------|---------|-------| +| TODO | Fixed price validation | Minimum price requirements | +| TODO | Revenue share calculation | Basis points enforcement | +| TODO | Hybrid model logic | Upfront + ongoing split | +| TODO | Multi-hook cap enforcement | Total pool share limits | + +## Future Mechanisms (Post-v1) + +| Status | Feature | Notes | +|--------|---------|-------| +| Future | Intent-based trading | Solver architecture for hook matching | +| Future | Capability descriptors | Standardized hook capabilities | +| Future | Subscription model | Recurring license payments | +| Future | Secondary market | License NFT transfers | diff --git a/docs/hook-pkg/market/solutionSpec.md b/docs/hook-pkg/market/solutionSpec.md new file mode 100644 index 000000000..f3c27274b --- /dev/null +++ b/docs/hook-pkg/market/solutionSpec.md @@ -0,0 +1,254 @@ +# hook-pkg/market: Hook Marketplace Solution Specification + +## Problem Description + +The Uniswap V4 hooks ecosystem lacks: +- Centralized discovery for hook implementations +- Standardized pricing and licensing models +- Safe deployment and attachment mechanisms +- Revenue distribution for hook developers + +## Solution Overview + +The market subsystem provides infrastructure for hook discovery, licensing, and deployment: + +```mermaid +flowchart TB + subgraph Context["Hook Marketplace Context"] + HooksMarket["IHaaSMarket
(Marketplace Interface)"] + HookLicenseIssuer["IHookLicenseIssuer
(License Management)"] + HookRegistry["Hook Registry
(Discovery)"] + SplitsIntegration["Splits Protocol
(Revenue Distribution)"] + end + + HookDeveloper["Hook Developer"] -->|"register hook template"| HookRegistry + HookDeveloper -->|"set pricing model"| HooksMarket + ProtocolAdmin["Protocol Admin"] -->|"browse hooks"| HookRegistry + ProtocolAdmin -->|"purchase license"| HooksMarket + HooksMarket -->|"issue license"| HookLicenseIssuer + HooksMarket -->|"configure splits"| SplitsIntegration + HooksMarket -->|"deploy clone"| MasterHook["MasterHook Diamond"] +``` + +## Context Diagram + +```mermaid +flowchart TB + subgraph Environment["Hook Market Environment"] + subgraph Marketplace["Hook Bazaar Marketplace"] + Registry["Hook Registry"] + Pricing["Pricing Engine"] + Licensing["License Manager"] + Deployment["Clone Deployer"] + end + end + + Developer["Hook Developer"] -->|"register"| Registry + Developer -->|"set price"| Pricing + + Protocol["Protocol Admin"] -->|"browse"| Registry + Protocol -->|"purchase"| Pricing + Protocol -->|"receive"| Licensing + + Pricing -->|"fixed/revenue-share"| Splits["Splits Protocol"] + Licensing -->|"unlock"| Deployment + Deployment -->|"attach facet"| MasterHook["MasterHook"] +``` + +## Pricing Models + +### Fixed Price Licensing + +```mermaid +sequenceDiagram + participant Protocol as Protocol Admin + participant Market as HooksMarket + participant Treasury as Developer Treasury + participant Diamond as MasterHook + + Protocol->>Market: purchaseHook(hookId, poolId, FIXED_PRICE) + Market->>Treasury: transfer(fixedAmount) + Market->>Market: issueLicense(protocol, hookId, poolId) + Market->>Diamond: attachFacet(hookFacet, poolId) + Market-->>Protocol: License NFT +``` + +### Revenue Share Licensing + +```mermaid +sequenceDiagram + participant Protocol as Protocol Admin + participant Market as HooksMarket + participant Splits as Splits Protocol + participant Diamond as MasterHook + participant Swap as Swap Execution + + Protocol->>Market: purchaseHook(hookId, poolId, REVENUE_SHARE) + Market->>Splits: createSplit(developer, protocol, shares) + Splits-->>Market: splitAddress + Market->>Diamond: attachFacet(hookFacet, poolId) + Market->>Diamond: configureFeeRecipient(splitAddress) + Market-->>Protocol: License with Split + + Note over Swap: Later, during swaps... + Swap->>Diamond: afterSwap() collects fees + Diamond->>Splits: distribute(fees) + Splits->>Developer: developer share + Splits->>Protocol: protocol share +``` + +### Hybrid Pricing + +```mermaid +flowchart LR + subgraph Hybrid["Hybrid Model"] + Fixed["Fixed Upfront
One-time payment"] + Revenue["Revenue Share
Ongoing distribution"] + end + + Purchase["Purchase"] --> Fixed + Fixed --> Revenue + Revenue -->|"swap fees"| Distribution["Fee Distribution"] +``` + +## Marketplace Interface + +```solidity +interface IHaaSMarket { + /// @notice Unlock a hook license for a pool + function unlock(IHookLicenseIssuer licenseIssuer, PoolId poolId) external; + + /// @notice Register a new hook template + function registerHook( + address hookTemplate, + PricingModel pricing, + bytes calldata metadata + ) external returns (uint256 hookId); + + /// @notice Purchase a hook license + function purchaseHook( + uint256 hookId, + PoolId targetPool, + PricingModel selectedModel + ) external payable returns (uint256 licenseId); + + /// @notice Get hook metadata + function getHookMetadata(uint256 hookId) external view returns (HookMetadata memory); +} + +enum PricingModel { + FIXED_PRICE, + REVENUE_SHARE, + HYBRID +} + +struct HookMetadata { + address developer; + address template; + string name; + string description; + string specificationURI; + uint256 fixedPrice; + uint256 revenueShareBps; + bool isAttested; + uint256 attestationExpiry; +} +``` + +## Integration with Splits Protocol + +Reference: [integrations.md](../../hook-market-pkg/integrations.md) + +```mermaid +flowchart TB + subgraph Splits["0xSplits Integration"] + SplitMain["SplitMain
(Factory)"] + Split["Split Contract
(Per License)"] + Warehouse["Warehouse
(Fee Collection)"] + end + + subgraph HookBazaar["Hook Bazaar"] + Market["HooksMarket"] + Hook["Hook Facet"] + end + + Market -->|"createSplit"| SplitMain + SplitMain -->|"deploy"| Split + Hook -->|"afterSwap fees"| Warehouse + Warehouse -->|"distribute"| Split + Split -->|"developer %"| Developer["Developer"] + Split -->|"protocol %"| Protocol["Protocol"] + Split -->|"marketplace %"| Marketplace["Marketplace Fee"] +``` + +## Revenue Share Safeguards + +| Safeguard | Limit | Enforcement | +|-----------|-------|-------------| +| Max developer share | 30% | Marketplace contract | +| Max total hook share | 50% | ProtocolAdmin | +| Min LP share | 50% | Diamond facet | + +## Hook Registration Flow + +```mermaid +sequenceDiagram + participant Dev as Hook Developer + participant Market as HooksMarket + participant Registry as Hook Registry + participant AVS as Attestation AVS + + Dev->>Market: registerHook(template, pricing, metadata) + Market->>Registry: store hook metadata + Registry-->>Market: hookId + + opt Request Attestation + Dev->>AVS: createAttestationTask(hook, specURI) + AVS-->>AVS: verify compliance + AVS->>Registry: updateAttestationStatus(hookId, attested) + end + + Market-->>Dev: hookId (listed in marketplace) +``` + +## Discovery Interface + +```mermaid +flowchart LR + subgraph Query["Discovery Queries"] + ByCategory["filterByCategory()"] + ByPrice["filterByPrice()"] + ByAttestation["filterByAttestation()"] + ByDeveloper["filterByDeveloper()"] + end + + subgraph Results["Query Results"] + Metadata["Hook Metadata"] + Pricing["Pricing Info"] + Attestation["Attestation Status"] + Usage["Usage Stats"] + end + + ByCategory --> Results + ByPrice --> Results + ByAttestation --> Results + ByDeveloper --> Results +``` + +## State Transition: License Lifecycle + +```mermaid +stateDiagram-v2 + [*] --> Unlisted: Developer creates hook + + Unlisted --> Listed: registerHook() + Listed --> Attested: AVS verification + + Listed --> Licensed: purchaseHook() + Attested --> Licensed: purchaseHook() + + Licensed --> Active: attachToPool() + Active --> Revoked: revokeLicense() + Active --> Expired: attestation expires + Expired --> Active: renewAttestation() +``` diff --git a/docs/mission-statement.json b/docs/mission-statement.json new file mode 100644 index 000000000..0e8de462a --- /dev/null +++ b/docs/mission-statement.json @@ -0,0 +1,26 @@ +{ + "name": "HookBazaar", + "purpose": "Enable trustless monetization of Uniswap V4 hooks through mathematical specifications, IP-protected implementations, and cryptoeconomic verification - connecting hook developers with protocol integrators while providing behavioral guarantees backed by economic stake.", + "composition": [ + "protocol-pkg: Protocol lifecycle management for pool creation and administration", + "hooks-operator-avs: EigenLayer AVS for hook specification attestation and verification", + "hook-pkg: HaaS (Hooks-as-a-Service) facet system for hook development and deployment", + "master-hook-pkg: Diamond-pattern multi-hook composition and routing", + "operator: Off-chain attestation task processing runtime" + ], + "responsibilities": [ + "R1: Provide protocol administrators with permissioned pool creation and management interfaces, contributing to the environment goal of enabling non-technical users to deploy custom DEX configurations.", + "R2: Verify hook implementations conform to mathematical specifications via decentralized operator sampling, contributing to the environment goal of establishing trustless behavioral guarantees.", + "R3: Issue, manage, and enforce HookLicenses as NFTs representing developer commitments to specifications, contributing to the environment goal of enabling IP-protected monetization.", + "R4: Coordinate bonded engagements between hook developers and protocols with escrow-backed service delivery, contributing to the environment goal of accountable service relationships.", + "R5: Record and maintain attestation status with challenge windows and revocation mechanisms, contributing to the environment goal of continuous compliance verification.", + "R6: Enable hook composition through Diamond-pattern facet routing with selector-level conflict detection, contributing to the environment goal of safe multi-hook execution." + ], + "exclusions": [ + "E1: Does not perform formal verification (TLA+, Coq proofs) - relies on behavioral sampling against specifications.", + "E2: Does not provide insurance or coverage products for hook failures.", + "E3: Does not support hooks for protocols other than Uniswap V4 in initial release.", + "E4: Does not implement cross-chain hook deployment or state synchronization.", + "E5: Does not include DAO governance of marketplace parameters." + ] +} diff --git a/docs/problem-description.md b/docs/problem-description.md new file mode 100644 index 000000000..49d0f8631 --- /dev/null +++ b/docs/problem-description.md @@ -0,0 +1,341 @@ +
+ +# Hook Bazaar โ€” Problem Description + +**Solving Critical Market Failures in the Uniswap v4 Ecosystem** + +
+ +--- + +## ๐Ÿ“‹ Table of Contents + +- [Overview](#overview) +- [1. Missing Marketplace for Uniswap v4 Hooks](#1-missing-marketplace-for-uniswap-v4-hooks) +- [2. High Barriers to Entry for Protocol Designers](#2-high-barriers-to-entry-for-protocol-designers) +- [3. No Incentive Layer for Hook Developers](#3-no-incentive-layer-for-hook-developers) +- [4. Lack of Standardization, Safety, and Transparency](#4-lack-of-standardization-safety-and-transparency) +- [5. No Mechanism for Multi-Hook Composition](#5-no-mechanism-for-multi-hook-composition) +- [6. No Competition or Selection Mechanism](#6-no-competition-or-selection-mechanism) +- [7. No IP Protection for Hook Developers](#7-no-ip-protection-for-hook-developers) +- [8. Developers and Protocols Cannot Build Reputation](#8-developers-and-protocols-cannot-build-reputation) +- [9. Lack of an Economically Sustainable Ecosystem](#9-lack-of-an-economically-sustainable-ecosystem) +- [Summary](#summary) + +--- + +## Overview + +This document describes the fundamental problems that Hook Bazaar solves in the Uniswap v4 ecosystem. It outlines: + +- โš ๏ธ **Core market failures** in the hooks ecosystem +- ๐Ÿ’ธ **Economic inefficiencies** affecting developers and protocols +- ๐Ÿ—๏ธ **Missing infrastructure layers** preventing adoption +- โœ… **Value propositions** for each side of the marketplace + +--- + +## 1. Missing Marketplace for Uniswap v4 Hooks + +### โš ๏ธ Problem + +Uniswap v4 introduced Hooks, but **no marketplace exists** where: + +- โŒ Developers can publish hooks +- โŒ Protocols can discover hooks +- โŒ Hooks can be purchased, evaluated, compared, or trusted + +> **Result**: Supply and demand exist, but **no mechanism connects them** โ†’ classic two-sided market failure. + +### โœ… What Hook Bazaar Solves + +| Stakeholder | Benefit | +|------------|---------| +| **Developers** | Place to publish, categorize, and commercialize their work | +| **Protocols** | Accessible discovery layer for hooks that solve business needs | +| **Ecosystem** | Centralized discovery layer connecting supply and demand | + +--- + +## 2. High Barriers to Entry for Protocol Designers + +### โš ๏ธ Problem + +To obtain a production-ready hook today, a protocol must: + +1. ๐Ÿ” Source a qualified developer +2. ๐Ÿ“ Write a specification +3. ๐Ÿ’ป Implement the hook +4. ๐Ÿงช Test extensively +5. ๐Ÿ”’ Pay for external security audit + +> **Cost**: **$10kโ€“$100k+** | **Time**: Weeks to months + +Most teams **cannot afford** this barrier. + +### โœ… What Hook Bazaar Solves + +| Before | After | +|--------|-------| +| $10kโ€“$100k+ | Fraction of the cost | +| Weeks to months | **Minutes** | +| Custom development | Ready-made, vetted hooks | +| High risk | Pre-audited, battle-tested | + +**Benefits**: +- โœ… Ready-made, vetted hooks +- โœ… Significantly cheaper than custom development +- โœ… Time-to-market drops from weeks to minutes +- โœ… Avoid R&D, testing overhead, and audit cycles + +--- + +## 3. No Incentive Layer for Hook Developers + +### โš ๏ธ Problem + +Developers have no: + +- ๐Ÿ“ฆ Marketplace to publish hooks +- ๐Ÿ‘ฅ Audience to discover their work +- ๐Ÿ’ฐ Monetization model +- ๐Ÿ”„ Feedback loop +- ๐Ÿ† Way to build professional reputation + +> Uniswap v4 offers powerful primitives but **no economic layer** that rewards innovation. + +### โœ… What Hook Bazaar Solves + +**Monetization Options**: +- ๐Ÿ’ต **Flat price**: One-time payment +- ๐Ÿ“ˆ **Revenue share**: % of swap fees +- ๐Ÿ”„ **Hybrid**: Combination of both + +**Professional Development**: +- ๐ŸŽฏ Direct exposure to protocol teams +- ๐Ÿ“Š **Hook Developer Reputation Profiles** +- ๐Ÿš€ Encourages a new professional category: *Hook Developers* + +--- + +## 4. Lack of Standardization, Safety, and Transparency + +### โš ๏ธ Problem + +Protocols cannot trust external hooks because there is no: + +| Missing Infrastructure | Impact | +|----------------------|--------| +| โŒ Standardized specification format | Cannot compare hooks objectively | +| โŒ Risk rating system | No safety guarantees | +| โŒ Audit metadata | Cannot verify security | +| โŒ Version tracking | No upgrade path | +| โŒ Safety guarantees | High adoption risk | + +> Protocol teams **cannot objectively evaluate** a hook's correctness or safety. + +### โœ… What Hook Bazaar Solves + +- ๐Ÿ“‹ Enforces standardized **Hook Specification Format (HSF)** +- ๐Ÿ”’ Provides clear audit status and risk flags +- ๐Ÿ“– Documents hook behavior, state transitions, and category +- ๐Ÿ” Ensures transparent metadata for each hook + +--- + +## 5. No Mechanism for Multi-Hook Composition + +### โš ๏ธ Problem + +Uniswap v4 supports multi-hook execution, but: + +``` +โŒ No interface for hook composition +โŒ Hooks may conflict with each other +โŒ No tooling to manage ordering +โŒ No built-in governance around selector routing +``` + +> This prevents protocols from **combining multiple behaviors safely**. + +### โœ… What Hook Bazaar Solves + +**MasterHook (Diamond Pattern)**: + +``` +โœ… Multi-hook routing via Diamond facets +โœ… Selector-level conflict detection +โœ… Per-pool attach/detach of hook facets +โœ… Configurable execution ordering +``` + +**Result**: Safe, composable hook execution. + +--- + +## 6. No Competition or Selection Mechanism + +### โš ๏ธ Problem + +Hooks operate in isolation: + +- ๐Ÿšซ No competition between alternative solutions +- ๐Ÿ’ธ No clear pricing benchmark +- ๐Ÿ“Š No feedback on performance +- ๐Ÿ“ˆ No incentive for developers to improve + +> Without a marketplace, **the best hooks do not naturally rise to the top**. + +### โœ… What Hook Bazaar Solves + +**Market Dynamics**: + +```mermaid +graph LR + A[Multiple Hooks] --> B[Competition] + B --> C[User Comparison] + C --> D[Reputation & Visibility] + D --> E[Quality Improvement] + E --> A +``` + +- ๐Ÿ† Creates a competitive environment +- ๐Ÿ“Š Users compare performance, price, features +- โญ Reputation and visibility drive developer quality +- ๐Ÿ’ฐ Market forces establish fair pricing + +--- + +## 7. No IP Protection for Hook Developers + +### โš ๏ธ Problem + +**All hook code is public** โ†’ trivial to copy. + +This prevents professional developers from building premium algorithms: +- ๐Ÿ›ก๏ธ MEV mitigation engines +- ๐Ÿ’ง IL (Impermanent Loss) protection +- ๐Ÿ“ˆ Dynamic fee curves +- ๐ŸŽฏ Advanced trading strategies + +> No IP protection = No incentive for premium development. + +### โœ… What Hook Bazaar Solves + +**Fhenix FHE Integration**: + +| Feature | Benefit | +|---------|---------| +| ๐Ÿ” Encrypted bytecode | Code remains confidential | +| ๐Ÿ”‘ Encrypted parameters | Private configuration | +| ๐Ÿ—„๏ธ Encrypted state | Hidden internal state | +| ๐Ÿงฎ Confidential computation | Execution without revealing logic | + +> Developers can safely publish **proprietary algorithms** without fear of theft. + +--- + +## 8. Developers and Protocols Cannot Build Reputation + +### โš ๏ธ Problem + +There is no: + +| Missing Element | Impact | +|----------------|--------| +| โญ Rating system | Cannot trust unknown developers | +| ๐Ÿ“Š Usage history | No proof of reliability | +| ๐Ÿ“ˆ Performance metrics | Cannot compare effectiveness | +| ๐ŸŽ–๏ธ Audit badges | No security verification | +| ๐Ÿ”’ Trust model | High risk, slow adoption | + +> Adoption becomes **risky and slow**. + +### โœ… What Hook Bazaar Solves + +**Reputation System**: + +- ๐Ÿ‘ค **Hook Developer Reputation Profiles** +- ๐Ÿ“Š **Hook Performance Metrics** +- โœ… **Verified Hook Labels** (audited, tested, etc.) +- ๐Ÿ“ˆ **Usage statistics** and historical data + +> Creates a **social and credibility layer** for hook adoption. + +--- + +## 9. Lack of an Economically Sustainable Ecosystem + +### โš ๏ธ Problem + +**Without a revenue model**: + +``` +No revenue โ†’ Devs won't build hooks + โ†’ Protocols won't adopt hooks + โ†’ Marketplace cannot grow + โ†’ Ecosystem collapses +``` + +### โœ… What Hook Bazaar Solves + +**Multi-Stream Monetization Model**: + +| Revenue Stream | Status | Description | +|---------------|--------|-------------| +| ๐Ÿ’ต Flat pricing | โœ… v1 | One-time purchase fee | +| ๐Ÿ“ˆ Revenue share (Splits) | โœ… v1 | % of swap fees | +| ๐Ÿ”„ Hybrid models | โœ… v1 | Flat + revenue share | +| ๐Ÿช Marketplace fees | โœ… v1 | Platform sustainability | +| ๐Ÿ” Premium encrypted hooks (FHE) | ๐Ÿ”„ Future | High-value IP protection | +| ๐Ÿ“… Subscription models | ๐Ÿ”„ Future | Recurring revenue | + +> Creates a **self-sustaining ecosystem** for all participants. + +--- + +## Summary + +### Problems Solved + +| # | Problem | Solution | +|---|---------|----------| +| 1 | No marketplace for hooks | โœ… Centralized discovery layer | +| 2 | High barriers to entry | โœ… Ready-made, vetted hooks | +| 3 | No developer incentives | โœ… Direct monetization | +| 4 | Lack of standardization | โœ… Hook Specification Format | +| 5 | No hook composition | โœ… MasterHook Diamond | +| 6 | No competition | โœ… Marketplace dynamics | +| 7 | No IP protection | โœ… Fhenix FHE integration | +| 8 | No reputation system | โœ… Developer profiles & metrics | +| 9 | Unsustainable economics | โœ… Multi-stream revenue | + +### Value Proposition + +**For Hook Developers**: +- ๐Ÿ’ฐ Direct monetization (flat, revenue-share, hybrid) +- ๐Ÿ‘ฅ Access to protocol teams +- ๐Ÿ† Build professional reputation +- ๐Ÿ” IP protection via FHE + +**For Protocol Designers**: +- โšก Instant deployment (minutes vs. weeks) +- ๐Ÿ’ธ Lower costs ($100s vs. $10k+) +- ๐Ÿ”’ Pre-audited, battle-tested hooks +- ๐Ÿ› ๏ธ Multi-hook composition + +**For the Ecosystem**: +- ๐ŸŒฑ Self-sustaining economic model +- ๐Ÿ“ˆ Quality improvement through competition +- ๐Ÿ”— Network effects and growth +- ๐Ÿš€ Accelerated Uniswap v4 adoption + +--- + +
+ +**Hook Bazaar**: *Building the infrastructure layer for the Uniswap v4 hooks economy* + +[Architecture Documentation](../../ARCHITECTURE.md) ยท [Splits Integration](../hook-pkg/integrations/splits.md) ยท [Main README](../../README.md) + +
\ No newline at end of file diff --git a/docs/protocol-pkg/roadmap.md b/docs/protocol-pkg/roadmap.md new file mode 100644 index 000000000..7b0933ffa --- /dev/null +++ b/docs/protocol-pkg/roadmap.md @@ -0,0 +1,15 @@ +# protocol-pkg: Roadmap + +| Status | Feature | Test Reference | +|--------|---------|----------------| +| Implemented | Initialize ProtocolAdminClient | [ProtocolAdminClient.t.sol:40](../../contracts/test/protocol-pkg/ProtocolAdminClient.t.sol) | +| Implemented | Prevent double initialization | [ProtocolAdminClient.t.sol:57](../../contracts/test/protocol-pkg/ProtocolAdminClient.t.sol) | +| Implemented | Create protocol with unique name | [ProtocolAdminClient.t.sol:72](../../contracts/test/protocol-pkg/ProtocolAdminClient.t.sol) | +| Implemented | Prevent duplicate protocol names | [ProtocolAdminClient.t.sol:91](../../contracts/test/protocol-pkg/ProtocolAdminClient.t.sol) | +| Implemented | Protocol creator role assignment | [ProtocolAdminManager.sol:114](../../contracts/src/protocol-pkg/ProtocolAdminManager.sol) | +| Implemented | Pool creator role delegation | [ProtocolAdminManager.sol:134](../../contracts/src/protocol-pkg/ProtocolAdminManager.sol) | +| TODO | Pool creation via ProtocolHookMediator | Requires ProtocolHookMediator integration | +| TODO | getProtocolRevenue() implementation | Returns 0, needs fee accounting | +| TODO | getPoolRevenue() implementation | Returns 0, needs per-pool fee tracking | +| TODO | Multi-pool protocol support testing | Edge cases for protocol with many pools | +| TODO | URI metadata validation | Validate URI format before storage | diff --git a/docs/protocol-pkg/solutionSpec.md b/docs/protocol-pkg/solutionSpec.md new file mode 100644 index 000000000..a28dfcf62 --- /dev/null +++ b/docs/protocol-pkg/solutionSpec.md @@ -0,0 +1,151 @@ +# protocol-pkg: Solution Specification + +## Problem Description + +Protocol designers require permissioned interfaces to: +- Create and manage Uniswap V4 pool configurations +- Delegate pool creation authority to team members +- Track protocol revenue and pool metrics +- Maintain protocol metadata and identity + +Without standardized tooling, each protocol must build custom administration infrastructure. + +## Solution Overview + +The `protocol-pkg` provides a hierarchical administration system using the Diamond pattern: + +```mermaid +flowchart TB + subgraph Context["protocol-pkg Context"] + ProtocolAdminClient["ProtocolAdminClient
(Entry Point)"] + ProtocolAdminPanel["ProtocolAdminPanel
(Diamond)"] + ProtocolAdminRegistry["ProtocolAdminRegistry
(Facet)"] + ProtocolFactoryFacet["ProtocolFactoryFacet
(Facet)"] + ProtocolAdminManager["ProtocolAdminManager
(Clone per Protocol)"] + end + + ProtocolAdmin["Protocol Admin"] -->|"create_protocol\ncreate_pool"| ProtocolAdminClient + ProtocolAdminClient --> ProtocolAdminPanel + ProtocolAdminPanel --> ProtocolAdminRegistry + ProtocolAdminPanel --> ProtocolFactoryFacet + ProtocolAdminRegistry -->|"clone"| ProtocolAdminManager + ProtocolAdminClient -->|"notify"| ProtocolHookMediator["ProtocolHookMediator"] + ProtocolHookMediator -->|"initialize"| UniswapV4["Uniswap V4 PoolManager"] +``` + +## Component Responsibilities + +| Contract | Source | Responsibility | +|----------|--------|----------------| +| `ProtocolAdminClient` | [src/protocol-pkg/ProtocolAdminClient.sol](../../contracts/src/protocol-pkg/ProtocolAdminClient.sol) | Entry point for protocol and pool creation | +| `ProtocolAdminPanel` | [src/protocol-pkg/ProtocolAdminPanel.sol](../../contracts/src/protocol-pkg/ProtocolAdminPanel.sol) | Diamond container for facets | +| `ProtocolAdminRegistry` | [src/protocol-pkg/ProtocolAdminRegistry.sol](../../contracts/src/protocol-pkg/ProtocolAdminRegistry.sol) | Protocol-to-manager mapping, pool tracking | +| `ProtocolFactoryFacet` | [src/protocol-pkg/ProtocolFactoryFacet.sol](../../contracts/src/protocol-pkg/ProtocolFactoryFacet.sol) | ERC1155 protocol token minting | +| `ProtocolAdminManager` | [src/protocol-pkg/ProtocolAdminManager.sol](../../contracts/src/protocol-pkg/ProtocolAdminManager.sol) | Per-protocol access control and pool storage | + +## Workflow Activity Diagram + +```mermaid +sequenceDiagram + participant PA as ProtocolAdmin + participant Client as ProtocolAdminClient + participant Panel as ProtocolAdminPanel + participant Registry as ProtocolAdminRegistry + participant Factory as ProtocolFactoryFacet + participant Manager as ProtocolAdminManager + participant Mediator as ProtocolHookMediator + participant V4 as UniswapV4 + + %% Protocol Creation + PA->>Client: create_protocol(name) + Client->>Panel: setProtocolManager(tokenId, caller) + Panel->>Registry: setProtocolManager() + Registry-->>Manager: clone + initialize + Panel->>Factory: create_protocol(name, manager, tokenId) + Factory-->>Manager: mint ERC1155 token + Manager-->>Manager: store tokenId, name via onERC1155Received + Client-->>PA: (tokenId, managerAddress) + + %% Pool Creation + PA->>Client: create_pool(protocolId, poolKey, sqrtPrice) + Client->>Panel: isPoolCreator(manager, caller) + Panel->>Registry: isPoolCreator() + Registry->>Manager: isPoolCreator(caller) + Manager-->>Registry: true/false + alt is pool creator + Client->>Mediator: notify(create_pool, encoded params) + Mediator->>V4: initialize(poolKey, sqrtPrice) + V4-->>Mediator: (tick, poolId) + Mediator-->>Client: (tick, poolId) + Client->>Panel: addPool(manager, poolId) + Panel->>Registry: addPool() + Registry->>Manager: setPool(poolId) + Client-->>PA: (poolId, tick) + else not pool creator + Client-->>PA: revert UnauthorizedCaller + end +``` + +## State Transition Diagram + +```mermaid +stateDiagram-v2 + [*] --> Uninitialized: Deploy + Uninitialized --> Initialized: initialize() + + state Initialized { + [*] --> NoProtocols + NoProtocols --> HasProtocols: create_protocol() + + state HasProtocols { + [*] --> NoPools + NoPools --> HasPools: create_pool() + HasPools --> HasPools: create_pool() + } + } +``` + +## Access Control Model + +```mermaid +flowchart TB + subgraph Roles["Access Control Roles"] + Owner["Owner
(Protocol Deployer)"] + Creator["CREATOR Role
(Protocol Creator)"] + PoolCreator["POOL_CREATOR Role
(Delegated)"] + end + + Owner -->|"initialize"| ProtocolAdminClient + Creator -->|"delegatePoolCreatorRole"| PoolCreator + Creator -->|"setURI"| ProtocolAdminManager + PoolCreator -->|"create_pool"| ProtocolAdminClient +``` + +## Data Structures + +```solidity +// ProtocolAdminManager storage +struct ProtocolAdminManagerStorage { + address adminPanel; + bool isClone; + uint256 tokenId; + string name; + mapping(URI_TYPE => string) uris; + PoolId[] pools; +} + +enum URI_TYPE { + ZORA, + WEBSITE, + X, + FARCASTER +} +``` + +## Integration Points + +| Integration | Direction | Purpose | +|-------------|-----------|---------| +| ProtocolHookMediator | Outbound | Pool initialization via Uniswap V4 | +| Uniswap V4 PoolManager | Indirect | Pool state management | +| ERC1155 Token | Ownership | Protocol identity and transferability |