From 77c59aefd5885460e8318c63abb54db5afe726eb Mon Sep 17 00:00:00 2001 From: JMSBPP Date: Tue, 9 Dec 2025 22:14:51 -0500 Subject: [PATCH 1/3] docs: add hook-pkg documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .gitignore | 17 - docs/hook-pkg/NOTES.md | 22 + .../architecture/avs-verification-system.md | 925 +++++++++++++ .../architecture/bonded-hooks-comparison.md | 419 ++++++ .../architecture/function-refinement-tree.md | 719 ++++++++++ docs/hook-pkg/architecture/goal-tree.md | 423 ++++++ ...ok-specification-platform-decomposition.md | 1163 +++++++++++++++++ .../architecture/mission-statement.md | 289 ++++ docs/hook-pkg/architecture/system-overview.md | 619 +++++++++ .../backend/hook-license-issuer-spec.md | 876 +++++++++++++ docs/hook-pkg/frontend/hook-developer-flow.md | 675 ++++++++++ .../mathematical-models/state-space-model.md | 702 ++++++++++ 12 files changed, 6832 insertions(+), 17 deletions(-) create mode 100644 docs/hook-pkg/NOTES.md create mode 100644 docs/hook-pkg/architecture/avs-verification-system.md create mode 100644 docs/hook-pkg/architecture/bonded-hooks-comparison.md create mode 100644 docs/hook-pkg/architecture/function-refinement-tree.md create mode 100644 docs/hook-pkg/architecture/goal-tree.md create mode 100644 docs/hook-pkg/architecture/hook-specification-platform-decomposition.md create mode 100644 docs/hook-pkg/architecture/mission-statement.md create mode 100644 docs/hook-pkg/architecture/system-overview.md create mode 100644 docs/hook-pkg/backend/hook-license-issuer-spec.md create mode 100644 docs/hook-pkg/frontend/hook-developer-flow.md create mode 100644 docs/hook-pkg/mathematical-models/state-space-model.md diff --git a/.gitignore b/.gitignore index 00c88a671..9722eeec3 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,3 @@ -<<<<<<< HEAD -# Compiler files -cache/ -out/ - -# Ignores development broadcast logs -======= # ============================================================================= # Environment Variables - CRITICAL: Never commit .env files # ============================================================================= @@ -26,23 +19,14 @@ contracts/foundry-out/ contracts/out/ # Development broadcast logs (keep broadcast structure, ignore specific chains) ->>>>>>> 8b13a35cb03fb14cdb9f34a7b7b429971bb197b8 !/broadcast /broadcast/*/31337/ /broadcast/**/dry-run/ -<<<<<<< HEAD -# Docs -docs/ - -# Dotenv file -.env -======= # ============================================================================= # Hardhat Build Artifacts (if used) # ============================================================================= artifacts/ -cache/ typechain/ typechain-types/ @@ -141,4 +125,3 @@ agents/ *.temp .cache/ .temp/ ->>>>>>> 8b13a35cb03fb14cdb9f34a7b7b429971bb197b8 diff --git a/docs/hook-pkg/NOTES.md b/docs/hook-pkg/NOTES.md new file mode 100644 index 000000000..34f71d5a7 --- /dev/null +++ b/docs/hook-pkg/NOTES.md @@ -0,0 +1,22 @@ +## Layer 1 +- The pool state variables MUST be given as a public document this can be either a paper or a docuemtn of instructions tht parse the STatetVIew interfaCE TO ACTUAL STATE VARIAbles + +- A Hook spec MUST contain: + - Hook state variables + - system fucntions and equations on how this fucntions affet pool state adn hook state + +The HookSpec.tex OR HookSpec.md is the URI of the IPFS document. +Thus the platform MUST have the service of a pool (This pool is independant of protocol implementations) + - letting view the system-state.md (READ ONLY) + - upload pdf that has HookSpec.md + - On this upload there must be a verification that accepts the document if it is compliant with system-state.md + -(Documents unrelated MUST be discarded) + - This generates a IPFS key assocuated with uploadre (Hook Developer) + - If successful this mints a HookLicense NFT with URI = the IPFS key generated by the document + + + +The other part of the hook developer task is to provide the raw code the AVS verifier AND to the COFHE encoded + - Then deployed bytecode is COGFHE encoded + - functionalitie request are sent to AVS verifier (staked amount by protocol designer making the query must havcve incentive economic meaning) + diff --git a/docs/hook-pkg/architecture/avs-verification-system.md b/docs/hook-pkg/architecture/avs-verification-system.md new file mode 100644 index 000000000..6e9ab1fba --- /dev/null +++ b/docs/hook-pkg/architecture/avs-verification-system.md @@ -0,0 +1,925 @@ +# Hook Attestation AVS: Verification Without Code Disclosure + +> **Status:** Architecture Design +> **Last Updated:** 2025-12-09 +> **Prerequisites:** [State-Space Model](../mathematical-models/state-space-model.md) +> **References:** [EigenLayer Middleware](https://github.com/Layr-Labs/eigenlayer-middleware), [Incredible Squaring AVS](https://github.com/Layr-Labs/incredible-squaring-avs) + +--- + +## 1. Executive Summary + +This document describes the **HookAttestationAVS** - an EigenLayer Actively Validated Service that verifies hook implementations match their formal specifications **without revealing the source code**. The system enables: + +1. **Hook developers** to prove their implementations are correct +2. **Integrators** to trust hooks based on cryptoeconomic guarantees +3. **The marketplace** to provide verified, IP-protected hooks + +--- + +## 2. System Architecture Overview + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOK BAZAAR ECOSYSTEM β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ HOOK DEVELOPER β”‚ β”‚ HOOK INTEGRATOR β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ 1. Write Spec β”‚ β”‚ 6. Query Attestation β”‚ β”‚ +β”‚ β”‚ 2. Implement β”‚ β”‚ 7. Deploy Verified Hook β”‚ β”‚ +β”‚ β”‚ 3. Request AVS β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ HOOK ATTESTATION AVS β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Service β”‚ β”‚ Task β”‚ β”‚ BLS Sig β”‚ β”‚ Slashing β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Manager β”‚ β”‚ Manager β”‚ β”‚ Checker β”‚ β”‚ Registry β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ AVS OPERATOR NETWORK β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚Operator 1β”‚ β”‚Operator 2β”‚ β”‚Operator 3β”‚ β”‚Operator Nβ”‚ ... β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Sampler β”‚ β”‚ Sampler β”‚ β”‚ Sampler β”‚ β”‚ Sampler β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Verifier β”‚ β”‚ Verifier β”‚ β”‚ Verifier β”‚ β”‚ Verifier β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ ON-CHAIN INFRASTRUCTURE β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Hook Market β”‚ β”‚ Pool Mgr β”‚ β”‚ Fhenix CoFHEβ”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (NFTs) │◄──►│ (Uniswap) │◄──►│ (Encrypted) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ IPFS β”‚ β”‚ Attestation β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Spec Docs) β”‚ β”‚ Registry β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 3. Core Components + +### 3.1 Hook Specification Document (IPFS) + +The hook developer creates a formal specification stored on IPFS: + +```markdown +# Hook Specification: DynamicFeeHook v1.0.0 + +## 1. Hook Identity +- **Hook Address:** 0x... (deployed via Fhenix CoFHE) +- **Callbacks Implemented:** beforeSwap, afterSwap +- **Specification Hash:** QmXyz... + +## 2. State Variables + +### Hook State (H) +| Variable | Type | Description | +|----------|------|-------------| +| volatilityWindow | uint256 | Rolling window for volatility calculation | +| lastPrice | uint160 | Last recorded sqrtPriceX96 | +| feeMultiplier | uint24 | Dynamic fee adjustment factor | + +### Pool State Dependencies (P) +- Reads: TRADER_SQRT_PRICE, TRADER_TICK, TRADER_LP_FEE +- Writes: TRADER_LP_FEE (via beforeSwap return) + +## 3. State Transition Functions + +### beforeSwap(H, P) β†’ (H', Ξ΄fee) + +$$ +\text{volatility} = |\sqrt{P}_{current} - \sqrt{P}_{last}| / \sqrt{P}_{last} +$$ + +$$ +\text{feeMultiplier}' = \min(\text{MAX\_FEE}, \text{baseFee} \times (1 + \text{volatility} \times \text{sensitivity})) +$$ + +$$ +\delta_{fee} = \text{feeMultiplier}' - \phi_{lp} +$$ + +### Constraints +- `0 <= feeMultiplier' <= MAX_FEE (10000 = 1%)` +- `volatility` computed over `volatilityWindow` blocks +- No state changes if `volatility < MIN_THRESHOLD` + +## 4. Invariants + +### INV-1: Fee Bounds +$$ +\forall t: \text{baseFee} \leq \phi_{lp}(t) \leq \text{MAX\_FEE} +$$ + +### INV-2: Monotonic Volatility Response +$$ +\text{volatility}_1 < \text{volatility}_2 \Rightarrow \phi_{lp,1} \leq \phi_{lp,2} +$$ + +## 5. Test Vectors + +| Pre-State | Input | Expected Post-State | +|-----------|-------|---------------------| +| lastPrice=1e18, fee=3000 | sqrtP=1.01e18 | fee=3030 | +| lastPrice=1e18, fee=3000 | sqrtP=1.10e18 | fee=MAX_FEE | +| lastPrice=1e18, fee=3000 | sqrtP=1.001e18 | fee=3000 (no change) | +``` + +### 3.2 Task Manager Contract + +Based on [Incredible Squaring AVS](https://github.com/Layr-Labs/incredible-squaring-avs/blob/master/contracts/src/IncredibleSquaringTaskManager.sol): + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.24; + +import {BLSSignatureChecker} from "@eigenlayer-middleware/src/BLSSignatureChecker.sol"; +import {OperatorStateRetriever} from "@eigenlayer-middleware/src/OperatorStateRetriever.sol"; +import {ISlashingRegistryCoordinator} from "@eigenlayer-middleware/src/interfaces/ISlashingRegistryCoordinator.sol"; + +/// @title IHookAttestationTaskManager +/// @notice Task manager for hook specification verification +interface IHookAttestationTaskManager { + + // ═══════════════════════════════════════════════════════════════════════ + // EVENTS + // ═══════════════════════════════════════════════════════════════════════ + + event AttestationTaskCreated( + uint32 indexed taskIndex, + AttestationTask task + ); + + event AttestationTaskResponded( + uint32 indexed taskIndex, + AttestationResponse response, + AttestationResponseMetadata metadata + ); + + event AttestationChallenged( + uint32 indexed taskIndex, + address indexed challenger, + bool challengeSuccessful + ); + + // ═══════════════════════════════════════════════════════════════════════ + // STRUCTS + // ═══════════════════════════════════════════════════════════════════════ + + /// @notice An attestation task to verify hook specification compliance + struct AttestationTask { + /// @dev The hook contract address to verify + address hook; + /// @dev IPFS CID of the formal specification + string specificationURI; + /// @dev Pool IDs to sample state from + bytes32[] poolIds; + /// @dev Callbacks to test + bytes4[] callbacks; + /// @dev Number of state samples required + uint32 sampleCount; + /// @dev Block when task was created + uint32 taskCreatedBlock; + /// @dev Quorum configuration + bytes quorumNumbers; + /// @dev Threshold percentage for consensus + uint32 quorumThresholdPercentage; + } + + /// @notice Response from operators after verification + struct AttestationResponse { + /// @dev Reference to the task being responded to + uint32 referenceTaskIndex; + /// @dev Whether the hook passes all spec tests + bool specCompliant; + /// @dev Hash of all state samples collected + bytes32 stateSamplesHash; + /// @dev Hash of test results + bytes32 testResultsHash; + /// @dev Number of invariants verified + uint32 invariantsVerified; + /// @dev Number of invariants failed + uint32 invariantsFailed; + } + + /// @notice Metadata about the response + struct AttestationResponseMetadata { + uint32 taskRespondedBlock; + bytes32 hashOfNonSigners; + } + + // ═══════════════════════════════════════════════════════════════════════ + // TASK LIFECYCLE + // ═══════════════════════════════════════════════════════════════════════ + + /// @notice Create a new attestation task + /// @param hook The hook contract to verify + /// @param specificationURI IPFS URI of formal specification + /// @param poolIds Pools to sample for verification + /// @param callbacks Hook callbacks to test + /// @param sampleCount Number of state samples to collect + function createAttestationTask( + address hook, + string calldata specificationURI, + bytes32[] calldata poolIds, + bytes4[] calldata callbacks, + uint32 sampleCount + ) external returns (uint32 taskIndex); + + /// @notice Respond to an attestation task + /// @param task The original task + /// @param response The verification response + /// @param nonSignerStakesAndSignature BLS signature data + function respondToAttestationTask( + AttestationTask calldata task, + AttestationResponse calldata response, + BLSSignatureChecker.NonSignerStakesAndSignature memory nonSignerStakesAndSignature + ) external; + + /// @notice Challenge an attestation response + /// @param task The original task + /// @param response The contested response + /// @param responseMetadata Response metadata + /// @param counterSamples State samples proving incorrect verification + function challengeAttestation( + AttestationTask calldata task, + AttestationResponse calldata response, + AttestationResponseMetadata calldata responseMetadata, + bytes calldata counterSamples + ) external; +} +``` + +### 3.3 Operator Verification Logic (Off-Chain) + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ OPERATOR VERIFICATION WORKFLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ 1. RECEIVE TASK β”‚ β”‚ +β”‚ β”‚ - Parse AttestationTask from NewTaskCreated event β”‚ β”‚ +β”‚ β”‚ - Fetch specification from IPFS (specificationURI) β”‚ β”‚ +β”‚ β”‚ - Parse spec into structured verification rules β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ 2. SAMPLE STATE β”‚ β”‚ +β”‚ β”‚ FOR each poolId in task.poolIds: β”‚ β”‚ +β”‚ β”‚ FOR i = 1 to task.sampleCount: β”‚ β”‚ +β”‚ β”‚ - Sample LP state via IHookStateView β”‚ β”‚ +β”‚ β”‚ - Sample Trader state via IHookStateView β”‚ β”‚ +β”‚ β”‚ - Sample Hook state via hook.getHookState() β”‚ β”‚ +β”‚ β”‚ - Record (preState, timestamp, blockNumber) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ 3. EXECUTE CALLBACKS β”‚ β”‚ +β”‚ β”‚ FOR each callback in task.callbacks: β”‚ β”‚ +β”‚ β”‚ FOR each preState sample: β”‚ β”‚ +β”‚ β”‚ - Generate valid callback input based on spec β”‚ β”‚ +β”‚ β”‚ - Execute callback via PoolManager (simulation) β”‚ β”‚ +β”‚ β”‚ - Capture postState β”‚ β”‚ +β”‚ β”‚ - Record StateTransition(preState, input, postState) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ 4. VERIFY AGAINST SPEC β”‚ β”‚ +β”‚ β”‚ FOR each StateTransition: β”‚ β”‚ +β”‚ β”‚ - Extract expected postState from spec equations β”‚ β”‚ +β”‚ β”‚ - Compare actual vs expected within tolerance β”‚ β”‚ +β”‚ β”‚ - Check all declared invariants hold β”‚ β”‚ +β”‚ β”‚ - Record (passed: bool, deviation: uint256) β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ IMPORTANT: Operators verify behavior, NOT code β”‚ β”‚ +β”‚ β”‚ - Code remains encrypted via Fhenix CoFHE β”‚ β”‚ +β”‚ β”‚ - Only inputβ†’output behavior is checked β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ 5. AGGREGATE RESULTS β”‚ β”‚ +β”‚ β”‚ - Compute stateSamplesHash = keccak256(all samples) β”‚ β”‚ +β”‚ β”‚ - Compute testResultsHash = keccak256(all results) β”‚ β”‚ +β”‚ β”‚ - Count invariantsVerified, invariantsFailed β”‚ β”‚ +β”‚ β”‚ - Determine specCompliant = (invariantsFailed == 0) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ 6. SIGN & SUBMIT β”‚ β”‚ +β”‚ β”‚ - Create AttestationResponse β”‚ β”‚ +β”‚ β”‚ - Sign response with BLS key β”‚ β”‚ +β”‚ β”‚ - Submit to Aggregator β”‚ β”‚ +β”‚ β”‚ - Aggregator collects signatures, submits to TaskManager β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 4. Verification Protocol: How to Prove Without Seeing Code + +### 4.1 The Core Insight + +The key to verifying hook compliance without seeing source code is **behavioral verification**: + +1. The **specification** defines expected inputβ†’output relationships +2. Operators **execute the hook** as a black box +3. Operators **compare actual outputs** to spec-defined expected outputs +4. Code remains encrypted; only **behavior** is verified + +### 4.2 Mathematical Formalization + +Given a hook specification $\mathcal{F} = (f_1, f_2, ..., f_N)$ where each $f_i: (H, P) \rightarrow (H', \Delta)$: + +**Verification Condition:** + +For sampled states $\{(H_j, P_j)\}_{j=1}^{M}$ and callback $f_i$: + +$$ +\text{PASS} \iff \forall j: \|f_i^{actual}(H_j, P_j) - f_i^{spec}(H_j, P_j)\| \leq \epsilon +$$ + +Where: +- $f_i^{actual}$ is the hook's actual behavior (black box execution) +- $f_i^{spec}$ is the expected behavior from specification +- $\epsilon$ is the acceptable deviation (due to gas, rounding, etc.) + +### 4.3 State Sampling Strategy + +```solidity +/// @title HookStateSampler +/// @notice Collects state samples for verification +/// @dev Used by AVS operators off-chain +contract HookStateSampler { + + struct StateSample { + /// @dev Block number when sampled + uint256 blockNumber; + /// @dev Timestamp when sampled + uint256 timestamp; + /// @dev Pool identifier + bytes32 poolId; + /// @dev Encoded LP state (LPPositionState[]) + bytes lpState; + /// @dev Encoded Trader state (TraderState) + bytes traderState; + /// @dev Encoded Hook state (hook-specific) + bytes hookState; + /// @dev Encoded shared state + bytes sharedState; + } + + struct TransitionSample { + /// @dev State before callback + StateSample preState; + /// @dev Callback executed + bytes4 callback; + /// @dev Callback input parameters + bytes input; + /// @dev State after callback + StateSample postState; + /// @dev Gas consumed + uint256 gasUsed; + /// @dev Return data from callback + bytes returnData; + } + + /// @notice Sample current pool and hook state + /// @param poolId Pool to sample + /// @param hook Hook contract + /// @param stateView State view contract + /// @return sample The state sample + function sampleCurrentState( + bytes32 poolId, + address hook, + address stateView + ) external view returns (StateSample memory sample) { + sample.blockNumber = block.number; + sample.timestamp = block.timestamp; + sample.poolId = poolId; + + // Sample via IHookStateView + IHookStateView view = IHookStateView(stateView); + + // Get trader state + TraderState memory traderState = view.getTraderState(PoolId.wrap(poolId)); + sample.traderState = abi.encode(traderState); + + // Get shared state + (uint256 feeGrowth0, uint256 feeGrowth1) = view.getSharedFeeState(PoolId.wrap(poolId)); + sample.sharedState = abi.encode(feeGrowth0, feeGrowth1); + + // Get hook-specific state + sample.hookState = view.getHookState(PoolId.wrap(poolId)); + } + + /// @notice Sample a state transition by executing callback + /// @param poolId Pool to test + /// @param hook Hook contract + /// @param callback Callback selector + /// @param input Callback input + /// @return transition The transition sample + function sampleTransition( + bytes32 poolId, + address hook, + bytes4 callback, + bytes calldata input + ) external returns (TransitionSample memory transition) { + // Record pre-state + transition.preState = this.sampleCurrentState(poolId, hook, address(stateView)); + transition.callback = callback; + transition.input = input; + + // Execute callback and measure gas + uint256 gasBefore = gasleft(); + + // Note: In practice, this would be done via PoolManager + // with proper context setup + (bool success, bytes memory returnData) = hook.call( + abi.encodeWithSelector(callback, input) + ); + + transition.gasUsed = gasBefore - gasleft(); + transition.returnData = returnData; + + // Record post-state + transition.postState = this.sampleCurrentState(poolId, hook, address(stateView)); + } +} +``` + +### 4.4 Specification Compliance Checker + +```solidity +/// @title SpecificationComplianceChecker +/// @notice Verifies hook behavior matches specification +/// @dev Run by AVS operators off-chain +library SpecificationComplianceChecker { + + struct ComplianceResult { + bool compliant; + uint256 deviationMagnitude; + bytes32 failedInvariant; + string failureReason; + } + + /// @notice Check if a state transition matches specification + /// @param spec Parsed specification + /// @param transition Observed transition + /// @param tolerance Acceptable deviation + /// @return result Compliance check result + function checkTransitionCompliance( + ParsedSpecification memory spec, + TransitionSample memory transition, + uint256 tolerance + ) internal pure returns (ComplianceResult memory result) { + result.compliant = true; + + // 1. Compute expected post-state from spec equations + bytes memory expectedPostState = computeExpectedState( + spec, + transition.preState, + transition.callback, + transition.input + ); + + // 2. Compare actual vs expected + uint256 deviation = computeDeviation( + transition.postState.hookState, + expectedPostState + ); + + if (deviation > tolerance) { + result.compliant = false; + result.deviationMagnitude = deviation; + result.failureReason = "State deviation exceeds tolerance"; + return result; + } + + // 3. Check all invariants + for (uint256 i = 0; i < spec.invariants.length; i++) { + bool invariantHolds = checkInvariant( + spec.invariants[i], + transition.preState, + transition.postState + ); + + if (!invariantHolds) { + result.compliant = false; + result.failedInvariant = spec.invariants[i].id; + result.failureReason = "Invariant violated"; + return result; + } + } + } + + /// @notice Compute expected state from specification equations + /// @dev This is the core spec-to-verification translation + function computeExpectedState( + ParsedSpecification memory spec, + StateSample memory preState, + bytes4 callback, + bytes memory input + ) internal pure returns (bytes memory expectedState) { + // Find the transition function for this callback + TransitionFunction memory fn = findTransitionFunction(spec, callback); + + // Decode pre-state variables needed by the function + HookState memory H = decodeHookState(preState.hookState); + TraderState memory P = abi.decode(preState.traderState, (TraderState)); + + // Apply the specification's transition equations + // This is pseudo-code - actual implementation depends on spec format + // + // Example for DynamicFeeHook: + // volatility = |P.sqrtPrice - H.lastPrice| / H.lastPrice + // H'.feeMultiplier = min(MAX_FEE, baseFee * (1 + volatility * sensitivity)) + // deltaFee = H'.feeMultiplier - P.lpFee + + expectedState = fn.apply(H, P, input); + } +} +``` + +--- + +## 5. Slashing Conditions + +Operators can be slashed for: + +### 5.1 False Positive (Attesting Non-Compliant Hook) + +```solidity +/// @notice Challenge: Hook was attested but doesn't match spec +/// @dev Challenger provides counter-sample proving non-compliance +function challengeFalsePositive( + AttestationTask calldata task, + AttestationResponse calldata response, + TransitionSample calldata counterSample +) external { + require(response.specCompliant == true, "Response already marked non-compliant"); + + // Verify counter-sample is valid + require( + verifyTransitionSampleAuthenticity(counterSample, task.taskCreatedBlock), + "Invalid counter-sample" + ); + + // Check if counter-sample proves non-compliance + ComplianceResult memory result = SpecificationComplianceChecker.checkTransitionCompliance( + fetchAndParseSpec(task.specificationURI), + counterSample, + COMPLIANCE_TOLERANCE + ); + + if (!result.compliant) { + // Challenge successful - slash operators who signed the response + _slashSigningOperators(task, response); + emit AttestationChallenged(response.referenceTaskIndex, msg.sender, true); + } else { + emit AttestationChallenged(response.referenceTaskIndex, msg.sender, false); + } +} +``` + +### 5.2 False Negative (Rejecting Compliant Hook) + +```solidity +/// @notice Challenge: Hook was rejected but actually matches spec +/// @dev Challenger provides samples proving compliance +function challengeFalseNegative( + AttestationTask calldata task, + AttestationResponse calldata response, + TransitionSample[] calldata complianceSamples +) external { + require(response.specCompliant == false, "Response already marked compliant"); + + // Verify all provided samples show compliance + ParsedSpecification memory spec = fetchAndParseSpec(task.specificationURI); + + for (uint256 i = 0; i < complianceSamples.length; i++) { + ComplianceResult memory result = SpecificationComplianceChecker.checkTransitionCompliance( + spec, + complianceSamples[i], + COMPLIANCE_TOLERANCE + ); + + require(result.compliant, "Sample does not prove compliance"); + } + + // Require minimum sample coverage + require( + complianceSamples.length >= task.sampleCount, + "Insufficient compliance evidence" + ); + + // Challenge successful - slash operators who signed the response + _slashSigningOperators(task, response); + emit AttestationChallenged(response.referenceTaskIndex, msg.sender, true); +} +``` + +--- + +## 6. Integration with Hook Marketplace + +### 6.1 Attestation Registry + +```solidity +/// @title AttestationRegistry +/// @notice On-chain registry of hook attestations +contract AttestationRegistry { + + struct Attestation { + bytes32 attestationId; + address hook; + string specificationURI; + bool isValid; + uint256 attestedAt; + uint256 expiresAt; + uint32 taskIndex; + bytes32 responsesHash; + } + + /// @dev hook address => Attestation + mapping(address => Attestation) public attestations; + + /// @dev hook address => attestation history + mapping(address => bytes32[]) public attestationHistory; + + event AttestationRecorded( + address indexed hook, + bytes32 indexed attestationId, + string specificationURI, + uint256 expiresAt + ); + + event AttestationRevoked( + address indexed hook, + bytes32 indexed attestationId, + string reason + ); + + /// @notice Record a successful attestation + /// @dev Called by TaskManager after successful response + function recordAttestation( + address hook, + string calldata specificationURI, + uint32 taskIndex, + bytes32 responsesHash + ) external onlyTaskManager { + bytes32 attestationId = keccak256(abi.encode( + hook, + specificationURI, + taskIndex, + block.timestamp + )); + + attestations[hook] = Attestation({ + attestationId: attestationId, + hook: hook, + specificationURI: specificationURI, + isValid: true, + attestedAt: block.timestamp, + expiresAt: block.timestamp + ATTESTATION_VALIDITY_PERIOD, + taskIndex: taskIndex, + responsesHash: responsesHash + }); + + attestationHistory[hook].push(attestationId); + + emit AttestationRecorded(hook, attestationId, specificationURI, block.timestamp + ATTESTATION_VALIDITY_PERIOD); + } + + /// @notice Check if a hook has valid attestation + function isHookAttested(address hook) external view returns (bool) { + Attestation storage att = attestations[hook]; + return att.isValid && att.expiresAt > block.timestamp; + } + + /// @notice Get full attestation details + function getAttestation(address hook) external view returns (Attestation memory) { + return attestations[hook]; + } +} +``` + +### 6.2 Hook Market Integration + +```solidity +/// @title HookMarket +/// @notice Marketplace for verified hooks +contract HookMarket { + + IAttestationRegistry public immutable attestationRegistry; + + /// @notice List a hook for sale/use + /// @dev Requires valid attestation + function listHook( + address hook, + uint256 price, + bytes calldata metadata + ) external { + require( + attestationRegistry.isHookAttested(hook), + "Hook must have valid attestation" + ); + + // ... listing logic + } + + /// @notice Deploy a verified hook to a pool + /// @dev Checks attestation before allowing deployment + function deployVerifiedHook( + bytes32 poolId, + address hook + ) external { + require( + attestationRegistry.isHookAttested(hook), + "Hook must have valid attestation" + ); + + IAttestationRegistry.Attestation memory att = attestationRegistry.getAttestation(hook); + + // Emit specification URI for integrators to review + emit HookDeployed(poolId, hook, att.specificationURI); + + // ... deployment logic + } +} +``` + +--- + +## 7. End-to-End Workflow + +### 7.1 Hook Developer Journey + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOK DEVELOPER WORKFLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ STEP 1: Write Specification β”‚ +β”‚ ───────────────────────────── β”‚ +β”‚ - Define state variables (H) β”‚ +β”‚ - Define state transitions f_i(H, P) β†’ (H', Ξ”) β”‚ +β”‚ - Define invariants β”‚ +β”‚ - Create test vectors β”‚ +β”‚ - Upload to IPFS β†’ specificationURI β”‚ +β”‚ β”‚ +β”‚ STEP 2: Implement Hook β”‚ +β”‚ ───────────────────────── β”‚ +β”‚ - Write Solidity implementation β”‚ +β”‚ - Ensure implementation matches specification β”‚ +β”‚ - Local testing against test vectors β”‚ +β”‚ β”‚ +β”‚ STEP 3: Deploy via Fhenix CoFHE β”‚ +β”‚ ─────────────────────────────── β”‚ +β”‚ - Encrypt hook bytecode using Fhenix β”‚ +β”‚ - Deploy encrypted contract β”‚ +β”‚ - Code is protected from decompilation β”‚ +β”‚ β”‚ +β”‚ STEP 4: Request Attestation β”‚ +β”‚ ─────────────────────────── β”‚ +β”‚ HookAttestationTaskManager.createAttestationTask( β”‚ +β”‚ hook: deployedHookAddress, β”‚ +β”‚ specificationURI: "ipfs://Qm...", β”‚ +β”‚ poolIds: [testPoolId1, testPoolId2], β”‚ +β”‚ callbacks: [beforeSwap.selector, afterSwap.selector], β”‚ +β”‚ sampleCount: 100 β”‚ +β”‚ ) β”‚ +β”‚ β”‚ +β”‚ STEP 5: Wait for Operator Verification β”‚ +β”‚ ────────────────────────────────────── β”‚ +β”‚ - Operators sample state from specified pools β”‚ +β”‚ - Operators execute callbacks as black-box β”‚ +β”‚ - Operators verify behavior matches spec β”‚ +β”‚ - Operators sign and submit response β”‚ +β”‚ β”‚ +β”‚ STEP 6: Receive Attestation β”‚ +β”‚ ─────────────────────────── β”‚ +β”‚ - If specCompliant == true: β”‚ +β”‚ - Attestation recorded in AttestationRegistry β”‚ +β”‚ - Hook can be listed in HookMarket β”‚ +β”‚ - If specCompliant == false: β”‚ +β”‚ - Developer reviews failure reasons β”‚ +β”‚ - Fix implementation and retry β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 7.2 Integrator Journey + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOK INTEGRATOR WORKFLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ STEP 1: Browse Hook Market β”‚ +β”‚ ────────────────────────── β”‚ +β”‚ - View available hooks with attestations β”‚ +β”‚ - Filter by: callback types, attestation status, price β”‚ +β”‚ β”‚ +β”‚ STEP 2: Review Specification β”‚ +β”‚ ──────────────────────────── β”‚ +β”‚ Attestation att = attestationRegistry.getAttestation(hookAddress); β”‚ +β”‚ - Fetch specification from att.specificationURI β”‚ +β”‚ - Review: β”‚ +β”‚ - State variables and their meaning β”‚ +β”‚ - Transition functions and expected behavior β”‚ +β”‚ - Invariants that are guaranteed β”‚ +β”‚ - Test vectors for validation β”‚ +β”‚ β”‚ +β”‚ STEP 3: Verify Attestation β”‚ +β”‚ ────────────────────────── β”‚ +β”‚ require(attestationRegistry.isHookAttested(hook), "Not attested"); β”‚ +β”‚ require(att.expiresAt > block.timestamp, "Attestation expired"); β”‚ +β”‚ require(att.taskIndex > 0, "Valid task index"); β”‚ +β”‚ β”‚ +β”‚ STEP 4: Deploy to Pool β”‚ +β”‚ ────────────────────── β”‚ +β”‚ hookMarket.deployVerifiedHook(poolId, hookAddress); β”‚ +β”‚ β”‚ +β”‚ STEP 5: Trust Guarantees β”‚ +β”‚ ──────────────────────── β”‚ +β”‚ - Hook behavior matches published specification β”‚ +β”‚ - Operators stake slashable collateral on this claim β”‚ +β”‚ - Economic security proportional to operator stake β”‚ +β”‚ - No need to audit source code β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 8. Security Considerations + +### 8.1 Attack Vectors & Mitigations + +| Attack | Description | Mitigation | +|--------|-------------|------------| +| **Spec Gaming** | Developer writes spec that matches malicious behavior | Community review of specs; spec quality scoring | +| **Sample Manipulation** | Hook behaves correctly only for sampled states | Random sampling; cross-operator sample comparison | +| **Operator Collusion** | Operators collude to attest false compliance | Minimum operator count; stake distribution requirements | +| **Time-Based Attacks** | Hook behavior changes after attestation | Attestation expiry; re-attestation requirements | +| **Gas Manipulation** | Hook uses excessive gas in non-sampled paths | Gas bounds in specification; gas monitoring | + +### 8.2 Trust Assumptions + +1. **Specification Trust**: Integrators must review and understand the specification +2. **Operator Honesty**: Majority of operators are honest (enforced by slashing) +3. **Sample Coverage**: Random sampling provides statistical coverage +4. **Fhenix Security**: Code encryption prevents reverse engineering + +--- + +## 9. References + +1. **[EigenLayer Middleware]** Layr-Labs. *eigenlayer-middleware*. https://github.com/Layr-Labs/eigenlayer-middleware + +2. **[Incredible Squaring AVS]** Layr-Labs. *incredible-squaring-avs*. https://github.com/Layr-Labs/incredible-squaring-avs + +3. **[Hello World AVS]** Layr-Labs. *hello-world-avs*. https://github.com/Layr-Labs/hello-world-avs + +4. **[State-Space Model]** Hook Bazaar. *Hook State-Space Model: Dual-Index Architecture*. `docs/hook-pkg/mathematical-models/state-space-model.md` + +5. **[arXiv:2512.06203]** Tranquilli & Gupta. *Formal State-Machine Models for Uniswap v3*. https://arxiv.org/abs/2512.06203 + +6. **[Fhenix CoFHE]** Fhenix Protocol. *CoFHE Documentation*. https://cofhe-docs.fhenix.zone/ + +--- + +## 10. Appendix: Contract Deployment Addresses + +*To be populated after deployment* + +| Contract | Network | Address | +|----------|---------|---------| +| HookAttestationServiceManager | - | - | +| HookAttestationTaskManager | - | - | +| AttestationRegistry | - | - | +| HookStateSampler | - | - | diff --git a/docs/hook-pkg/architecture/bonded-hooks-comparison.md b/docs/hook-pkg/architecture/bonded-hooks-comparison.md new file mode 100644 index 000000000..91990eea5 --- /dev/null +++ b/docs/hook-pkg/architecture/bonded-hooks-comparison.md @@ -0,0 +1,419 @@ +# Bonded Hooks vs Hook Bazaar: Comparative Analysis + +> **Document Type:** Competitive Analysis +> **Last Updated:** 2025-12-09 +> **Related:** [Mission Statement](./mission-statement.md) | [System Overview](./system-overview.md) + +--- + +## 1. Executive Summary + +This document provides a comprehensive comparison between **Bonded Hooks** and **Hook Bazaar**, two distinct approaches to creating marketplaces and ecosystems for Uniswap V4 hooks. While both projects aim to make hook development more accessible and provide economic incentives, they solve fundamentally different problems and serve different user personas. + +| Aspect | Bonded Hooks | Hook Bazaar | +|--------|-------------|-------------| +| **Primary Focus** | Low-code hook composition | IP-protected hook marketplace | +| **Target User** | Pool admins, non-developers | Hook developers, integrators | +| **Core Innovation** | Crowdfunded command development | Mathematical specification + verification | +| **IP Model** | Open source commands | Encrypted implementations | +| **Verification** | Centralized AVS operator | Decentralized EigenLayer AVS | +| **Economic Model** | Bond-to-earn, gas rebates | Purchase/license hooks | + +--- + +## 2. Architecture Comparison + +### 2.1 Bonded Hooks Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ BONDED HOOKS ARCHITECTURE β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Pool Admin β”‚ ─── selects ───▢ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ BLOCKS β”‚ β”‚ +β”‚ β”‚ (curated sets) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ MASTER CONTROL β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚Command 1 β”‚β†’ β”‚Command 2 β”‚β†’ β”‚Command 3 β”‚β†’ β”‚Command N β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚(Points) β”‚ β”‚(Fees) β”‚ β”‚(Rebates) β”‚ β”‚(Custom) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ Sequential execution per callback β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ ECONOMIC LAYER β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Bonding β”‚ β”‚ DegenPool β”‚ β”‚ GasRebateManagerβ”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (ETH) β”‚ β”‚ (Points) β”‚ β”‚ (Centralized) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Key Components:** +- **MasterControl**: Routes callbacks to ordered Command[] lists +- **Commands**: Small, modular behavior units (~200-500 LOC each) +- **Blocks**: Curated bundles of commands for common use cases +- **Bonding**: "Bond once, earn forever" rewards-per-share model +- **MemoryCard**: Per-pool storage abstraction + +### 2.2 Hook Bazaar Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOK BAZAAR ARCHITECTURE β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ SPECIFICATION LAYER β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Mathematical Spec (LaTeX/JSON) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - State variables & indices β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Transition functions: f(H, P) β†’ (H', Ξ”) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Invariants & bounds β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ IMPLEMENTATION LAYER β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Encrypted Code β”‚ β”‚ NFT Ownership β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Fhenix CoFHE) β”‚ β”‚ (Royalties/Sales) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VERIFICATION LAYER (EigenLayer AVS) β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Op 1 β”‚ β”‚ Op 2 β”‚ β”‚ Op 3 β”‚ β”‚ Op N β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚(staked)β”‚ β”‚(staked)β”‚ β”‚(staked)β”‚ β”‚(staked)β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ Distributed verification with slashing β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Key Components:** +- **Specification**: Mathematical description of hook behavior +- **Encrypted Implementation**: Source code protected via FHE +- **AVS**: Decentralized verification network with economic security +- **NFT**: Ownership, licensing, and royalty distribution + +--- + +## 3. Feature-by-Feature Comparison + +### 3.1 Hook Development Model + +| Feature | Bonded Hooks | Hook Bazaar | +|---------|-------------|-------------| +| **Development Approach** | Compose existing commands | Write full implementations | +| **Code Visibility** | Open source commands | Encrypted, IP protected | +| **Customization** | Select from whitelisted blocks | Full implementation freedom | +| **Learning Curve** | Low (pick commands) | High (write specs + code) | +| **Innovation Potential** | Limited to existing commands | Unlimited | + +**Bonded Hooks Approach:** +```solidity +// Pool admin selects a Block (curated command set) +MasterHook.install(poolId, blockId); + +// Commands execute sequentially +// Command 1: PointsCommand (award points) +// Command 2: FeeDistributorCommand (split fees) +// Command 3: GasRebateCommand (track gas) +``` + +**Hook Bazaar Approach:** +```solidity +// Developer writes mathematical specification +specification TWAMM { + state: { virtualReserves: (uint256, uint256), lastBlock: uint256 } + invariant: virtualReserves.0 * virtualReserves.1 >= k + transition beforeSwap: (H, P) β†’ (H', Ξ”) where ... +} + +// Developer implements specification (encrypted) +// Integrator deploys verified instance +``` + +### 3.2 Economic Model + +| Feature | Bonded Hooks | Hook Bazaar | +|---------|-------------|-------------| +| **Primary Revenue** | Bond yields, gas rebates | Hook sales/licensing | +| **Funding Model** | Crowdfunded development | Developer self-funded | +| **User Incentives** | Points, rebates, airdrops | Verified hook guarantees | +| **Developer Incentives** | Bond rewards | Sales royalties | + +**Bonded Hooks Economics:** +``` +Bond ETH β†’ Receive share of pool fees + β†’ Earn gas rebates (via centralized AVS) + β†’ Accumulate points for airdrops +``` + +**Hook Bazaar Economics:** +``` +Developer β†’ Lists hook (pays listing fee) + β†’ Sets price/licensing terms + β†’ Earns royalties on each deployment + +Integrator β†’ Browses marketplace + β†’ Purchases license + β†’ Deploys verified instance +``` + +### 3.3 Verification & Trust + +| Feature | Bonded Hooks | Hook Bazaar | +|---------|-------------|-------------| +| **Verification Model** | Centralized AVS operator | Decentralized EigenLayer AVS | +| **Trust Assumption** | Trust AVS operator | Trust cryptoeconomics | +| **Slashing** | Not mentioned | Full slashing conditions | +| **Challenge Period** | Not implemented | 7-day challenge window | +| **What's Verified** | Gas usage (for rebates) | Behavioral compliance | + +**Bonded Hooks Trust Model:** +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CENTRALIZED AVS β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Single Operator β”‚ β”‚ +β”‚ β”‚ - Runs Python signer β”‚ β”‚ +β”‚ β”‚ - Signs rebate proofs β”‚ β”‚ +β”‚ β”‚ - Trusted to be honest β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Hook Bazaar Trust Model:** +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DECENTRALIZED AVS β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Op 1 β”‚ β”‚ Op 2 β”‚ β”‚ Op 3 β”‚ β”‚ Op N β”‚ β”‚ +β”‚ β”‚ $500K β”‚ β”‚ $300K β”‚ β”‚ $800K β”‚ β”‚ $200K β”‚ β”‚ +β”‚ β”‚ staked β”‚ β”‚ staked β”‚ β”‚ staked β”‚ β”‚ staked β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ BLS Aggregate β”‚ +β”‚ (quorum threshold: 67%) β”‚ +β”‚ β”‚ +β”‚ Slashing Conditions: β”‚ +β”‚ - False attestation: 100% slash β”‚ +β”‚ - Missed duty: 1% per miss β”‚ +β”‚ - Collusion: 100% slash + ban β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 3.4 IP Protection + +| Feature | Bonded Hooks | Hook Bazaar | +|---------|-------------|-------------| +| **Code Visibility** | Fully open source | Encrypted via Fhenix | +| **IP Protection** | None (by design) | Full protection | +| **Copying Prevention** | Social/reputation only | Cryptographic | +| **Monetization of IP** | Not possible | Core feature | + +### 3.5 Composability + +| Feature | Bonded Hooks | Hook Bazaar | +|---------|-------------|-------------| +| **Hook Composition** | Native (command chaining) | Not native (single hook) | +| **Modularity** | High (pick and choose) | Low (monolithic) | +| **Upgrade Path** | Swap commands | Deploy new version | +| **Storage Model** | MemoryCard (per-pool) | Hook-specific storage | + +--- + +## 4. Advantages & Disadvantages + +### 4.1 Bonded Hooks + +#### Advantages + +| Advantage | Description | +|-----------|-------------| +| **Low Barrier to Entry** | Pool admins need no coding skills | +| **Rapid Deployment** | Select block β†’ deploy β†’ done | +| **Built-in Incentives** | Points, rebates, bond yields attract users | +| **Community Funded** | Crowdfunded development reduces individual risk | +| **Composable** | Mix and match commands per pool | +| **Gas Optimized** | Single MasterHook contract, shared code | + +#### Disadvantages + +| Disadvantage | Description | +|--------------|-------------| +| **Limited Innovation** | Constrained to existing commands | +| **Centralized AVS** | Single point of failure for rebates | +| **No IP Protection** | Code is fully open source | +| **Whitelist Dependency** | Commands must be approved | +| **Complex Economics** | Multiple token types (bonds, points, shares) | +| **Upgrade Risk** | Command upgrades affect all pools | + +### 4.2 Hook Bazaar + +#### Advantages + +| Advantage | Description | +|-----------|-------------| +| **Full IP Protection** | Encrypted code cannot be copied | +| **Unlimited Innovation** | Any hook design possible | +| **Decentralized Verification** | No single point of failure | +| **Mathematical Guarantees** | Formal specifications | +| **Clear Monetization** | Direct sales and licensing | +| **Economic Security** | Slashing provides accountability | + +#### Disadvantages + +| Disadvantage | Description | +|--------------|-------------| +| **High Barrier** | Requires spec + implementation | +| **Complexity** | Mathematical specifications are difficult | +| **FHE Overhead** | Encrypted execution has gas cost | +| **Slower Iteration** | New spec required for changes | +| **No Composition** | Hooks are monolithic units | +| **Infrastructure Dependent** | Requires Fhenix + EigenLayer | + +--- + +## 5. Problem-Solution Matrix + +### 5.1 What Problems Does Each Solve? + +| Problem | Bonded Hooks | Hook Bazaar | +|---------|:-----------:|:-----------:| +| **"I want to deploy a hook but can't code"** | βœ… Solves | ❌ Does not solve | +| **"I want to monetize my hook without revealing code"** | ❌ Does not solve | βœ… Solves | +| **"I need guaranteed hook behavior"** | ⚠️ Partial (trusted AVS) | βœ… Solves (cryptoeconomic) | +| **"I want gas rebates for traders"** | βœ… Solves | ❌ Does not solve | +| **"I want to crowdfund hook development"** | βœ… Solves | ❌ Does not solve | +| **"I want to protect my algorithm from competitors"** | ❌ Does not solve | βœ… Solves | +| **"I want to combine multiple behaviors in one pool"** | βœ… Solves | ❌ Does not solve | +| **"I want trustless verification without code disclosure"** | ❌ Does not solve | βœ… Solves | +| **"I want simple hook discovery"** | ⚠️ Partial (blocks only) | βœ… Solves | +| **"I want economic accountability for hook failures"** | ❌ Does not solve | βœ… Solves | + +### 5.2 User Persona Fit + +| User Persona | Bonded Hooks | Hook Bazaar | +|--------------|:-----------:|:-----------:| +| **Non-technical Pool Admin** | βœ… Perfect fit | ❌ Not suitable | +| **Hook Developer (IP-sensitive)** | ❌ Not suitable | βœ… Perfect fit | +| **Hook Developer (Open source)** | ⚠️ Limited (commands) | ⚠️ Overkill | +| **DeFi Protocol Integrator** | ⚠️ Limited customization | βœ… Perfect fit | +| **Yield Farmer/Trader** | βœ… Points & rebates | ❌ No direct benefits | +| **Institutional Integrator** | ❌ Trust concerns | βœ… Perfect fit | + +--- + +## 6. Which Is Better? + +### 6.1 It Depends on the Use Case + +**Choose Bonded Hooks if:** +- You're a pool admin who wants pre-built functionality +- You want to attract traders with gas rebates and points +- You prioritize simplicity over customization +- You're comfortable with centralized AVS trust +- You want to participate in crowdfunded development +- You need composable behaviors (multiple commands) + +**Choose Hook Bazaar if:** +- You're a developer with proprietary algorithms +- You need IP protection for your hook implementation +- You require trustless, decentralized verification +- You want mathematical guarantees of behavior +- You're building for institutional integrators +- You need economic accountability (slashing) + +### 6.2 Complementary, Not Competing + +The two projects address different market segments: + +``` + HOOK ECOSYSTEM SPECTRUM + + Simple ◀──────────────────────────────────────────▢ Complex + Composed ◀─────────────────────────────────────────▢ Custom + Open ◀────────────────────────────────────────────▢ Protected + + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ BONDED HOOKS β”‚ β”‚ HOOK BAZAAR β”‚ + β”‚ β”‚ β”‚ β”‚ + β”‚ Pool admins β”‚ β”‚ Developers β”‚ + β”‚ Yield farmers β”‚ β”‚ Institutions β”‚ + β”‚ Quick deploy β”‚ β”‚ Custom algos β”‚ + β”‚ Gas rebates β”‚ β”‚ IP protection β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ + β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ + └───▢│ Could integrate β”‚β—€β”€β”€β”€β”˜ + β”‚ Bazaar hooks as β”‚ + β”‚ Bonded commands β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 6.3 Potential Integration + +A future integration could combine both approaches: + +1. **Hook Bazaar hooks as Bonded Commands**: Verified, IP-protected hooks could be wrapped as Bonded Hooks commands, allowing pool admins to use them without understanding the implementation. + +2. **Bonded Hooks economics on Bazaar**: The bond-to-earn model could be applied to Hook Bazaar hooks, creating staking incentives around verified hooks. + +3. **Shared verification**: Hook Bazaar's decentralized AVS could replace Bonded Hooks' centralized AVS for stronger trust guarantees. + +--- + +## 7. Summary Table + +| Dimension | Bonded Hooks | Hook Bazaar | Winner | +|-----------|-------------|-------------|--------| +| **Ease of Use** | ⭐⭐⭐⭐⭐ | ⭐⭐ | Bonded Hooks | +| **IP Protection** | ⭐ | ⭐⭐⭐⭐⭐ | Hook Bazaar | +| **Decentralization** | ⭐⭐ | ⭐⭐⭐⭐⭐ | Hook Bazaar | +| **Innovation Potential** | ⭐⭐ | ⭐⭐⭐⭐⭐ | Hook Bazaar | +| **User Incentives** | ⭐⭐⭐⭐⭐ | ⭐⭐ | Bonded Hooks | +| **Composability** | ⭐⭐⭐⭐⭐ | ⭐⭐ | Bonded Hooks | +| **Economic Security** | ⭐⭐ | ⭐⭐⭐⭐⭐ | Hook Bazaar | +| **Developer Monetization** | ⭐⭐ | ⭐⭐⭐⭐⭐ | Hook Bazaar | +| **Infrastructure Dependencies** | ⭐⭐⭐⭐ | ⭐⭐ | Bonded Hooks | +| **Institutional Appeal** | ⭐⭐ | ⭐⭐⭐⭐⭐ | Hook Bazaar | + +--- + +## 8. Conclusion + +**Bonded Hooks** and **Hook Bazaar** are not competitorsβ€”they are complementary solutions for different segments of the Uniswap V4 hook ecosystem: + +- **Bonded Hooks** democratizes hook access for non-developers through composable commands and gamified economics (points, rebates, bonds). It excels at rapid deployment and user engagement but sacrifices IP protection and decentralized trust. + +- **Hook Bazaar** professionalizes hook development by enabling developers to monetize proprietary algorithms while providing integrators with mathematical guarantees backed by cryptoeconomic security. It excels at IP protection and verification but requires significant technical expertise. + +**The market needs both**: Bonded Hooks grows the pie by making hooks accessible to everyone, while Hook Bazaar elevates the standard by introducing formal specifications and trustless verification. Together, they can create a robust, multi-layered hook ecosystem for Uniswap V4. + +--- + +## 9. References + +- [Bonded Hooks Repository](https://github.com/Jammabeans/Bonded-hooks) +- [Hook Bazaar Mission Statement](./mission-statement.md) +- [Hook Bazaar System Overview](./system-overview.md) +- [EigenLayer Documentation](https://docs.eigenlayer.xyz/) +- [Fhenix CoFHE Documentation](https://docs.fhenix.zone/) +- [Uniswap V4 Hooks](https://docs.uniswap.org/contracts/v4/concepts/hooks) diff --git a/docs/hook-pkg/architecture/function-refinement-tree.md b/docs/hook-pkg/architecture/function-refinement-tree.md new file mode 100644 index 000000000..061a3ccc7 --- /dev/null +++ b/docs/hook-pkg/architecture/function-refinement-tree.md @@ -0,0 +1,719 @@ +# Hook Bazaar: Function Refinement Tree + +> **Document Type:** Functional Decomposition +> **Last Updated:** 2025-12-09 +> **Related:** [Mission Statement](./mission-statement.md) | [Goal Tree](./goal-tree.md) | [State-Space Model](../mathematical-models/state-space-model.md) + +--- + +## 1. Overview + +This document decomposes the Hook Bazaar system into hierarchical functions, connecting high-level capabilities to concrete mathematical operations and interface definitions. + +--- + +## 2. Top-Level Function Decomposition + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ F0: HOOK BAZAAR SYSTEM β”‚ +β”‚ β”‚ +β”‚ Enable trading of verified, IP-protected Uniswap V4 hooks β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ F1 β”‚ β”‚ F2 β”‚ β”‚ F3 β”‚ β”‚ +β”‚ β”‚ SPECIFY β”‚ β”‚ VERIFY β”‚ β”‚ TRADE β”‚ β”‚ +β”‚ β”‚ HOOKS β”‚ β”‚ HOOKS β”‚ β”‚ HOOKS β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ F1.1 Define β”‚ β”‚ F2.1 Sample β”‚ β”‚ F3.1 List β”‚ β”‚ +β”‚ β”‚ F1.2 Declare β”‚ β”‚ F2.2 Execute β”‚ β”‚ F3.2 Purchase β”‚ β”‚ +β”‚ β”‚ F1.3 Validate β”‚ β”‚ F2.3 Compare β”‚ β”‚ F3.3 Deploy β”‚ β”‚ +β”‚ β”‚ F1.4 Store β”‚ β”‚ F2.4 Attest β”‚ β”‚ F3.4 Route β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 3. F1: Specify Hooks + +### 3.1 Function Hierarchy + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ F1: SPECIFY HOOKS β”‚ +β”‚ β”‚ +β”‚ Transform hook requirements into formal mathematical specifications β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ F1.1: Define State Variables β”‚ +β”‚ ════════════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.1.1: defineHookState(hookId) β†’ H β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Define the hook-specific state variables β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Input: hookId: bytes32 β”‚ +β”‚ β”‚ β”‚ Output: H = {h_1, h_2, ..., h_n} where h_i ∈ Type_i β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Example: β”‚ +β”‚ β”‚ β”‚ H_DynamicFee = { β”‚ +β”‚ β”‚ β”‚ volatilityWindow: uint256, β”‚ +β”‚ β”‚ β”‚ lastPrice: uint160, β”‚ +β”‚ β”‚ β”‚ feeMultiplier: uint24 β”‚ +β”‚ β”‚ β”‚ } β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Interface: IHookSpecification.declareStateWrites() β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.1.2: declarePoolStateReads() β†’ (S_LP, S_T, S_shared) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Declare which pool state variables the hook reads β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: Bitmasks indicating accessed variables β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ S_LP βŠ† {L_k, t_l, t_u, f_0^in, f_1^in, L_g, L_n, ...} β”‚ +β”‚ β”‚ β”‚ S_T βŠ† {√P, t_c, Ο†_lp, Ο†_proto, L_act, B_tick} β”‚ +β”‚ β”‚ β”‚ S_shared βŠ† {f_0^global, f_1^global} β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Interface: IHookSpecification.declareStateReads() β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F1.1.3: mapToStateView() β†’ IHookStateView calls β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Map formal variables to concrete getter functions β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ √P β†’ IStateView.getSlot0().sqrtPriceX96 β”‚ +β”‚ β”‚ L_k β†’ IStateView.getPositionLiquidity() β”‚ +β”‚ β”‚ ... β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Reference: state-space-model.md Section 9 β”‚ +β”‚ β”‚ +β”‚ F1.2: Declare Transition Functions β”‚ +β”‚ ══════════════════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.2.1: specifyCallback(callback) β†’ f_i(H, P) β†’ (H', Ξ”) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Define state transition for a specific callback β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Input: callback ∈ {beforeSwap, afterSwap, beforeMint, ...} β”‚ +β”‚ β”‚ β”‚ Output: Transition function specification β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Mathematical Form: β”‚ +β”‚ β”‚ β”‚ f_i: (H Γ— P Γ— Input_i) β†’ (H' Γ— Ξ”_i) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ where: β”‚ +β”‚ β”‚ β”‚ - H is hook state before β”‚ +β”‚ β”‚ β”‚ - P is pool state (read-only for hook) β”‚ +β”‚ β”‚ β”‚ - Input_i is callback-specific input β”‚ +β”‚ β”‚ β”‚ - H' is hook state after β”‚ +β”‚ β”‚ β”‚ - Ξ”_i is return delta (fee override, etc.) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Interface: IHookSpecification.transitionBounds() β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.2.2: specifyBeforeSwap(H, P, swapParams) β†’ (H', Ξ΄_fee) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Concrete specification for beforeSwap callback β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Inputs: β”‚ +β”‚ β”‚ β”‚ - H: Current hook state β”‚ +β”‚ β”‚ β”‚ - P.sqrtPriceX96: Current price β”‚ +β”‚ β”‚ β”‚ - P.tick: Current tick β”‚ +β”‚ β”‚ β”‚ - P.lpFee: Current LP fee β”‚ +β”‚ β”‚ β”‚ - swapParams: (zeroForOne, amountSpecified, ...) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Outputs: β”‚ +β”‚ β”‚ β”‚ - H': Updated hook state β”‚ +β”‚ β”‚ β”‚ - Ξ΄_fee: Fee adjustment (can be 0) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Example (DynamicFeeHook): β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ volatility = |P.sqrtPriceX96 - H.lastPrice| / H.lastPriceβ”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ H'.feeMultiplier = min(MAX_FEE, baseFee Γ— (1 + v Γ— k)) β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ H'.lastPrice = P.sqrtPriceX96 β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Ξ΄_fee = H'.feeMultiplier - P.lpFee β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Reference: IHooks.beforeSwap() β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.2.3: specifyAfterSwap(H, P, swapResult) β†’ (H', Ξ΄_amounts) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Concrete specification for afterSwap callback β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Inputs: β”‚ +β”‚ β”‚ β”‚ - H: Current hook state (post-beforeSwap) β”‚ +β”‚ β”‚ β”‚ - P: Pool state after swap execution β”‚ +β”‚ β”‚ β”‚ - swapResult: (amount0, amount1, sqrtPriceAfter, ...) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Outputs: β”‚ +β”‚ β”‚ β”‚ - H': Final hook state β”‚ +β”‚ β”‚ β”‚ - Ξ΄_amounts: Amount adjustments (usually 0) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Reference: IHooks.afterSwap() β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F1.2.4: specifyLiquidityCallbacks(...) β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Similar structure for: β”‚ +β”‚ β”‚ - beforeAddLiquidity / afterAddLiquidity β”‚ +β”‚ β”‚ - beforeRemoveLiquidity / afterRemoveLiquidity β”‚ +β”‚ β”‚ - beforeDonate / afterDonate β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Each follows f_i(H, P, Input) β†’ (H', Ξ”) pattern β”‚ +β”‚ β”‚ +β”‚ F1.3: Declare Invariants β”‚ +β”‚ ════════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.3.1: declareStateInvariant(inv_id) β†’ Ο†(H) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Invariant over hook state only β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Form: Ο†(H) ≑ predicate that must hold βˆ€ reachable H β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Example: β”‚ +β”‚ β”‚ β”‚ INV-FEE-BOUNDS: 0 ≀ H.feeMultiplier ≀ MAX_FEE β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Interface: IHookSpecification.declareInvariants() β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.3.2: declareTransitionInvariant(callback) β†’ ψ(H, H', P) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Invariant relating pre and post states β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Form: ψ(H, H', P) ≑ relationship that must hold β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Example: β”‚ +β”‚ β”‚ β”‚ INV-MONOTONIC: volatility₁ < volatilityβ‚‚ ⟹ fee₁ ≀ feeβ‚‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Used in behavioral verification β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F1.3.3: declarePoolInvariant() β†’ Ο‡(P, H) β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Invariant relating pool state to hook state β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Example (from arXiv:2512.06203): β”‚ +β”‚ β”‚ INV-PRODUCT: |K_n - K_0| ≀ n Γ— B β”‚ +β”‚ β”‚ where K = X Γ— Y (constant product) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Reference: state-space-model.md Section 4 β”‚ +β”‚ β”‚ +β”‚ F1.4: Store Specification β”‚ +β”‚ ═════════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.4.1: serializeSpec(spec) β†’ bytes β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Convert specification to storable format β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: Markdown + LaTeX document β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Format: See specification-template.md (to be created) β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F1.4.2: uploadToIPFS(specBytes) β†’ CID β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Store specification on IPFS β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: Content Identifier (CID) string β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Example: "ipfs://QmXyz..." β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F1.4.3: linkToHook(hookAddress, specCID) β†’ void β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Associate specification with deployed hook β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ On-chain: hook.specificationURI = specCID β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Interface: IHookSpecification.specificationURI() β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 4. F2: Verify Hooks + +### 4.1 Function Hierarchy + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ F2: VERIFY HOOKS β”‚ +β”‚ β”‚ +β”‚ Prove hook implementation matches specification without code disclosure β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ F2.1: Sample State β”‚ +β”‚ ══════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.1.1: samplePoolState(poolId) β†’ StateSample β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Capture current pool state snapshot β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: StateSample = { β”‚ +β”‚ β”‚ β”‚ blockNumber: uint256, β”‚ +β”‚ β”‚ β”‚ timestamp: uint256, β”‚ +β”‚ β”‚ β”‚ poolId: bytes32, β”‚ +β”‚ β”‚ β”‚ lpState: bytes, // encoded LPPositionState[] β”‚ +β”‚ β”‚ β”‚ traderState: bytes, // encoded TraderState β”‚ +β”‚ β”‚ β”‚ hookState: bytes, // encoded hook-specific state β”‚ +β”‚ β”‚ β”‚ sharedState: bytes // encoded fee growth β”‚ +β”‚ β”‚ β”‚ } β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Uses: IHookStateView.getTraderState(), etc. β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.1.2: sampleHookState(hook, poolId) β†’ bytes β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Capture hook-specific state β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: Encoded H values β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Uses: IHookStateView.getHookState() β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F2.1.3: generateSampleSet(poolIds, n) β†’ StateSample[] β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Generate n samples across specified pools β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Strategy: β”‚ +β”‚ β”‚ - Random block selection within recent window β”‚ +β”‚ β”‚ - Diverse pool states (different liquidity, prices) β”‚ +β”‚ β”‚ - Edge cases (near tick boundaries, low liquidity) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Used by: AVS operators β”‚ +β”‚ β”‚ +β”‚ F2.2: Execute Callbacks β”‚ +β”‚ ═══════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.2.1: executeCallback(hook, callback, input) β†’ (output, gasUsed) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Execute hook callback as black box β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Input: β”‚ +β”‚ β”‚ β”‚ - hook: address (encrypted bytecode) β”‚ +β”‚ β”‚ β”‚ - callback: bytes4 selector β”‚ +β”‚ β”‚ β”‚ - input: bytes (callback parameters) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: β”‚ +β”‚ β”‚ β”‚ - output: bytes (return data) β”‚ +β”‚ β”‚ β”‚ - gasUsed: uint256 β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Note: Code remains encrypted; only behavior observed β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Execution via: PoolManager simulation or direct call β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.2.2: recordTransition(pre, callback, input, post) β†’ TransitionSampleβ”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Record complete state transition β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: TransitionSample = { β”‚ +β”‚ β”‚ β”‚ preState: StateSample, β”‚ +β”‚ β”‚ β”‚ callback: bytes4, β”‚ +β”‚ β”‚ β”‚ input: bytes, β”‚ +β”‚ β”‚ β”‚ postState: StateSample, β”‚ +β”‚ β”‚ β”‚ gasUsed: uint256, β”‚ +β”‚ β”‚ β”‚ returnData: bytes β”‚ +β”‚ β”‚ β”‚ } β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Used for: Verification comparison β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F2.2.3: batchExecute(hook, callbacks[], inputs[]) β†’ TransitionSample[] β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Execute multiple callbacks for comprehensive testing β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Used by: AVS operators for task completion β”‚ +β”‚ β”‚ +β”‚ F2.3: Compare Against Specification β”‚ +β”‚ ═══════════════════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.3.1: parseSpecification(specURI) β†’ ParsedSpec β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Load and parse specification from IPFS β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: ParsedSpec = { β”‚ +β”‚ β”‚ β”‚ stateVars: StateVarDef[], β”‚ +β”‚ β”‚ β”‚ transitions: TransitionDef[], β”‚ +β”‚ β”‚ β”‚ invariants: InvariantDef[], β”‚ +β”‚ β”‚ β”‚ testVectors: TestVector[] β”‚ +β”‚ β”‚ β”‚ } β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Parsing: Markdown β†’ structured objects β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.3.2: computeExpectedOutput(spec, preState, callback, input) β†’ bytes β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Calculate expected output from specification β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Process: β”‚ +β”‚ β”‚ β”‚ 1. Find transition function f_i for callback β”‚ +β”‚ β”‚ β”‚ 2. Decode preState into (H, P) β”‚ +β”‚ β”‚ β”‚ 3. Apply f_i(H, P, input) equations β”‚ +β”‚ β”‚ β”‚ 4. Encode expected (H', Ξ”) as bytes β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ This is the CORE of spec-to-verification translation β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Mathematical: f_i^spec(H, P, input) β†’ (H', Ξ”) β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.3.3: compareOutputs(actual, expected, Ξ΅) β†’ ComparisonResult β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Compare actual hook output to expected β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Input: β”‚ +β”‚ β”‚ β”‚ - actual: bytes (from executeCallback) β”‚ +β”‚ β”‚ β”‚ - expected: bytes (from computeExpectedOutput) β”‚ +β”‚ β”‚ β”‚ - Ξ΅: uint256 (tolerance for rounding) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: ComparisonResult = { β”‚ +β”‚ β”‚ β”‚ matches: bool, β”‚ +β”‚ β”‚ β”‚ deviation: uint256, β”‚ +β”‚ β”‚ β”‚ fieldDeviations: mapping(field β†’ deviation) β”‚ +β”‚ β”‚ β”‚ } β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Condition: matches = (deviation ≀ Ξ΅) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Accounts for: Rounding, gas limits, ordering β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F2.3.4: checkInvariants(spec, pre, post) β†’ InvariantResult[] β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Verify all declared invariants hold β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ For each invariant Ο† ∈ spec.invariants: β”‚ +β”‚ β”‚ result[Ο†.id] = evaluate(Ο†, pre, post) β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Output: Array of (invariantId, holds: bool, reason: string) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Used for: Comprehensive compliance check β”‚ +β”‚ β”‚ +β”‚ F2.4: Attest Compliance β”‚ +β”‚ ═══════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.4.1: aggregateResults(comparisons[], invariants[]) β†’ AttestResult β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Combine all verification results β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: AttestResult = { β”‚ +β”‚ β”‚ β”‚ specCompliant: bool, β”‚ +β”‚ β”‚ β”‚ totalSamples: uint32, β”‚ +β”‚ β”‚ β”‚ passingsamples: uint32, β”‚ +β”‚ β”‚ β”‚ invariantsChecked: uint32, β”‚ +β”‚ β”‚ β”‚ invariantsPassed: uint32, β”‚ +β”‚ β”‚ β”‚ stateSamplesHash: bytes32, β”‚ +β”‚ β”‚ β”‚ testResultsHash: bytes32 β”‚ +β”‚ β”‚ β”‚ } β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ specCompliant = (passingSamples == totalSamples) && β”‚ +β”‚ β”‚ β”‚ (invariantsPassed == invariantsChecked) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Used by: AVS operators β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.4.2: signAttestation(result, operatorKey) β†’ Signature β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Sign attestation result with BLS key β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ signature = BLS.sign(operatorKey, hash(result)) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Used for: Aggregated signature submission β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F2.4.3: submitResponse(task, result, signatures) β†’ void β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Submit aggregated response to TaskManager β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ On-chain: TaskManager.respondToAttestationTask(...) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Emits: AttestationTaskResponded event β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F2.4.4: recordAttestation(hook, specURI, taskIndex) β†’ attestationId β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Record successful attestation on-chain β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ On-chain: AttestationRegistry.recordAttestation(...) β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Output: attestationId = keccak256(hook, specURI, taskIndex, now) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Enables: Marketplace listing β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 5. F3: Trade Hooks + +### 5.1 Function Hierarchy + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ F3: TRADE HOOKS β”‚ +β”‚ β”‚ +β”‚ Enable discovery, purchase, and deployment of verified hooks β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ F3.1: List Hooks β”‚ +β”‚ ════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.1.1: mintHookNFT(hook, specURI, metadata) β†’ tokenId β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Create NFT representing hook ownership β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Requires: Valid attestation for hook β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: ERC-721 token with: β”‚ +β”‚ β”‚ β”‚ - hook address β”‚ +β”‚ β”‚ β”‚ - specification URI β”‚ +β”‚ β”‚ β”‚ - attestation ID β”‚ +β”‚ β”‚ β”‚ - metadata URI β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Contract: HookNFTRegistry.mint() β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.1.2: createListing(tokenId, price, terms) β†’ listingId β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ List hook for sale in marketplace β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Listing types: β”‚ +β”‚ β”‚ β”‚ - SALE: One-time transfer of ownership β”‚ +β”‚ β”‚ β”‚ - LICENSE: Per-use or subscription fee β”‚ +β”‚ β”‚ β”‚ - FREE: Open source with optional donation β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Contract: HookMarket.list() β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F3.1.3: updateListing(listingId, newPrice, newTerms) β†’ void β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Modify existing listing β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Contract: HookMarket.update() β”‚ +β”‚ β”‚ +β”‚ F3.2: Purchase Hooks β”‚ +β”‚ ════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.2.1: queryListings(filters) β†’ Listing[] β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Search available hooks β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Filters: β”‚ +β”‚ β”‚ β”‚ - callbacks: bytes4[] (implemented callbacks) β”‚ +β”‚ β”‚ β”‚ - priceRange: (min, max) β”‚ +β”‚ β”‚ β”‚ - attestationStatus: enum β”‚ +β”‚ β”‚ β”‚ - category: string β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Off-chain: Indexer + on-chain verification β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.2.2: verifyAttestation(hook) β†’ AttestationInfo β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Check attestation validity before purchase β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Output: AttestationInfo = { β”‚ +β”‚ β”‚ β”‚ isValid: bool, β”‚ +β”‚ β”‚ β”‚ attestationId: bytes32, β”‚ +β”‚ β”‚ β”‚ expiresAt: uint256, β”‚ +β”‚ β”‚ β”‚ specificationURI: string β”‚ +β”‚ β”‚ β”‚ } β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Contract: AttestationRegistry.getAttestation() β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F3.2.3: purchaseHook(listingId, payment) β†’ receipt β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Complete hook purchase/license β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Process: β”‚ +β”‚ β”‚ 1. Verify attestation still valid β”‚ +β”‚ β”‚ 2. Transfer payment to seller β”‚ +β”‚ β”‚ 3. If SALE: Transfer NFT ownership β”‚ +β”‚ β”‚ 4. If LICENSE: Grant usage rights β”‚ +β”‚ β”‚ 5. Emit purchase event β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Contract: HookMarket.purchase() β”‚ +β”‚ β”‚ +β”‚ F3.3: Deploy Hooks β”‚ +β”‚ ══════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.3.1: registerHookForPool(poolId, hook) β†’ void β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Associate hook with a pool via MasterHook β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Requires: β”‚ +β”‚ β”‚ β”‚ - Caller has usage rights (owner or licensee) β”‚ +β”‚ β”‚ β”‚ - Hook has valid attestation β”‚ +β”‚ β”‚ β”‚ - Pool exists β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Contract: ProtocolHookMediator.registerHook() β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.3.2: initializePoolWithHook(params, hook) β†’ poolId β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Create new pool with verified hook β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Process: β”‚ +β”‚ β”‚ β”‚ 1. Verify hook attestation β”‚ +β”‚ β”‚ β”‚ 2. Call PoolManager.initialize() with MasterHook β”‚ +β”‚ β”‚ β”‚ 3. Register specific hook in MasterHook β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Uses: Uniswap V4 PoolManager β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F3.3.3: composeHooks(poolId, hooks[]) β†’ void β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Chain multiple hooks for a pool β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Execution order defined by MasterHook β”‚ +β”‚ β”‚ Each hook must have valid attestation β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Contract: MasterHook.setHookChain() β”‚ +β”‚ β”‚ +β”‚ F3.4: Route Callbacks β”‚ +β”‚ ═════════════════════ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.4.1: routeCallback(poolId, callback, data) β†’ result β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ MasterHook routes callback to registered hook(s) β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Process: β”‚ +β”‚ β”‚ β”‚ 1. Look up registered hooks for poolId β”‚ +β”‚ β”‚ β”‚ 2. For each hook in chain: β”‚ +β”‚ β”‚ β”‚ - Execute callback β”‚ +β”‚ β”‚ β”‚ - Aggregate results β”‚ +β”‚ β”‚ β”‚ 3. Return combined result to PoolManager β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Contract: MasterHook (Diamond facet) β”‚ +β”‚ β”‚ β”‚ +β”‚ β”œβ”€β”€ F3.4.2: aggregateDeltas(deltas[]) β†’ combinedDelta β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Combine return values from chained hooks β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Strategy depends on callback type: β”‚ +β”‚ β”‚ β”‚ - beforeSwap: Last non-zero fee wins, or sum β”‚ +β”‚ β”‚ β”‚ - afterSwap: Sum of amount deltas β”‚ +β”‚ β”‚ β”‚ - etc. β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ └── Defined in: Hook composition rules β”‚ +β”‚ β”‚ β”‚ +β”‚ └── F3.4.3: handleHookFailure(poolId, hook, error) β†’ fallback β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Handle hook execution failures β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Options: β”‚ +β”‚ β”‚ - REVERT: Entire transaction fails β”‚ +β”‚ β”‚ - SKIP: Continue without hook β”‚ +β”‚ β”‚ - FALLBACK: Use default behavior β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Configurable per pool β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 6. Cross-Cutting Functions + +### 6.1 State Management + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ FC.1: STATE MANAGEMENT β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ FC.1.1: encodeState(state) β†’ bytes β”‚ +β”‚ ───────────────────────────────── β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Convert typed state structs to bytes for hashing/storage β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Used by: F2.1 (sampling), F2.3 (comparison) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Implementation: abi.encode(state) β”‚ +β”‚ β”‚ +β”‚ FC.1.2: decodeState(bytes, stateType) β†’ state β”‚ +β”‚ ────────────────────────────────────────────── β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Reconstruct typed state from bytes β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Used by: F2.3 (spec computation) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Implementation: abi.decode(bytes, (Type)) β”‚ +β”‚ β”‚ +β”‚ FC.1.3: hashState(state) β†’ bytes32 β”‚ +β”‚ ────────────────────────────────── β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Compute deterministic hash of state β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Used by: F2.4 (attestation recording) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Implementation: keccak256(encodeState(state)) β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 6.2 Cryptographic Functions + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ FC.2: CRYPTOGRAPHIC FUNCTIONS β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ FC.2.1: encryptBytecode(bytecode, key) β†’ encryptedBytecode β”‚ +β”‚ ────────────────────────────────────────────────────────── β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Encrypt hook bytecode via Fhenix CoFHE β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Used by: Hook deployment β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Technology: Fhenix CoFHE β”‚ +β”‚ β”‚ +β”‚ FC.2.2: signBLS(message, privateKey) β†’ signature β”‚ +β”‚ ───────────────────────────────────────────────── β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Sign message with BLS private key β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Used by: F2.4.2 (operator signatures) β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Technology: EigenLayer BLS library β”‚ +β”‚ β”‚ +β”‚ FC.2.3: verifyBLSAggregate(message, pubkeys[], aggSig) β†’ bool β”‚ +β”‚ ────────────────────────────────────────────────────────────── β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Verify aggregated BLS signature β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ Used by: TaskManager response verification β”‚ +β”‚ β”‚ β”‚ +β”‚ └── Contract: BLSSignatureChecker β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 7. Function-to-Interface Mapping + +| Function | Interface/Contract | Method | +|----------|-------------------|--------| +| F1.1.1 | `IHookSpecification` | `declareStateWrites()` | +| F1.1.2 | `IHookSpecification` | `declareStateReads()` | +| F1.3.1 | `IHookSpecification` | `declareInvariants()` | +| F1.4.3 | `IHookSpecification` | `specificationURI()` | +| F2.1.1 | `IHookStateView` | `getTraderState()`, `getLPPositionState()` | +| F2.1.2 | `IHookStateView` | `getHookState()` | +| F2.4.3 | `IHookAttestationTaskManager` | `respondToAttestationTask()` | +| F2.4.4 | `IAttestationRegistry` | `recordAttestation()` | +| F3.1.1 | `IHookNFTRegistry` | `mint()` | +| F3.1.2 | `IHookMarket` | `list()` | +| F3.2.2 | `IAttestationRegistry` | `getAttestation()` | +| F3.2.3 | `IHookMarket` | `purchase()` | +| F3.3.1 | `IProtocolHookMediator` | `registerHook()` | +| F3.4.1 | `IMasterHook` | `beforeSwap()`, etc. | + +--- + +## 8. Mathematical Foundation Mapping + +| Function | Mathematical Concept | Reference | +|----------|---------------------|-----------| +| F1.1.1-3 | State space $\mathcal{S} = \mathcal{S}_{LP} \times \mathcal{S}_T \times \mathcal{S}_{shared}$ | state-space-model.md Β§2 | +| F1.2.1-4 | Transition functions $f_i: (H \times P) \rightarrow (H' \times \Delta)$ | state-space-model.md Β§3 | +| F1.3.1-3 | Invariants $\phi(H)$, $\psi(H, H', P)$, $\chi(P, H)$ | state-space-model.md Β§4 | +| F2.3.2 | Expected output $f_i^{spec}(H, P, input)$ | avs-verification-system.md Β§4.2 | +| F2.3.3 | Tolerance $\|f^{actual} - f^{spec}\| \leq \epsilon$ | avs-verification-system.md Β§4.2 | +| F2.3.4 | Invariant verification $\forall \phi: \phi(H, P) = \text{true}$ | state-space-model.md Β§4 | + +--- + +## 9. Next Steps + +Based on this decomposition, the priority implementation order is: + +1. **Specification Template (F1.4)**: Create concrete template developers can fill in +2. **Spec Parser (F2.3.1)**: Build tool to parse specifications into verification rules +3. **Expected Output Calculator (F2.3.2)**: Core spec-to-verification translation +4. **State Sampler (F2.1)**: Implement sampling utilities +5. **Comparison Logic (F2.3.3-4)**: Build verification comparison functions diff --git a/docs/hook-pkg/architecture/goal-tree.md b/docs/hook-pkg/architecture/goal-tree.md new file mode 100644 index 000000000..9b55b40f3 --- /dev/null +++ b/docs/hook-pkg/architecture/goal-tree.md @@ -0,0 +1,423 @@ +# Hook Bazaar: Goal Tree + +> **Document Type:** Strategic Decomposition +> **Last Updated:** 2025-12-09 +> **Related:** [Mission Statement](./mission-statement.md) | [Function Refinement Tree](./function-refinement-tree.md) + +--- + +## 1. Goal Tree Overview + +The goal tree decomposes the mission into hierarchical objectives, showing how lower-level goals contribute to higher-level outcomes. + +``` + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ MISSION β”‚ + β”‚ Trustless marketplace for β”‚ + β”‚ verified, IP-protected hooks β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ GOAL 1 β”‚ β”‚ GOAL 2 β”‚ β”‚ GOAL 3 β”‚ + β”‚ Enable Mathematical β”‚ β”‚ Provide Trustless β”‚ β”‚ Create Sustainable β”‚ + β”‚ Hook Specification β”‚ β”‚ Verification β”‚ β”‚ Marketplace β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ + β–Ό β–Ό β–Ό β–Ό β–Ό β–Ό + [G1.1-G1.4] [G2.1-G2.4] [G3.1-G3.4] + Subgoals Subgoals Subgoals +``` + +--- + +## 2. Primary Goals + +### G1: Enable Mathematical Hook Specification + +**Objective:** Create a formal framework for specifying hook behavior as mathematical systems + +**Success Criteria:** +- Specification language can express all Uniswap V4 hook callbacks +- Specifications are machine-parseable for verification +- Specifications are human-readable for review + +--- + +### G2: Provide Trustless Verification + +**Objective:** Verify that hook implementations match specifications without code disclosure + +**Success Criteria:** +- Verification does not require access to source code +- Economic security proportional to risk +- Challenge mechanism for incorrect attestations + +--- + +### G3: Create Sustainable Marketplace + +**Objective:** Build an economically viable platform for hook trading + +**Success Criteria:** +- Developers can monetize hooks +- Integrators can easily discover and deploy hooks +- Platform is self-sustaining + +--- + +## 3. Goal Decomposition + +### 3.1 G1: Enable Mathematical Hook Specification + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ G1: ENABLE MATHEMATICAL HOOK SPECIFICATION β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.1: Define State Space Model β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Formalize the state variables that hooks can read and write β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.1.1: Partition pool state by user type (LP/Trader) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.1.2: Define hook-specific state variables (H) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.1.3: Map IStateView to formal state vectors β”‚ β”‚ +β”‚ β”‚ └── G1.1.4: Document state variable semantics β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: state-space-model.md β”‚ β”‚ +β”‚ β”‚ Status: COMPLETE β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.2: Define Transition Functions β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Specify how each callback transforms state β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.2.1: Map callbacks to state transitions β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.2.2: Define f_i(H, P) β†’ (H', Ξ”) for each callback β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.2.3: Specify pre/post conditions β”‚ β”‚ +β”‚ β”‚ └── G1.2.4: Define composition rules for chained hooks β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: transition-functions.md β”‚ β”‚ +β”‚ β”‚ Status: PARTIAL (in state-space-model.md) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.3: Define Invariant Framework β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Specify properties that must always hold β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.3.1: Catalog pool invariants (constant product, etc.) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.3.2: Define hook-specific invariant types β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.3.3: Create invariant verification rules β”‚ β”‚ +β”‚ β”‚ └── G1.3.4: Document invariant composition β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: invariant-framework.md β”‚ β”‚ +β”‚ β”‚ Status: PARTIAL (in state-space-model.md) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.4: Create Specification Template β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Provide reusable template for hook specifications β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.4.1: Design specification document structure β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.4.2: Create LaTeX/Markdown template β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G1.4.3: Define test vector format β”‚ β”‚ +β”‚ β”‚ └── G1.4.4: Build specification validator tool β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: specification-template.md β”‚ β”‚ +β”‚ β”‚ Status: NOT STARTED β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 3.2 G2: Provide Trustless Verification + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ G2: PROVIDE TRUSTLESS VERIFICATION β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G2.1: Design AVS Architecture β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Create EigenLayer AVS for hook verification β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.1.1: Define task structure (AttestationTask) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.1.2: Define response structure (AttestationResponse) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.1.3: Design operator workflow β”‚ β”‚ +β”‚ β”‚ └── G2.1.4: Integrate with EigenLayer middleware β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: avs-verification-system.md β”‚ β”‚ +β”‚ β”‚ Status: COMPLETE β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G2.2: Implement Behavioral Verification β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Verify hook behavior without code access β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.2.1: Design state sampling strategy β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.2.2: Implement spec-to-expected-output translation β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.2.3: Define tolerance/epsilon for comparisons β”‚ β”‚ +β”‚ β”‚ └── G2.2.4: Create verification result aggregation β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: behavioral-verification.md + contracts β”‚ β”‚ +β”‚ β”‚ Status: DOCUMENTED (in avs-verification-system.md) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G2.3: Implement Challenge Mechanism β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Allow disputes of incorrect attestations β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.3.1: Define false positive challenge (bad attestation) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.3.2: Define false negative challenge (wrong rejection) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.3.3: Implement slashing logic β”‚ β”‚ +β”‚ β”‚ └── G2.3.4: Define challenge window and resolution β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: challenge-mechanism.md + contracts β”‚ β”‚ +β”‚ β”‚ Status: DOCUMENTED (in avs-verification-system.md) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G2.4: Integrate Code Protection β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Protect hook code from decompilation β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.4.1: Integrate Fhenix CoFHE for bytecode encryption β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.4.2: Define encryption/deployment workflow β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G2.4.3: Verify encrypted hooks remain callable β”‚ β”‚ +β”‚ β”‚ └── G2.4.4: Document gas overhead of encrypted execution β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: code-protection.md + integration guide β”‚ β”‚ +β”‚ β”‚ Status: NOT STARTED β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 3.3 G3: Create Sustainable Marketplace + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ G3: CREATE SUSTAINABLE MARKETPLACE β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G3.1: Design NFT-Based Ownership β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Represent hook ownership and rights as NFTs β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.1.1: Define NFT metadata schema β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.1.2: Link NFT to specification URI β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.1.3: Link NFT to deployed hook address β”‚ β”‚ +β”‚ β”‚ └── G3.1.4: Implement royalty mechanism (EIP-2981) β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: HookNFTRegistry.sol β”‚ β”‚ +β”‚ β”‚ Status: NOT STARTED β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G3.2: Build Hook Market β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Create listing, discovery, and purchase mechanics β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.2.1: Implement hook listing function β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.2.2: Enforce attestation requirement for listing β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.2.3: Implement purchase/licensing flow β”‚ β”‚ +β”‚ β”‚ └── G3.2.4: Build search and filter capabilities β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: HookMarket.sol β”‚ β”‚ +β”‚ β”‚ Status: NOT STARTED β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G3.3: Integrate with Uniswap V4 β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Connect marketplace hooks to PoolManager β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.3.1: Design MasterHook (Diamond pattern) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.3.2: Implement ProtocolHookMediator β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.3.3: Create hook registration flow β”‚ β”‚ +β”‚ β”‚ └── G3.3.4: Handle hook composition and routing β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: MasterHook.sol, ProtocolHookMediator.sol β”‚ β”‚ +β”‚ β”‚ Status: IN PROGRESS (existing contracts) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G3.4: Define Economic Model β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Create sustainable economics for all participants β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Subgoals: β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.4.1: Define developer revenue model (sales, licensing, fees) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.4.2: Define operator incentives (verification rewards) β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ G3.4.3: Define platform fees β”‚ β”‚ +β”‚ β”‚ └── G3.4.4: Model economic sustainability β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Deliverable: economic-model.md β”‚ β”‚ +β”‚ β”‚ Status: NOT STARTED β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 4. Goal Dependencies + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ GOAL DEPENDENCY GRAPH β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ MISSION β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1 β”‚ β”‚ G2 β”‚ β”‚ G3 β”‚ β”‚ +β”‚ β”‚ Spec β”‚ β”‚Verify β”‚ β”‚Market β”‚ β”‚ +β”‚ β””β”€β”€β”€β”¬β”€β”€β”€β”˜ β””β”€β”€β”€β”¬β”€β”€β”€β”˜ β””β”€β”€β”€β”¬β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.1 │◄──────│ G2.2 β”‚ β”‚ G2.1 │◄──────────│ G3.2 β”‚ β”‚ +β”‚ β”‚ State β”‚ β”‚Behav. β”‚ β”‚ AVS β”‚ β”‚Market β”‚ β”‚ +β”‚ β”‚ Model β”‚ β”‚Verify β”‚ β”‚ Arch β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β–² β–² β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.2 │──────▢│ G1.3 β”‚ β”‚ G2.4 │◄──────────│ G3.3 β”‚ β”‚ +β”‚ β”‚Trans. β”‚ β”‚Invari.β”‚ β”‚ Code β”‚ β”‚Uniswapβ”‚ β”‚ +β”‚ β”‚ Func β”‚ β”‚ β”‚ β”‚Protectβ”‚ β”‚Integr.β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.4 β”‚ β”‚ G3.1 β”‚ β”‚ +β”‚ β”‚ Spec Template │◄──────────────────────────────│ NFT β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”‚ +β”‚ LEGEND: β”‚ +β”‚ ───────▢ depends on (must complete before) β”‚ +β”‚ ◄────── enables (completion enables) β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 5. Critical Path + +The critical path to minimum viable product (MVP): + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CRITICAL PATH TO MVP β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ Phase 1: Foundation β”‚ +β”‚ ═══════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G1.1 │────▢│ G1.2 │────▢│ G1.3 β”‚ β”‚ +β”‚ β”‚ State β”‚ β”‚ Trans. β”‚ β”‚ Invari. β”‚ β”‚ +β”‚ β”‚ Model β”‚ β”‚ Funcs β”‚ β”‚ Frame. β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ Phase 2: Verification β”‚ β”‚ +β”‚ ═════════════════════ β”‚ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”΄β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G2.1 │────▢│ G2.2 │◄────│ G1.4 β”‚ β”‚ +β”‚ β”‚ AVS β”‚ β”‚ Behav. β”‚ β”‚ Spec β”‚ β”‚ +β”‚ β”‚ Arch β”‚ β”‚ Verify β”‚ β”‚ Templateβ”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G2.3 β”‚ β”‚ G2.4 β”‚ β”‚ +β”‚ β”‚Challengeβ”‚ β”‚ Code β”‚ β”‚ +β”‚ β”‚ Mech. β”‚ β”‚ Protect β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β–Ό β”‚ +β”‚ Phase 3: Marketplace β”‚ +β”‚ ════════════════════ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ G3.1 │────▢│ G3.2 │────▢│ G3.3 β”‚ β”‚ +β”‚ β”‚ NFT β”‚ β”‚ Market β”‚ β”‚ Uniswap β”‚ β”‚ +β”‚ β”‚ Ownershipβ”‚ β”‚ β”‚ β”‚ Integr. β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ MVP β”‚ β”‚ +β”‚ β”‚ LAUNCH β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 6. Goal Status Summary + +| Goal | Description | Status | Priority | +|------|-------------|--------|----------| +| G1.1 | State Space Model | COMPLETE | - | +| G1.2 | Transition Functions | PARTIAL | HIGH | +| G1.3 | Invariant Framework | PARTIAL | HIGH | +| G1.4 | Specification Template | NOT STARTED | HIGH | +| G2.1 | AVS Architecture | COMPLETE | - | +| G2.2 | Behavioral Verification | DOCUMENTED | MEDIUM | +| G2.3 | Challenge Mechanism | DOCUMENTED | MEDIUM | +| G2.4 | Code Protection | NOT STARTED | HIGH | +| G3.1 | NFT Ownership | NOT STARTED | MEDIUM | +| G3.2 | Hook Market | NOT STARTED | MEDIUM | +| G3.3 | Uniswap Integration | IN PROGRESS | HIGH | +| G3.4 | Economic Model | NOT STARTED | LOW | + +--- + +## 7. Next Actions + +Based on critical path and dependencies: + +1. **G1.2/G1.3**: Complete transition function and invariant documentation +2. **G1.4**: Create specification template that developers can use +3. **G2.4**: Begin Fhenix CoFHE integration research +4. **G3.3**: Continue MasterHook and ProtocolHookMediator development diff --git a/docs/hook-pkg/architecture/hook-specification-platform-decomposition.md b/docs/hook-pkg/architecture/hook-specification-platform-decomposition.md new file mode 100644 index 000000000..11180bf84 --- /dev/null +++ b/docs/hook-pkg/architecture/hook-specification-platform-decomposition.md @@ -0,0 +1,1163 @@ +# Hook Specification Platform: System Decomposition + +> **Document Type:** Implementation TODO System +> **Last Updated:** 2025-12-09 +> **Status:** Ready for Implementation +> **Related:** [State-Space Model](../mathematical-models/state-space-model.md) | [System Overview](./system-overview.md) + +--- + +## 1. Executive Summary + +This document decomposes the **Hook Specification Platform** into implementable components. The platform enables: + +1. **Public system state documentation** - Read-only `system-state.md` derived from `IStateView` +2. **HookSpec upload & validation** - Verify spec compliance with system state schema +3. **IPFS storage** - Generate content-addressed URIs for specifications +4. **NFT minting** - Issue `HookLicense` NFTs with IPFS URI + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOK SPECIFICATION PLATFORM FLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ system-state.md │◀───── IStateView Interface Parsing β”‚ +β”‚ β”‚ (READ ONLY) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ HOOK DEVELOPER UPLOADS β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ HookSpec.md β”‚ ─── Contains: hook state vars + system funcs β”‚ β”‚ +β”‚ β”‚ β”‚ (or .tex/.pdf) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ VALIDATION SERVICE β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ 1. Parse HookSpec document β”‚ β”‚ +β”‚ β”‚ 2. Extract declared state variables β”‚ β”‚ +β”‚ β”‚ 3. Verify all referenced pool vars exist in system-state.md β”‚ β”‚ +β”‚ β”‚ 4. Validate function signatures reference valid state β”‚ β”‚ +β”‚ β”‚ 5. Check mathematical notation compliance β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ ACCEPT βœ“ β”‚ β”‚ REJECT βœ— β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (compliant)β”‚ β”‚ (invalid) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ IPFS UPLOAD SERVICE β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ 1. Pin document to IPFS β”‚ β”‚ +β”‚ β”‚ 2. Generate CID (content-addressed hash) β”‚ β”‚ +β”‚ β”‚ 3. Associate CID with uploader address β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ Output: ipfs://Qm... or ipfs://bafy... β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ HOOKLICENSE NFT MINTING β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ tokenURI = IPFS CID β”‚ β”‚ +β”‚ β”‚ owner = uploader (hook developer) β”‚ β”‚ +β”‚ β”‚ metadata = { name, description, specVersion, ... } β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Component Decomposition + +### 2.1 Component Overview + +| ID | Component | Type | Priority | Dependencies | +|----|-----------|------|----------|--------------| +| C1 | System State Document | Documentation | P0 | IStateView interface | +| C2 | HookSpec Schema | Schema/Spec | P0 | C1 | +| C3 | Validation Service | Backend Service | P1 | C1, C2 | +| C4 | IPFS Integration | Backend Service | P1 | C3 | +| C5 | HookLicense NFT | Smart Contract | P1 | C4 | +| C6 | Platform Frontend | Web App | P2 | C3, C4, C5 | + +--- + +## 3. C1: System State Document (`system-state.md`) + +### 3.1 Purpose + +A **canonical, read-only document** that defines all pool state variables available for hooks to reference. Derived directly from parsing the `IStateView` interface. + +### 3.2 TODO Tasks + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ C1: SYSTEM STATE DOCUMENT β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β–‘ C1.1 Parse IStateView Interface β”‚ +β”‚ β”œβ”€β”€ Read contracts/lib/v4-periphery/src/interfaces/IStateView.sol β”‚ +β”‚ β”œβ”€β”€ Extract all function signatures β”‚ +β”‚ β”œβ”€β”€ Map return types to state variable definitions β”‚ +β”‚ └── Output: structured JSON of state variables β”‚ +β”‚ β”‚ +β”‚ β–‘ C1.2 Generate system-state.md Document β”‚ +β”‚ β”œβ”€β”€ Create markdown template with sections: β”‚ +β”‚ β”‚ β”œβ”€β”€ Pool Configuration Variables β”‚ +β”‚ β”‚ β”œβ”€β”€ LP Index Variables (positions, ticks) β”‚ +β”‚ β”‚ β”œβ”€β”€ Trader Index Variables (slot0, liquidity) β”‚ +β”‚ β”‚ └── Shared Variables (fee growth) β”‚ +β”‚ β”œβ”€β”€ Include mathematical notation for each variable β”‚ +β”‚ β”œβ”€β”€ Include Solidity type for each variable β”‚ +β”‚ └── Include IStateView getter mapping β”‚ +β”‚ β”‚ +β”‚ β–‘ C1.3 Version Control & Immutability β”‚ +β”‚ β”œβ”€β”€ Pin system-state.md to IPFS β”‚ +β”‚ β”œβ”€β”€ Store IPFS CID in platform contract β”‚ +β”‚ └── Document versioning strategy for V4 upgrades β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 3.3 Output Schema + +```yaml +# system-state.schema.yaml +version: "1.0.0" +uniswap_version: "v4" + +state_indices: + lp_index: + description: "Variables accessed by liquidity providers" + variables: + - name: "position_liquidity" + symbol: "L_k" + type: "uint128" + getter: "getPositionLiquidity(PoolId, bytes32)" + description: "Liquidity amount for a specific position" + + - name: "tick_lower" + symbol: "t_l^k" + type: "int24" + getter: "getPositionInfo(PoolId, bytes32)" + description: "Lower tick bound of position" + + # ... more variables + + trader_index: + description: "Variables accessed by traders during swaps" + variables: + - name: "sqrt_price" + symbol: "√P" + type: "uint160" + getter: "getSlot0(PoolId)" + description: "Current sqrt price in Q64.96 format" + + # ... more variables + + shared: + description: "Variables accessed by both LPs and traders" + variables: + - name: "fee_growth_global_0" + symbol: "f_0^{global}" + type: "uint256" + getter: "getFeeGrowthGlobals(PoolId)" + description: "Cumulative fee growth for token0" + + # ... more variables +``` + +### 3.4 Example system-state.md Output + +```markdown +# System State Variables + +> **Version:** 1.0.0 +> **Uniswap Version:** V4 +> **IPFS CID:** QmXxx... +> **Status:** READ ONLY - Canonical Reference + +--- + +## 1. LP Index Variables ($\mathcal{S}_{LP}$) + +Variables primarily accessed by liquidity providers. + +### 1.1 Position Variables + +| Variable | Symbol | Type | IStateView Getter | +|----------|--------|------|-------------------| +| Position Liquidity | $L_k$ | `uint128` | `getPositionLiquidity(poolId, positionId)` | +| Tick Lower | $t_l^k$ | `int24` | `getPositionInfo(poolId, positionId)` | +| Tick Upper | $t_u^k$ | `int24` | `getPositionInfo(poolId, positionId)` | +| Fee Growth Inside 0 | $f_{0,k}^{in}$ | `uint256` | `getPositionInfo(poolId, positionId)` | +| Fee Growth Inside 1 | $f_{1,k}^{in}$ | `uint256` | `getPositionInfo(poolId, positionId)` | + +### 1.2 Tick Variables + +| Variable | Symbol | Type | IStateView Getter | +|----------|--------|------|-------------------| +| Liquidity Gross | $L_g^{tick}$ | `uint128` | `getTickLiquidity(poolId, tick)` | +| Liquidity Net | $L_n^{tick}$ | `int128` | `getTickLiquidity(poolId, tick)` | +| Fee Growth Outside 0 | $f_0^{out,tick}$ | `uint256` | `getTickFeeGrowthOutside(poolId, tick)` | +| Fee Growth Outside 1 | $f_1^{out,tick}$ | `uint256` | `getTickFeeGrowthOutside(poolId, tick)` | + +--- + +## 2. Trader Index Variables ($\mathcal{S}_T$) + +Variables primarily accessed by traders during swaps. + +| Variable | Symbol | Type | IStateView Getter | +|----------|--------|------|-------------------| +| Sqrt Price | $\sqrt{P}$ | `uint160` | `getSlot0(poolId)` | +| Current Tick | $t_c$ | `int24` | `getSlot0(poolId)` | +| LP Fee | $\phi_{lp}$ | `uint24` | `getSlot0(poolId)` | +| Protocol Fee | $\phi_{proto}$ | `uint24` | `getSlot0(poolId)` | +| Active Liquidity | $L_{act}$ | `uint128` | `getLiquidity(poolId)` | +| Tick Bitmap | $B_{tick}$ | `uint256` | `getTickBitmap(poolId, wordPos)` | + +--- + +## 3. Shared Variables ($\mathcal{S}_{shared}$) + +Variables accessed by both LPs and traders. + +| Variable | Symbol | Type | IStateView Getter | +|----------|--------|------|-------------------| +| Fee Growth Global 0 | $f_0^{global}$ | `uint256` | `getFeeGrowthGlobals(poolId)` | +| Fee Growth Global 1 | $f_1^{global}$ | `uint256` | `getFeeGrowthGlobals(poolId)` | + +--- + +## 4. Usage in HookSpec Documents + +When writing a HookSpec, you MUST reference state variables using: +- The **Symbol** (e.g., $L_k$) for mathematical equations +- The **Variable Name** (e.g., `position_liquidity`) for schema declarations + +Example: +```yaml +hook_state: + - name: "accumulated_fees" + symbol: "F_{acc}" + type: "uint256" + +system_functions: + - callback: "afterSwap" + reads: ["sqrt_price", "active_liquidity"] + writes: ["accumulated_fees"] + equation: "F_{acc}' = F_{acc} + \phi_{lp} \cdot \Delta" +``` +``` + +--- + +## 4. C2: HookSpec Schema + +### 4.1 Purpose + +Define the **schema and validation rules** for HookSpec documents that developers upload. + +### 4.2 TODO Tasks + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ C2: HOOKSPEC SCHEMA β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β–‘ C2.1 Define HookSpec JSON Schema β”‚ +β”‚ β”œβ”€β”€ Required sections: β”‚ +β”‚ β”‚ β”œβ”€β”€ metadata (name, version, author, description) β”‚ +β”‚ β”‚ β”œβ”€β”€ hook_state (custom state variables) β”‚ +β”‚ β”‚ β”œβ”€β”€ system_functions (callback specifications) β”‚ +β”‚ β”‚ └── invariants (constraints that must hold) β”‚ +β”‚ β”œβ”€β”€ Optional sections: β”‚ +β”‚ β”‚ β”œβ”€β”€ examples (usage examples) β”‚ +β”‚ β”‚ └── references (citations, related work) β”‚ +β”‚ └── Output: hookspec.schema.json β”‚ +β”‚ β”‚ +β”‚ β–‘ C2.2 Define Validation Rules β”‚ +β”‚ β”œβ”€β”€ Rule V1: All referenced pool vars MUST exist in system-state.md β”‚ +β”‚ β”œβ”€β”€ Rule V2: Hook state vars MUST have unique names β”‚ +β”‚ β”œβ”€β”€ Rule V3: System functions MUST map to valid callbacks β”‚ +β”‚ β”œβ”€β”€ Rule V4: Equations MUST use valid symbols from state defs β”‚ +β”‚ β”œβ”€β”€ Rule V5: Types MUST be valid Solidity types β”‚ +β”‚ └── Output: validation-rules.md β”‚ +β”‚ β”‚ +β”‚ β–‘ C2.3 Support Multiple Formats β”‚ +β”‚ β”œβ”€β”€ Primary: YAML/JSON (machine-readable) β”‚ +β”‚ β”œβ”€β”€ Secondary: Markdown with YAML frontmatter β”‚ +β”‚ β”œβ”€β”€ Tertiary: LaTeX with structured comments β”‚ +β”‚ └── Define format detection and parsing strategy β”‚ +β”‚ β”‚ +β”‚ β–‘ C2.4 Create Example HookSpecs β”‚ +β”‚ β”œβ”€β”€ Example 1: Simple fee accumulator hook β”‚ +β”‚ β”œβ”€β”€ Example 2: TWAP oracle hook β”‚ +β”‚ β”œβ”€β”€ Example 3: Dynamic fee hook β”‚ +β”‚ └── Example 4: Liquidity mining hook β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 4.3 HookSpec Schema Definition + +```json +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://hookbazaar.io/schemas/hookspec/v1.0.0", + "title": "HookSpec", + "description": "Schema for Hook Specification documents", + "type": "object", + "required": ["metadata", "hook_state", "system_functions"], + "properties": { + "metadata": { + "type": "object", + "required": ["name", "version", "author"], + "properties": { + "name": { + "type": "string", + "description": "Human-readable hook name", + "pattern": "^[a-zA-Z][a-zA-Z0-9_-]{2,63}$" + }, + "version": { + "type": "string", + "pattern": "^\\d+\\.\\d+\\.\\d+$" + }, + "author": { + "type": "string", + "description": "Ethereum address or ENS name" + }, + "description": { + "type": "string", + "maxLength": 1000 + }, + "license": { + "type": "string", + "enum": ["MIT", "GPL-3.0", "BUSL-1.1", "PROPRIETARY"] + }, + "system_state_version": { + "type": "string", + "description": "IPFS CID of system-state.md this spec targets" + } + } + }, + "hook_state": { + "type": "array", + "description": "Custom state variables maintained by the hook", + "items": { + "$ref": "#/definitions/StateVariable" + } + }, + "system_functions": { + "type": "array", + "description": "Callback specifications", + "items": { + "$ref": "#/definitions/SystemFunction" + } + }, + "invariants": { + "type": "array", + "description": "Constraints that must always hold", + "items": { + "$ref": "#/definitions/Invariant" + } + } + }, + "definitions": { + "StateVariable": { + "type": "object", + "required": ["name", "symbol", "type"], + "properties": { + "name": { + "type": "string", + "pattern": "^[a-z][a-z0-9_]*$" + }, + "symbol": { + "type": "string", + "description": "LaTeX symbol (e.g., 'F_{acc}')" + }, + "type": { + "type": "string", + "enum": ["uint8", "uint16", "uint24", "uint32", "uint64", "uint128", "uint256", + "int8", "int16", "int24", "int32", "int64", "int128", "int256", + "address", "bool", "bytes32"] + }, + "description": { + "type": "string" + }, + "initial_value": { + "type": "string", + "description": "Initial value expression" + } + } + }, + "SystemFunction": { + "type": "object", + "required": ["callback", "reads", "writes", "transition"], + "properties": { + "callback": { + "type": "string", + "enum": ["beforeInitialize", "afterInitialize", + "beforeAddLiquidity", "afterAddLiquidity", + "beforeRemoveLiquidity", "afterRemoveLiquidity", + "beforeSwap", "afterSwap", + "beforeDonate", "afterDonate"] + }, + "reads": { + "type": "array", + "description": "Pool state variables read (from system-state.md)", + "items": { "type": "string" } + }, + "writes": { + "type": "array", + "description": "Hook state variables modified", + "items": { "type": "string" } + }, + "transition": { + "type": "object", + "description": "State transition specification", + "properties": { + "preconditions": { + "type": "array", + "items": { "type": "string" } + }, + "equation": { + "type": "string", + "description": "LaTeX equation: H' = f(H, P)" + }, + "postconditions": { + "type": "array", + "items": { "type": "string" } + }, + "delta_returns": { + "type": "object", + "description": "BalanceDelta modifications", + "properties": { + "amount0": { "type": "string" }, + "amount1": { "type": "string" } + } + } + } + } + } + }, + "Invariant": { + "type": "object", + "required": ["name", "expression"], + "properties": { + "name": { + "type": "string" + }, + "expression": { + "type": "string", + "description": "LaTeX boolean expression" + }, + "description": { + "type": "string" + } + } + } + } +} +``` + +### 4.4 Example HookSpec Document + +```yaml +# HookSpec: Fee Accumulator +# Format: YAML with embedded LaTeX + +metadata: + name: "FeeAccumulatorHook" + version: "1.0.0" + author: "0x1234...abcd" + description: "Accumulates swap fees for later distribution" + license: "MIT" + system_state_version: "QmSystemStateV1..." + +hook_state: + - name: "accumulated_fees_0" + symbol: "F_0" + type: "uint256" + description: "Accumulated fees for token0" + initial_value: "0" + + - name: "accumulated_fees_1" + symbol: "F_1" + type: "uint256" + description: "Accumulated fees for token1" + initial_value: "0" + + - name: "last_distribution_block" + symbol: "b_{dist}" + type: "uint256" + description: "Block number of last fee distribution" + initial_value: "block.number" + +system_functions: + - callback: "afterSwap" + reads: + - "sqrt_price" # √P from trader index + - "active_liquidity" # L_act from trader index + - "lp_fee" # Ο†_lp from trader index + writes: + - "accumulated_fees_0" + - "accumulated_fees_1" + transition: + preconditions: + - "swapDelta.amount0 != 0 OR swapDelta.amount1 != 0" + equation: | + F_0' = F_0 + |Ξ”_0| \cdot \phi_{lp} + F_1' = F_1 + |Ξ”_1| \cdot \phi_{lp} + postconditions: + - "F_0' >= F_0" + - "F_1' >= F_1" + delta_returns: + amount0: "0" + amount1: "0" + +invariants: + - name: "fees_non_negative" + expression: "F_0 \\geq 0 \\land F_1 \\geq 0" + description: "Accumulated fees cannot be negative" + + - name: "monotonic_accumulation" + expression: "F_0' \\geq F_0 \\land F_1' \\geq F_1" + description: "Fees only increase (within same epoch)" +``` + +--- + +## 5. C3: Validation Service + +### 5.1 Purpose + +Backend service that **validates HookSpec documents** against the system state schema. + +### 5.2 TODO Tasks + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ C3: VALIDATION SERVICE β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β–‘ C3.1 Document Parser β”‚ +β”‚ β”œβ”€β”€ Implement YAML parser with schema validation β”‚ +β”‚ β”œβ”€β”€ Implement Markdown+frontmatter parser β”‚ +β”‚ β”œβ”€β”€ Implement LaTeX parser (extract structured data) β”‚ +β”‚ β”œβ”€β”€ Auto-detect format from file extension/content β”‚ +β”‚ └── Output: Normalized HookSpec object β”‚ +β”‚ β”‚ +β”‚ β–‘ C3.2 State Variable Validator β”‚ +β”‚ β”œβ”€β”€ Load system-state.md (from IPFS or local cache) β”‚ +β”‚ β”œβ”€β”€ Build lookup table of valid state variables β”‚ +β”‚ β”œβ”€β”€ Validate all `reads` reference valid system variables β”‚ +β”‚ β”œβ”€β”€ Validate all `writes` reference declared hook_state β”‚ +β”‚ └── Output: ValidationResult with errors/warnings β”‚ +β”‚ β”‚ +β”‚ β–‘ C3.3 Equation Validator β”‚ +β”‚ β”œβ”€β”€ Parse LaTeX equations β”‚ +β”‚ β”œβ”€β”€ Extract symbols used in equations β”‚ +β”‚ β”œβ”€β”€ Verify all symbols are declared (hook_state or system state) β”‚ +β”‚ β”œβ”€β”€ Check equation syntax validity β”‚ +β”‚ └── Output: EquationValidationResult β”‚ +β”‚ β”‚ +β”‚ β–‘ C3.4 Callback Validator β”‚ +β”‚ β”œβ”€β”€ Verify callbacks are valid Uniswap V4 hook callbacks β”‚ +β”‚ β”œβ”€β”€ Verify state access patterns match callback semantics β”‚ +β”‚ β”‚ β”œβ”€β”€ beforeSwap: can read trader state, cannot modify pool β”‚ +β”‚ β”‚ β”œβ”€β”€ afterSwap: can read/modify, can return delta β”‚ +β”‚ β”‚ └── ... (define for each callback) β”‚ +β”‚ └── Output: CallbackValidationResult β”‚ +β”‚ β”‚ +β”‚ β–‘ C3.5 Invariant Validator β”‚ +β”‚ β”œβ”€β”€ Parse invariant expressions β”‚ +β”‚ β”œβ”€β”€ Verify symbols are valid β”‚ +β”‚ β”œβ”€β”€ Check logical consistency (no contradictions) β”‚ +β”‚ └── Output: InvariantValidationResult β”‚ +β”‚ β”‚ +β”‚ β–‘ C3.6 API Endpoints β”‚ +β”‚ β”œβ”€β”€ POST /validate - Upload and validate HookSpec β”‚ +β”‚ β”œβ”€β”€ GET /system-state - Retrieve current system-state.md β”‚ +β”‚ β”œβ”€β”€ GET /schema - Retrieve HookSpec JSON schema β”‚ +β”‚ └── GET /examples - Retrieve example HookSpecs β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 5.3 Validation Rules Specification + +```typescript +// validation-rules.ts + +interface ValidationRule { + id: string; + name: string; + severity: 'error' | 'warning'; + validate: (spec: HookSpec, systemState: SystemState) => ValidationResult; +} + +const VALIDATION_RULES: ValidationRule[] = [ + { + id: 'V1', + name: 'ValidPoolStateReferences', + severity: 'error', + validate: (spec, systemState) => { + // All referenced pool vars MUST exist in system-state.md + const invalidRefs: string[] = []; + for (const func of spec.system_functions) { + for (const readVar of func.reads) { + if (!systemState.hasVariable(readVar)) { + invalidRefs.push(`${func.callback}.reads: '${readVar}'`); + } + } + } + return { + valid: invalidRefs.length === 0, + errors: invalidRefs.map(ref => `Invalid state reference: ${ref}`) + }; + } + }, + { + id: 'V2', + name: 'UniqueHookStateNames', + severity: 'error', + validate: (spec, _) => { + // Hook state vars MUST have unique names + const names = spec.hook_state.map(v => v.name); + const duplicates = names.filter((n, i) => names.indexOf(n) !== i); + return { + valid: duplicates.length === 0, + errors: duplicates.map(d => `Duplicate hook state variable: '${d}'`) + }; + } + }, + { + id: 'V3', + name: 'ValidCallbacks', + severity: 'error', + validate: (spec, _) => { + // System functions MUST map to valid callbacks + const validCallbacks = [ + 'beforeInitialize', 'afterInitialize', + 'beforeAddLiquidity', 'afterAddLiquidity', + 'beforeRemoveLiquidity', 'afterRemoveLiquidity', + 'beforeSwap', 'afterSwap', + 'beforeDonate', 'afterDonate' + ]; + const invalidCallbacks = spec.system_functions + .filter(f => !validCallbacks.includes(f.callback)) + .map(f => f.callback); + return { + valid: invalidCallbacks.length === 0, + errors: invalidCallbacks.map(c => `Invalid callback: '${c}'`) + }; + } + }, + { + id: 'V4', + name: 'ValidEquationSymbols', + severity: 'error', + validate: (spec, systemState) => { + // Equations MUST use valid symbols from state defs + const validSymbols = new Set([ + ...spec.hook_state.map(v => v.symbol), + ...systemState.getAllSymbols() + ]); + const errors: string[] = []; + for (const func of spec.system_functions) { + const usedSymbols = extractLatexSymbols(func.transition.equation); + for (const sym of usedSymbols) { + if (!validSymbols.has(sym)) { + errors.push(`Unknown symbol '${sym}' in ${func.callback} equation`); + } + } + } + return { valid: errors.length === 0, errors }; + } + }, + { + id: 'V5', + name: 'ValidSolidityTypes', + severity: 'error', + validate: (spec, _) => { + // Types MUST be valid Solidity types + const validTypes = [ + 'uint8', 'uint16', 'uint24', 'uint32', 'uint64', 'uint128', 'uint256', + 'int8', 'int16', 'int24', 'int32', 'int64', 'int128', 'int256', + 'address', 'bool', 'bytes32' + ]; + const invalidTypes = spec.hook_state + .filter(v => !validTypes.includes(v.type)) + .map(v => `${v.name}: ${v.type}`); + return { + valid: invalidTypes.length === 0, + errors: invalidTypes.map(t => `Invalid Solidity type: ${t}`) + }; + } + }, + { + id: 'V6', + name: 'WritesMatchHookState', + severity: 'error', + validate: (spec, _) => { + // All writes MUST reference declared hook_state variables + const hookStateNames = new Set(spec.hook_state.map(v => v.name)); + const errors: string[] = []; + for (const func of spec.system_functions) { + for (const writeVar of func.writes) { + if (!hookStateNames.has(writeVar)) { + errors.push(`${func.callback} writes undeclared variable: '${writeVar}'`); + } + } + } + return { valid: errors.length === 0, errors }; + } + } +]; +``` + +--- + +## 6. C4: IPFS Integration + +### 6.1 Purpose + +Service to **pin validated HookSpecs to IPFS** and generate content-addressed URIs. + +### 6.2 TODO Tasks + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ C4: IPFS INTEGRATION β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β–‘ C4.1 IPFS Client Setup β”‚ +β”‚ β”œβ”€β”€ Choose IPFS provider (Pinata, Infura, web3.storage, self-hosted) β”‚ +β”‚ β”œβ”€β”€ Implement upload/pin functionality β”‚ +β”‚ β”œβ”€β”€ Implement retrieval functionality β”‚ +β”‚ └── Handle CID v0 vs v1 format β”‚ +β”‚ β”‚ +β”‚ β–‘ C4.2 Document Packaging β”‚ +β”‚ β”œβ”€β”€ Normalize document format before pinning β”‚ +β”‚ β”œβ”€β”€ Add metadata wrapper with timestamp, uploader, version β”‚ +β”‚ β”œβ”€β”€ Generate deterministic CID (same content = same CID) β”‚ +β”‚ └── Support both raw content and directory structures β”‚ +β”‚ β”‚ +β”‚ β–‘ C4.3 Upload Registry β”‚ +β”‚ β”œβ”€β”€ Store mapping: uploader_address => [CID, CID, ...] β”‚ +β”‚ β”œβ”€β”€ Store mapping: CID => { uploader, timestamp, status } β”‚ +β”‚ β”œβ”€β”€ Implement duplicate detection β”‚ +β”‚ └── Support revocation/deprecation marking β”‚ +β”‚ β”‚ +β”‚ β–‘ C4.4 Gateway & Retrieval β”‚ +β”‚ β”œβ”€β”€ Configure IPFS gateway URLs β”‚ +β”‚ β”œβ”€β”€ Implement fallback to multiple gateways β”‚ +β”‚ β”œβ”€β”€ Cache frequently accessed documents β”‚ +β”‚ └── Verify content hash on retrieval β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 6.3 IPFS Service Interface + +```typescript +// ipfs-service.ts + +interface IPFSService { + /** + * Pin a validated HookSpec document to IPFS + * @param document - The validated HookSpec content + * @param uploader - Ethereum address of uploader + * @returns CID and full IPFS URI + */ + pinDocument(document: HookSpec, uploader: string): Promise<{ + cid: string; + uri: string; // ipfs://Qm... or ipfs://bafy... + timestamp: number; + }>; + + /** + * Retrieve a HookSpec document by CID + */ + getDocument(cid: string): Promise; + + /** + * Check if a CID exists and is pinned + */ + isPinned(cid: string): Promise; + + /** + * Get all CIDs uploaded by an address + */ + getUploaderDocuments(uploader: string): Promise; +} + +// Document wrapper for IPFS storage +interface IPFSHookSpecWrapper { + schema_version: "1.0.0"; + content_type: "hookspec"; + uploader: string; // Ethereum address + uploaded_at: number; // Unix timestamp + signature?: string; // Optional EIP-712 signature + content: HookSpec; // The actual spec +} +``` + +--- + +## 7. C5: HookLicense NFT Contract + +### 7.1 Purpose + +ERC-721 NFT contract that **represents ownership of a HookSpec**, with `tokenURI` pointing to IPFS. + +### 7.2 TODO Tasks + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ C5: HOOKLICENSE NFT CONTRACT β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β–‘ C5.1 Contract Design β”‚ +β”‚ β”œβ”€β”€ Inherit ERC721 + ERC721URIStorage β”‚ +β”‚ β”œβ”€β”€ Add minting function (callable by platform only) β”‚ +β”‚ β”œβ”€β”€ Store IPFS URI as tokenURI β”‚ +β”‚ β”œβ”€β”€ Add on-chain metadata (name, version, author) β”‚ +β”‚ └── Consider ERC-2981 royalty standard β”‚ +β”‚ β”‚ +β”‚ β–‘ C5.2 Access Control β”‚ +β”‚ β”œβ”€β”€ Only validated specs can mint β”‚ +β”‚ β”œβ”€β”€ Platform address has MINTER_ROLE β”‚ +β”‚ β”œβ”€β”€ Developer (uploader) receives minted NFT β”‚ +β”‚ └── Add pause functionality for emergencies β”‚ +β”‚ β”‚ +β”‚ β–‘ C5.3 Metadata Standard β”‚ +β”‚ β”œβ”€β”€ Define on-chain vs off-chain metadata split β”‚ +β”‚ β”œβ”€β”€ Implement tokenURI returning IPFS gateway URL β”‚ +β”‚ β”œβ”€β”€ Support ERC-721 Metadata JSON schema β”‚ +β”‚ └── Include hook-specific attributes β”‚ +β”‚ β”‚ +β”‚ β–‘ C5.4 Events & Indexing β”‚ +β”‚ β”œβ”€β”€ HookSpecRegistered(tokenId, cid, developer) β”‚ +β”‚ β”œβ”€β”€ HookSpecDeprecated(tokenId, reason) β”‚ +β”‚ β”œβ”€β”€ Design subgraph schema for indexing β”‚ +β”‚ └── Support querying by developer, CID, etc. β”‚ +β”‚ β”‚ +β”‚ β–‘ C5.5 Integration Points β”‚ +β”‚ β”œβ”€β”€ Link to HookImplementation registry (future) β”‚ +β”‚ β”œβ”€β”€ Link to AVS attestation system (future) β”‚ +β”‚ └── Support royalty distribution on hook usage β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 7.3 Contract Interface + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.24; + +import {ERC721} from "@openzeppelin/contracts/token/ERC721/ERC721.sol"; +import {ERC721URIStorage} from "@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol"; +import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol"; +import {ERC2981} from "@openzeppelin/contracts/token/common/ERC2981.sol"; + +/// @title HookLicense +/// @notice ERC-721 NFT representing ownership of a validated HookSpec +/// @dev tokenURI points to IPFS CID of the HookSpec document +contract HookLicense is ERC721, ERC721URIStorage, ERC2981, AccessControl { + + bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE"); + + /// @notice Counter for token IDs + uint256 private _nextTokenId; + + /// @notice Mapping from IPFS CID to token ID + mapping(string => uint256) public cidToTokenId; + + /// @notice Mapping from token ID to on-chain metadata + mapping(uint256 => HookMetadata) public hookMetadata; + + /// @notice On-chain metadata for a HookSpec + struct HookMetadata { + string name; + string version; + address developer; + uint256 registeredAt; + bool deprecated; + } + + /// @notice Emitted when a new HookSpec is registered + event HookSpecRegistered( + uint256 indexed tokenId, + string indexed cid, + address indexed developer, + string name, + string version + ); + + /// @notice Emitted when a HookSpec is deprecated + event HookSpecDeprecated( + uint256 indexed tokenId, + string reason + ); + + constructor() ERC721("HookLicense", "HOOK") { + _grantRole(DEFAULT_ADMIN_ROLE, msg.sender); + _grantRole(MINTER_ROLE, msg.sender); + } + + /// @notice Mint a new HookLicense NFT for a validated spec + /// @param developer Address of the hook developer (receives NFT) + /// @param ipfsCid IPFS CID of the validated HookSpec document + /// @param name Human-readable name of the hook + /// @param version Semantic version of the spec + /// @param royaltyBps Royalty percentage in basis points (e.g., 500 = 5%) + /// @return tokenId The minted token ID + function mint( + address developer, + string calldata ipfsCid, + string calldata name, + string calldata version, + uint96 royaltyBps + ) external onlyRole(MINTER_ROLE) returns (uint256 tokenId) { + require(cidToTokenId[ipfsCid] == 0, "CID already registered"); + require(bytes(ipfsCid).length > 0, "Empty CID"); + require(developer != address(0), "Zero address developer"); + + tokenId = ++_nextTokenId; + + _safeMint(developer, tokenId); + _setTokenURI(tokenId, string(abi.encodePacked("ipfs://", ipfsCid))); + + cidToTokenId[ipfsCid] = tokenId; + hookMetadata[tokenId] = HookMetadata({ + name: name, + version: version, + developer: developer, + registeredAt: block.timestamp, + deprecated: false + }); + + // Set royalty for this token + if (royaltyBps > 0) { + _setTokenRoyalty(tokenId, developer, royaltyBps); + } + + emit HookSpecRegistered(tokenId, ipfsCid, developer, name, version); + } + + /// @notice Mark a HookSpec as deprecated + /// @param tokenId Token ID to deprecate + /// @param reason Reason for deprecation + function deprecate(uint256 tokenId, string calldata reason) external { + require( + ownerOf(tokenId) == msg.sender || hasRole(DEFAULT_ADMIN_ROLE, msg.sender), + "Not authorized" + ); + hookMetadata[tokenId].deprecated = true; + emit HookSpecDeprecated(tokenId, reason); + } + + /// @notice Get token ID by IPFS CID + function getTokenByCid(string calldata cid) external view returns (uint256) { + uint256 tokenId = cidToTokenId[cid]; + require(tokenId != 0, "CID not registered"); + return tokenId; + } + + /// @notice Check if a CID is registered + function isRegistered(string calldata cid) external view returns (bool) { + return cidToTokenId[cid] != 0; + } + + // Required overrides + function tokenURI(uint256 tokenId) + public + view + override(ERC721, ERC721URIStorage) + returns (string memory) + { + return super.tokenURI(tokenId); + } + + function supportsInterface(bytes4 interfaceId) + public + view + override(ERC721, ERC721URIStorage, ERC2981, AccessControl) + returns (bool) + { + return super.supportsInterface(interfaceId); + } +} +``` + +--- + +## 8. C6: Platform Frontend + +### 8.1 Purpose + +Web application for developers to **view system state, upload specs, and manage licenses**. + +### 8.2 TODO Tasks + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ C6: PLATFORM FRONTEND β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β–‘ C6.1 System State Viewer (READ ONLY) β”‚ +β”‚ β”œβ”€β”€ Display system-state.md in formatted view β”‚ +β”‚ β”œβ”€β”€ Searchable table of state variables β”‚ +β”‚ β”œβ”€β”€ Copy-to-clipboard for symbols and types β”‚ +β”‚ β”œβ”€β”€ Show IPFS CID and version info β”‚ +β”‚ └── Link to IStateView source code β”‚ +β”‚ β”‚ +β”‚ β–‘ C6.2 HookSpec Upload Flow β”‚ +β”‚ β”œβ”€β”€ File upload (YAML, MD, LaTeX, JSON) β”‚ +β”‚ β”œβ”€β”€ Live validation feedback β”‚ +β”‚ β”œβ”€β”€ Error highlighting with fix suggestions β”‚ +β”‚ β”œβ”€β”€ Preview rendered spec before submission β”‚ +β”‚ └── Wallet connection for authentication β”‚ +β”‚ β”‚ +β”‚ β–‘ C6.3 Validation Results UI β”‚ +β”‚ β”œβ”€β”€ Show pass/fail for each validation rule β”‚ +β”‚ β”œβ”€β”€ Display detailed error messages β”‚ +β”‚ β”œβ”€β”€ Link errors to relevant spec sections β”‚ +β”‚ └── Suggest corrections where possible β”‚ +β”‚ β”‚ +β”‚ β–‘ C6.4 IPFS & NFT Minting Flow β”‚ +β”‚ β”œβ”€β”€ Show IPFS upload progress β”‚ +β”‚ β”œβ”€β”€ Display generated CID β”‚ +β”‚ β”œβ”€β”€ Trigger NFT mint transaction β”‚ +β”‚ β”œβ”€β”€ Show transaction confirmation β”‚ +β”‚ └── Display minted NFT with OpenSea link β”‚ +β”‚ β”‚ +β”‚ β–‘ C6.5 Developer Dashboard β”‚ +β”‚ β”œβ”€β”€ List all HookLicense NFTs owned β”‚ +β”‚ β”œβ”€β”€ View spec details and IPFS link β”‚ +β”‚ β”œβ”€β”€ Deprecation controls β”‚ +β”‚ └── Analytics (views, attestations, deployments) β”‚ +β”‚ β”‚ +β”‚ β–‘ C6.6 HookSpec Editor (Optional) β”‚ +β”‚ β”œβ”€β”€ In-browser YAML/Markdown editor β”‚ +β”‚ β”œβ”€β”€ Syntax highlighting for LaTeX equations β”‚ +β”‚ β”œβ”€β”€ Auto-complete for state variable names β”‚ +β”‚ └── Real-time validation as you type β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 9. Implementation Priority & Dependencies + +### 9.1 Dependency Graph + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ IMPLEMENTATION DEPENDENCY GRAPH β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ C1: System State β”‚ β”‚ +β”‚ β”‚ (system-state.md) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ C2: HookSpec Schema β”‚ β”‚ +β”‚ β”‚ (hookspec.schema) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ C3: Validation β”‚ β”‚ C4: IPFS β”‚ β”‚ C5: HookLicense β”‚ β”‚ +β”‚ β”‚ Service β”‚ β”‚ Integration β”‚ β”‚ NFT Contract β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ C6: Platform β”‚ β”‚ +β”‚ β”‚ Frontend β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 9.2 Implementation Phases + +| Phase | Components | Deliverables | Duration | +|-------|------------|--------------|----------| +| **Phase 1** | C1, C2 | system-state.md, hookspec.schema.json | - | +| **Phase 2** | C3, C4 | Validation API, IPFS service | - | +| **Phase 3** | C5 | HookLicense.sol deployed | - | +| **Phase 4** | C6 | MVP frontend | - | + +### 9.3 Master TODO Checklist + +``` +PHASE 1: FOUNDATION +β”œβ”€β”€ β–‘ C1.1 Parse IStateView interface +β”œβ”€β”€ β–‘ C1.2 Generate system-state.md +β”œβ”€β”€ β–‘ C1.3 Pin to IPFS and version +β”œβ”€β”€ β–‘ C2.1 Define HookSpec JSON schema +β”œβ”€β”€ β–‘ C2.2 Define validation rules +β”œβ”€β”€ β–‘ C2.3 Support multiple formats +└── β–‘ C2.4 Create example HookSpecs + +PHASE 2: SERVICES +β”œβ”€β”€ β–‘ C3.1 Document parser +β”œβ”€β”€ β–‘ C3.2 State variable validator +β”œβ”€β”€ β–‘ C3.3 Equation validator +β”œβ”€β”€ β–‘ C3.4 Callback validator +β”œβ”€β”€ β–‘ C3.5 Invariant validator +β”œβ”€β”€ β–‘ C3.6 API endpoints +β”œβ”€β”€ β–‘ C4.1 IPFS client setup +β”œβ”€β”€ β–‘ C4.2 Document packaging +β”œβ”€β”€ β–‘ C4.3 Upload registry +└── β–‘ C4.4 Gateway & retrieval + +PHASE 3: CONTRACT +β”œβ”€β”€ β–‘ C5.1 Contract design +β”œβ”€β”€ β–‘ C5.2 Access control +β”œβ”€β”€ β–‘ C5.3 Metadata standard +β”œβ”€β”€ β–‘ C5.4 Events & indexing +└── β–‘ C5.5 Integration points + +PHASE 4: FRONTEND +β”œβ”€β”€ β–‘ C6.1 System state viewer +β”œβ”€β”€ β–‘ C6.2 HookSpec upload flow +β”œβ”€β”€ β–‘ C6.3 Validation results UI +β”œβ”€β”€ β–‘ C6.4 IPFS & NFT minting flow +β”œβ”€β”€ β–‘ C6.5 Developer dashboard +└── β–‘ C6.6 HookSpec editor (optional) +``` + +--- + +## 10. References + +- [State-Space Model](../mathematical-models/state-space-model.md) +- [System Overview](./system-overview.md) +- [Mission Statement](./mission-statement.md) +- [IStateView Interface](https://github.com/Uniswap/v4-periphery/blob/main/src/interfaces/IStateView.sol) +- [ERC-721 Standard](https://eips.ethereum.org/EIPS/eip-721) +- [ERC-2981 Royalty Standard](https://eips.ethereum.org/EIPS/eip-2981) +- [IPFS Documentation](https://docs.ipfs.tech/) diff --git a/docs/hook-pkg/architecture/mission-statement.md b/docs/hook-pkg/architecture/mission-statement.md new file mode 100644 index 000000000..ce74ee28b --- /dev/null +++ b/docs/hook-pkg/architecture/mission-statement.md @@ -0,0 +1,289 @@ +# Hook Bazaar: Mission Statement + +> **Document Type:** Strategic Foundation +> **Last Updated:** 2025-12-09 +> **Related:** [Goal Tree](./goal-tree.md) | [Function Refinement Tree](./function-refinement-tree.md) + +--- + +## 1. Mission + +**To create a trustless marketplace where Uniswap V4 hook developers can monetize mathematically-specified implementations while protecting their intellectual property, and where integrators can deploy verified hooks with cryptoeconomic guarantees.** + +--- + +## 2. Vision + +A future where: + +- **Hook development** becomes a sustainable business model for DeFi innovators +- **Hook quality** is mathematically provable, not just auditable +- **Hook discovery** is as simple as browsing an app store +- **Hook trust** is backed by economic stake, not reputation alone + +--- + +## 3. Core Problem Statement + +### 3.1 The Hook Developer's Dilemma + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CURRENT STATE (PROBLEM) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ Hook Developer creates innovative algorithm β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Deploy on-chain β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ PROBLEM: Code is publicly visible β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ - Anyone can decompile bytecode β”‚ β”‚ +β”‚ β”‚ - Competitors can copy the algorithm β”‚ β”‚ +β”‚ β”‚ - No way to monetize without giving away IP β”‚ β”‚ +β”‚ β”‚ - Audits are expensive and don't guarantee correctness β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 3.2 The Integrator's Dilemma + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ CURRENT STATE (PROBLEM) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ Integrator wants to use a third-party hook β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ PROBLEM: How to trust the hook? β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ - Audits are point-in-time, expensive β”‚ β”‚ +β”‚ β”‚ - No formal specification of expected behavior β”‚ β”‚ +β”‚ β”‚ - "Trust me bro" is the default model β”‚ β”‚ +β”‚ β”‚ - No recourse if hook misbehaves β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 4. Solution Overview + +### 4.1 The Hook Bazaar Model + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DESIRED STATE (SOLUTION) β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ MATHEMATICAL SPECIFICATION β”‚ β”‚ +β”‚ β”‚ - Hook behavior defined as system of equations β”‚ β”‚ +β”‚ β”‚ - State transitions formally specified β”‚ β”‚ +β”‚ β”‚ - Invariants explicitly declared β”‚ β”‚ +β”‚ β”‚ - Stored on IPFS, linked to NFT β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ ENCRYPTED IMPLEMENTATION β”‚ β”‚ +β”‚ β”‚ - Code encrypted via Fhenix CoFHE β”‚ β”‚ +β”‚ β”‚ - Cannot be decompiled or reverse-engineered β”‚ β”‚ +β”‚ β”‚ - IP remains protected on-chain β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CRYPTOECONOMIC VERIFICATION β”‚ β”‚ +β”‚ β”‚ - EigenLayer AVS verifies behavior matches spec β”‚ β”‚ +β”‚ β”‚ - Operators stake collateral on correctness β”‚ β”‚ +β”‚ β”‚ - Slashing for false attestations β”‚ β”‚ +β”‚ β”‚ - No code disclosure required β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ MARKETPLACE ECONOMICS β”‚ β”‚ +β”‚ β”‚ - Developers monetize via licensing/sales β”‚ β”‚ +β”‚ β”‚ - Integrators pay for verified, trusted hooks β”‚ β”‚ +β”‚ β”‚ - NFT represents ownership and royalty rights β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 5. Value Propositions + +### 5.1 For Hook Developers + +| Value | Description | +|-------|-------------| +| **IP Protection** | Code remains encrypted; competitors cannot copy | +| **Monetization** | Sell or license hooks without revealing implementation | +| **Credibility** | Mathematical specification proves design quality | +| **Distribution** | Marketplace provides discoverability and reach | + +### 5.2 For Integrators + +| Value | Description | +|-------|-------------| +| **Trust** | Cryptoeconomic guarantees, not just audits | +| **Transparency** | Read specification to understand exact behavior | +| **Recourse** | Slashing provides economic accountability | +| **Simplicity** | Browse, verify, deploy - no custom audits needed | + +### 5.3 For the Ecosystem + +| Value | Description | +|-------|-------------| +| **Innovation** | Developers can profit from novel algorithms | +| **Standards** | Mathematical specifications become the norm | +| **Composability** | Verified hooks can be safely composed | +| **Security** | Formal methods reduce exploit surface | + +--- + +## 6. Success Metrics + +### 6.1 Quantitative Metrics + +| Metric | Target (Year 1) | Target (Year 3) | +|--------|-----------------|-----------------| +| Hooks Listed | 50 | 500 | +| Hooks Attested | 40 | 400 | +| Active Integrators | 20 | 200 | +| TVL in Pools with Bazaar Hooks | $10M | $1B | +| AVS Operators | 20 | 100 | +| Total Stake (AVS) | $5M | $50M | + +### 6.2 Qualitative Metrics + +- **Developer Satisfaction**: NPS > 50 +- **Specification Quality**: Community review scores +- **Attestation Accuracy**: Challenge success rate < 1% +- **Market Liquidity**: Time-to-first-sale < 7 days + +--- + +## 7. Constraints and Boundaries + +### 7.1 In Scope + +- Uniswap V4 hooks on Ethereum mainnet and L2s +- EigenLayer-based verification +- Fhenix-based code encryption +- NFT-based ownership model +- Mathematical specification framework + +### 7.2 Out of Scope (Initial Release) + +- Hooks for protocols other than Uniswap V4 +- Formal verification (TLA+, Coq proofs) +- Cross-chain hook deployment +- DAO governance of marketplace +- Insurance/coverage products + +### 7.3 Assumptions + +1. Fhenix CoFHE provides sufficient code protection +2. EigenLayer operator set is sufficiently decentralized +3. Integrators will read and understand specifications +4. Mathematical specifications can capture hook behavior adequately +5. Gas costs for encrypted execution are acceptable + +### 7.4 Dependencies + +| Dependency | Risk Level | Mitigation | +|------------|------------|------------| +| Uniswap V4 Launch | Medium | Track V4 development closely | +| Fhenix CoFHE Mainnet | High | Early integration, fallback plans | +| EigenLayer Stability | Medium | Conservative operator requirements | +| IPFS Availability | Low | Multiple pinning services | + +--- + +## 8. Stakeholders + +### 8.1 Primary Stakeholders + +| Stakeholder | Role | Interest | +|-------------|------|----------| +| Hook Developers | Creators | Monetization, IP protection | +| Pool Operators | Buyers | Verified hooks, easy deployment | +| AVS Operators | Validators | Rewards, stake returns | +| Liquidity Providers | End Users | Better pool performance | + +### 8.2 Secondary Stakeholders + +| Stakeholder | Role | Interest | +|-------------|------|----------| +| Uniswap Governance | Platform | Ecosystem growth | +| EigenLayer | Infrastructure | AVS adoption | +| Fhenix | Technology | Use case validation | +| Auditors | Service Providers | Specification review services | + +--- + +## 9. Guiding Principles + +### 9.1 Design Principles + +1. **Specification First**: No implementation without formal spec +2. **Verify, Don't Trust**: Cryptoeconomic guarantees over reputation +3. **Protect Creators**: IP protection is non-negotiable +4. **Empower Users**: Clear specs enable informed decisions +5. **Minimize Trust**: Reduce trusted parties to minimum + +### 9.2 Technical Principles + +1. **Mathematical Rigor**: Use formal notation, cite academic sources +2. **Behavioral Verification**: Verify what code does, not what it is +3. **Economic Security**: Security budget proportional to TVL at risk +4. **Composability**: Hooks should work together safely +5. **Gas Efficiency**: Encrypted execution must remain practical + +--- + +## 10. Strategic Alignment + +### 10.1 Alignment with Uniswap V4 + +- Hooks are the core extensibility primitive of V4 +- Hook Bazaar amplifies the value of the hooks architecture +- Creates sustainable ecosystem for hook innovation + +### 10.2 Alignment with EigenLayer + +- Novel AVS use case: specification verification +- Demonstrates programmable trust beyond simple tasks +- Expands AVS adoption to DeFi primitives + +### 10.3 Alignment with Fhenix + +- Real-world use case for on-chain encryption +- High-value IP protection requirement +- Demonstrates CoFHE in production + +--- + +## 11. Call to Action + +**For Hook Developers:** +> Define your hook's behavior mathematically. Protect your code with encryption. Let the market reward your innovation. + +**For Integrators:** +> Stop trusting code you can't verify. Read specifications, check attestations, deploy with confidence. + +**For the Community:** +> Help us build the standard for trusted, verified DeFi primitives. Review specs, run operators, grow the ecosystem. diff --git a/docs/hook-pkg/architecture/system-overview.md b/docs/hook-pkg/architecture/system-overview.md new file mode 100644 index 000000000..037f16f79 --- /dev/null +++ b/docs/hook-pkg/architecture/system-overview.md @@ -0,0 +1,619 @@ +# Hook Bazaar: Complete System Architecture + +> **Status:** Architecture Specification +> **Last Updated:** 2025-12-09 +> **Related Documents:** +> - [State-Space Model](../mathematical-models/state-space-model.md) +> - [AVS Verification System](./avs-verification-system.md) + +--- + +## 1. Vision + +Hook Bazaar is a **marketplace for verified Uniswap V4 hooks** that enables: + +1. **Hook Developers** to monetize their implementations while protecting intellectual property +2. **Pool Operators** to discover and deploy verified hooks with cryptoeconomic guarantees +3. **The Ecosystem** to grow through composable, trusted hook infrastructure + +--- + +## 2. System Components + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOK BAZAAR ARCHITECTURE β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LAYER 1: SPECIFICATIONS β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Hook β”‚ β”‚ State β”‚ β”‚ Invariant β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Spec β”‚ β”‚ Transition β”‚ β”‚ Definitions β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Markdown) β”‚ β”‚ Equations β”‚ β”‚ (LaTeX) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β–Ό β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ IPFS Storage β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Spec Document) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LAYER 2: IMPLEMENTATION β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ β–Ό β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Solidity │───▢│ Fhenix │───▢│ Encrypted β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Code β”‚ β”‚ CoFHE β”‚ β”‚ Bytecode β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Hook Developer's Local Environment β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β–Ό β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Deployed Hook Contract β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (Code hidden, behavior β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ publicly observable) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LAYER 3: VERIFICATION β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ EigenLayer AVS β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β–Ό β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Service β”‚ β”‚ Task Manager β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Manager │◄──▢│ - createAttestationTask β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ - respondToTask β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ - challengeAttestation β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Operator Network β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β–Ό β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚OP 1 β”‚ β”‚OP 2 β”‚ β”‚OP N β”‚ ... β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚Sample β”‚ β”‚Sample β”‚ β”‚Sample β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚Verify β”‚ β”‚Verify β”‚ β”‚Verify β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚Sign β”‚ β”‚Sign β”‚ β”‚Sign β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β–Ό β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Attestation Registry β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ (On-chain record) β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LAYER 4: MARKETPLACE β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β–Ό β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Hook NFT │◄──▢│ Hook Market │◄──▢│ Protocol β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Registry β”‚ β”‚ (Listings) β”‚ β”‚ Mediator β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β–Ό β–Ό β–Ό β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ MasterHook (Diamond) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Routes callbacks to verified hooks β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Enforces attestation requirements β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Manages hook composition β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ LAYER 5: UNISWAP V4 β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ PoolManager β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Executes swaps, mints, burns β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Invokes hook callbacks β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ - Manages pool state β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 3. Component Specifications + +### 3.1 Specification Layer + +**Purpose:** Define hook behavior mathematically before implementation + +**Components:** + +| Component | Format | Storage | Purpose | +|-----------|--------|---------|---------| +| Hook Specification | Markdown + LaTeX | IPFS | Human-readable behavior description | +| State Variables | JSON Schema | IPFS | Formal state definitions ($H$) | +| Transition Functions | LaTeX equations | IPFS | $f_i(H, P) \rightarrow (H', \Delta)$ | +| Invariants | First-order logic | IPFS | Properties that must always hold | +| Test Vectors | JSON | IPFS | Inputβ†’Output pairs for validation | + +**Interface:** + +```solidity +interface IHookSpecification { + /// @return specURI IPFS CID of complete specification + function specificationURI() external pure returns (string memory specURI); + + /// @return vars Bitmask of state variables accessed + function declareStateReads() external pure returns ( + uint256 lpStateVars, + uint256 traderStateVars, + uint256 sharedStateVars + ); + + /// @return invariantIds Identifiers for declared invariants + function declareInvariants() external pure returns (bytes32[] memory invariantIds); +} +``` + +### 3.2 Implementation Layer + +**Purpose:** Transform specifications into executable code with IP protection + +**Components:** + +| Component | Technology | Purpose | +|-----------|------------|---------| +| Hook Contract | Solidity | Implements specification as executable code | +| Fhenix CoFHE | FHE Encryption | Encrypts bytecode to prevent decompilation | +| IHookStateView | Interface | Exposes hook state for verification | + +**Code Protection Flow:** + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Solidity │────▢│ Compile │────▢│ Bytecode β”‚ +β”‚ Source β”‚ β”‚ (solc) β”‚ β”‚ (clear) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Fhenix CoFHE β”‚ + β”‚ Encrypt β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Encrypted β”‚ + β”‚ Bytecode β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Deploy β”‚ + β”‚ (on-chain) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 3.3 Verification Layer + +**Purpose:** Prove implementation matches specification without code disclosure + +**Reference:** [AVS Verification System](./avs-verification-system.md) + +**Key Contracts:** + +| Contract | Function | +|----------|----------| +| `HookAttestationServiceManager` | EigenLayer AVS registration and operator management | +| `HookAttestationTaskManager` | Task creation, response, and challenge handling | +| `AttestationRegistry` | On-chain record of valid attestations | +| `HookStateSampler` | State sampling utilities for operators | + +**Verification Guarantee:** + +$$ +\text{Attestation} \implies P(\text{spec compliance}) \geq 1 - \epsilon +$$ + +Where $\epsilon$ depends on: +- Sample count +- Operator count +- Stake amount +- Challenge period duration + +### 3.4 Marketplace Layer + +**Purpose:** Enable discovery, trading, and deployment of verified hooks + +**Components:** + +| Contract | Purpose | +|----------|---------| +| `HookNFTRegistry` | ERC-721 tokens representing hook ownership | +| `HookMarket` | Listings, pricing, and purchase mechanics | +| `ProtocolHookMediator` | Interfaces between protocols and hooks | +| `MasterHook` | Diamond-pattern hub routing callbacks | + +**NFT Metadata Schema:** + +```json +{ + "name": "DynamicFeeHook v1.0.0", + "description": "Volatility-responsive fee adjustment hook", + "image": "ipfs://Qm.../preview.png", + "external_url": "https://hookbazaar.xyz/hooks/0x...", + "attributes": [ + { "trait_type": "Callbacks", "value": ["beforeSwap", "afterSwap"] }, + { "trait_type": "Attestation Status", "value": "Verified" }, + { "trait_type": "Attestation Expiry", "value": 1735689600 }, + { "trait_type": "Specification URI", "value": "ipfs://Qm.../spec.md" }, + { "trait_type": "Developer", "value": "0x..." } + ] +} +``` + +### 3.5 Integration Layer (Uniswap V4) + +**Purpose:** Connect verified hooks to Uniswap V4 PoolManager + +**Key Integration Points:** + +| Component | Integration | +|-----------|-------------| +| `PoolManager` | Hook address registered at pool creation | +| `IHooks` | Standard callback interface implementation | +| `StateView` | Exposes pool state for verification sampling | + +--- + +## 4. Data Flow Diagrams + +### 4.1 Hook Registration Flow + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Developer β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 1. Create Specification + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ IPFS │◄─────────────────────────────────────────┐ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β”‚ 2. specificationURI β”‚ + β–Ό β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ Implement β”‚ β”‚ +β”‚ Hook β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β”‚ 3. Encrypt via Fhenix β”‚ + β–Ό β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ Deploy β”‚ β”‚ +β”‚ Contract β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β”‚ 4. hookAddress β”‚ + β–Ό β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ createAttestationTaskβ”‚ β”‚ +β”‚ (hookAddress, specURI)β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ + β”‚ β”‚ + β”‚ 5. Task emitted β”‚ + β–Ό β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” 6. Fetch spec β”‚ +β”‚ AVS Operators │─────────────────────────────────▢│ +β”‚ - Sample state β”‚ +β”‚ - Execute callbacksβ”‚ +β”‚ - Verify behavior β”‚ +β”‚ - Sign response β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 7. Aggregated response + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ respondToTask β”‚ +β”‚ (BLS signatures) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 8. If compliant + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ AttestationRegistry β”‚ +β”‚ .recordAttestation()β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 9. Attestation recorded + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HookMarket β”‚ +β”‚ .listHook() β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 4.2 Hook Deployment Flow + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Integrator β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 1. Browse HookMarket + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HookMarket β”‚ +β”‚ .getListings()β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 2. Select hook + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ AttestationRegistry β”‚ +β”‚ .getAttestation() β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 3. Verify attestation + β”‚ - isValid == true + β”‚ - expiresAt > now + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” 4. Fetch spec +β”‚ IPFS │◄───────────────────────────────────────────── +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 5. Review specification + β”‚ - State variables + β”‚ - Transition functions + β”‚ - Invariants + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HookMarket β”‚ +β”‚ .purchaseHook() β”‚ +β”‚ (if paid model) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 6. Deploy to pool + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ ProtocolHookMediatorβ”‚ +β”‚ .registerHook() β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 7. Route via MasterHook + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ MasterHook β”‚ +β”‚ (Diamond facet) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 8. Connect to PoolManager + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PoolManager β”‚ +β”‚ .initialize(hook) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 4.3 Runtime Callback Flow + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Trader β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 1. swap(poolId, params) + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PoolManager β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 2. hook.beforeSwap(...) + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ MasterHook β”‚ +β”‚ (Diamond Hub) β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 3. Route to registered hook + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ DynamicFeeHook β”‚ ◄── Encrypted bytecode +β”‚ (Fhenix protected) β”‚ (cannot decompile) +β”‚ β”‚ +β”‚ Executes: β”‚ +β”‚ - Read H (hook state)β”‚ +β”‚ - Read P (pool state)β”‚ +β”‚ - Compute f(H,P) β”‚ +β”‚ - Return Ξ” β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 4. Return (deltaFee, hookData) + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ MasterHook β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 5. Return to PoolManager + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PoolManager β”‚ +β”‚ - Apply fee Ξ” β”‚ +β”‚ - Execute swap β”‚ +β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ 6. hook.afterSwap(...) + β”‚ (similar flow) + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Swap Complete β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 5. Security Model + +### 5.1 Trust Boundaries + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TRUST BOUNDARY 1 β”‚ +β”‚ (Cryptographic: Fhenix CoFHE) β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Hook Source Code - Encrypted, cannot be extracted β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TRUST BOUNDARY 2 β”‚ +β”‚ (Cryptoeconomic: EigenLayer AVS) β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Specification Compliance - Verified by staked operators β”‚ β”‚ +β”‚ β”‚ Economic security: Ξ£(operator_stake) Γ— slashing_rate β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ TRUST BOUNDARY 3 β”‚ +β”‚ (Social: Specification Review) β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Specification Quality - Community review, audits, reputation β”‚ β”‚ +β”‚ β”‚ Risk: Malicious spec that matches malicious behavior β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 5.2 Threat Model + +| Threat | Impact | Mitigation | Residual Risk | +|--------|--------|------------|---------------| +| Code Extraction | IP theft | Fhenix FHE encryption | Cryptographic break | +| False Attestation | Deploy malicious hook | Slashing, multi-operator | Operator collusion | +| Spec Gaming | Approved malicious behavior | Community review | Undetected malicious spec | +| State Manipulation | Bypass verification | Random sampling | Statistical edge cases | +| Time-of-Check Attack | Behavior change after attestation | Attestation expiry | Short-term exploitation | + +### 5.3 Economic Security + +**Attestation Security Budget:** + +$$ +\text{Security} = \sum_{i \in \text{Operators}} \text{Stake}_i \times \text{SlashRate} +$$ + +**Recommended Parameters:** + +| Parameter | Value | Rationale | +|-----------|-------|-----------| +| Minimum Operator Count | 10 | Decentralization | +| Quorum Threshold | 67% | BFT assumption | +| Slash Rate | 10% | Sufficient deterrent | +| Attestation Validity | 30 days | Balance freshness vs. overhead | +| Sample Count | 100 | Statistical confidence | + +--- + +## 6. Deployment Architecture + +### 6.1 Contract Deployment Order + +``` +Phase 1: Core Infrastructure +β”œβ”€β”€ 1.1 Deploy EigenLayer middleware (if not existing) +β”œβ”€β”€ 1.2 Deploy HookAttestationServiceManager +β”œβ”€β”€ 1.3 Deploy HookAttestationTaskManager +└── 1.4 Deploy AttestationRegistry + +Phase 2: Marketplace +β”œβ”€β”€ 2.1 Deploy HookNFTRegistry +β”œβ”€β”€ 2.2 Deploy HookMarket +β”œβ”€β”€ 2.3 Deploy ProtocolHookMediator +└── 2.4 Deploy MasterHook (Diamond) + +Phase 3: Integration +β”œβ”€β”€ 3.1 Register AVS with EigenLayer +β”œβ”€β”€ 3.2 Onboard initial operators +β”œβ”€β”€ 3.3 Connect MasterHook to PoolManager +└── 3.4 Deploy StateView adapter + +Phase 4: Testing +β”œβ”€β”€ 4.1 Deploy test hooks +β”œβ”€β”€ 4.2 Run attestation workflow +β”œβ”€β”€ 4.3 Verify marketplace flow +└── 4.4 Test slashing conditions +``` + +### 6.2 Operator Requirements + +**Hardware:** +- CPU: 4+ cores +- RAM: 8GB+ +- Storage: 100GB SSD +- Network: 100Mbps+ + +**Software:** +- Ethereum node (archive preferred) +- AVS operator client +- BLS key management +- IPFS gateway access + +**Stake:** +- Minimum: 32 ETH equivalent +- Recommended: 100+ ETH for higher task allocation + +--- + +## 7. Future Extensions + +### 7.1 Planned Features + +| Feature | Description | Priority | +|---------|-------------|----------| +| Hook Composition | Chain multiple hooks on same pool | High | +| Subscription Model | Recurring payments for hook usage | Medium | +| Governance | DAO control of marketplace parameters | Medium | +| Cross-chain | Deploy hooks on L2s and other chains | Low | +| Formal Verification | TLA+ specs alongside Solidity | Low | + +### 7.2 Research Questions + +1. **Optimal Sample Distribution**: How to select state samples that maximize coverage with minimum count? +2. **Specification Language**: Can we create a DSL that compiles to both Solidity and verification rules? +3. **Incentive Alignment**: How to reward operators for thorough verification vs. speed? +4. **Upgradeability**: How to handle hook upgrades while maintaining attestation? + +--- + +## 8. References + +1. **[Uniswap V4 Core]** https://github.com/Uniswap/v4-core +2. **[EigenLayer]** https://github.com/Layr-Labs/eigenlayer-contracts +3. **[Fhenix CoFHE]** https://cofhe-docs.fhenix.zone/ +4. **[Bonded Hooks]** https://github.com/Jammabeans/Bonded-hooks +5. **[arXiv:2512.06203]** Formal State-Machine Models for Uniswap v3 +6. **[Diamond Pattern]** EIP-2535 Diamonds + +--- + +## 9. Glossary + +| Term | Definition | +|------|------------| +| **Hook** | Smart contract extending Uniswap V4 pool behavior via callbacks | +| **Specification** | Formal document defining hook behavior mathematically | +| **Attestation** | On-chain proof that hook implementation matches specification | +| **AVS** | Actively Validated Service - EigenLayer service for decentralized verification | +| **CoFHE** | Co-processing Fully Homomorphic Encryption | +| **MasterHook** | Diamond-pattern contract routing callbacks to registered hooks | +| **State Index** | Partitioning of pool state by user type (LP vs Trader) | diff --git a/docs/hook-pkg/backend/hook-license-issuer-spec.md b/docs/hook-pkg/backend/hook-license-issuer-spec.md new file mode 100644 index 000000000..927552fab --- /dev/null +++ b/docs/hook-pkg/backend/hook-license-issuer-spec.md @@ -0,0 +1,876 @@ +# HookLicenseIssuer Service Specification + +> **Document Type:** Backend Service Specification +> **Last Updated:** 2025-12-09 +> **Status:** Ready for Implementation + +--- + +## 1. Service Overview + +The **HookLicenseIssuer** is a modular backend service that: +1. Receives validated HookSpecs from the frontend +2. Uploads specs to IPFS +3. Mints HookLicense NFTs +4. Returns the license to the user + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOKLICENSEISSUER FLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ FRONTEND β”‚ +β”‚ ──────── β”‚ +β”‚ β”‚ +β”‚ createHook ──► HookDashboard ──► StateSpaceModel ──► [Validate] ──► submitHookSpec β”‚ +β”‚ (READ ONLY) Compatibility β”‚ +β”‚ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ POST /api/hookspec/submit β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ BACKEND β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ SubmitHookSpecRequest β”‚ β”‚ +β”‚ β”‚ { β”‚ β”‚ +β”‚ β”‚ spec: HookSpec, β”‚ β”‚ +β”‚ β”‚ signature: string, // EIP-712 signature β”‚ β”‚ +β”‚ β”‚ royaltyBps?: number // Optional royalty (default: 500 = 5%) β”‚ β”‚ +β”‚ β”‚ } β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β–Ό β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ HOOKLICENSEISSUER SERVICE β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ SignatureModule│───►│ IPFSModule │───►│ MintModule β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ verify(sig, β”‚ β”‚ upload(spec) β”‚ β”‚ mint(dev,cid, β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ signer) β”‚ β”‚ ──► CID β”‚ β”‚ metadata) β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β–Ό β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ HookLicense β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ NFT Contract β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ tokenId: 42 β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ owner: user β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ uri: ipfs://...β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β–Ό β”‚ β”‚ +β”‚ β”‚ SubmissionResult β”‚ β”‚ +β”‚ β”‚ { β”‚ β”‚ +β”‚ β”‚ success: true, β”‚ β”‚ +β”‚ β”‚ ipfsCid: "Qm...", β”‚ β”‚ +β”‚ β”‚ tokenId: 42, β”‚ β”‚ +β”‚ β”‚ transactionHash: "0x...", β”‚ β”‚ +β”‚ β”‚ ownerAddress: "0x1234...", β”‚ β”‚ +β”‚ β”‚ ipfsGatewayUrl: "https://ipfs.io/ipfs/Qm..." β”‚ β”‚ +β”‚ β”‚ } β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β–Ό β”‚ +β”‚ FRONTEND receives (user, HookLicense) β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Modular Architecture + +### 2.1 Module Breakdown + +``` +HookLicenseIssuer/ +β”œβ”€β”€ index.ts # Main service orchestrator +β”œβ”€β”€ modules/ +β”‚ β”œβ”€β”€ SignatureModule.ts # EIP-712 signature verification +β”‚ β”œβ”€β”€ ValidationModule.ts # HookSpec re-validation +β”‚ β”œβ”€β”€ IPFSModule.ts # IPFS upload abstraction +β”‚ └── MintModule.ts # NFT minting abstraction +β”œβ”€β”€ interfaces/ +β”‚ β”œβ”€β”€ ISignatureVerifier.ts # Signature interface +β”‚ β”œβ”€β”€ IIPFSProvider.ts # IPFS provider interface +β”‚ └── IMinter.ts # NFT minter interface +β”œβ”€β”€ providers/ +β”‚ β”œβ”€β”€ PinataProvider.ts # Pinata IPFS implementation +β”‚ β”œβ”€β”€ Web3StorageProvider.ts # Web3.storage implementation +β”‚ └── InfuraProvider.ts # Infura IPFS implementation +└── config/ + └── index.ts # Configuration management +``` + +### 2.2 Dependency Injection + +```typescript +// Interfaces for dependency injection (fully modular) + +interface ISignatureVerifier { + verify(message: SignedMessage, signature: string, expectedSigner: string): boolean; + recoverSigner(message: SignedMessage, signature: string): string; +} + +interface IIPFSProvider { + upload(content: string | Buffer): Promise; // Returns CID + pin(cid: string): Promise; + unpin(cid: string): Promise; + getGatewayUrl(cid: string): string; +} + +interface IMinter { + mint( + developer: string, + ipfsCid: string, + name: string, + version: string, + royaltyBps: number + ): Promise; + + getTokenByCid(cid: string): Promise; + isRegistered(cid: string): Promise; +} + +interface MintResult { + tokenId: number; + transactionHash: string; + blockNumber: number; +} +``` + +--- + +## 3. Input/Output Contracts + +### 3.1 Service Input (What HookLicenseIssuer Receives) + +```typescript +// POST /api/hookspec/submit +interface SubmitHookSpecRequest { + // The validated HookSpec document + spec: HookSpec; + + // EIP-712 signature proving user consent + signature: string; + + // Optional royalty percentage (basis points) + // Default: 500 (5%) + // Range: 0-10000 (0-100%) + royaltyBps?: number; +} + +// HookSpec structure (from frontend validation) +interface HookSpec { + metadata: { + name: string; // e.g., "DynamicFeeHook" + version: string; // e.g., "1.0.0" + author: string; // Ethereum address + description?: string; + license?: string; + system_state_version?: string; // IPFS CID of system-state.md + }; + hook_state: StateVariable[]; + system_functions: SystemFunction[]; + invariants?: Invariant[]; +} + +// EIP-712 Typed Data being signed +interface SignedMessage { + name: string; // spec.metadata.name + version: string; // spec.metadata.version + specHash: string; // keccak256(JSON.stringify(spec)) + developer: string; // User's address + nonce: number; // Replay protection + deadline: number; // Unix timestamp +} +``` + +### 3.2 Service Output (What HookLicenseIssuer Returns) + +```typescript +// Success Response +interface SubmissionResult { + success: true; + + // IPFS CID of the uploaded spec + ipfsCid: string; // e.g., "QmXyz..." + + // Minted NFT token ID + tokenId: number; // e.g., 42 + + // Transaction hash of mint + transactionHash: string; // e.g., "0xabc..." + + // Owner of the NFT (developer) + ownerAddress: string; // e.g., "0x1234..." + + // Convenience URLs + ipfsGatewayUrl: string; // e.g., "https://ipfs.io/ipfs/QmXyz..." + openSeaUrl?: string; // e.g., "https://opensea.io/assets/..." + etherscanUrl?: string; // e.g., "https://etherscan.io/tx/..." +} + +// Error Response +interface SubmissionError { + success: false; + error: { + code: ErrorCode; + message: string; + details?: Record; + }; +} + +type ErrorCode = + | 'INVALID_SIGNATURE' + | 'SIGNATURE_EXPIRED' + | 'INVALID_SPEC' + | 'IPFS_UPLOAD_FAILED' + | 'CID_ALREADY_REGISTERED' + | 'MINT_FAILED' + | 'INSUFFICIENT_GAS' + | 'CONTRACT_ERROR' + | 'NETWORK_ERROR'; +``` + +--- + +## 4. Module Specifications + +### 4.1 SignatureModule + +**Purpose**: Verify EIP-712 signatures to ensure user consent. + +```typescript +// modules/SignatureModule.ts + +import { ethers } from 'ethers'; + +interface SignatureModuleConfig { + domain: EIP712Domain; + types: EIP712Types; +} + +interface EIP712Domain { + name: string; // "HookBazaar" + version: string; // "1" + chainId: number; // 1 (mainnet) or testnet + verifyingContract: string; // HookLicense contract address +} + +class SignatureModule implements ISignatureVerifier { + constructor(private config: SignatureModuleConfig) {} + + /** + * Verify signature matches expected signer + */ + verify(message: SignedMessage, signature: string, expectedSigner: string): boolean { + const recoveredSigner = this.recoverSigner(message, signature); + return recoveredSigner.toLowerCase() === expectedSigner.toLowerCase(); + } + + /** + * Recover signer address from signature + */ + recoverSigner(message: SignedMessage, signature: string): string { + return ethers.verifyTypedData( + this.config.domain, + this.config.types, + message, + signature + ); + } + + /** + * Check if signature deadline has passed + */ + isExpired(message: SignedMessage): boolean { + return Date.now() / 1000 > message.deadline; + } +} +``` + +**Input**: +- `message`: The typed data that was signed +- `signature`: The hex-encoded signature +- `expectedSigner`: The address we expect signed it + +**Output**: +- `boolean`: Whether signature is valid + +### 4.2 ValidationModule + +**Purpose**: Re-validate HookSpec before processing (defense in depth). + +```typescript +// modules/ValidationModule.ts + +interface ValidationModuleConfig { + systemStateUrl: string; // URL or IPFS CID of system-state.md + strictMode: boolean; // Fail on warnings +} + +class ValidationModule { + private systemState: StateSpaceModel | null = null; + + constructor(private config: ValidationModuleConfig) {} + + /** + * Load system state model + */ + async initialize(): Promise { + this.systemState = await this.fetchSystemState(); + } + + /** + * Validate HookSpec against system state + */ + validate(spec: HookSpec): ValidationResult[] { + const results: ValidationResult[] = []; + + // Run all validation rules + results.push(this.validatePoolStateReferences(spec)); + results.push(this.validateUniqueHookStateNames(spec)); + results.push(this.validateCallbacks(spec)); + results.push(this.validateEquationSymbols(spec)); + results.push(this.validateSolidityTypes(spec)); + results.push(this.validateWritesMatchHookState(spec)); + + return results; + } + + /** + * Quick check if spec is valid + */ + isValid(spec: HookSpec): boolean { + const results = this.validate(spec); + return results.every(r => r.passed); + } +} +``` + +**Input**: +- `spec`: HookSpec document + +**Output**: +- `ValidationResult[]`: Array of rule results +- `boolean`: Overall validity + +### 4.3 IPFSModule + +**Purpose**: Abstract IPFS operations with provider flexibility. + +```typescript +// modules/IPFSModule.ts + +interface IPFSModuleConfig { + provider: 'pinata' | 'web3storage' | 'infura'; + apiKey: string; + apiSecret?: string; + gateway: string; +} + +class IPFSModule implements IIPFSProvider { + private provider: IIPFSProvider; + + constructor(private config: IPFSModuleConfig) { + // Factory pattern for provider selection + this.provider = this.createProvider(config); + } + + private createProvider(config: IPFSModuleConfig): IIPFSProvider { + switch (config.provider) { + case 'pinata': + return new PinataProvider(config.apiKey, config.apiSecret); + case 'web3storage': + return new Web3StorageProvider(config.apiKey); + case 'infura': + return new InfuraProvider(config.apiKey, config.apiSecret); + default: + throw new Error(`Unknown IPFS provider: ${config.provider}`); + } + } + + /** + * Upload HookSpec to IPFS + */ + async upload(spec: HookSpec, developer: string): Promise { + // Wrap spec with metadata + const wrapper: IPFSHookSpecWrapper = { + schema_version: '1.0.0', + content_type: 'hookspec', + uploader: developer, + uploaded_at: Date.now(), + content: spec + }; + + const content = JSON.stringify(wrapper, null, 2); + const cid = await this.provider.upload(content); + + // Ensure pinned + await this.provider.pin(cid); + + return cid; + } + + /** + * Get gateway URL for CID + */ + getGatewayUrl(cid: string): string { + return `${this.config.gateway}/ipfs/${cid}`; + } +} +``` + +**Input**: +- `spec`: HookSpec document +- `developer`: Uploader address + +**Output**: +- `string`: IPFS CID + +### 4.4 MintModule + +**Purpose**: Abstract NFT minting operations. + +```typescript +// modules/MintModule.ts + +interface MintModuleConfig { + contractAddress: string; + rpcUrl: string; + signerPrivateKey: string; // Backend signer with MINTER_ROLE + chainId: number; + gasLimit?: number; +} + +class MintModule implements IMinter { + private contract: ethers.Contract; + private signer: ethers.Wallet; + + constructor(private config: MintModuleConfig) { + const provider = new ethers.JsonRpcProvider(config.rpcUrl); + this.signer = new ethers.Wallet(config.signerPrivateKey, provider); + this.contract = new ethers.Contract( + config.contractAddress, + HookLicenseABI, + this.signer + ); + } + + /** + * Mint HookLicense NFT + */ + async mint( + developer: string, + ipfsCid: string, + name: string, + version: string, + royaltyBps: number + ): Promise { + // Check if already registered + if (await this.isRegistered(ipfsCid)) { + throw new MintError('CID_ALREADY_REGISTERED', `CID ${ipfsCid} already registered`); + } + + // Estimate gas + const estimatedGas = await this.contract.mint.estimateGas( + developer, + ipfsCid, + name, + version, + royaltyBps + ); + + // Execute mint + const tx = await this.contract.mint( + developer, + ipfsCid, + name, + version, + royaltyBps, + { + gasLimit: Math.ceil(Number(estimatedGas) * 1.2) // 20% buffer + } + ); + + // Wait for confirmation + const receipt = await tx.wait(); + + // Extract tokenId from event + const event = receipt.logs.find( + (log: any) => log.fragment?.name === 'HookSpecRegistered' + ); + const tokenId = event?.args?.tokenId?.toNumber() ?? 0; + + return { + tokenId, + transactionHash: receipt.hash, + blockNumber: receipt.blockNumber + }; + } + + /** + * Check if CID is already registered + */ + async isRegistered(cid: string): Promise { + return await this.contract.isRegistered(cid); + } + + /** + * Get token ID by CID + */ + async getTokenByCid(cid: string): Promise { + try { + const tokenId = await this.contract.getTokenByCid(cid); + return tokenId.toNumber(); + } catch { + return null; + } + } +} +``` + +**Input**: +- `developer`: Address to receive NFT +- `ipfsCid`: IPFS CID of spec +- `name`: Hook name +- `version`: Hook version +- `royaltyBps`: Royalty percentage + +**Output**: +- `MintResult`: Token ID, tx hash, block number + +--- + +## 5. Main Service Orchestrator + +```typescript +// index.ts - HookLicenseIssuer main service + +interface HookLicenseIssuerConfig { + signature: SignatureModuleConfig; + validation: ValidationModuleConfig; + ipfs: IPFSModuleConfig; + mint: MintModuleConfig; +} + +class HookLicenseIssuer { + private signatureModule: SignatureModule; + private validationModule: ValidationModule; + private ipfsModule: IPFSModule; + private mintModule: MintModule; + + constructor(config: HookLicenseIssuerConfig) { + this.signatureModule = new SignatureModule(config.signature); + this.validationModule = new ValidationModule(config.validation); + this.ipfsModule = new IPFSModule(config.ipfs); + this.mintModule = new MintModule(config.mint); + } + + /** + * Initialize service (load system state, etc.) + */ + async initialize(): Promise { + await this.validationModule.initialize(); + } + + /** + * Main entry point: Issue a HookLicense NFT + * + * @param request - The submission request from frontend + * @returns SubmissionResult on success, throws on error + */ + async issueHookLicense(request: SubmitHookSpecRequest): Promise { + const { spec, signature, royaltyBps = 500 } = request; + const developer = spec.metadata.author; + + // Step 1: Verify signature + const specHash = this.computeSpecHash(spec); + const signedMessage: SignedMessage = { + name: spec.metadata.name, + version: spec.metadata.version, + specHash, + developer, + nonce: await this.getNonce(developer), + deadline: Math.floor(Date.now() / 1000) + 3600 // Assume 1 hour validity + }; + + if (this.signatureModule.isExpired(signedMessage)) { + throw new IssuerError('SIGNATURE_EXPIRED', 'Signature deadline has passed'); + } + + if (!this.signatureModule.verify(signedMessage, signature, developer)) { + throw new IssuerError('INVALID_SIGNATURE', 'Signature verification failed'); + } + + // Step 2: Re-validate spec (defense in depth) + if (!this.validationModule.isValid(spec)) { + const results = this.validationModule.validate(spec); + const errors = results.filter(r => !r.passed).flatMap(r => r.errors); + throw new IssuerError('INVALID_SPEC', 'HookSpec validation failed', { errors }); + } + + // Step 3: Upload to IPFS + let ipfsCid: string; + try { + ipfsCid = await this.ipfsModule.upload(spec, developer); + } catch (error) { + throw new IssuerError('IPFS_UPLOAD_FAILED', 'Failed to upload to IPFS', { error }); + } + + // Step 4: Mint NFT + let mintResult: MintResult; + try { + mintResult = await this.mintModule.mint( + developer, + ipfsCid, + spec.metadata.name, + spec.metadata.version, + royaltyBps + ); + } catch (error) { + if (error instanceof MintError && error.code === 'CID_ALREADY_REGISTERED') { + throw new IssuerError('CID_ALREADY_REGISTERED', 'This spec is already registered'); + } + throw new IssuerError('MINT_FAILED', 'Failed to mint NFT', { error }); + } + + // Step 5: Return result + return { + success: true, + ipfsCid, + tokenId: mintResult.tokenId, + transactionHash: mintResult.transactionHash, + ownerAddress: developer, + ipfsGatewayUrl: this.ipfsModule.getGatewayUrl(ipfsCid), + openSeaUrl: this.buildOpenSeaUrl(mintResult.tokenId), + etherscanUrl: this.buildEtherscanUrl(mintResult.transactionHash) + }; + } + + private computeSpecHash(spec: HookSpec): string { + return ethers.keccak256( + ethers.toUtf8Bytes(JSON.stringify(spec)) + ); + } + + private async getNonce(address: string): Promise { + // Implement nonce tracking (could be from contract or database) + return 0; + } + + private buildOpenSeaUrl(tokenId: number): string { + // Build OpenSea URL based on network + return `https://opensea.io/assets/ethereum/${this.mintModule.config.contractAddress}/${tokenId}`; + } + + private buildEtherscanUrl(txHash: string): string { + return `https://etherscan.io/tx/${txHash}`; + } +} +``` + +--- + +## 6. API Endpoint Implementation + +```typescript +// routes/hookspec.ts + +import { Router } from 'express'; +import { HookLicenseIssuer } from '../services/HookLicenseIssuer'; + +const router = Router(); +const issuer = new HookLicenseIssuer(config); + +// Initialize on startup +issuer.initialize(); + +/** + * POST /api/hookspec/submit + * + * Submit a validated HookSpec for IPFS upload and NFT minting + */ +router.post('/submit', async (req, res) => { + try { + const request: SubmitHookSpecRequest = req.body; + + // Validate request shape + if (!request.spec || !request.signature) { + return res.status(400).json({ + success: false, + error: { + code: 'INVALID_REQUEST', + message: 'Missing required fields: spec, signature' + } + }); + } + + // Issue the license + const result = await issuer.issueHookLicense(request); + + return res.status(201).json(result); + + } catch (error) { + if (error instanceof IssuerError) { + return res.status(400).json({ + success: false, + error: { + code: error.code, + message: error.message, + details: error.details + } + }); + } + + // Unexpected error + console.error('Unexpected error in /submit:', error); + return res.status(500).json({ + success: false, + error: { + code: 'INTERNAL_ERROR', + message: 'An unexpected error occurred' + } + }); + } +}); + +export default router; +``` + +--- + +## 7. Configuration + +```typescript +// config/index.ts + +interface Config { + // Network + chainId: number; + rpcUrl: string; + + // Contracts + hookLicenseContract: string; + + // IPFS + ipfsProvider: 'pinata' | 'web3storage' | 'infura'; + ipfsApiKey: string; + ipfsApiSecret?: string; + ipfsGateway: string; + + // Signing + signerPrivateKey: string; // For backend minting + + // Validation + systemStateCid: string; // IPFS CID of system-state.md + strictValidation: boolean; +} + +// Example config loading +function loadConfig(): Config { + return { + chainId: parseInt(process.env.CHAIN_ID || '1'), + rpcUrl: process.env.RPC_URL || 'https://mainnet.infura.io/v3/...', + hookLicenseContract: process.env.HOOK_LICENSE_CONTRACT!, + ipfsProvider: (process.env.IPFS_PROVIDER || 'pinata') as any, + ipfsApiKey: process.env.IPFS_API_KEY!, + ipfsApiSecret: process.env.IPFS_API_SECRET, + ipfsGateway: process.env.IPFS_GATEWAY || 'https://ipfs.io', + signerPrivateKey: process.env.SIGNER_PRIVATE_KEY!, + systemStateCid: process.env.SYSTEM_STATE_CID!, + strictValidation: process.env.STRICT_VALIDATION === 'true' + }; +} +``` + +--- + +## 8. Modularity Benefits + +### 8.1 Swappable Components + +| Component | Interface | Implementations | +|-----------|-----------|-----------------| +| Signature Verification | `ISignatureVerifier` | EIP-712, EIP-1271 (smart contract wallets) | +| IPFS Upload | `IIPFSProvider` | Pinata, Web3.storage, Infura, IPFS daemon | +| NFT Minting | `IMinter` | HookLicense (ERC-721), HookLicense1155 (ERC-1155) | + +### 8.2 Testing Strategy + +```typescript +// Mock implementations for testing + +class MockIPFSProvider implements IIPFSProvider { + private storage = new Map(); + + async upload(content: string): Promise { + const cid = `Qm${Math.random().toString(36).slice(2)}`; + this.storage.set(cid, content); + return cid; + } + + // ... other methods +} + +class MockMinter implements IMinter { + private tokenCounter = 0; + private registry = new Map(); + + async mint(developer, ipfsCid, name, version, royaltyBps): Promise { + const tokenId = ++this.tokenCounter; + this.registry.set(ipfsCid, tokenId); + return { + tokenId, + transactionHash: `0x${Math.random().toString(16).slice(2)}`, + blockNumber: 12345 + }; + } + + // ... other methods +} +``` + +### 8.3 Future Extensions + +1. **Multi-chain Support**: Add chain-specific minters +2. **Batch Minting**: Support minting multiple specs at once +3. **Upgradeable Specs**: Support versioning and updates +4. **AVS Integration**: Add attestation before minting +5. **Payment Integration**: Add payment module for paid listings + +--- + +## 9. Summary + +**HookLicenseIssuer receives:** +```typescript +{ + spec: HookSpec, // The validated hook specification + signature: string, // EIP-712 signature proving consent + royaltyBps?: number // Optional royalty (default 5%) +} +``` + +**HookLicenseIssuer returns:** +```typescript +{ + success: true, + ipfsCid: string, // IPFS content address + tokenId: number, // NFT token ID + transactionHash: string, + ownerAddress: string, + ipfsGatewayUrl: string, + openSeaUrl?: string +} +``` + +**Modular design via interfaces:** +- `ISignatureVerifier` - Verify user consent +- `IIPFSProvider` - Store spec immutably +- `IMinter` - Issue NFT ownership + +Each module can be independently tested, replaced, or upgraded without affecting the others. diff --git a/docs/hook-pkg/frontend/hook-developer-flow.md b/docs/hook-pkg/frontend/hook-developer-flow.md new file mode 100644 index 000000000..0e547538d --- /dev/null +++ b/docs/hook-pkg/frontend/hook-developer-flow.md @@ -0,0 +1,675 @@ +# Hook Developer Dashboard: Frontend Flow & API Specification + +> **Document Type:** Implementation Specification +> **Last Updated:** 2025-12-09 +> **Status:** Ready for Implementation + +--- + +## 1. User Flow Diagram + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ HOOK DEVELOPER DASHBOARD FLOW β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ HookDeveloper β”‚ β”‚ +β”‚ β”‚ Dashboard β”‚ β”‚ +β”‚ β”‚ /hook-developer β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”‚ clicks "Create New Hook" β”‚ +β”‚ β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ CreateHook Page β”‚ β”‚ +β”‚ β”‚ /hook-developer/create β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Step 1: View State Space Model (READ ONLY) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ StateSpaceModelViewer β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ - LP Index Variables (positions, ticks) β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ - Trader Index Variables (slot0, liquidity) β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ - Shared Variables (fee growth) β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ [Search] [Copy Symbol] [View IStateView Source] β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Step 2: Write/Upload HookSpec β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ [Upload File] or [Use Editor] β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ HookSpecEditor β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ metadata: β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ name: "MyHook" β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ version: "1.0.0" β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ hook_state: β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ - name: accumulated_fees β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ symbol: F_acc β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ type: uint256 β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ system_functions: β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ - callback: afterSwap β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ reads: [sqrt_price, active_liquidity] β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ ... β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Step 3: Validate Compatibility β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ [Validate HookSpec] β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ ValidationResults β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ“ V1: Valid pool state references β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ“ V2: Unique hook state names β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ“ V3: Valid callbacks β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ— V4: Invalid symbol 'X_invalid' in equation β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ“ V5: Valid Solidity types β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ“ V6: Writes match hook state β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ +β”‚ β”‚ β”‚ Step 4: Submit & Mint License (if validation passes) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ [Submit HookSpec] β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ Backend Flow: β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ 1. Upload to IPFS β†’ Get CID β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ 2. Call HookLicenseIssuer.mint(user, CID, metadata) β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ 3. Return HookLicense NFT β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ SubmissionResult β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ“ HookSpec uploaded to IPFS β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ CID: QmXyz... β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ βœ“ HookLicense NFT minted β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Token ID: #42 β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Owner: 0x1234...abcd β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ [View on OpenSea] [View on IPFS] [Back to Dashboard] β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ +β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## 2. Frontend Routes + +| Route | Component | Description | +|-------|-----------|-------------| +| `/hook-developer` | `HookDeveloperDashboard` | Main dashboard with stats and hook list | +| `/hook-developer/create` | `CreateHookPage` | Create new hook flow | +| `/hook-developer/hooks/:tokenId` | `HookDetailPage` | View specific hook details | +| `/hook-developer/hooks/:tokenId/edit` | `EditHookPage` | Edit hook metadata | + +--- + +## 3. Frontend Components + +### 3.1 Component Hierarchy + +``` +CreateHookPage +β”œβ”€β”€ StateSpaceModelViewer (Step 1) +β”‚ β”œβ”€β”€ StateVariableTable +β”‚ β”‚ β”œβ”€β”€ LPIndexSection +β”‚ β”‚ β”œβ”€β”€ TraderIndexSection +β”‚ β”‚ └── SharedSection +β”‚ └── SearchInput +β”œβ”€β”€ HookSpecEditor (Step 2) +β”‚ β”œβ”€β”€ MetadataForm +β”‚ β”œβ”€β”€ HookStateForm +β”‚ β”œβ”€β”€ SystemFunctionsForm +β”‚ └── InvariantsForm +β”œβ”€β”€ ValidationResults (Step 3) +β”‚ β”œβ”€β”€ ValidationRuleResult (x6) +β”‚ └── ErrorDetails +└── SubmissionFlow (Step 4) + β”œβ”€β”€ IPFSUploadStatus + β”œβ”€β”€ MintTransaction + └── SubmissionResult +``` + +### 3.2 Component Specifications + +#### StateSpaceModelViewer + +```typescript +// components/hook/StateSpaceModelViewer.tsx + +interface StateVariable { + name: string; + symbol: string; + type: string; + getter: string; + description: string; +} + +interface StateSpaceModel { + version: string; + ipfsCid: string; + lpIndex: StateVariable[]; + traderIndex: StateVariable[]; + shared: StateVariable[]; +} + +interface StateSpaceModelViewerProps { + model: StateSpaceModel; + onSelectVariable?: (variable: StateVariable) => void; +} + +// Features: +// - Collapsible sections for each index +// - Search/filter by name, symbol, or type +// - Copy-to-clipboard for symbols +// - Tooltip with full description +// - Link to IStateView source code +``` + +#### HookSpecEditor + +```typescript +// components/hook/HookSpecEditor.tsx + +interface HookSpecEditorProps { + initialSpec?: HookSpec; + stateSpaceModel: StateSpaceModel; + onChange: (spec: HookSpec) => void; + onValidate: () => void; +} + +// Features: +// - Monaco editor or CodeMirror for YAML editing +// - Syntax highlighting +// - Auto-complete for state variable names +// - Real-time schema validation +// - Upload from file option +// - Template selection +``` + +#### ValidationResults + +```typescript +// components/hook/ValidationResults.tsx + +interface ValidationResult { + ruleId: string; + ruleName: string; + passed: boolean; + errors: string[]; + warnings: string[]; +} + +interface ValidationResultsProps { + results: ValidationResult[]; + isLoading: boolean; + onFixError?: (ruleId: string, errorIndex: number) => void; +} + +// Features: +// - Visual pass/fail indicator for each rule +// - Expandable error details +// - Link to relevant spec section +// - Fix suggestions where possible +``` + +#### SubmissionFlow + +```typescript +// components/hook/SubmissionFlow.tsx + +interface SubmissionFlowProps { + hookSpec: HookSpec; + validationPassed: boolean; + onSubmit: () => Promise; +} + +interface SubmissionResult { + ipfsCid: string; + tokenId: number; + transactionHash: string; + ownerAddress: string; +} + +// Features: +// - Step-by-step progress indicator +// - IPFS upload progress +// - Transaction confirmation +// - Success/error states +// - Links to OpenSea, IPFS, Etherscan +``` + +--- + +## 4. API Endpoints + +### 4.1 Frontend β†’ Backend API + +| Method | Endpoint | Request | Response | Description | +|--------|----------|---------|----------|-------------| +| `GET` | `/api/state-space-model` | - | `StateSpaceModel` | Get current system state model | +| `POST` | `/api/hookspec/validate` | `HookSpec` | `ValidationResult[]` | Validate a HookSpec | +| `POST` | `/api/hookspec/submit` | `{ spec: HookSpec, signature: string }` | `SubmissionResult` | Submit spec, upload to IPFS, mint NFT | +| `GET` | `/api/hooks` | `?owner=0x...` | `HookLicense[]` | List user's hook licenses | +| `GET` | `/api/hooks/:tokenId` | - | `HookLicenseDetail` | Get hook license details | + +### 4.2 API Type Definitions + +```typescript +// types/api.ts + +// GET /api/state-space-model +interface StateSpaceModelResponse { + version: string; + ipfsCid: string; + uniswapVersion: string; + updatedAt: string; + indices: { + lp: StateVariable[]; + trader: StateVariable[]; + shared: StateVariable[]; + }; +} + +// POST /api/hookspec/validate +interface ValidateHookSpecRequest { + spec: HookSpec; +} + +interface ValidateHookSpecResponse { + valid: boolean; + results: ValidationResult[]; + errors: string[]; + warnings: string[]; +} + +// POST /api/hookspec/submit +interface SubmitHookSpecRequest { + spec: HookSpec; + signature: string; // EIP-712 signature from wallet + royaltyBps?: number; // Royalty percentage (default: 500 = 5%) +} + +interface SubmitHookSpecResponse { + success: boolean; + ipfsCid: string; + tokenId: number; + transactionHash: string; + ownerAddress: string; + openSeaUrl?: string; + ipfsGatewayUrl: string; +} + +// GET /api/hooks +interface ListHooksRequest { + owner?: string; + page?: number; + limit?: number; +} + +interface ListHooksResponse { + hooks: HookLicenseSummary[]; + total: number; + page: number; + limit: number; +} + +interface HookLicenseSummary { + tokenId: number; + name: string; + version: string; + ipfsCid: string; + deprecated: boolean; + registeredAt: string; +} + +// GET /api/hooks/:tokenId +interface HookLicenseDetailResponse { + tokenId: number; + owner: string; + metadata: { + name: string; + version: string; + description?: string; + developer: string; + registeredAt: string; + deprecated: boolean; + }; + ipfsCid: string; + ipfsGatewayUrl: string; + spec: HookSpec; // Full spec content + attestations?: AttestationInfo[]; + deployments?: DeploymentInfo[]; +} +``` + +--- + +## 5. Backend Services + +### 5.1 Service Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ BACKEND SERVICES β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ API Gateway β”‚ β”‚ +β”‚ β”‚ (Express / Fastify) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ StateSpace β”‚ β”‚ Validation β”‚ β”‚ HookLicense β”‚ β”‚ +β”‚ β”‚ Service β”‚ β”‚ Service β”‚ β”‚ Issuer β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ IPFS β”‚ β”‚ IPFS β”‚ β”‚ Blockchain β”‚ β”‚ +β”‚ β”‚ Gateway β”‚ β”‚ (fetch spec) β”‚ β”‚ (mint NFT) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### 5.2 HookLicenseIssuer Service + +```typescript +// services/HookLicenseIssuer.ts + +interface HookLicenseIssuerConfig { + contractAddress: string; + ipfsProvider: 'pinata' | 'infura' | 'web3storage'; + ipfsApiKey: string; + ipfsGatewayUrl: string; + rpcUrl: string; + signerPrivateKey: string; // Backend signer with MINTER_ROLE +} + +interface MintRequest { + developer: string; // User's address (receives NFT) + spec: HookSpec; // Validated HookSpec + signature: string; // User's EIP-712 signature + royaltyBps?: number; +} + +interface MintResult { + success: boolean; + tokenId: number; + ipfsCid: string; + transactionHash: string; + error?: string; +} + +class HookLicenseIssuer { + constructor(config: HookLicenseIssuerConfig); + + /** + * Issue a new HookLicense NFT + * + * Flow: + * 1. Verify user signature + * 2. Validate HookSpec (double-check) + * 3. Package and upload to IPFS + * 4. Call HookLicense.mint() on-chain + * 5. Return result with tokenId and CID + */ + async issueHookLicense(request: MintRequest): Promise; + + /** + * Upload HookSpec to IPFS + */ + async uploadToIPFS(spec: HookSpec, developer: string): Promise; + + /** + * Mint NFT on-chain + */ + async mintNFT( + developer: string, + ipfsCid: string, + name: string, + version: string, + royaltyBps: number + ): Promise<{ tokenId: number; transactionHash: string }>; + + /** + * Verify EIP-712 signature + */ + verifySignature(spec: HookSpec, signature: string, expectedSigner: string): boolean; +} +``` + +### 5.3 EIP-712 Signature Schema + +```typescript +// For user to sign before submission +const HOOKSPEC_TYPEHASH = { + HookSpecSubmission: [ + { name: 'name', type: 'string' }, + { name: 'version', type: 'string' }, + { name: 'specHash', type: 'bytes32' }, // keccak256(JSON.stringify(spec)) + { name: 'developer', type: 'address' }, + { name: 'nonce', type: 'uint256' }, + { name: 'deadline', type: 'uint256' }, + ], +}; + +const domain = { + name: 'HookBazaar', + version: '1', + chainId: 1, // or appropriate chain + verifyingContract: HOOK_LICENSE_CONTRACT_ADDRESS, +}; +``` + +--- + +## 6. Implementation Files + +### 6.1 File Structure + +``` +client2/src/ +β”œβ”€β”€ components/ +β”‚ └── hook/ +β”‚ β”œβ”€β”€ CreateHookPage.tsx # Main create hook flow +β”‚ β”œβ”€β”€ StateSpaceModelViewer.tsx # Read-only state model viewer +β”‚ β”œβ”€β”€ HookSpecEditor.tsx # YAML/JSON editor for specs +β”‚ β”œβ”€β”€ ValidationResults.tsx # Validation results display +β”‚ β”œβ”€β”€ SubmissionFlow.tsx # Submit, IPFS, mint flow +β”‚ β”œβ”€β”€ HookDetailPage.tsx # View single hook details +β”‚ └── HookCard.tsx # Hook list item component +β”œβ”€β”€ hooks/ +β”‚ β”œβ”€β”€ useStateSpaceModel.ts # Fetch state space model +β”‚ β”œβ”€β”€ useValidateHookSpec.ts # Validate hook spec +β”‚ β”œβ”€β”€ useSubmitHookSpec.ts # Submit and mint +β”‚ └── useHookLicenses.ts # List user's hooks +β”œβ”€β”€ lib/ +β”‚ └── api/ +β”‚ β”œβ”€β”€ hookApi.ts # API client for hooks +β”‚ └── types.ts # API type definitions +└── types/ + └── hookSpec.ts # HookSpec type definitions +``` + +--- + +## 7. State Management + +### 7.1 Create Hook Flow State + +```typescript +// hooks/useCreateHookFlow.ts + +interface CreateHookState { + step: 'view-model' | 'edit-spec' | 'validate' | 'submit' | 'complete'; + stateSpaceModel: StateSpaceModel | null; + hookSpec: HookSpec | null; + validationResults: ValidationResult[] | null; + submissionResult: SubmissionResult | null; + error: string | null; + isLoading: boolean; +} + +type CreateHookAction = + | { type: 'LOAD_STATE_MODEL'; payload: StateSpaceModel } + | { type: 'UPDATE_SPEC'; payload: HookSpec } + | { type: 'VALIDATE_START' } + | { type: 'VALIDATE_SUCCESS'; payload: ValidationResult[] } + | { type: 'VALIDATE_ERROR'; payload: string } + | { type: 'SUBMIT_START' } + | { type: 'SUBMIT_SUCCESS'; payload: SubmissionResult } + | { type: 'SUBMIT_ERROR'; payload: string } + | { type: 'RESET' }; + +function useCreateHookFlow() { + const [state, dispatch] = useReducer(createHookReducer, initialState); + + // Actions + const loadStateModel = async () => { ... }; + const updateSpec = (spec: HookSpec) => { ... }; + const validateSpec = async () => { ... }; + const submitSpec = async (signature: string) => { ... }; + const reset = () => { ... }; + + return { state, loadStateModel, updateSpec, validateSpec, submitSpec, reset }; +} +``` + +--- + +## 8. Wallet Integration + +### 8.1 Required Wallet Actions + +| Action | Method | When | +|--------|--------|------| +| Connect Wallet | `connect()` | On page load or "Connect" button | +| Sign Message | `signTypedData()` | Before submitting HookSpec | +| View Transaction | - | After mint transaction | + +### 8.2 Signature Flow + +```typescript +// hooks/useSignHookSpec.ts + +async function signHookSpec( + spec: HookSpec, + walletClient: WalletClient +): Promise { + const specHash = keccak256( + toBytes(JSON.stringify(spec)) + ); + + const nonce = await getNonce(walletClient.account.address); + const deadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour + + const signature = await walletClient.signTypedData({ + domain, + types: HOOKSPEC_TYPEHASH, + primaryType: 'HookSpecSubmission', + message: { + name: spec.metadata.name, + version: spec.metadata.version, + specHash, + developer: walletClient.account.address, + nonce, + deadline, + }, + }); + + return signature; +} +``` + +--- + +## 9. Error Handling + +### 9.1 Error Types + +```typescript +// types/errors.ts + +enum HookErrorCode { + // Validation errors + INVALID_SPEC_FORMAT = 'INVALID_SPEC_FORMAT', + INVALID_STATE_REFERENCE = 'INVALID_STATE_REFERENCE', + INVALID_CALLBACK = 'INVALID_CALLBACK', + INVALID_TYPE = 'INVALID_TYPE', + DUPLICATE_STATE_NAME = 'DUPLICATE_STATE_NAME', + INVALID_EQUATION = 'INVALID_EQUATION', + + // Submission errors + IPFS_UPLOAD_FAILED = 'IPFS_UPLOAD_FAILED', + SIGNATURE_INVALID = 'SIGNATURE_INVALID', + MINT_FAILED = 'MINT_FAILED', + CID_ALREADY_REGISTERED = 'CID_ALREADY_REGISTERED', + + // Network errors + NETWORK_ERROR = 'NETWORK_ERROR', + CONTRACT_ERROR = 'CONTRACT_ERROR', +} + +interface HookError { + code: HookErrorCode; + message: string; + details?: Record; +} +``` + +--- + +## 10. Testing Strategy + +### 10.1 Unit Tests + +- StateSpaceModelViewer: renders all sections, search works +- HookSpecEditor: updates state on change, validates schema +- ValidationResults: displays pass/fail correctly +- SubmissionFlow: handles all states + +### 10.2 Integration Tests + +- Full create flow: view model β†’ edit spec β†’ validate β†’ submit +- API mocking for backend calls +- Wallet signature mocking + +### 10.3 E2E Tests + +- Connect wallet β†’ create hook β†’ verify NFT minted +- Invalid spec rejection flow +- Network error handling + +--- + +## 11. Next Steps + +1. **Create component files** in `client2/src/components/hook/` +2. **Add routes** to `App.tsx` +3. **Implement hooks** for API calls +4. **Set up backend API** endpoints +5. **Deploy HookLicense contract** to testnet +6. **Integrate IPFS provider** diff --git a/docs/hook-pkg/mathematical-models/state-space-model.md b/docs/hook-pkg/mathematical-models/state-space-model.md new file mode 100644 index 000000000..92ca177c0 --- /dev/null +++ b/docs/hook-pkg/mathematical-models/state-space-model.md @@ -0,0 +1,702 @@ +# Hook State-Space Model: Dual-Index Architecture + +> **Status:** Research Foundation +> **Last Updated:** 2025-12-09 +> **References:** [arXiv:2512.06203](https://arxiv.org/abs/2512.06203), [arXiv:2103.12732](https://arxiv.org/abs/2103.12732), [arXiv:2103.00540](https://arxiv.org/abs/2103.00540) + +## 1. Overview + +This document formalizes the state-space model for Uniswap V4 hooks using a **dual-index architecture** that separates state variables by primary user interaction patterns: + +- **LP Index ($\mathcal{S}_{LP}$)**: State accessed/modified by liquidity providers +- **Trader Index ($\mathcal{S}_T$)**: State accessed/modified by traders/swappers + +This partitioning enables: +1. Efficient state queries per user type +2. Clear hook callback β†’ state mapping +3. Formal verification of hook invariants +4. Gas-optimized storage patterns + +--- + +## 2. State Vector Definitions + +### 2.1 Complete Pool State + +Following [Tranquilli & Gupta, 2025](https://arxiv.org/abs/2512.06203), Definition 1: + +``` +Pool Configuration: cfg = (ic, X, Y, Lact, L, Fx, Fy) +``` + +We decompose this into three partitions: + +$$ +\mathcal{S} = \mathcal{S}_{LP} \times \mathcal{S}_T \times \mathcal{S}_{shared} +$$ + +### 2.2 LP State Index ($\mathcal{S}_{LP}$) + +Variables primarily accessed by liquidity providers: + +| Variable | Type | Description | IStateView Getter | +|----------|------|-------------|-------------------| +| $L_k$ | `uint128` | Position liquidity | `getPositionLiquidity()` | +| $t_l^k$ | `int24` | Lower tick bound | `getPositionInfo()` | +| $t_u^k$ | `int24` | Upper tick bound | `getPositionInfo()` | +| $f_{0,k}^{in}$ | `uint256` | Fee growth inside (token0) | `getPositionInfo()` | +| $f_{1,k}^{in}$ | `uint256` | Fee growth inside (token1) | `getPositionInfo()` | +| $L_g^{tick}$ | `uint128` | Gross liquidity at tick | `getTickLiquidity()` | +| $L_n^{tick}$ | `int128` | Net liquidity at tick | `getTickLiquidity()` | +| $f_0^{out,tick}$ | `uint256` | Fee growth outside (token0) | `getTickFeeGrowthOutside()` | +| $f_1^{out,tick}$ | `uint256` | Fee growth outside (token1) | `getTickFeeGrowthOutside()` | + +**Formal Definition:** + +$$ +\mathcal{S}_{LP} = \bigcup_{k \in \mathcal{I}} \{(L_k, t_l^k, t_u^k, f_{0,k}^{in}, f_{1,k}^{in})\} \cup \bigcup_{i \in \text{Tick}} \{(L_g^i, L_n^i, f_0^{out,i}, f_1^{out,i})\} +$$ + +**Solidity Struct Mapping:** + +```solidity +/// @notice LP-indexed state for a position +/// @dev Maps to IStateView.getPositionInfo() +struct LPPositionState { + uint128 liquidity; // L_k + int24 tickLower; // t_l^k + int24 tickUpper; // t_u^k + uint256 feeGrowthInside0; // f_{0,k}^{in} + uint256 feeGrowthInside1; // f_{1,k}^{in} +} + +/// @notice LP-indexed state for a tick +/// @dev Maps to IStateView.getTickInfo() +struct LPTickState { + uint128 liquidityGross; // L_g^{tick} + int128 liquidityNet; // L_n^{tick} + uint256 feeGrowthOutside0; // f_0^{out,tick} + uint256 feeGrowthOutside1; // f_1^{out,tick} +} +``` + +### 2.3 Trader State Index ($\mathcal{S}_T$) + +Variables primarily accessed by traders during swaps: + +| Variable | Type | Description | IStateView Getter | +|----------|------|-------------|-------------------| +| $\sqrt{P}$ | `uint160` | Current sqrt price (Q64.96) | `getSlot0()` | +| $t_c$ | `int24` | Current tick | `getSlot0()` | +| $\phi_{lp}$ | `uint24` | LP fee (swap fee) | `getSlot0()` | +| $\phi_{proto}$ | `uint24` | Protocol fee | `getSlot0()` | +| $L_{act}$ | `uint128` | Active liquidity | `getLiquidity()` | +| $B_{tick}$ | `uint256` | Tick bitmap | `getTickBitmap()` | + +**Formal Definition:** + +$$ +\mathcal{S}_T = (\sqrt{P}, t_c, \phi_{lp}, \phi_{proto}, L_{act}, B_{tick}) +$$ + +**Solidity Struct Mapping:** + +```solidity +/// @notice Trader-indexed state (Slot0 + active liquidity) +/// @dev Maps to IStateView.getSlot0() and getLiquidity() +struct TraderState { + uint160 sqrtPriceX96; // sqrt(P) in Q64.96 + int24 tick; // t_c - current tick + uint24 lpFee; // phi_lp - fee paid to LPs + uint24 protocolFee; // phi_proto - protocol fee + uint128 liquidity; // L_act - active liquidity for swaps +} + +/// @notice Extended trader state with routing info +struct TraderStateExtended { + TraderState core; + uint256 tickBitmap; // B_tick - for finding next initialized tick +} +``` + +### 2.4 Shared State ($\mathcal{S}_{shared}$) + +Variables accessed by both LPs and traders: + +| Variable | Type | Description | IStateView Getter | +|----------|------|-------------|-------------------| +| $f_0^{global}$ | `uint256` | Global fee growth (token0) | `getFeeGrowthGlobals()` | +| $f_1^{global}$ | `uint256` | Global fee growth (token1) | `getFeeGrowthGlobals()` | + +**Formal Definition:** + +$$ +\mathcal{S}_{shared} = (f_0^{global}, f_1^{global}) +$$ + +**Derived Invariant** (from [arXiv:2512.06203](https://arxiv.org/abs/2512.06203), Definition 2): + +$$ +K_i(X, Y, L_{act}) := X \cdot Y +$$ + +Where $X, Y$ are virtual reserves computed from $L_{act}$ and $\sqrt{P}$. + +--- + +## 3. State Transition System + +### 3.1 Transition Types + +Following [Tranquilli & Gupta, 2025](https://arxiv.org/abs/2512.06203), Section III-B: + +``` +Transitions := SWAP(Ξ΄) | MINT(k, ...) | BURN(k) | CROSS(Β±) +``` + +### 3.2 Hook Callback β†’ State Mapping + +| Hook Callback | Transition Type | Primary Index | Secondary Index | State Changes | +|---------------|-----------------|---------------|-----------------|---------------| +| `beforeSwap` | SWAP | $\mathcal{S}_T$ | read $\mathcal{S}_{LP}$ | May modify fee, block swap | +| `afterSwap` | SWAP | $\mathcal{S}_T$, $\mathcal{S}_{shared}$ | - | Fee accounting, delta modifications | +| `beforeAddLiquidity` | MINT | $\mathcal{S}_{LP}$ | - | Validation, custom accounting | +| `afterAddLiquidity` | MINT | $\mathcal{S}_{LP}$ | $\mathcal{S}_T$ ($L_{act}$) | Position creation, liquidity update | +| `beforeRemoveLiquidity` | BURN | $\mathcal{S}_{LP}$ | - | Validation, lock checks | +| `afterRemoveLiquidity` | BURN | $\mathcal{S}_{LP}$ | $\mathcal{S}_T$ ($L_{act}$) | Position removal, fee collection | +| `beforeDonate` | - | $\mathcal{S}_{shared}$ | - | Custom donation logic | +| `afterDonate` | - | $\mathcal{S}_{shared}$ | - | Fee distribution | + +### 3.3 Formal Transition Rules + +**SWAP Transition (within tick):** + +From [arXiv:2512.06203](https://arxiv.org/abs/2512.06203), Section III-B: + +``` +Given cfg with tick ic and Lact > 0: + +X' = X + Ξ΄x +Y' = Y - βŒŠΟ†(Ξ΄x, Lact, ic)βŒ‹ +ic' = ic +Lact' = Lact +``` + +**Solidity Implementation Pattern:** + +```solidity +/// @notice State changes for a swap within a single tick +/// @dev Implements the discretized constant-product update +/// @param state Current trader state +/// @param deltaX Input amount of token0 +/// @return newState Updated trader state +/// @return deltaY Output amount of token1 +function applySwapTransition( + TraderState memory state, + int256 deltaX +) internal pure returns (TraderState memory newState, int256 deltaY) { + // K = X * Y (virtual reserves from L and sqrtP) + // X' = X + Ξ΄x + // Y' = ⌊K / X'βŒ‹ + + uint160 sqrtPriceNext = SqrtPriceMath.getNextSqrtPriceFromInput( + state.sqrtPriceX96, + state.liquidity, + uint256(deltaX), + true // zeroForOne + ); + + newState = TraderState({ + sqrtPriceX96: sqrtPriceNext, + tick: TickMath.getTickAtSqrtPrice(sqrtPriceNext), + lpFee: state.lpFee, + protocolFee: state.protocolFee, + liquidity: state.liquidity + }); + + deltaY = SqrtPriceMath.getAmount1Delta( + state.sqrtPriceX96, + sqrtPriceNext, + state.liquidity, + false // roundUp + ); +} +``` + +**CROSS Transition (tick crossing):** + +``` +If swap drives price to P_{ic+1}: + +ic' = ic + 1 +Lact' = Lact + Ξ”L_{ic+1} +X' = X (unchanged) +Y' = Y (unchanged) +``` + +**Solidity Implementation Pattern:** + +```solidity +/// @notice State changes when crossing a tick boundary +/// @dev Updates active liquidity based on net liquidity at tick +/// @param state Current trader state +/// @param tickNext The tick being crossed into +/// @param liquidityNet Net liquidity change at the tick boundary +/// @return newState Updated trader state +function applyTickCrossTransition( + TraderState memory state, + int24 tickNext, + int128 liquidityNet +) internal pure returns (TraderState memory newState) { + // Lact' = Lact + Ξ”L_{tick} + // Sign depends on direction: add when crossing up, subtract when crossing down + + bool crossingUp = tickNext > state.tick; + int128 liquidityDelta = crossingUp ? liquidityNet : -liquidityNet; + + newState = TraderState({ + sqrtPriceX96: TickMath.getSqrtPriceAtTick(tickNext), + tick: tickNext, + lpFee: state.lpFee, + protocolFee: state.protocolFee, + liquidity: LiquidityMath.addDelta(state.liquidity, liquidityDelta) + }); +} +``` + +--- + +## 4. Invariant Properties + +### 4.1 Tick-wise Constant Product Invariant + +From [arXiv:2512.06203](https://arxiv.org/abs/2512.06203), Lemma 1: + +**Single-Swap Bound:** + +$$ +K - X' \leq K' \leq K +$$ + +Where $K = X \cdot Y$ and $K' = X' \cdot Y'$. + +**Multi-Swap Bound (Theorem 1):** + +For a sequence of $n$ swaps with $X_j \leq B$ at each step: + +$$ +|K_n - K_0| \leq n \cdot B +$$ + +**Solidity Invariant Check:** + +```solidity +/// @notice Verifies the constant product invariant holds within epsilon +/// @dev Based on arXiv:2512.06203 Theorem 1 +/// @param k0 Initial product K = X * Y +/// @param kN Final product after n swaps +/// @param n Number of swaps executed +/// @param maxReserve Maximum reserve bound B +/// @return valid True if invariant holds +function checkProductInvariant( + uint256 k0, + uint256 kN, + uint256 n, + uint256 maxReserve +) internal pure returns (bool valid) { + // |K_n - K_0| <= n * B + uint256 epsilon = n * maxReserve; + + if (kN <= k0) { + return (k0 - kN) <= epsilon; + } else { + // K should never increase (rounding always reduces) + return false; + } +} +``` + +### 4.2 Cross-Tick k-Invariance + +From [arXiv:2512.06203](https://arxiv.org/abs/2512.06203), Definition 3: + +A CLAMM satisfies **cross-tick k-invariance** if: + +$$ +|K_{i_c}(X, Y, L_{act}) - k| \leq \epsilon +$$ + +for all reachable configurations and some constant $k$, $\epsilon \geq 0$. + +### 4.3 LP State Consistency Invariants + +```solidity +/// @notice Invariants that must hold for LP state consistency +interface ILPStateInvariants { + /// @dev Sum of position liquidities in range equals active liquidity + /// Ξ£ L_k (where t_l^k <= t_c < t_u^k) == L_act + function invariantActiveLiquiditySum(PoolId poolId) external view returns (bool); + + /// @dev Gross liquidity at tick equals sum of all positions touching that tick + /// L_g^{tick} == Ξ£ L_k (where t_l^k == tick OR t_u^k == tick) + function invariantGrossLiquiditySum(PoolId poolId, int24 tick) external view returns (bool); + + /// @dev Fee growth inside is bounded by global fee growth + /// f_{0,k}^{in} <= f_0^{global} for all positions k + function invariantFeeGrowthBounded(PoolId poolId, bytes32 positionId) external view returns (bool); +} +``` + +--- + +## 5. Hook State View Interface + +### 5.1 Proposed IHookStateView + +Extending `IStateView` for hook-specific state: + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +import {PoolId} from "@uniswap/v4-core/src/types/PoolId.sol"; + +/// @title IHookStateView +/// @notice Interface for querying hook-specific state partitioned by user type +/// @dev Extends the concept from IStateView with hook state variables +/// @custom:reference arXiv:2512.06203 - Formal State-Machine Models for Uniswap v3 +interface IHookStateView { + + // ============ LP Index Queries ============ + + /// @notice Get LP-relevant state for a specific position + /// @param poolId The pool identifier + /// @param owner Position owner + /// @param tickLower Lower tick bound + /// @param tickUpper Upper tick bound + /// @param salt Position salt + /// @return state The LP position state struct + function getLPPositionState( + PoolId poolId, + address owner, + int24 tickLower, + int24 tickUpper, + bytes32 salt + ) external view returns (LPPositionState memory state); + + /// @notice Get LP-relevant state for a tick + /// @param poolId The pool identifier + /// @param tick The tick index + /// @return state The LP tick state struct + function getLPTickState( + PoolId poolId, + int24 tick + ) external view returns (LPTickState memory state); + + /// @notice Batch query LP states for multiple positions + /// @param poolId The pool identifier + /// @param positionIds Array of position identifiers + /// @return states Array of LP position states + function batchGetLPPositionStates( + PoolId poolId, + bytes32[] calldata positionIds + ) external view returns (LPPositionState[] memory states); + + // ============ Trader Index Queries ============ + + /// @notice Get all trader-relevant state in a single call + /// @param poolId The pool identifier + /// @return state The trader state struct + function getTraderState( + PoolId poolId + ) external view returns (TraderState memory state); + + /// @notice Get extended trader state including routing info + /// @param poolId The pool identifier + /// @param tickBitmapIndex The word position in tick bitmap + /// @return state The extended trader state struct + function getTraderStateExtended( + PoolId poolId, + int16 tickBitmapIndex + ) external view returns (TraderStateExtended memory state); + + // ============ Shared State Queries ============ + + /// @notice Get global fee growth state + /// @param poolId The pool identifier + /// @return feeGrowthGlobal0 Global fee growth for token0 + /// @return feeGrowthGlobal1 Global fee growth for token1 + function getSharedFeeState( + PoolId poolId + ) external view returns (uint256 feeGrowthGlobal0, uint256 feeGrowthGlobal1); + + // ============ Hook-Specific State ============ + + /// @notice Get hook-specific state variables + /// @dev H in the notation (f_{it}(H, P)) + /// @param poolId The pool identifier + /// @return hookState Encoded hook state + function getHookState( + PoolId poolId + ) external view returns (bytes memory hookState); + + /// @notice Get hook state for a specific position + /// @param poolId The pool identifier + /// @param positionId The position identifier + /// @return hookPositionState Encoded hook state for position + function getHookPositionState( + PoolId poolId, + bytes32 positionId + ) external view returns (bytes memory hookPositionState); +} + +/// @notice LP-indexed state for a position +struct LPPositionState { + uint128 liquidity; + int24 tickLower; + int24 tickUpper; + uint256 feeGrowthInside0LastX128; + uint256 feeGrowthInside1LastX128; +} + +/// @notice LP-indexed state for a tick +struct LPTickState { + uint128 liquidityGross; + int128 liquidityNet; + uint256 feeGrowthOutside0X128; + uint256 feeGrowthOutside1X128; +} + +/// @notice Trader-indexed state +struct TraderState { + uint160 sqrtPriceX96; + int24 tick; + uint24 lpFee; + uint24 protocolFee; + uint128 liquidity; +} + +/// @notice Extended trader state with routing info +struct TraderStateExtended { + TraderState core; + uint256 tickBitmap; +} +``` + +--- + +## 6. Hook Specification Framework + +### 6.1 Hook as Dynamic System + +From the project notes, a hook is specified as: + +$$ +(f_{it}(H, P))_{i=1}^{N} +$$ + +Where: +- $f_i$ is the $i$-th hook callback function +- $H$ is the hook state (exposed via `IHookStateView.getHookState()`) +- $P$ is the pool state ($\mathcal{S}_{LP} \cup \mathcal{S}_T \cup \mathcal{S}_{shared}$) +- $N$ is the number of implemented callbacks + +### 6.2 Hook Specification Interface + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +import {PoolId} from "@uniswap/v4-core/src/types/PoolId.sol"; + +/// @title IHookSpecification +/// @notice Interface for declaring hook behavior as a formal specification +/// @dev Enables verification and attestation without code disclosure +/// @custom:reference Project NOTES.md - Hook specification framework +interface IHookSpecification { + + /// @notice Declares which state variables the hook reads + /// @return lpStateVars Bitmask of LP state variables accessed + /// @return traderStateVars Bitmask of trader state variables accessed + /// @return sharedStateVars Bitmask of shared state variables accessed + function declareStateReads() external pure returns ( + uint256 lpStateVars, + uint256 traderStateVars, + uint256 sharedStateVars + ); + + /// @notice Declares which state variables the hook writes + /// @return hookStateVars Bitmask of hook state variables modified + function declareStateWrites() external pure returns (uint256 hookStateVars); + + /// @notice Declares invariants the hook maintains + /// @return invariantIds Array of invariant identifiers + function declareInvariants() external pure returns (bytes32[] memory invariantIds); + + /// @notice Returns the IPFS hash of the formal specification document + /// @dev Document contains system of equations in LaTeX/markdown format + /// @return specHash IPFS CID of specification document + function specificationURI() external pure returns (string memory specHash); + + /// @notice Returns state transition bounds for verification + /// @param callback The callback being analyzed + /// @return maxStateChange Maximum state change magnitude + /// @return affectedVariables Variables potentially modified + function transitionBounds(bytes4 callback) external pure returns ( + uint256 maxStateChange, + bytes32[] memory affectedVariables + ); +} + +/// @notice State variable identifiers for bitmask operations +library StateVarIds { + // LP State Variables (bits 0-31) + uint256 constant LP_LIQUIDITY = 1 << 0; + uint256 constant LP_TICK_LOWER = 1 << 1; + uint256 constant LP_TICK_UPPER = 1 << 2; + uint256 constant LP_FEE_GROWTH_INSIDE_0 = 1 << 3; + uint256 constant LP_FEE_GROWTH_INSIDE_1 = 1 << 4; + uint256 constant LP_LIQUIDITY_GROSS = 1 << 5; + uint256 constant LP_LIQUIDITY_NET = 1 << 6; + uint256 constant LP_FEE_GROWTH_OUTSIDE_0 = 1 << 7; + uint256 constant LP_FEE_GROWTH_OUTSIDE_1 = 1 << 8; + + // Trader State Variables (bits 0-31) + uint256 constant TRADER_SQRT_PRICE = 1 << 0; + uint256 constant TRADER_TICK = 1 << 1; + uint256 constant TRADER_LP_FEE = 1 << 2; + uint256 constant TRADER_PROTOCOL_FEE = 1 << 3; + uint256 constant TRADER_LIQUIDITY = 1 << 4; + uint256 constant TRADER_TICK_BITMAP = 1 << 5; + + // Shared State Variables (bits 0-31) + uint256 constant SHARED_FEE_GROWTH_GLOBAL_0 = 1 << 0; + uint256 constant SHARED_FEE_GROWTH_GLOBAL_1 = 1 << 1; +} +``` + +--- + +## 7. Verification Integration + +### 7.1 Connecting to EigenLayer AVS + +For attestation without code disclosure: + +```solidity +/// @title IHookAttestationAVS +/// @notice Interface for EigenLayer AVS that verifies hook specifications +/// @custom:reference EigenLayer middleware contracts +interface IHookAttestationAVS { + + /// @notice Submit hook specification for verification + /// @param hook Address of the hook contract + /// @param specURI IPFS URI of formal specification + /// @param sampleData Fuzzer-generated test data + /// @return attestationId Unique identifier for this attestation request + function requestAttestation( + address hook, + string calldata specURI, + bytes calldata sampleData + ) external returns (bytes32 attestationId); + + /// @notice Check if a hook has valid attestation + /// @param hook Address of the hook contract + /// @return isValid True if hook has valid attestation + /// @return attestationId The attestation identifier + /// @return expiresAt Timestamp when attestation expires + function getAttestation(address hook) external view returns ( + bool isValid, + bytes32 attestationId, + uint256 expiresAt + ); + + /// @notice Verify state transition matches specification + /// @param hook Address of the hook + /// @param preState State before hook execution + /// @param postState State after hook execution + /// @param callback The callback that was executed + /// @return valid True if transition matches spec + function verifyTransition( + address hook, + bytes calldata preState, + bytes calldata postState, + bytes4 callback + ) external view returns (bool valid); +} +``` + +### 7.2 State Sampling for Fuzzer + +```solidity +/// @title IHookStateSampler +/// @notice Interface for sampling hook state for verification +/// @dev Used by fuzzer service to collect data for attestation +interface IHookStateSampler { + + /// @notice Sample current state snapshot + /// @param poolId The pool to sample + /// @return lpState Encoded LP state + /// @return traderState Encoded trader state + /// @return hookState Encoded hook-specific state + /// @return timestamp Block timestamp of sample + function sampleState(PoolId poolId) external view returns ( + bytes memory lpState, + bytes memory traderState, + bytes memory hookState, + uint256 timestamp + ); + + /// @notice Sample state transition + /// @param poolId The pool + /// @param callback The callback to execute + /// @param calldata_ The callback parameters + /// @return preState State before + /// @return postState State after + /// @return gasUsed Gas consumed + function sampleTransition( + PoolId poolId, + bytes4 callback, + bytes calldata calldata_ + ) external returns ( + bytes memory preState, + bytes memory postState, + uint256 gasUsed + ); +} +``` + +--- + +## 8. References + +1. **[arXiv:2512.06203]** Tranquilli, J., & Gupta, N. (2025). *Formal State-Machine Models for Uniswap v3 Concentrated-Liquidity AMMs: Priced Timed Automata, Finite-State Transducers, and Provable Rounding Bounds*. https://arxiv.org/abs/2512.06203 + +2. **[arXiv:2103.12732]** Xu, J., Paruch, K., Cousaert, S., & Feng, Y. (2021). *SoK: Decentralized Exchanges (DEX) with Automated Market Maker (AMM) Protocols*. https://arxiv.org/abs/2103.12732 + +3. **[arXiv:2103.00540]** Tolmach, P., Li, Y., Lin, S.-W., & Liu, Y. (2021). *Formal Analysis of Composable DeFi Protocols*. https://arxiv.org/abs/2103.00540 + +4. **[arXiv:2205.08904]** Heimbach, L., Schertenleib, E., & Wattenhofer, R. (2022). *Risks and Returns of Uniswap V3 Liquidity Providers*. https://arxiv.org/abs/2205.08904 + +5. **[Uniswap V4]** Adams, H. et al. *Uniswap V4 Core*. https://github.com/Uniswap/v4-core + +6. **[IStateView]** Uniswap V4 Periphery. `contracts/lib/v4-periphery/src/interfaces/IStateView.sol` + +--- + +## 9. Appendix: State Variable Quick Reference + +### IStateView β†’ Dual Index Mapping + +| IStateView Method | Returns | LP Index | Trader Index | Shared | +|-------------------|---------|:--------:|:------------:|:------:| +| `getSlot0()` | sqrtPriceX96, tick, protocolFee, lpFee | | X | | +| `getTickInfo()` | liquidityGross, liquidityNet, feeGrowthOutside0, feeGrowthOutside1 | X | | | +| `getTickLiquidity()` | liquidityGross, liquidityNet | X | | | +| `getTickFeeGrowthOutside()` | feeGrowthOutside0, feeGrowthOutside1 | X | | | +| `getFeeGrowthGlobals()` | feeGrowthGlobal0, feeGrowthGlobal1 | | | X | +| `getLiquidity()` | liquidity | | X | | +| `getTickBitmap()` | tickBitmap | | X | | +| `getPositionInfo()` | liquidity, feeGrowthInside0, feeGrowthInside1 | X | | | +| `getPositionLiquidity()` | liquidity | X | | | +| `getFeeGrowthInside()` | feeGrowthInside0, feeGrowthInside1 | X | | | From a27a4763a025e87d3d5ba0650adff1709c403d82 Mon Sep 17 00:00:00 2001 From: JMSBPP Date: Tue, 9 Dec 2025 22:37:17 -0500 Subject: [PATCH 2/3] feat: frontend hook developer components and updated packages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- client2/package-lock.json | 139 +++ client2/package.json | 10 + client2/src/App.tsx | 2 + .../src/components/HookDeveloperDashboard.tsx | 10 +- .../src/components/common/LatexRenderer.tsx | 136 +++ .../src/components/hook/CreateHookPage.tsx | 518 ++++++++++ .../src/components/hook/HookSpecEditor.tsx | 898 ++++++++++++++++++ .../components/hook/StateSpaceModelViewer.tsx | 510 ++++++++++ .../src/components/hook/SubmissionFlow.tsx | 683 +++++++++++++ .../src/components/hook/ValidationResults.tsx | 437 +++++++++ client2/src/components/hook/index.ts | 6 + .../lib/deployments/static-deployments.json | 9 +- client2/src/types/hookSpec.ts | 155 +++ 13 files changed, 3504 insertions(+), 9 deletions(-) create mode 100644 client2/package-lock.json create mode 100644 client2/package.json create mode 100644 client2/src/components/common/LatexRenderer.tsx create mode 100644 client2/src/components/hook/CreateHookPage.tsx create mode 100644 client2/src/components/hook/HookSpecEditor.tsx create mode 100644 client2/src/components/hook/StateSpaceModelViewer.tsx create mode 100644 client2/src/components/hook/SubmissionFlow.tsx create mode 100644 client2/src/components/hook/ValidationResults.tsx create mode 100644 client2/src/components/hook/index.ts create mode 100644 client2/src/types/hookSpec.ts diff --git a/client2/package-lock.json b/client2/package-lock.json new file mode 100644 index 000000000..90fd62a42 --- /dev/null +++ b/client2/package-lock.json @@ -0,0 +1,139 @@ +{ + "name": "client2", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "dependencies": { + "katex": "^0.16.27", + "react-katex": "^3.1.0" + }, + "devDependencies": { + "@types/katex": "^0.16.7", + "@types/react-katex": "^3.0.4" + } + }, + "node_modules/@types/katex": { + "version": "0.16.7", + "resolved": "https://registry.npmjs.org/@types/katex/-/katex-0.16.7.tgz", + "integrity": "sha512-HMwFiRujE5PjrgwHQ25+bsLJgowjGjm5Z8FVSf0N6PwgJrwxH0QxzHYDcKsTfV3wva0vzrpqMTJS2jXPr5BMEQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/react": { + "version": "19.2.7", + "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.7.tgz", + "integrity": "sha512-MWtvHrGZLFttgeEj28VXHxpmwYbor/ATPYbBfSFZEIRK0ecCFLl2Qo55z52Hss+UV9CRN7trSeq1zbgx7YDWWg==", + "dev": true, + "license": "MIT", + "dependencies": { + "csstype": "^3.2.2" + } + }, + "node_modules/@types/react-katex": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/react-katex/-/react-katex-3.0.4.tgz", + "integrity": "sha512-aLkykKzSKLpXI6REJ3uClao6P47HAFfR1gcHOZwDeTuALsyjgMhz+oynLV4gX0kiJVnvHrBKF/TLXqyNTpHDUg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/react": "*" + } + }, + "node_modules/csstype": { + "version": "3.2.3", + "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz", + "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/js-tokens": { + "version": "4.0.0", + "license": "MIT", + "peer": true + }, + "node_modules/katex": { + "version": "0.16.27", + "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.27.tgz", + "integrity": "sha512-aeQoDkuRWSqQN6nSvVCEFvfXdqo1OQiCmmW1kc9xSdjutPv7BGO7pqY9sQRJpMOGrEdfDgF2TfRXe5eUAD2Waw==", + "funding": [ + "https://opencollective.com/katex", + "https://github.com/sponsors/katex" + ], + "license": "MIT", + "dependencies": { + "commander": "^8.3.0" + }, + "bin": { + "katex": "cli.js" + } + }, + "node_modules/katex/node_modules/commander": { + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz", + "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==", + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/loose-envify": { + "version": "1.4.0", + "license": "MIT", + "peer": true, + "dependencies": { + "js-tokens": "^3.0.0 || ^4.0.0" + }, + "bin": { + "loose-envify": "cli.js" + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "license": "MIT", + "peer": true, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/prop-types": { + "version": "15.8.1", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.4.0", + "object-assign": "^4.1.1", + "react-is": "^16.13.1" + } + }, + "node_modules/prop-types/node_modules/react-is": { + "version": "16.13.1", + "license": "MIT", + "peer": true + }, + "node_modules/react": { + "version": "18.3.1", + "license": "MIT", + "peer": true, + "dependencies": { + "loose-envify": "^1.1.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/react-katex": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/react-katex/-/react-katex-3.1.0.tgz", + "integrity": "sha512-At9uLOkC75gwn2N+ZXc5HD8TlATsB+3Hkp9OGs6uA8tM3dwZ3Wljn74Bk3JyHFPgSnesY/EMrIAB1WJwqZqejA==", + "license": "MIT", + "dependencies": { + "katex": "^0.16.0" + }, + "peerDependencies": { + "prop-types": "^15.8.1", + "react": ">=15.3.2 <20" + } + } + } +} diff --git a/client2/package.json b/client2/package.json new file mode 100644 index 000000000..1f7443caa --- /dev/null +++ b/client2/package.json @@ -0,0 +1,10 @@ +{ + "dependencies": { + "katex": "^0.16.27", + "react-katex": "^3.1.0" + }, + "devDependencies": { + "@types/katex": "^0.16.7", + "@types/react-katex": "^3.0.4" + } +} diff --git a/client2/src/App.tsx b/client2/src/App.tsx index ca8cc3611..d78c9966c 100644 --- a/client2/src/App.tsx +++ b/client2/src/App.tsx @@ -7,6 +7,7 @@ import ProtocolDesignerDashboard from './components/ProtocolDesignerDashboard'; import CreateProtocolPage from './components/protocol/CreateProtocolPage'; import IntegratorPortal from './components/IntegratorPortal'; import SkipLink from './components/common/SkipLink'; +import { CreateHookPage } from './components/hook'; export default function App() { return ( @@ -19,6 +20,7 @@ export default function App() { {}} />} /> {}} />} /> {}} />} /> + } /> {}} />} /> } /> {}} />} /> diff --git a/client2/src/components/HookDeveloperDashboard.tsx b/client2/src/components/HookDeveloperDashboard.tsx index 3bc2c4769..042a3f2dc 100644 --- a/client2/src/components/HookDeveloperDashboard.tsx +++ b/client2/src/components/HookDeveloperDashboard.tsx @@ -1,4 +1,5 @@ import { ArrowLeft, Code, DollarSign, Package, Plus, TrendingUp } from 'lucide-react'; +import { useNavigate } from 'react-router-dom'; import Navigation from './Navigation'; import Footer from './Footer'; @@ -7,6 +8,12 @@ interface HookDeveloperDashboardProps { } export default function HookDeveloperDashboard({ onNavigate }: HookDeveloperDashboardProps) { + const navigate = useNavigate(); + + const handleCreateHook = () => { + navigate('/hook-developer/create'); + }; + const stats = [ { icon: Package, label: 'Total Hooks', value: '3', color: 'primary' }, { icon: DollarSign, label: 'Total Revenue', value: '$12,450', color: 'secondary' }, @@ -95,6 +102,7 @@ export default function HookDeveloperDashboard({ onNavigate }: HookDeveloperDash diff --git a/client2/src/components/common/LatexRenderer.tsx b/client2/src/components/common/LatexRenderer.tsx new file mode 100644 index 000000000..6ed0bc013 --- /dev/null +++ b/client2/src/components/common/LatexRenderer.tsx @@ -0,0 +1,136 @@ +import { useMemo } from 'react'; +import katex from 'katex'; +import 'katex/dist/katex.min.css'; + +interface LatexRendererProps { + latex: string; + displayMode?: boolean; + className?: string; + style?: React.CSSProperties; +} + +/** + * Renders LaTeX mathematical expressions using KaTeX + * Handles both inline ($...$) and display ($$...$$) math + */ +export default function LatexRenderer({ + latex, + displayMode = false, + className = '', + style = {} +}: LatexRendererProps) { + const renderedHtml = useMemo(() => { + try { + // Clean up the LaTeX string - handle common subscript/superscript patterns + let cleanLatex = latex; + + // If it doesn't look like LaTeX, wrap simple subscripts + if (!latex.includes('\\') && !latex.includes('{')) { + // Convert simple patterns like L_k to L_{k} + cleanLatex = latex + .replace(/([A-Za-z])_([A-Za-z0-9])/g, '$1_{$2}') + .replace(/([A-Za-z])\^([A-Za-z0-9])/g, '$1^{$2}'); + } + + return katex.renderToString(cleanLatex, { + displayMode, + throwOnError: false, + strict: false, + trust: true, + macros: { + // Common macros for DeFi/AMM notation + '\\R': '\\mathbb{R}', + '\\N': '\\mathbb{N}', + '\\Z': '\\mathbb{Z}', + } + }); + } catch (error) { + // Fallback to plain text if LaTeX parsing fails + return `${latex}`; + } + }, [latex, displayMode]); + + return ( + + ); +} + +/** + * Parse and render a string that may contain mixed text and LaTeX + * Handles inline $...$ and display $$...$$ delimiters + */ +export function MixedLatexRenderer({ + content, + className = '', + style = {} +}: { + content: string; + className?: string; + style?: React.CSSProperties; +}) { + const parts = useMemo(() => { + const result: { type: 'text' | 'latex' | 'displayLatex'; content: string }[] = []; + + // Match $$...$$ (display) and $...$ (inline) + const regex = /(\$\$[\s\S]*?\$\$|\$[^$]+\$)/g; + let lastIndex = 0; + let match; + + while ((match = regex.exec(content)) !== null) { + // Add text before this match + if (match.index > lastIndex) { + result.push({ + type: 'text', + content: content.slice(lastIndex, match.index) + }); + } + + // Add the LaTeX part + const matched = match[0]; + if (matched.startsWith('$$')) { + result.push({ + type: 'displayLatex', + content: matched.slice(2, -2) + }); + } else { + result.push({ + type: 'latex', + content: matched.slice(1, -1) + }); + } + + lastIndex = regex.lastIndex; + } + + // Add remaining text + if (lastIndex < content.length) { + result.push({ + type: 'text', + content: content.slice(lastIndex) + }); + } + + return result; + }, [content]); + + return ( + + {parts.map((part, index) => { + if (part.type === 'text') { + return {part.content}; + } + return ( + + ); + })} + + ); +} diff --git a/client2/src/components/hook/CreateHookPage.tsx b/client2/src/components/hook/CreateHookPage.tsx new file mode 100644 index 000000000..d14481877 --- /dev/null +++ b/client2/src/components/hook/CreateHookPage.tsx @@ -0,0 +1,518 @@ +import { useState, useCallback } from 'react'; +import { ArrowLeft, ChevronRight } from 'lucide-react'; +import { useNavigate } from 'react-router-dom'; +import Navigation from '../Navigation'; +import Footer from '../Footer'; +import StateSpaceModelViewer from './StateSpaceModelViewer'; +import HookSpecEditor from './HookSpecEditor'; +import ValidationResults from './ValidationResults'; +import SubmissionFlow from './SubmissionFlow'; +import type { + HookSpec, + StateSpaceModel, + ValidationResult, + SubmissionResult, + SystemStateVariable +} from '../../types/hookSpec'; + +interface CreateHookPageProps { + onNavigate?: (page: string) => void; +} + +type FlowStep = 'view-model' | 'edit-spec' | 'validate' | 'submit'; + +const STEPS: { id: FlowStep; title: string; description: string }[] = [ + { + id: 'view-model', + title: 'View State Model', + description: 'Review available pool state variables' + }, + { + id: 'edit-spec', + title: 'Write HookSpec', + description: 'Define your hook behavior' + }, + { + id: 'validate', + title: 'Validate', + description: 'Check compatibility' + }, + { + id: 'submit', + title: 'Submit', + description: 'Mint HookLicense NFT' + } +]; + +// Mock data - replace with API calls +const MOCK_STATE_SPACE_MODEL: StateSpaceModel = { + version: '1.0.0', + ipfsCid: 'QmSystemStateModelV1abc123def456', + uniswapVersion: 'v4', + updatedAt: '2025-12-09', + indices: { + lp: [ + { + name: 'position_liquidity', + symbol: 'L_k', + type: 'uint128', + getter: 'getPositionLiquidity(poolId, positionId)', + description: 'Liquidity amount for a specific position' + }, + { + name: 'tick_lower', + symbol: 't_l^k', + type: 'int24', + getter: 'getPositionInfo(poolId, positionId)', + description: 'Lower tick bound of position' + }, + { + name: 'tick_upper', + symbol: 't_u^k', + type: 'int24', + getter: 'getPositionInfo(poolId, positionId)', + description: 'Upper tick bound of position' + }, + { + name: 'fee_growth_inside_0', + symbol: 'f_{0,k}^{in}', + type: 'uint256', + getter: 'getPositionInfo(poolId, positionId)', + description: 'Fee growth inside position for token0' + }, + { + name: 'fee_growth_inside_1', + symbol: 'f_{1,k}^{in}', + type: 'uint256', + getter: 'getPositionInfo(poolId, positionId)', + description: 'Fee growth inside position for token1' + }, + { + name: 'liquidity_gross', + symbol: 'L_g^{tick}', + type: 'uint128', + getter: 'getTickLiquidity(poolId, tick)', + description: 'Gross liquidity at tick' + }, + { + name: 'liquidity_net', + symbol: 'L_n^{tick}', + type: 'int128', + getter: 'getTickLiquidity(poolId, tick)', + description: 'Net liquidity change at tick' + } + ], + trader: [ + { + name: 'sqrt_price', + symbol: '\\sqrt{P}', + type: 'uint160', + getter: 'getSlot0(poolId)', + description: 'Current sqrt price in Q64.96 format' + }, + { + name: 'current_tick', + symbol: 't_c', + type: 'int24', + getter: 'getSlot0(poolId)', + description: 'Current tick index' + }, + { + name: 'lp_fee', + symbol: '\\phi_{lp}', + type: 'uint24', + getter: 'getSlot0(poolId)', + description: 'Fee paid to liquidity providers' + }, + { + name: 'protocol_fee', + symbol: '\\phi_{proto}', + type: 'uint24', + getter: 'getSlot0(poolId)', + description: 'Protocol fee percentage' + }, + { + name: 'active_liquidity', + symbol: 'L_{act}', + type: 'uint128', + getter: 'getLiquidity(poolId)', + description: 'Currently active liquidity for swaps' + }, + { + name: 'tick_bitmap', + symbol: 'B_{tick}', + type: 'uint256', + getter: 'getTickBitmap(poolId, wordPos)', + description: 'Bitmap for initialized ticks' + } + ], + shared: [ + { + name: 'fee_growth_global_0', + symbol: 'f_0^{global}', + type: 'uint256', + getter: 'getFeeGrowthGlobals(poolId)', + description: 'Cumulative fee growth for token0' + }, + { + name: 'fee_growth_global_1', + symbol: 'f_1^{global}', + type: 'uint256', + getter: 'getFeeGrowthGlobals(poolId)', + description: 'Cumulative fee growth for token1' + } + ] + } +}; + +export default function CreateHookPage({ onNavigate }: CreateHookPageProps) { + const navigate = useNavigate(); + const [currentStep, setCurrentStep] = useState('view-model'); + const [hookSpec, setHookSpec] = useState(null); + const [validationResults, setValidationResults] = useState([]); + const [isValidating, setIsValidating] = useState(false); + const [validationPassed, setValidationPassed] = useState(false); + + // Mock wallet state - replace with actual wallet integration + const [walletConnected, setWalletConnected] = useState(false); + const [walletAddress, setWalletAddress] = useState(undefined); + + const handleNavigate = (page: string) => { + if (onNavigate) { + onNavigate(page); + } else { + navigate(`/${page}`); + } + }; + + const handleSelectVariable = useCallback((variable: SystemStateVariable) => { + // Could open a tooltip or copy to clipboard + console.log('Selected variable:', variable); + }, []); + + const handleSpecChange = useCallback((spec: HookSpec) => { + setHookSpec(spec); + // Reset validation when spec changes + setValidationResults([]); + setValidationPassed(false); + }, []); + + const handleValidate = useCallback(async () => { + if (!hookSpec) return; + + setIsValidating(true); + setValidationResults([]); + + // Simulate API call + await new Promise(resolve => setTimeout(resolve, 1500)); + + // Mock validation results + const mockResults: ValidationResult[] = [ + { + ruleId: 'V1', + ruleName: 'ValidPoolStateReferences', + passed: true, + errors: [], + warnings: [] + }, + { + ruleId: 'V2', + ruleName: 'UniqueHookStateNames', + passed: hookSpec.hook_state.length === new Set(hookSpec.hook_state.map(v => v.name)).size, + errors: hookSpec.hook_state.length !== new Set(hookSpec.hook_state.map(v => v.name)).size + ? ['Duplicate hook state variable names detected'] + : [], + warnings: [] + }, + { + ruleId: 'V3', + ruleName: 'ValidCallbacks', + passed: true, + errors: [], + warnings: [] + }, + { + ruleId: 'V4', + ruleName: 'ValidEquationSymbols', + passed: true, + errors: [], + warnings: hookSpec.system_functions.some(f => !f.transition.equation) + ? ['Some functions are missing transition equations'] + : [] + }, + { + ruleId: 'V5', + ruleName: 'ValidSolidityTypes', + passed: true, + errors: [], + warnings: [] + }, + { + ruleId: 'V6', + ruleName: 'WritesMatchHookState', + passed: true, + errors: [], + warnings: [] + } + ]; + + setValidationResults(mockResults); + setValidationPassed(mockResults.every(r => r.passed)); + setIsValidating(false); + setCurrentStep('validate'); + }, [hookSpec]); + + const handleSubmit = useCallback(async (): Promise => { + // Simulate submission + await new Promise(resolve => setTimeout(resolve, 2000)); + + return { + success: true, + ipfsCid: 'QmNewHookSpec' + Math.random().toString(36).slice(2, 10), + tokenId: Math.floor(Math.random() * 1000) + 1, + transactionHash: '0x' + Math.random().toString(16).slice(2) + Math.random().toString(16).slice(2), + ownerAddress: walletAddress || '0x0000000000000000000000000000000000000000', + ipfsGatewayUrl: 'https://ipfs.io/ipfs/QmNewHookSpec...', + openSeaUrl: 'https://opensea.io/assets/ethereum/...' + }; + }, [walletAddress]); + + const handleConnectWallet = useCallback(() => { + // Simulate wallet connection + setWalletConnected(true); + setWalletAddress('0x1234567890abcdef1234567890abcdef12345678'); + }, []); + + const goToStep = (step: FlowStep) => { + // Only allow going back or to already completed steps + const stepOrder: FlowStep[] = ['view-model', 'edit-spec', 'validate', 'submit']; + const currentIndex = stepOrder.indexOf(currentStep); + const targetIndex = stepOrder.indexOf(step); + + if (targetIndex <= currentIndex || (step === 'submit' && validationPassed)) { + setCurrentStep(step); + } + }; + + const nextStep = () => { + const stepOrder: FlowStep[] = ['view-model', 'edit-spec', 'validate', 'submit']; + const currentIndex = stepOrder.indexOf(currentStep); + if (currentIndex < stepOrder.length - 1) { + setCurrentStep(stepOrder[currentIndex + 1]); + } + }; + + return ( +
+ + + {/* Hero Section */} +
+
+ + +

+ Create New Hook +

+

+ Define your hook specification and mint a HookLicense NFT +

+
+
+ + {/* Step Indicator */} +
+
+
+ {STEPS.map((step, index) => { + const stepOrder: FlowStep[] = ['view-model', 'edit-spec', 'validate', 'submit']; + const currentIndex = stepOrder.indexOf(currentStep); + const stepIndex = stepOrder.indexOf(step.id); + const isActive = step.id === currentStep; + const isCompleted = stepIndex < currentIndex; + const isAccessible = stepIndex <= currentIndex || (step.id === 'submit' && validationPassed); + + return ( +
+ + + {index < STEPS.length - 1 && ( + + )} +
+ ); + })} +
+
+
+ + {/* Main Content */} +
+
+
+ {/* Left Panel - State Space Model (Always visible) */} +
+ + + {currentStep === 'view-model' && ( + + )} +
+ + {/* Right Panel - Editor/Validation/Submission */} + {currentStep !== 'view-model' && ( +
+ {(currentStep === 'edit-spec' || currentStep === 'validate') && ( + + )} + + {currentStep === 'validate' && ( + <> + + + {validationPassed && ( + + )} + + )} + + {currentStep === 'submit' && hookSpec && ( + + )} +
+ )} +
+
+
+ +
+
+ ); +} diff --git a/client2/src/components/hook/HookSpecEditor.tsx b/client2/src/components/hook/HookSpecEditor.tsx new file mode 100644 index 000000000..a3cac51e4 --- /dev/null +++ b/client2/src/components/hook/HookSpecEditor.tsx @@ -0,0 +1,898 @@ +import { useState, useCallback } from 'react'; +import { Upload, FileText, AlertCircle, CheckCircle, Info, Eye } from 'lucide-react'; +import type { HookSpec, StateSpaceModel, HookCallback } from '../../types/hookSpec'; +import LatexRenderer from '../common/LatexRenderer'; + +interface HookSpecEditorProps { + initialSpec?: HookSpec; + stateSpaceModel: StateSpaceModel; + onChange: (spec: HookSpec) => void; + onValidate: () => void; + isValidating?: boolean; +} + +const VALID_CALLBACKS: HookCallback[] = [ + 'beforeInitialize', 'afterInitialize', + 'beforeAddLiquidity', 'afterAddLiquidity', + 'beforeRemoveLiquidity', 'afterRemoveLiquidity', + 'beforeSwap', 'afterSwap', + 'beforeDonate', 'afterDonate' +]; + +const SOLIDITY_TYPES = [ + 'uint8', 'uint16', 'uint24', 'uint32', 'uint64', 'uint128', 'uint256', + 'int8', 'int16', 'int24', 'int32', 'int64', 'int128', 'int256', + 'address', 'bool', 'bytes32' +]; + +const DEFAULT_SPEC: HookSpec = { + metadata: { + name: '', + version: '1.0.0', + author: '', + description: '', + license: 'MIT' + }, + hook_state: [], + system_functions: [], + invariants: [] +}; + +export default function HookSpecEditor({ + initialSpec, + stateSpaceModel, + onChange, + onValidate, + isValidating = false +}: HookSpecEditorProps) { + const [spec, setSpec] = useState(initialSpec || DEFAULT_SPEC); + const [activeTab, setActiveTab] = useState<'metadata' | 'state' | 'functions' | 'invariants'>('metadata'); + const [uploadError, setUploadError] = useState(null); + + // Get all available state variables for autocomplete + const availableStateVars = [ + ...stateSpaceModel.indices.lp.map(v => v.name), + ...stateSpaceModel.indices.trader.map(v => v.name), + ...stateSpaceModel.indices.shared.map(v => v.name) + ]; + + const updateSpec = useCallback((updates: Partial) => { + const newSpec = { ...spec, ...updates }; + setSpec(newSpec); + onChange(newSpec); + }, [spec, onChange]); + + const handleFileUpload = async (event: React.ChangeEvent) => { + const file = event.target.files?.[0]; + if (!file) return; + + setUploadError(null); + + try { + // Handle PDF files + if (file.name.endsWith('.pdf')) { + // For PDF, we can't parse it directly in browser without a library + // Inform user that PDF upload will store reference for manual processing + setUploadError( + 'PDF files are accepted for reference. The PDF will be stored alongside your HookSpec. ' + + 'Please also fill in the form fields below to create the machine-readable specification.' + ); + // Store PDF reference in metadata + const pdfUrl = URL.createObjectURL(file); + updateSpec({ + metadata: { + ...spec.metadata, + description: `${spec.metadata.description || ''}\n\n[Uploaded PDF: ${file.name}]`.trim(), + attachments: [{ type: 'pdf', name: file.name, url: pdfUrl }] + } + }); + return; + } + + const content = await file.text(); + let parsed: HookSpec; + + if (file.name.endsWith('.json')) { + parsed = JSON.parse(content); + } else if (file.name.endsWith('.yaml') || file.name.endsWith('.yml')) { + // Simple YAML parsing (in production, use a proper YAML library) + setUploadError('YAML parsing requires a YAML library. Please use JSON format.'); + return; + } else { + setUploadError('Unsupported file format. Supported formats: .json, .yaml, .yml, .pdf'); + return; + } + + // Basic validation + if (!parsed.metadata?.name || !parsed.metadata?.version) { + setUploadError('Invalid HookSpec: missing required metadata fields'); + return; + } + + setSpec(parsed); + onChange(parsed); + } catch (error) { + setUploadError(`Failed to parse file: ${error instanceof Error ? error.message : 'Unknown error'}`); + } + }; + + const addHookStateVariable = () => { + updateSpec({ + hook_state: [ + ...spec.hook_state, + { name: '', symbol: '', type: 'uint256', description: '' } + ] + }); + }; + + const removeHookStateVariable = (index: number) => { + updateSpec({ + hook_state: spec.hook_state.filter((_, i) => i !== index) + }); + }; + + const updateHookStateVariable = (index: number, field: string, value: string) => { + const newState = [...spec.hook_state]; + newState[index] = { ...newState[index], [field]: value }; + updateSpec({ hook_state: newState }); + }; + + const addSystemFunction = () => { + updateSpec({ + system_functions: [ + ...spec.system_functions, + { + callback: 'afterSwap', + reads: [], + writes: [], + transition: { + preconditions: [], + equation: '', + postconditions: [] + } + } + ] + }); + }; + + const removeSystemFunction = (index: number) => { + updateSpec({ + system_functions: spec.system_functions.filter((_, i) => i !== index) + }); + }; + + const addInvariant = () => { + updateSpec({ + invariants: [ + ...(spec.invariants || []), + { name: '', expression: '', description: '' } + ] + }); + }; + + const removeInvariant = (index: number) => { + updateSpec({ + invariants: (spec.invariants || []).filter((_, i) => i !== index) + }); + }; + + return ( +
+ {/* Header */} +
+
+

+ HookSpec Editor +

+

+ Define your hook's state variables and system functions +

+
+ + {/* Upload Button */} + +
+ + {/* Upload Error */} + {uploadError && ( +
+ + + {uploadError} + +
+ )} + + {/* Tabs */} +
+ {(['metadata', 'state', 'functions', 'invariants'] as const).map(tab => ( + + ))} +
+ + {/* Metadata Tab */} + {activeTab === 'metadata' && ( +
+
+
+ + updateSpec({ + metadata: { ...spec.metadata, name: e.target.value } + })} + placeholder="e.g., DynamicFeeHook" + className="angular-clip w-full px-3 py-2 font-body" + style={{ + background: 'var(--color-marble-light)', + border: '2px solid var(--color-secondary)', + color: 'var(--color-secondary)', + fontSize: 'var(--font-size-body-sm)' + }} + /> +
+ +
+ + updateSpec({ + metadata: { ...spec.metadata, version: e.target.value } + })} + placeholder="1.0.0" + className="angular-clip w-full px-3 py-2 font-body" + style={{ + background: 'var(--color-marble-light)', + border: '2px solid var(--color-secondary)', + color: 'var(--color-secondary)', + fontSize: 'var(--font-size-body-sm)' + }} + /> +
+ +
+ + updateSpec({ + metadata: { ...spec.metadata, author: e.target.value } + })} + placeholder="0x..." + className="angular-clip w-full px-3 py-2 font-mono" + style={{ + background: 'var(--color-marble-light)', + border: '2px solid var(--color-secondary)', + color: 'var(--color-secondary)', + fontSize: 'var(--font-size-body-sm)' + }} + /> +
+ +
+ + +
+
+ +
+ +