diff --git a/demo/presentation.aux b/demo/presentation.aux index 56776afa..a45274ef 100644 --- a/demo/presentation.aux +++ b/demo/presentation.aux @@ -19,9 +19,15 @@ \HyPL@Entry{5<>} \@writefile{nav}{\headcommand {\slideentry {0}{0}{6}{6/6}{}{0}}} \@writefile{nav}{\headcommand {\beamer@framepages {6}{6}}} -\@writefile{nav}{\headcommand {\beamer@partpages {1}{6}}} -\@writefile{nav}{\headcommand {\beamer@subsectionpages {1}{6}}} -\@writefile{nav}{\headcommand {\beamer@sectionpages {1}{6}}} -\@writefile{nav}{\headcommand {\beamer@documentpages {6}}} -\@writefile{nav}{\headcommand {\gdef \inserttotalframenumber {6}}} -\gdef \@abspage@last{6} +\HyPL@Entry{6<>} +\@writefile{nav}{\headcommand {\slideentry {0}{0}{7}{7/7}{}{0}}} +\@writefile{nav}{\headcommand {\beamer@framepages {7}{7}}} +\HyPL@Entry{7<>} +\@writefile{nav}{\headcommand {\slideentry {0}{0}{8}{8/8}{}{0}}} +\@writefile{nav}{\headcommand {\beamer@framepages {8}{8}}} +\@writefile{nav}{\headcommand {\beamer@partpages {1}{8}}} +\@writefile{nav}{\headcommand {\beamer@subsectionpages {1}{8}}} +\@writefile{nav}{\headcommand {\beamer@sectionpages {1}{8}}} +\@writefile{nav}{\headcommand {\beamer@documentpages {8}}} +\@writefile{nav}{\headcommand {\gdef \inserttotalframenumber {8}}} +\gdef \@abspage@last{8} diff --git a/demo/presentation.nav b/demo/presentation.nav index 2094a074..0244164f 100644 --- a/demo/presentation.nav +++ b/demo/presentation.nav @@ -10,8 +10,12 @@ \headcommand {\beamer@framepages {5}{5}} \headcommand {\slideentry {0}{0}{6}{6/6}{}{0}} \headcommand {\beamer@framepages {6}{6}} -\headcommand {\beamer@partpages {1}{6}} -\headcommand {\beamer@subsectionpages {1}{6}} -\headcommand {\beamer@sectionpages {1}{6}} -\headcommand {\beamer@documentpages {6}} -\headcommand {\gdef \inserttotalframenumber {6}} +\headcommand {\slideentry {0}{0}{7}{7/7}{}{0}} +\headcommand {\beamer@framepages {7}{7}} +\headcommand {\slideentry {0}{0}{8}{8/8}{}{0}} +\headcommand {\beamer@framepages {8}{8}} +\headcommand {\beamer@partpages {1}{8}} +\headcommand {\beamer@subsectionpages {1}{8}} +\headcommand {\beamer@sectionpages {1}{8}} +\headcommand {\beamer@documentpages {8}} +\headcommand {\gdef \inserttotalframenumber {8}} diff --git a/demo/presentation.pdf b/demo/presentation.pdf index ba66660c..ed3a1fe1 100644 Binary files a/demo/presentation.pdf and b/demo/presentation.pdf differ diff --git a/demo/presentation.vrb b/demo/presentation.vrb new file mode 100644 index 00000000..37f8fac7 --- /dev/null +++ b/demo/presentation.vrb @@ -0,0 +1,44 @@ +\frametitle{How HookBazaar Works} + +\begin{center} +\begin{tikzpicture}[ + scale=0.72, + step/.style={draw=hbPrimary, line width=1.5pt, fill=hbSecondary, rounded corners=5pt, minimum width=2.2cm, minimum height=1.2cm, align=center, font=\scriptsize}, + detail/.style={draw=hbAccent, fill=hbBgDark, rounded corners=3pt, minimum width=1.8cm, minimum height=0.6cm, align=center, font=\tiny}, + arrow/.style={-{Stealth}, thick, hbPrimary} +] + % 5 Steps + \node[step] (s1) at (0,0) {\textcolor{hbPrimary}{\textbf{1}} \\ \textcolor{hbWhite}{Protocol} \\ \textcolor{hbWhite}{Definition}}; + \node[step] (s2) at (3.2,0) {\textcolor{hbPrimary}{\textbf{2}} \\ \textcolor{hbWhite}{Browse} \\ \textcolor{hbWhite}{Hooks}}; + \node[step] (s3) at (6.4,0) {\textcolor{hbPrimary}{\textbf{3}} \\ \textcolor{hbWhite}{AVS} \\ \textcolor{hbWhite}{Verification}}; + \node[step] (s4) at (9.6,0) {\textcolor{hbPrimary}{\textbf{4}} \\ \textcolor{hbWhite}{IP} \\ \textcolor{hbWhite}{Protection}}; + \node[step] (s5) at (12.8,0) {\textcolor{hbPrimary}{\textbf{5}} \\ \textcolor{hbWhite}{Market} \\ \textcolor{hbWhite}{Dynamics}}; + + % Details below + \node[detail] at (0,-1.2) {\textcolor{hbMarble}{Pools + Master}}; + \node[detail] at (3.2,-1.2) {\textcolor{hbMarble}{Specs + Compat}}; + \node[detail] at (6.4,-1.2) {\textcolor{hbMarble}{EigenLayer}}; + \node[detail] at (9.6,-1.2) {\textcolor{hbMarble}{Fhenix FHE}}; + \node[detail] at (12.8,-1.2) {\textcolor{hbMarble}{Price by Demand}}; + + % Arrows + \draw[arrow] (s1) -- (s2); + \draw[arrow] (s2) -- (s3); + \draw[arrow] (s3) -- (s4); + \draw[arrow] (s4) -- (s5); + + % Hook Submission Flow (bottom) + \node[draw=hbPrimary, dashed, rounded corners=8pt, minimum width=13cm, minimum height=1.8cm] at (6.4,-3) {}; + + \node[draw=hbAccent, fill=hbSecondary, rounded corners=3pt, minimum width=1.6cm, minimum height=0.7cm, font=\tiny, align=center] (c1) at (1.5,-2.8) {Encrypted\\Code}; + \node[draw=hbAccent, fill=hbSecondary, rounded corners=3pt, minimum width=1.6cm, minimum height=0.7cm, font=\tiny, align=center] (c2) at (4.5,-2.8) {Formal\\Spec}; + \node[draw=hbSuccess, fill=hbSecondary, rounded corners=3pt, minimum width=1.6cm, minimum height=0.7cm, font=\tiny, align=center] (c3) at (7.5,-2.8) {AVS\\Attestation}; + \node[draw=hbPrimary, fill=hbSecondary, rounded corners=3pt, minimum width=1.6cm, minimum height=0.7cm, font=\tiny, align=center] (c4) at (10.5,-2.8) {Listed in\\Market}; + + \draw[-{Stealth}, hbAccent, thick] (c1) -- (c2); + \draw[-{Stealth}, hbAccent, thick] (c2) -- (c3); + \draw[-{Stealth}, hbSuccess, thick] (c3) -- (c4); + + \node[text=hbMarble, font=\tiny] at (6.4,-3.8) {Hook Submission Flow}; +\end{tikzpicture} +\end{center} diff --git a/docs/ontology/Hooks.md b/docs/ontology/Hooks.md new file mode 100644 index 00000000..3d610757 --- /dev/null +++ b/docs/ontology/Hooks.md @@ -0,0 +1,526 @@ + + +## User Only + +- **Hooks**: Firms producing differentiated factors of production services and intermediate inputs (e.g., liquidity management, fee adjustment, MEV protection). Hooks are the means to the protocol (end). + +$H_{ij}$ where: + - $i:=$ row: receipt income earned from employment in $H_j$ (e.g liquiidty rebalancer hook, fee adjsutment, etc) + - $j:=$ column: disposition on factor income + +- **Hook Redeployability** (analogous to Factor Mobility / Asset Redeployability): +The ease with which hooks can be employed (integrated) in other production activities (i.e., other protocol pools). + - Each protocol defines its state variables differently and has different flows, business models, etc. + + +- **Market Classification**: A market for hooks is a type of factor market within a General Equilibrium (GE) model framework. + +- **Pools**: Consumers of hook services, representing firms providing final services to end users. + - Each pool demands specific functionalities + - Pools choose among competing hooks offering these functions + +- **Hook Competition**: Hooks with same functionality compete for liquidity and take on protocol fees (firms competing on markets +for revenue share). + +--- + +## Elaboration: Hook Factor Income Matrix $H_{ij}$ + +### Matrix Structure + +The hook factor income matrix $\mathbf{H} = [H_{ij}]$ is an $n \times n$ matrix where $n$ is the number of distinct hook types: + +$$\mathbf{H} = \begin{bmatrix} +H_{11} & H_{12} & \cdots & H_{1n} \\ +H_{21} & H_{22} & \cdots & H_{2n} \\ +\vdots & \vdots & \ddots & \vdots \\ +H_{n1} & H_{n2} & \cdots & H_{nn} +\end{bmatrix}$$ + +| Dimension | Economic Interpretation | SAM Convention | +|-----------|------------------------|----------------| +| **Row $i$** | Income receipt account | "Where income comes FROM" | +| **Column $j$** | Expenditure/disposition account | "Where income GOES TO" | + +### Row Interpretation: Income Streams + +Hook $i$'s total receipts: + +$$R_i = \sum_{j=1}^{n} H_{ij} = H_{i,\text{fees}} + H_{i,\text{MEV}} + H_{i,\text{subsidy}} + H_{i,\text{inter-hook}}$$ + +| Income Type | Symbol | Source | +|-------------|--------|--------| +| Direct Fee Income | $H_{i,\text{fees}}$ | Pool swap fees allocated to hook | +| MEV Capture | $H_{i,\text{MEV}}$ | Arbitrage/sandwich extraction | +| Protocol Subsidies | $H_{i,\text{subsidy}}$ | Grants, incentives | +| Inter-Hook Transfers | $H_{ij}, i \neq j$ | Payments between composable hooks | + +**"Employment in $H_j$"**: Hook $i$ is invoked during $j$'s execution path: + +$$H_{ij} = \int_0^T \tau_{ij}(t) \cdot p_i(t) \cdot q_{ij}(t) \, dt$$ + +Where: +- $\tau_{ij}(t)$: invocation count of hook $i$ by hook $j$ at time $t$ +- $p_i(t)$: price per invocation +- $q_{ij}(t)$: quality/intensity of service + +### Column Interpretation: Disposition of Factor Income + +How hook $j$'s generated value is distributed: + +$$E_j = D_j + P_j + LP_j + S_j$$ + +| Recipient | Share ($\theta$) | Description | +|-----------|------------------|-------------| +| $D_j$ (Developer) | 70-90% | Hook developer earnings | +| $P_j$ (Protocol) | 5-15% | Protocol treasury | +| $LP_j$ (LP) | 0-10% | LP enhancement | +| $S_j$ (Savings) | Remainder | Reinvestment | + +### Off-Diagonal Elements: Composability Flows ($i \neq j$) + +$$H_{ij} \neq 0 \iff \text{Hook } i \text{ provides factor services to Hook } j$$ + +**Examples:** +- $H_{13}$: Oracle → Rebalancer (price data enables rebalancing) +- $H_{32}$: Fee Hook → Oracle (fee hook pays for volatility data) +- $H_{41}$: Rebalancer → MEV Protection (pays for MEV shield) + +### Competition Dynamics + +Substitution effects between competing hooks: + +$$\frac{\partial H_{ii}}{\partial H_{jj}} < 0 \quad \text{(Substitute hooks)}$$ +$$\frac{\partial H_{ii}}{\partial H_{jj}} > 0 \quad \text{(Complement hooks)}$$ + +Cross-price elasticity: +$$\epsilon_{ij} = \frac{\partial \ln Q_i}{\partial \ln p_j}$$ + +### Accounting Identity + +$$\boxed{\sum_j H_{ij} = \sum_j H_{ji} + \text{Net external flows}}$$ + +Row totals must equal column totals for SAM balance. + +### Example Calibrated Matrix (ETH/week) + +| | $H_1$ (Rebalancer) | $H_2$ (Fee Adj) | $H_3$ (Oracle) | $H_4$ (MEV Prot) | **Row Total** | +|--|-------------------|-----------------|----------------|------------------|---------------| +| $H_1$ | **12.5** | 0.8 | 0 | 1.2 | 14.5 | +| $H_2$ | 0.3 | **8.7** | 2.1 | 0.5 | 11.6 | +| $H_3$ | 1.5 | 1.8 | **4.2** | 0.9 | 8.4 | +| $H_4$ | 0.7 | 0.4 | 0.3 | **6.1** | 7.5 | +| **Col Total** | 15.0 | 11.7 | 6.6 | 8.7 | **42.0** | + +--- + +## Hook Redeployability + +> **Definition**: The degree to which a Uniswap V4 hook can be productively integrated across heterogeneous protocol pools without substantial adaptation costs, measured by the weighted compatibility of hook design with the state variable schemas, callback interfaces, and business model requirements of alternative deployment targets. + +### Terminology Comparison + +| Term | Source Domain | Limitation for Hooks | +|------|---------------|---------------------| +| Factor Mobility | Labor Economics | Too macro-level (countries/sectors) | +| Asset Specificity | Transaction Cost Economics (Williamson) | Focuses on the *problem* (lock-in), not the *solution* | +| Portability | Immigration Economics | More commonly used for human capital | +| Fungibility | Finance | Too strong—hooks are differentiated, not identical | +| Composability | DeFi | Describes *what* happens, not the friction of doing so | +| **Redeployability** | Corporate Finance (Kim & Kung, 2017) | ✓ Directly captures integration friction | + +### Theoretical Foundations + +#### Transaction Cost Economics (Williamson) + +**Asset Specificity** has four dimensions relevant to hooks: + +| Specificity Type | Hook Manifestation | +|------------------|-------------------| +| Site specificity | Hook designed for specific chain/L2 environment | +| Physical asset specificity | State variable structures, data schemas | +| Human asset specificity | Developer knowledge of particular hook's internals | +| Dedicated assets | Integration code, adapters, testing infrastructure | + +The **hold-up problem** arises when hooks require relationship-specific investments that create bilateral dependency and reduce redeployability. + +#### Labor Economics: Skill Transferability + +From Gathmann & Schonberg (2010) on task-specific human capital: +- Skills are more portable than thought when *tasks* are similar +- Wage losses depend on switching *skill portfolios*, not occupation codes + +**Hook analog**: Integration costs depend on "hook distance"—how different the target pool's requirements are from the hook's native design. + +#### Platform Economics: Multi-homing + +From Bank of England Working Paper 839: + +| Cost Type | Definition | Hook Application | +|-----------|------------|------------------| +| Multi-homing costs | Fixed costs of maintaining presence on multiple platforms | Maintaining hook across multiple pool architectures | +| Switching costs | One-time costs of moving between platforms | Migrating hook from Pool A to Pool B | +| Data portability | Ability to transfer state/history | Hook state migration across protocols | + +### Mathematical Formalization + +#### Redeployability Index + +Adapted from Kim & Kung (2017): + +$$\rho_h = \sum_{p \in \mathcal{P}} \omega_p \cdot \text{Compatibility}(h, p)$$ + +Where: +- $\rho_h \in [0,1]$: Redeployability index for hook $h$ +- $\omega_p$: Importance weight of pool $p$ (e.g., TVL share) +- $\text{Compatibility}(h, p) \in [0,1]$: Degree to which hook $h$ integrates with pool $p$ + +#### Integration Cost Function + +$$C_{\text{int}}(h, p) = \alpha \cdot d_{\text{state}}(h, p) + \beta \cdot d_{\text{flow}}(h, p) + \gamma \cdot d_{\text{model}}(h, p)$$ + +Where: +- $d_{\text{state}}(h, p)$: State variable distance (schema incompatibility) +- $d_{\text{flow}}(h, p)$: Flow incompatibility (callback sequence mismatch) +- $d_{\text{model}}(h, p)$: Business model mismatch (revenue structure) +- $\alpha, \beta, \gamma$: Weighting coefficients + +#### Hook Distance Metric + +Analogous to occupational distance in labor economics: + +$$D(h; p_1, p_2) = \|\mathbf{r}_{p_1} - \mathbf{r}_{p_2}\|$$ + +Where $\mathbf{r}_p$ is the **requirement vector** for pool $p$, capturing: +- Callback interfaces required +- State variable schemas +- Gas efficiency constraints +- Security assumptions + +### Barriers to Redeployability + +| Barrier | Description | Williamson Classification | +|---------|-------------|--------------------------| +| **State Variable Heterogeneity** | Each protocol defines state variables differently | Physical asset specificity | +| **Flow Incompatibility** | Different transaction flows and callback sequences | Site specificity | +| **Business Model Divergence** | Revenue models vary (fixed fee, dynamic, revenue share) | Dedicated assets | +| **Security Assumptions** | Different trust models and audit requirements | Human asset specificity | + +### Market Segmentation Effects + +Low hook redeployability creates **segmented factor markets**: + +$$p_h^{(A)} \neq p_h^{(B)} \quad \text{when } \rho_h \approx 0$$ + +Where $p_h^{(A)}$ and $p_h^{(B)}$ are prices for hook $h$ in protocols A and B. + +**Economic consequences**: +- Price discovery is impaired (fewer competing hooks per pool) +- Rent extraction by pools that have captured specific hooks +- Reduced allocative efficiency across the ecosystem + +### Policy Interventions to Increase Redeployability + +| Intervention | Source | Hook Bazaar Implementation | +|--------------|--------|---------------------------| +| **Standardization** | TCE | Common callback interfaces (ERC-style standards) | +| **Modular Design** | Software Engineering | Separate hook logic from pool-specific adapters | +| **Data Portability** | Platform Economics | Standardized hook state interfaces | +| **Transparent Registries** | Information Economics | Capability metadata, audit status | +| **Adapter Layers** | DeFi Composability | Diamond pattern with facet abstraction | + +**Hook Bazaar's role**: Increase $\rho_h$ through standardized interfaces, adapter layers, and reputation portability. + +--- + +## Protocol SAM Structure ($P_{ij}$) + +### Ontological Classification + +Protocols occupy a **hybrid position** in the SAM: + +| SAM Role | Traditional Economy | DeFi Protocol Analog | Justification | +|----------|---------------------|---------------------|---------------| +| **Activity** | Industry/Production | Pool operations | Protocols "produce" liquidity services | +| **Institution** | Government/Households | Governance layer | Protocols coordinate factor allocation | +| **Factor Owner** | Land, Labor, Capital | Smart contract owner | Protocols own pool infrastructure | + +The appropriate representation is a **dual-account structure**: + +$$\mathbf{P} = \mathbf{P}^{A} \oplus \mathbf{P}^{I}$$ + +Where: +- $\mathbf{P}^{A}$: Protocol Activity accounts (production/consumption of hook services) +- $\mathbf{P}^{I}$: Protocol Institutional accounts (governance, transfers, coordination) + +### Protocol Activity Matrix $P^{A}_{ij}$ + +The protocol activity matrix captures protocols as **consumers of hook factor services**: + +$$\mathbf{P}^{A} = [P^{A}_{ij}] \quad \text{where } i \in \{1,...,m\}, j \in \{1,...,m\}$$ + +| Dimension | Interpretation | +|-----------|---------------| +| Row $i$ | Protocol $i$'s **receipts** from providing pool services | +| Column $j$ | Protocol $j$'s **expenditures** on inputs (including hooks) | + +**Column Structure (Expenditures by Protocol $j$)**: + +$$E_j^{P} = \underbrace{\sum_{h=1}^{n} F_{hj}}_{\text{Hook Factor Payments}} + \underbrace{L_j + K_j}_{\text{Primary Factors}} + \underbrace{T_j^{import}}_{\text{Intermediate Imports}}$$ + +Where: +- $F_{hj}$: Payment to hook $h$ by protocol $j$ +- $L_j$: Developer labor costs +- $K_j$: Infrastructure capital costs +- $T_j^{import}$: Imported services from other protocols + +### Protocol Institutional Matrix $P^{I}_{ij}$ + +Protocols exercise institutional functions analogous to government: + +| Entry | Description | +|-------|-------------| +| $P^{I}_{HH}$ | Hook-to-hook inter-protocol transfers | +| $P^{I}_{HP}$ | Hook income paid to protocol treasuries | +| $P^{I}_{PL}$ | Protocol distributions to LPs | +| $P^{I}_{PS}$ | Protocol savings/reinvestment | +| $P^{I}_{PM}$ | Protocol payments to marketplace (Hook Bazaar) | + +### Quasi-Governmental Functions + +| Government Function | Protocol Analog | SAM Account | +|--------------------|-----------------|-------------| +| **Taxation** | Protocol fees on swaps | $P^{I}_{fee}$ | +| **Redistribution** | Fee distribution to LPs | $P^{I}_{PL}$ | +| **Public Goods** | Pool infrastructure | $P^{A}_{infra}$ | +| **Regulation** | Hook selection/governance | $P^{I}_{gov}$ | +| **Monetary Policy** | Dynamic fee adjustment | $P^{I}_{dyn}$ | + +--- + +## Hook-Protocol Integration Matrix $\Phi$ + +### Formal Linkage Structure + +The connection between protocol accounts ($P$) and hook accounts ($H$) is mediated by an **integration matrix** $\Phi$: + +$$\Phi: \mathbf{H} \times \mathbf{P}^{A} \rightarrow \mathbb{R}^{n \times m}$$ + +Where $\Phi_{hp}$ represents hook $h$'s value contribution to protocol $p$. + +### Revenue Share Model Mapping + +Three pricing models map to SAM entries: + +**Model 1: Fixed Price (One-time)** + +$$\Phi_{hp}^{fixed} = \pi_h \cdot \mathbb{1}_{t=0}$$ + +SAM entry: Single capital transfer from protocol to hook developer at $t=0$. + +**Model 2: Revenue Share** + +$$\Phi_{hp}^{share}(t) = \theta_h \cdot \phi_p(t) \cdot V_p(t)$$ + +Where: +- $\theta_h \in [0, 0.3]$: Hook's revenue share (capped at 30%) +- $\phi_p(t)$: Pool $p$'s swap fee rate +- $V_p(t)$: Swap volume at time $t$ + +SAM entries: Continuous flow from pool fee account to hook income account. + +**Model 3: Hybrid** + +$$\Phi_{hp}^{hybrid} = \pi_h^{fixed} + \int_0^T \theta_h \cdot \phi_p(t) \cdot V_p(t) \, dt$$ + +### Matrix Entry Specification + +For each $(h, p)$ pair: + +$$\Phi_{hp} = \begin{cases} +\pi_h & \text{if fixed price} \\ +\sum_{t=1}^{T} \theta_h \phi_p V_{pt} & \text{if revenue share} \\ +\pi_h + \sum_{t=1}^{T} \theta_h \phi_p V_{pt} & \text{if hybrid} +\end{cases}$$ + +--- + +## Complete SAM Block Structure + +### Full Hook Bazaar SAM + +$$\mathbf{SAM} = \begin{bmatrix} +\mathbf{H} & \mathbf{\Phi} & \mathbf{0} & \mathbf{\Omega}_H \\ +\mathbf{\Phi}^T & \mathbf{P}^A & \mathbf{\Lambda} & \mathbf{\Omega}_P \\ +\mathbf{0} & \mathbf{\Lambda}^T & \mathbf{E} & \mathbf{\Omega}_E \\ +\mathbf{\Omega}_H^T & \mathbf{\Omega}_P^T & \mathbf{\Omega}_E^T & \mathbf{I} +\end{bmatrix}$$ + +Where: +- $\mathbf{H}$: Hook factor accounts ($n \times n$) +- $\mathbf{P}^A$: Protocol activity accounts ($m \times m$) +- $\mathbf{E}$: External agent accounts (LPs, swappers, developers) +- $\mathbf{I}$: Institutional accounts (protocol treasuries, marketplace) +- $\mathbf{\Phi}$: Hook-Protocol integration matrix ($n \times m$) +- $\mathbf{\Lambda}$: Protocol-External flows ($m \times k$) +- $\mathbf{\Omega}$: Cross-block transfer matrices + +### Accounting Identities + +**Identity 1: Hook Income Balance** + +$$\sum_j H_{ij} = \sum_j H_{ji} + \sum_p \Phi_{ip} + \Omega_{iE}$$ + +**Identity 2: Protocol Activity Balance** + +$$\sum_h \Phi_{hp} + \sum_q P^A_{qp} = \sum_h \Phi_{ph} + \sum_q P^A_{pq} + \Lambda_p$$ + +**Identity 3: SAM Global Balance** + +$$\sum_{i} R_i = \sum_{j} E_j$$ + +**Identity 4: Multi-Sided Market Balance** + +For each agent class $c \in \{D, P, L, S\}$ (Developers, Protocols, LPs, Swappers): + +$$\sum_{i \in c} \text{Income}_i = \sum_{j \in c} \text{Expenditure}_j + \text{Net Savings}_c$$ + +### Integrated SAM Example (ETH/week) + +| | $H_1$ | $H_2$ | $H_3$ | $H_4$ | $P_1$ | $P_2$ | LP | Swap | **Row** | +|--|-------|-------|-------|-------|-------|-------|-----|------|---------| +| $H_1$ | 12.5 | 0.8 | 0 | 1.2 | **3.5** | **2.0** | 0 | 0 | 20.0 | +| $H_2$ | 0.3 | 8.7 | 2.1 | 0.5 | **1.8** | **1.2** | 0 | 0 | 14.6 | +| $H_3$ | 1.5 | 1.8 | 4.2 | 0.9 | **0.9** | **0.7** | 0 | 0 | 10.0 | +| $H_4$ | 0.7 | 0.4 | 0.3 | 6.1 | **1.3** | **0.6** | 0 | 0 | 9.4 | +| $P_1$ | 0 | 0 | 0 | 0 | 0 | 5.2 | **8.5** | **22.3** | 36.0 | +| $P_2$ | 0 | 0 | 0 | 0 | 4.8 | 0 | **6.2** | **18.5** | 29.5 | +| LP | 0 | 0 | 0 | 0 | 18.2 | 14.8 | 0 | 0 | 33.0 | +| Swap | 0 | 0 | 0 | 0 | 0 | 0 | 18.3 | 0 | 18.3 | +| **Col** | 15.0 | 11.7 | 6.6 | 8.7 | 30.5 | 24.5 | 33.0 | 40.8 | **170.8** | + +**Bold entries** = $\Phi$ matrix (hook-protocol linkages) + +--- + +## Market Failure Representation in SAM + +### SAM Diagnosis of Market Failures + +The nine market failures from the Problem Description map to SAM structural deficiencies: + +| Market Failure | SAM Symptom | Missing Flow | +|----------------|-------------|--------------| +| **1. Missing Marketplace** | $\Phi_{hp} = 0 \; \forall h,p$ | Hook-protocol linkage | +| **2. High Barriers** | $P^A_{entry} \gg 0$ | Capital-to-production flow blocked | +| **3. No Incentive Layer** | $T_{PH} = 0$ | Developer income channel | +| **4. No Standardization** | $\text{Var}(H_{ij}) \rightarrow \infty$ | Incomparable hook accounts | +| **5. No Composition** | $H_{ij} = 0 \; \forall i \neq j$ | Inter-hook value flows | +| **6. No Competition** | $\partial H_{ii}/\partial H_{jj} = 0$ | Substitution effects absent | +| **7. No IP Protection** | $\theta_h \rightarrow 0$ | Developer income eroded | +| **8. No Reputation** | $\alpha_p(h) \sim \text{Uniform}$ | Information asymmetry | +| **9. Unsustainable Economics** | $\sum_t R_h < \sum_t C_h$ | Negative NPV for developers | + +### Formal Market Failure Conditions + +**Definition (Missing Market)**: A market $M_{hp}$ between hook $h$ and protocol $p$ is **missing** iff: + +$$\Phi_{hp} = 0 \quad \text{and} \quad \exists \; \text{gains from trade} \; (V_h^* > V_h^{autarky}, V_p^* > V_p^{autarky})$$ + +**Definition (Blocked Flow)**: A SAM flow $F_{ij}$ is **blocked** iff: + +$$F_{ij} = 0 \quad \text{while} \quad \partial U_i / \partial F_{ij} > 0 \quad \text{and} \quad \partial U_j / \partial F_{ij} > 0$$ + +### How Hook Bazaar "Completes" the SAM + +**Before Hook Bazaar** (sparse, missing markets): + +$$\mathbf{SAM}_{before} = \begin{bmatrix} +\mathbf{H}_{sparse} & \mathbf{0} & \mathbf{0} \\ +\mathbf{0} & \mathbf{P}^A_{isolated} & \mathbf{\Lambda} \\ +\mathbf{0} & \mathbf{\Lambda}^T & \mathbf{E} +\end{bmatrix}$$ + +**After Hook Bazaar** (dense, functioning markets): + +$$\mathbf{SAM}_{after} = \begin{bmatrix} +\mathbf{H}_{dense} & \mathbf{\Phi} & \mathbf{\Omega}_H \\ +\mathbf{\Phi}^T & \mathbf{P}^A_{integrated} & \mathbf{\Lambda} \\ +\mathbf{\Omega}_H^T & \mathbf{\Lambda}^T & \mathbf{E} +\end{bmatrix}$$ + +### Market Completion Effects + +| SAM Region | Before | After | Economic Effect | +|------------|--------|-------|-----------------| +| $\mathbf{\Phi}$ | Zero matrix | Dense | Hook factor market activated | +| $\mathbf{H}$ diagonal | Sparse | Dense | Hook specialization | +| $\mathbf{H}$ off-diagonal | Zero | Positive | Composability value | +| $\mathbf{\Omega}_H$ | Zero | Positive | Developer income | +| $\mathbf{P}^A$ | Isolated | Integrated | Protocol efficiency gains | + +--- + +## Notation Summary + +| Symbol | Dimension | Description | +|--------|-----------|-------------| +| $\mathbf{H}$ | $n \times n$ | Hook factor income matrix | +| $\mathbf{P}^A$ | $m \times m$ | Protocol activity matrix | +| $\mathbf{P}^I$ | $m \times m$ | Protocol institutional matrix | +| $\mathbf{\Phi}$ | $n \times m$ | Hook-Protocol integration matrix | +| $\mathbf{\Lambda}$ | $m \times k$ | Protocol-External flow matrix | +| $\mathbf{T}$ | $(n+m+k)^2$ | Transfer matrix | +| $\theta_h$ | Scalar | Revenue share rate for hook $h$ | +| $\alpha_p(h)$ | Scalar | Protocol $p$'s selection probability for hook $h$ | +| $\rho_h$ | Scalar | Redeployability index for hook $h$ | + +--- + +## References + +### SAM and General Equilibrium + +1. Arrow, K. J., & Debreu, G. (1954). Existence of an equilibrium for a competitive economy. *Econometrica*, 22(3), 265-290. + +2. Leontief, W. W. (1936). Quantitative input and output relations in the economic systems of the United States. *Review of Economics and Statistics*, 18(3), 105-125. + +3. Pyatt, G., & Round, J. I. (1979). Accounting and fixed price multipliers in a social accounting matrix framework. *Economic Journal*, 89(356), 850-873. + +4. Samuelson, P. A. (1953). Prices of factors and goods in general equilibrium. *Review of Economic Studies*, 21(1), 1-20. + +5. Reinert, K. A., & Roland-Holst, D. W. (1997). Social Accounting Matrices. In *Applied Methods for Trade Policy Analysis*, 94-121. Cambridge University Press. + +### Transaction Cost Economics + +6. Williamson, O. E. (2009). Transaction Cost Economics: The Natural Progression. *Nobel Prize Lecture*. https://www.nobelprize.org/uploads/2018/06/williamson_lecture.pdf + +7. Tadelis, S., & Williamson, O. E. (2012). Transaction Cost Economics. In *Handbook of Organizational Economics*. https://faculty.haas.berkeley.edu/stadelis/tce_org_handbook_111410.pdf + +### Asset Redeployability + +8. Kim, H., & Kung, H. (2017). The Asset Redeployability Channel: How Uncertainty Affects Corporate Investment. *Review of Financial Studies*, 30(1), 245-280. https://academic.oup.com/rfs/article-abstract/30/1/245/2669940 + +### Labor Economics and Skill Transferability + +9. Gathmann, C., & Schonberg, U. (2010). How General Is Human Capital? A Task-Based Approach. *Journal of Labor Economics*, 28(1), 1-49. https://www.journals.uchicago.edu/doi/10.1086/649786 + +10. NBER Working Paper 32908 (2024). Skills and Human Capital. https://www.nber.org/papers/w32908 + +### Platform Economics + +11. Rochet, J. C., & Tirole, J. (2003). Platform Competition in Two-Sided Markets. *Journal of the European Economic Association*, 1(4), 990-1029. + +12. Bank of England (2019). Platform Competition and Data Portability. *Working Paper 839*. https://ideas.repec.org/p/boe/boeewp/0839.html + +13. Lam, W. M. W. (2017). Switching Costs in Two-Sided Markets. *Journal of Industrial Economics*. https://onlinelibrary.wiley.com/doi/10.1111/joie.12133 + +### DeFi and Composability + +14. von Wachter, V., Jensen, J. R., & Ross, O. (2021). Measuring Asset Composability as a Proxy for DeFi Integration. *arXiv:2102.04227*. https://arxiv.org/abs/2102.04227 + +15. Bartoletti, M., Chiang, J. H., & Lluch-Lafuente, A. (2023). A Theory of Compositionality for Smart Contracts. *arXiv:2309.10781*. https://arxiv.org/abs/2309.10781 + +16. Schär, F. (2021). Decentralized Finance: On Blockchain and Smart Contract-Based Financial Markets. *Federal Reserve Bank of St. Louis Review*. https://www.stlouisfed.org/publications/review/2021/02/05/decentralized-finance-on-blockchain-and-smart-contract-based-financial-markets + +17. Adams, H., et al. (2024). Uniswap V4 Core. *Uniswap Labs Technical Documentation*. diff --git a/docs/problem-description/Hooks.md b/docs/problem-description/Hooks.md new file mode 100644 index 00000000..944feeb0 --- /dev/null +++ b/docs/problem-description/Hooks.md @@ -0,0 +1,713 @@ +## User Only + +Let's consider a protocol $P_i = \cup p_{ij} \in \mathbb{P}$ in the space of all protocols +- economicaly $P_i$ delivers a final product that satisifies certain utility for its intended end user +- The collection of pools on the protocol MUST have a economic menaning that aligns with the economic meaning given to hooks +- linkages among protocols can be studied through it's demands for intermediary inputs and their competition for the factors of production + +- On the SAM for protocols the "Acticity" column describe thee inputs used by (the equivalent to insdustries on DeFi protocols) +- THe activity row describes the "Use of indststries" (or the equivalent on DeFi protocols) as inpouts for other (equivalent to insdustries on DeFi protocols) + +- Protocol are assumed to maximize their efficiency subject to the flexibility afforded by the technological production process (some index on infra on Blockchain) + +Based on that protcols choose their __inputs and output levels__ + +--- + +## Hypothesis: Vanilla Pools as Intermediate Inputs + +### Core Thesis + +**Vanilla pools (without hooks) should be classified as intermediate inputs**, since they lack the differentiation that provides competitive advantage. Only when hooks are added do pools transform into **production units (firms)**. + +### Economic Justification + +| Pool Type | Classification | Economic Character | +|-----------|---------------|-------------------| +| **Vanilla Pool** (no hooks) | **Intermediate Input** | Homogeneous, commodity-like, perfectly substitutable | +| **Pool + Hooks** | **Production Unit (Firm)** | Differentiated, competitive advantage, value-creating | + +### Why Vanilla Pools = Intermediate Inputs + +From Leontief-Sraffa input-output theory, intermediate inputs are characterized by: + +1. **Homogeneity**: All vanilla ETH/USDC pools are functionally identical +2. **Perfect substitutability**: Users are indifferent between vanilla pools (given same fees) +3. **No value added**: Just "pass-through" of liquidity services +4. **Price = marginal cost**: No economic profit in competitive equilibrium + +$$\pi_{vanilla} = 0 \quad \text{(zero economic profit)}$$ + +### Why Pool + Hooks = Production Unit + +Adding hooks transforms the pool because: + +1. **Differentiation**: MEV protection, dynamic fees, oracle integration create unique value +2. **Competitive advantage**: Quality competition, not just price competition +3. **Value added**: Hook services create surplus above commodity value +4. **Economic profit possible**: Differentiation enables $\pi > 0$ + +$$\pi_{enhanced} = V_{hooks} - C_{hooks} > 0 \quad \text{(positive returns to differentiation)}$$ + +### The Hook Transformation + +$$\text{Intermediate Input} \xrightarrow{\text{+ Hooks}} \text{Production Unit}$$ + +| Dimension | Vanilla Pool | Pool + Hooks | +|-----------|--------------|--------------| +| **Competition** | Price only | Price + Quality | +| **Substitutability** | Perfect | Imperfect | +| **Economic profit** | Zero | Positive possible | +| **SAM classification** | Intermediate flow | Activity column | +| **I-O treatment** | In $\mathbf{A}$ matrix | Separate sector | + +--- + +## Input-Output Coefficients ($a_{ij}$) + +### Definition + +The **technical coefficient** measures input requirements: + +$$a_{ij} = \frac{z_{ij}}{X_j} = \frac{\text{Value of input } i \text{ consumed by } j}{\text{Total output of } j}$$ + +### Hook Bazaar Equivalences + +| Coefficient | Economic Meaning | Example | +|-------------|------------------|---------| +| $a_{H \to P}$ | Hook services per unit of pool output | 5% of swap value → hook fees | +| $a_{K \to P}$ | Capital (TVL) required per unit swap volume | Capital efficiency ratio | +| $a_{P \to P'}$ | Inter-pool flows (liquidity routing) | Aggregator routing | +| $a_{L \to H}$ | Developer labor per unit of hook output | Hook production cost structure | + +### Leontief System + +$$\mathbf{x} = \mathbf{A}\mathbf{x} + \mathbf{f}$$ + +Where: +- $\mathbf{x}$ = output vector (hooks, pools, protocols) +- $\mathbf{A}$ = matrix of technical coefficients $[a_{ij}]$ +- $\mathbf{f}$ = final demand (swappers + LPs) + +**Solving for total output:** + +$$\mathbf{x} = (\mathbf{I} - \mathbf{A})^{-1} \mathbf{f}$$ + +The **Leontief inverse** $(\mathbf{I} - \mathbf{A})^{-1}$ captures direct and indirect requirements. + +--- + +## Production Chain + +``` +PRIMARY FACTORS +├── Labor (developers, operators) +├── Capital (infrastructure, audits) +└── Land (blockchain compute) + ↓ +HOOK PRODUCTION (Hook Developers) + ↓ +┌─────────────────────────────────┐ +│ VANILLA POOLS │ ← INTERMEDIATE INPUT +│ (Commoditized liquidity) │ (homogeneous, no differentiation) +│ • Homogeneous │ +│ • Zero economic profit │ +│ • Perfect substitutes │ +└─────────────────────────────────┘ + ↓ + Hooks (Factor Services) +┌─────────────────────────────────┐ +│ ENHANCED POOLS │ ← PRODUCTION UNIT (FIRM) +│ (Differentiated services) │ (competitive advantage) +│ • Heterogeneous │ +│ • Positive economic profit │ +│ • Imperfect substitutes │ +└─────────────────────────────────┘ + ↓ +┌─────────────────────────────────┐ +│ FINAL DEMAND (End Users) │ +│ ├── Swappers (consume swaps) │ +│ └── LPs (consume yield) │ +└─────────────────────────────────┘ +``` + +--- + +## Mathematical Formalization + +### Value Decomposition + +$$V_{pool} = \underbrace{V_{vanilla}}_{\text{Intermediate input value}} + \underbrace{V_{hooks}}_{\text{Value added by hooks}}$$ + +### Production Function Transformation + +**Vanilla Pool** (single-factor, commodity): +$$Y_{vanilla} = f(K_{TVL})$$ + +**Enhanced Pool** (multi-factor, differentiated): +$$Y_{enhanced} = F(K_{TVL}, \mathbf{H})$$ + +The hooks ($\mathbf{H}$) transform the production function from commodity to differentiated. + +### Differentiation Operator + +Define $\mathcal{D}$: + +$$\mathcal{D}: \text{IntermediateInput} \times \text{Hooks} \rightarrow \text{ProductionUnit}$$ + +$$\mathcal{D}(P_{vanilla}, \mathbf{H}) = P_{enhanced}$$ + +Where: +- $P_{vanilla} \in \mathcal{I}$ (intermediate input space) +- $P_{enhanced} \in \mathcal{F}$ (firm/production unit space) +- $\mathbf{H}$ = hook bundle enabling transformation + +--- + +## SAM Implications + +### I-O Matrix Before Hooks + +Vanilla pools appear only as intermediate flows: + +$$\mathbf{A}_{before} = \begin{bmatrix} +0 & 0 & a_{P \to Agg} \\ +0 & 0 & a_{P \to Agg} \\ +0 & 0 & 0 +\end{bmatrix}$$ + +### I-O Matrix After Hooks + +Pools become production units with value added: + +$$\mathbf{A}_{after} = \begin{bmatrix} +H_{11} & H_{12} & 0 \\ +H_{21} & H_{22} & 0 \\ +\Phi_{1P} & \Phi_{2P} & 0 +\end{bmatrix}$$ + +Now pools have: +- Hook factor income flows ($H_{ij}$) +- Hook-pool integration ($\Phi$) +- Value added component (outside A matrix) + +### Complete I-O Balance + +$$\underbrace{\mathbf{x}}_{\text{Total Output}} = \underbrace{\mathbf{A}\mathbf{x}}_{\text{Intermediate Demand}} + \underbrace{\mathbf{f}}_{\text{Final Demand (Swappers + LPs)}}$$ + +--- + +## Key Insight + +**Hook Bazaar's economic function**: Transform commodity intermediate inputs (vanilla pools) into differentiated production units (enhanced pools) by providing factor services. + +Analogous to: +- **Manufacturing**: Raw steel (intermediate) + machinery (capital) → differentiated products +- **DeFi**: Vanilla liquidity (intermediate) + hooks (factor services) → differentiated pool services + +--- + +--- + +## Elaboration: Hook Factor Income Matrix $H_{ij}$ + +### Matrix Structure + +The hook factor income matrix $\mathbf{H} = [H_{ij}]$ is an $n \times n$ matrix where $n$ is the number of distinct hook types: + +$$\mathbf{H} = \begin{bmatrix} +H_{11} & H_{12} & \cdots & H_{1n} \\ +H_{21} & H_{22} & \cdots & H_{2n} \\ +\vdots & \vdots & \ddots & \vdots \\ +H_{n1} & H_{n2} & \cdots & H_{nn} +\end{bmatrix}$$ + +| Dimension | Economic Interpretation | SAM Convention | +|-----------|------------------------|----------------| +| **Row $i$** | Income receipt account | "Where income comes FROM" | +| **Column $j$** | Expenditure/disposition account | "Where income GOES TO" | + +### Row Interpretation: Income Streams + +Hook $i$'s total receipts: + +$$R_i = \sum_{j=1}^{n} H_{ij} = H_{i,\text{fees}} + H_{i,\text{MEV}} + H_{i,\text{subsidy}} + H_{i,\text{inter-hook}}$$ + +| Income Type | Symbol | Source | +|-------------|--------|--------| +| Direct Fee Income | $H_{i,\text{fees}}$ | Pool swap fees allocated to hook | +| MEV Capture | $H_{i,\text{MEV}}$ | Arbitrage/sandwich extraction | +| Protocol Subsidies | $H_{i,\text{subsidy}}$ | Grants, incentives | +| Inter-Hook Transfers | $H_{ij}, i \neq j$ | Payments between composable hooks | + +**"Employment in $H_j$"**: Hook $i$ is invoked during $j$'s execution path: + +$$H_{ij} = \int_0^T \tau_{ij}(t) \cdot p_i(t) \cdot q_{ij}(t) \, dt$$ + +Where: +- $\tau_{ij}(t)$: invocation count of hook $i$ by hook $j$ at time $t$ +- $p_i(t)$: price per invocation +- $q_{ij}(t)$: quality/intensity of service + +### Column Interpretation: Disposition of Factor Income + +How hook $j$'s generated value is distributed: + +$$E_j = D_j + P_j + LP_j + S_j$$ + +| Recipient | Share ($\theta$) | Description | +|-----------|------------------|-------------| +| $D_j$ (Developer) | 70-90% | Hook developer earnings | +| $P_j$ (Protocol) | 5-15% | Protocol treasury | +| $LP_j$ (LP) | 0-10% | LP enhancement | +| $S_j$ (Savings) | Remainder | Reinvestment | + +### Off-Diagonal Elements: Composability Flows ($i \neq j$) + +$$H_{ij} \neq 0 \iff \text{Hook } i \text{ provides factor services to Hook } j$$ + +**Examples:** +- $H_{13}$: Oracle → Rebalancer (price data enables rebalancing) +- $H_{32}$: Fee Hook → Oracle (fee hook pays for volatility data) +- $H_{41}$: Rebalancer → MEV Protection (pays for MEV shield) + +### Competition Dynamics + +Substitution effects between competing hooks: + +$$\frac{\partial H_{ii}}{\partial H_{jj}} < 0 \quad \text{(Substitute hooks)}$$ +$$\frac{\partial H_{ii}}{\partial H_{jj}} > 0 \quad \text{(Complement hooks)}$$ + +Cross-price elasticity: +$$\epsilon_{ij} = \frac{\partial \ln Q_i}{\partial \ln p_j}$$ + +### Accounting Identity + +$$\boxed{\sum_j H_{ij} = \sum_j H_{ji} + \text{Net external flows}}$$ + +Row totals must equal column totals for SAM balance. + +### Example Calibrated Matrix (ETH/week) + +| | $H_1$ (Rebalancer) | $H_2$ (Fee Adj) | $H_3$ (Oracle) | $H_4$ (MEV Prot) | **Row Total** | +|--|-------------------|-----------------|----------------|------------------|---------------| +| $H_1$ | **12.5** | 0.8 | 0 | 1.2 | 14.5 | +| $H_2$ | 0.3 | **8.7** | 2.1 | 0.5 | 11.6 | +| $H_3$ | 1.5 | 1.8 | **4.2** | 0.9 | 8.4 | +| $H_4$ | 0.7 | 0.4 | 0.3 | **6.1** | 7.5 | +| **Col Total** | 15.0 | 11.7 | 6.6 | 8.7 | **42.0** | + +--- + +## Hook Redeployability + +> **Definition**: The degree to which a Uniswap V4 hook can be productively integrated across heterogeneous protocol pools without substantial adaptation costs, measured by the weighted compatibility of hook design with the state variable schemas, callback interfaces, and business model requirements of alternative deployment targets. + +### Terminology Comparison + +| Term | Source Domain | Limitation for Hooks | +|------|---------------|---------------------| +| Factor Mobility | Labor Economics | Too macro-level (countries/sectors) | +| Asset Specificity | Transaction Cost Economics (Williamson) | Focuses on the *problem* (lock-in), not the *solution* | +| Portability | Immigration Economics | More commonly used for human capital | +| Fungibility | Finance | Too strong—hooks are differentiated, not identical | +| Composability | DeFi | Describes *what* happens, not the friction of doing so | +| **Redeployability** | Corporate Finance (Kim & Kung, 2017) | ✓ Directly captures integration friction | + +### Theoretical Foundations + +#### Transaction Cost Economics (Williamson) + +**Asset Specificity** has four dimensions relevant to hooks: + +| Specificity Type | Hook Manifestation | +|------------------|-------------------| +| Site specificity | Hook designed for specific chain/L2 environment | +| Physical asset specificity | State variable structures, data schemas | +| Human asset specificity | Developer knowledge of particular hook's internals | +| Dedicated assets | Integration code, adapters, testing infrastructure | + +The **hold-up problem** arises when hooks require relationship-specific investments that create bilateral dependency and reduce redeployability. + +#### Labor Economics: Skill Transferability + +From Gathmann & Schonberg (2010) on task-specific human capital: +- Skills are more portable than thought when *tasks* are similar +- Wage losses depend on switching *skill portfolios*, not occupation codes + +**Hook analog**: Integration costs depend on "hook distance"—how different the target pool's requirements are from the hook's native design. + +#### Platform Economics: Multi-homing + +From Bank of England Working Paper 839: + +| Cost Type | Definition | Hook Application | +|-----------|------------|------------------| +| Multi-homing costs | Fixed costs of maintaining presence on multiple platforms | Maintaining hook across multiple pool architectures | +| Switching costs | One-time costs of moving between platforms | Migrating hook from Pool A to Pool B | +| Data portability | Ability to transfer state/history | Hook state migration across protocols | + +### Mathematical Formalization + +#### Redeployability Index + +Adapted from Kim & Kung (2017): + +$$\rho_h = \sum_{p \in \mathcal{P}} \omega_p \cdot \text{Compatibility}(h, p)$$ + +Where: +- $\rho_h \in [0,1]$: Redeployability index for hook $h$ +- $\omega_p$: Importance weight of pool $p$ (e.g., TVL share) +- $\text{Compatibility}(h, p) \in [0,1]$: Degree to which hook $h$ integrates with pool $p$ + +#### Integration Cost Function + +$$C_{\text{int}}(h, p) = \alpha \cdot d_{\text{state}}(h, p) + \beta \cdot d_{\text{flow}}(h, p) + \gamma \cdot d_{\text{model}}(h, p)$$ + +Where: +- $d_{\text{state}}(h, p)$: State variable distance (schema incompatibility) +- $d_{\text{flow}}(h, p)$: Flow incompatibility (callback sequence mismatch) +- $d_{\text{model}}(h, p)$: Business model mismatch (revenue structure) +- $\alpha, \beta, \gamma$: Weighting coefficients + +#### Hook Distance Metric + +Analogous to occupational distance in labor economics: + +$$D(h; p_1, p_2) = \|\mathbf{r}_{p_1} - \mathbf{r}_{p_2}\|$$ + +Where $\mathbf{r}_p$ is the **requirement vector** for pool $p$, capturing: +- Callback interfaces required +- State variable schemas +- Gas efficiency constraints +- Security assumptions + +### Barriers to Redeployability + +| Barrier | Description | Williamson Classification | +|---------|-------------|--------------------------| +| **State Variable Heterogeneity** | Each protocol defines state variables differently | Physical asset specificity | +| **Flow Incompatibility** | Different transaction flows and callback sequences | Site specificity | +| **Business Model Divergence** | Revenue models vary (fixed fee, dynamic, revenue share) | Dedicated assets | +| **Security Assumptions** | Different trust models and audit requirements | Human asset specificity | + +### Market Segmentation Effects + +Low hook redeployability creates **segmented factor markets**: + +$$p_h^{(A)} \neq p_h^{(B)} \quad \text{when } \rho_h \approx 0$$ + +Where $p_h^{(A)}$ and $p_h^{(B)}$ are prices for hook $h$ in protocols A and B. + +**Economic consequences**: +- Price discovery is impaired (fewer competing hooks per pool) +- Rent extraction by pools that have captured specific hooks +- Reduced allocative efficiency across the ecosystem + +### Policy Interventions to Increase Redeployability + +| Intervention | Source | Hook Bazaar Implementation | +|--------------|--------|---------------------------| +| **Standardization** | TCE | Common callback interfaces (ERC-style standards) | +| **Modular Design** | Software Engineering | Separate hook logic from pool-specific adapters | +| **Data Portability** | Platform Economics | Standardized hook state interfaces | +| **Transparent Registries** | Information Economics | Capability metadata, audit status | +| **Adapter Layers** | DeFi Composability | Diamond pattern with facet abstraction | + +**Hook Bazaar's role**: Increase $\rho_h$ through standardized interfaces, adapter layers, and reputation portability. + +--- + +## Protocol SAM Structure ($P_{ij}$) + +### Ontological Classification + +Protocols occupy a **hybrid position** in the SAM: + +| SAM Role | Traditional Economy | DeFi Protocol Analog | Justification | +|----------|---------------------|---------------------|---------------| +| **Activity** | Industry/Production | Pool operations | Protocols "produce" liquidity services | +| **Institution** | Government/Households | Governance layer | Protocols coordinate factor allocation | +| **Factor Owner** | Land, Labor, Capital | Smart contract owner | Protocols own pool infrastructure | + +The appropriate representation is a **dual-account structure**: + +$$\mathbf{P} = \mathbf{P}^{A} \oplus \mathbf{P}^{I}$$ + +Where: +- $\mathbf{P}^{A}$: Protocol Activity accounts (production/consumption of hook services) +- $\mathbf{P}^{I}$: Protocol Institutional accounts (governance, transfers, coordination) + +### Protocol Activity Matrix $P^{A}_{ij}$ + +The protocol activity matrix captures protocols as **consumers of hook factor services**: + +$$\mathbf{P}^{A} = [P^{A}_{ij}] \quad \text{where } i \in \{1,...,m\}, j \in \{1,...,m\}$$ + +| Dimension | Interpretation | +|-----------|---------------| +| Row $i$ | Protocol $i$'s **receipts** from providing pool services | +| Column $j$ | Protocol $j$'s **expenditures** on inputs (including hooks) | + +**Column Structure (Expenditures by Protocol $j$)**: + +$$E_j^{P} = \underbrace{\sum_{h=1}^{n} F_{hj}}_{\text{Hook Factor Payments}} + \underbrace{L_j + K_j}_{\text{Primary Factors}} + \underbrace{T_j^{import}}_{\text{Intermediate Imports}}$$ + +Where: +- $F_{hj}$: Payment to hook $h$ by protocol $j$ +- $L_j$: Developer labor costs +- $K_j$: Infrastructure capital costs +- $T_j^{import}$: Imported services from other protocols + +### Protocol Institutional Matrix $P^{I}_{ij}$ + +Protocols exercise institutional functions analogous to government: + +| Entry | Description | +|-------|-------------| +| $P^{I}_{HH}$ | Hook-to-hook inter-protocol transfers | +| $P^{I}_{HP}$ | Hook income paid to protocol treasuries | +| $P^{I}_{PL}$ | Protocol distributions to LPs | +| $P^{I}_{PS}$ | Protocol savings/reinvestment | +| $P^{I}_{PM}$ | Protocol payments to marketplace (Hook Bazaar) | + +### Quasi-Governmental Functions + +| Government Function | Protocol Analog | SAM Account | +|--------------------|-----------------|-------------| +| **Taxation** | Protocol fees on swaps | $P^{I}_{fee}$ | +| **Redistribution** | Fee distribution to LPs | $P^{I}_{PL}$ | +| **Public Goods** | Pool infrastructure | $P^{A}_{infra}$ | +| **Regulation** | Hook selection/governance | $P^{I}_{gov}$ | +| **Monetary Policy** | Dynamic fee adjustment | $P^{I}_{dyn}$ | + +--- + +## Hook-Protocol Integration Matrix $\Phi$ + +### Formal Linkage Structure + +The connection between protocol accounts ($P$) and hook accounts ($H$) is mediated by an **integration matrix** $\Phi$: + +$$\Phi: \mathbf{H} \times \mathbf{P}^{A} \rightarrow \mathbb{R}^{n \times m}$$ + +Where $\Phi_{hp}$ represents hook $h$'s value contribution to protocol $p$. + +### Revenue Share Model Mapping + +Three pricing models map to SAM entries: + +**Model 1: Fixed Price (One-time)** + +$$\Phi_{hp}^{fixed} = \pi_h \cdot \mathbb{1}_{t=0}$$ + +SAM entry: Single capital transfer from protocol to hook developer at $t=0$. + +**Model 2: Revenue Share** + +$$\Phi_{hp}^{share}(t) = \theta_h \cdot \phi_p(t) \cdot V_p(t)$$ + +Where: +- $\theta_h \in [0, 0.3]$: Hook's revenue share (capped at 30%) +- $\phi_p(t)$: Pool $p$'s swap fee rate +- $V_p(t)$: Swap volume at time $t$ + +SAM entries: Continuous flow from pool fee account to hook income account. + +**Model 3: Hybrid** + +$$\Phi_{hp}^{hybrid} = \pi_h^{fixed} + \int_0^T \theta_h \cdot \phi_p(t) \cdot V_p(t) \, dt$$ + +### Matrix Entry Specification + +For each $(h, p)$ pair: + +$$\Phi_{hp} = \begin{cases} +\pi_h & \text{if fixed price} \\ +\sum_{t=1}^{T} \theta_h \phi_p V_{pt} & \text{if revenue share} \\ +\pi_h + \sum_{t=1}^{T} \theta_h \phi_p V_{pt} & \text{if hybrid} +\end{cases}$$ + +--- + +## Complete SAM Block Structure + +### Full Hook Bazaar SAM + +$$\mathbf{SAM} = \begin{bmatrix} +\mathbf{H} & \mathbf{\Phi} & \mathbf{0} & \mathbf{\Omega}_H \\ +\mathbf{\Phi}^T & \mathbf{P}^A & \mathbf{\Lambda} & \mathbf{\Omega}_P \\ +\mathbf{0} & \mathbf{\Lambda}^T & \mathbf{E} & \mathbf{\Omega}_E \\ +\mathbf{\Omega}_H^T & \mathbf{\Omega}_P^T & \mathbf{\Omega}_E^T & \mathbf{I} +\end{bmatrix}$$ + +Where: +- $\mathbf{H}$: Hook factor accounts ($n \times n$) +- $\mathbf{P}^A$: Protocol activity accounts ($m \times m$) +- $\mathbf{E}$: External agent accounts (LPs, swappers, developers) +- $\mathbf{I}$: Institutional accounts (protocol treasuries, marketplace) +- $\mathbf{\Phi}$: Hook-Protocol integration matrix ($n \times m$) +- $\mathbf{\Lambda}$: Protocol-External flows ($m \times k$) +- $\mathbf{\Omega}$: Cross-block transfer matrices + +### Accounting Identities + +**Identity 1: Hook Income Balance** + +$$\sum_j H_{ij} = \sum_j H_{ji} + \sum_p \Phi_{ip} + \Omega_{iE}$$ + +**Identity 2: Protocol Activity Balance** + +$$\sum_h \Phi_{hp} + \sum_q P^A_{qp} = \sum_h \Phi_{ph} + \sum_q P^A_{pq} + \Lambda_p$$ + +**Identity 3: SAM Global Balance** + +$$\sum_{i} R_i = \sum_{j} E_j$$ + +**Identity 4: Multi-Sided Market Balance** + +For each agent class $c \in \{D, P, L, S\}$ (Developers, Protocols, LPs, Swappers): + +$$\sum_{i \in c} \text{Income}_i = \sum_{j \in c} \text{Expenditure}_j + \text{Net Savings}_c$$ + +### Integrated SAM Example (ETH/week) + +| | $H_1$ | $H_2$ | $H_3$ | $H_4$ | $P_1$ | $P_2$ | LP | Swap | **Row** | +|--|-------|-------|-------|-------|-------|-------|-----|------|---------| +| $H_1$ | 12.5 | 0.8 | 0 | 1.2 | **3.5** | **2.0** | 0 | 0 | 20.0 | +| $H_2$ | 0.3 | 8.7 | 2.1 | 0.5 | **1.8** | **1.2** | 0 | 0 | 14.6 | +| $H_3$ | 1.5 | 1.8 | 4.2 | 0.9 | **0.9** | **0.7** | 0 | 0 | 10.0 | +| $H_4$ | 0.7 | 0.4 | 0.3 | 6.1 | **1.3** | **0.6** | 0 | 0 | 9.4 | +| $P_1$ | 0 | 0 | 0 | 0 | 0 | 5.2 | **8.5** | **22.3** | 36.0 | +| $P_2$ | 0 | 0 | 0 | 0 | 4.8 | 0 | **6.2** | **18.5** | 29.5 | +| LP | 0 | 0 | 0 | 0 | 18.2 | 14.8 | 0 | 0 | 33.0 | +| Swap | 0 | 0 | 0 | 0 | 0 | 0 | 18.3 | 0 | 18.3 | +| **Col** | 15.0 | 11.7 | 6.6 | 8.7 | 30.5 | 24.5 | 33.0 | 40.8 | **170.8** | + +**Bold entries** = $\Phi$ matrix (hook-protocol linkages) + +--- + +## Market Failure Representation in SAM + +### SAM Diagnosis of Market Failures + +The nine market failures from the Problem Description map to SAM structural deficiencies: + +| Market Failure | SAM Symptom | Missing Flow | +|----------------|-------------|--------------| +| **1. Missing Marketplace** | $\Phi_{hp} = 0 \; \forall h,p$ | Hook-protocol linkage | +| **2. High Barriers** | $P^A_{entry} \gg 0$ | Capital-to-production flow blocked | +| **3. No Incentive Layer** | $T_{PH} = 0$ | Developer income channel | +| **4. No Standardization** | $\text{Var}(H_{ij}) \rightarrow \infty$ | Incomparable hook accounts | +| **5. No Composition** | $H_{ij} = 0 \; \forall i \neq j$ | Inter-hook value flows | +| **6. No Competition** | $\partial H_{ii}/\partial H_{jj} = 0$ | Substitution effects absent | +| **7. No IP Protection** | $\theta_h \rightarrow 0$ | Developer income eroded | +| **8. No Reputation** | $\alpha_p(h) \sim \text{Uniform}$ | Information asymmetry | +| **9. Unsustainable Economics** | $\sum_t R_h < \sum_t C_h$ | Negative NPV for developers | + +### Formal Market Failure Conditions + +**Definition (Missing Market)**: A market $M_{hp}$ between hook $h$ and protocol $p$ is **missing** iff: + +$$\Phi_{hp} = 0 \quad \text{and} \quad \exists \; \text{gains from trade} \; (V_h^* > V_h^{autarky}, V_p^* > V_p^{autarky})$$ + +**Definition (Blocked Flow)**: A SAM flow $F_{ij}$ is **blocked** iff: + +$$F_{ij} = 0 \quad \text{while} \quad \partial U_i / \partial F_{ij} > 0 \quad \text{and} \quad \partial U_j / \partial F_{ij} > 0$$ + +### How Hook Bazaar "Completes" the SAM + +**Before Hook Bazaar** (sparse, missing markets): + +$$\mathbf{SAM}_{before} = \begin{bmatrix} +\mathbf{H}_{sparse} & \mathbf{0} & \mathbf{0} \\ +\mathbf{0} & \mathbf{P}^A_{isolated} & \mathbf{\Lambda} \\ +\mathbf{0} & \mathbf{\Lambda}^T & \mathbf{E} +\end{bmatrix}$$ + +**After Hook Bazaar** (dense, functioning markets): + +$$\mathbf{SAM}_{after} = \begin{bmatrix} +\mathbf{H}_{dense} & \mathbf{\Phi} & \mathbf{\Omega}_H \\ +\mathbf{\Phi}^T & \mathbf{P}^A_{integrated} & \mathbf{\Lambda} \\ +\mathbf{\Omega}_H^T & \mathbf{\Lambda}^T & \mathbf{E} +\end{bmatrix}$$ + +### Market Completion Effects + +| SAM Region | Before | After | Economic Effect | +|------------|--------|-------|-----------------| +| $\mathbf{\Phi}$ | Zero matrix | Dense | Hook factor market activated | +| $\mathbf{H}$ diagonal | Sparse | Dense | Hook specialization | +| $\mathbf{H}$ off-diagonal | Zero | Positive | Composability value | +| $\mathbf{\Omega}_H$ | Zero | Positive | Developer income | +| $\mathbf{P}^A$ | Isolated | Integrated | Protocol efficiency gains | + +--- + +## Notation Summary + +| Symbol | Dimension | Description | +|--------|-----------|-------------| +| $\mathbf{H}$ | $n \times n$ | Hook factor income matrix | +| $\mathbf{P}^A$ | $m \times m$ | Protocol activity matrix | +| $\mathbf{P}^I$ | $m \times m$ | Protocol institutional matrix | +| $\mathbf{\Phi}$ | $n \times m$ | Hook-Protocol integration matrix | +| $\mathbf{\Lambda}$ | $m \times k$ | Protocol-External flow matrix | +| $\mathbf{T}$ | $(n+m+k)^2$ | Transfer matrix | +| $\theta_h$ | Scalar | Revenue share rate for hook $h$ | +| $\alpha_p(h)$ | Scalar | Protocol $p$'s selection probability for hook $h$ | +| $\rho_h$ | Scalar | Redeployability index for hook $h$ | + +--- + +## References + +### SAM and General Equilibrium + +1. Arrow, K. J., & Debreu, G. (1954). Existence of an equilibrium for a competitive economy. *Econometrica*, 22(3), 265-290. + +2. Leontief, W. W. (1936). Quantitative input and output relations in the economic systems of the United States. *Review of Economics and Statistics*, 18(3), 105-125. + +3. Pyatt, G., & Round, J. I. (1979). Accounting and fixed price multipliers in a social accounting matrix framework. *Economic Journal*, 89(356), 850-873. + +4. Samuelson, P. A. (1953). Prices of factors and goods in general equilibrium. *Review of Economic Studies*, 21(1), 1-20. + +5. Reinert, K. A., & Roland-Holst, D. W. (1997). Social Accounting Matrices. In *Applied Methods for Trade Policy Analysis*, 94-121. Cambridge University Press. + +6. Sraffa, P. (1960). *Production of Commodities by Means of Commodities*. Cambridge University Press. + +### Transaction Cost Economics + +7. Williamson, O. E. (2009). Transaction Cost Economics: The Natural Progression. *Nobel Prize Lecture*. https://www.nobelprize.org/uploads/2018/06/williamson_lecture.pdf + +8. Tadelis, S., & Williamson, O. E. (2012). Transaction Cost Economics. In *Handbook of Organizational Economics*. https://faculty.haas.berkeley.edu/stadelis/tce_org_handbook_111410.pdf + +### Asset Redeployability + +9. Kim, H., & Kung, H. (2017). The Asset Redeployability Channel: How Uncertainty Affects Corporate Investment. *Review of Financial Studies*, 30(1), 245-280. https://academic.oup.com/rfs/article-abstract/30/1/245/2669940 + +### Labor Economics and Skill Transferability + +10. Gathmann, C., & Schonberg, U. (2010). How General Is Human Capital? A Task-Based Approach. *Journal of Labor Economics*, 28(1), 1-49. https://www.journals.uchicago.edu/doi/10.1086/649786 + +11. NBER Working Paper 32908 (2024). Skills and Human Capital. https://www.nber.org/papers/w32908 + +### Platform Economics + +12. Rochet, J. C., & Tirole, J. (2003). Platform Competition in Two-Sided Markets. *Journal of the European Economic Association*, 1(4), 990-1029. + +13. Bank of England (2019). Platform Competition and Data Portability. *Working Paper 839*. https://ideas.repec.org/p/boe/boeewp/0839.html + +14. Lam, W. M. W. (2017). Switching Costs in Two-Sided Markets. *Journal of Industrial Economics*. https://onlinelibrary.wiley.com/doi/10.1111/joie.12133 + +### DeFi and Composability + +15. von Wachter, V., Jensen, J. R., & Ross, O. (2021). Measuring Asset Composability as a Proxy for DeFi Integration. *arXiv:2102.04227*. https://arxiv.org/abs/2102.04227 + +16. Bartoletti, M., Chiang, J. H., & Lluch-Lafuente, A. (2023). A Theory of Compositionality for Smart Contracts. *arXiv:2309.10781*. https://arxiv.org/abs/2309.10781 + +17. Schär, F. (2021). Decentralized Finance: On Blockchain and Smart Contract-Based Financial Markets. *Federal Reserve Bank of St. Louis Review*. https://www.stlouisfed.org/publications/review/2021/02/05/decentralized-finance-on-blockchain-and-smart-contract-based-financial-markets + +18. Adams, H., et al. (2024). Uniswap V4 Core. *Uniswap Labs Technical Documentation*. + diff --git a/docs/problem-description/Protocol_Cost_Function.md b/docs/problem-description/Protocol_Cost_Function.md new file mode 100644 index 00000000..05746f9a --- /dev/null +++ b/docs/problem-description/Protocol_Cost_Function.md @@ -0,0 +1,414 @@ +## Protocol Cost Function for DeFi Hook Deployment + +### Overview + +This document formalizes the **total cost** faced by protocols deploying Uniswap V4 hooks. The cost function captures both integration costs and the inherent costs of production-ready code deployment in DeFi. + +--- + +## The Cost Minimization Problem + +Protocols aim to minimize total deployment cost: + +$$\min_{h \in \mathcal{H}} C_{total}(h, p)$$ + +Subject to: +- Hook functionality requirements $f_p$ +- Security constraints $s_p$ +- Gas efficiency bounds $g_p$ + +--- + +## Total Cost Decomposition + +$$C_{total}(h, p) = \underbrace{C_{int}(h, p)}_{\text{Integration Cost}} + \underbrace{C_{prod}(h)}_{\text{Production Cost}}$$ + +Where: +- $C_{int}$: Cost of integrating hook $h$ with protocol $p$ +- $C_{prod}$: Cost of producing production-ready code + +--- + +## Integration Cost ($C_{int}$) + +From [Hooks.md](./Hooks.md): + +$$C_{int}(h, p) = \alpha \cdot d_{state}(h, p) + \beta \cdot d_{flow}(h, p) + \gamma \cdot d_{model}(h, p)$$ + +| Component | Symbol | Description | +|-----------|--------|-------------| +| State distance | $d_{state}$ | Schema incompatibility between hook and pool | +| Flow distance | $d_{flow}$ | Callback sequence mismatch | +| Model distance | $d_{model}$ | Business model mismatch | + +### Self-Built Hook Case + +When a protocol builds its own hook: + +$$d_j \to 0 \implies C_{int} \sim 0$$ + +**Why**: The protocol has full control over minimizing state, flow, and model distances by designing the hook to match their exact specifications. + +--- + +## Production Cost ($C_{prod}$) + +The production cost captures inherent costs of deploying code in DeFi: + +$$C_{prod}(h) = C_{audit}(h) + C_{dev}(h) + C_{opp}(h) + C_{test}(h) + C_{maint}(h)$$ + +### Component Breakdown (Empirically Derived) + +| Cost | Symbol | Description | Empirical Range | Source | +|------|--------|-------------|-----------------|--------| +| **Audit Cost** | $C_{audit}$ | External security audit | $10k - $100k+ | Sherlock, Code4rena | +| **Developer Labor** | $C_{dev}$ | Specification + implementation | $5k - $50k+ | Web3.career, Arc | +| **Opportunity Cost** | $C_{opp}$ | Time-to-market delay | Variable | - | +| **Testing Cost** | $C_{test}$ | Unit, integration, fuzzing | $2k - $20k | - | +| **Maintenance Cost** | $C_{maint}$ | Ongoing updates, patches | $1k - $10k/yr | - | + +--- + +## Empirical Audit Cost Data + +### Competitive Audit Platforms + +#### Sherlock Protocol + +| Metric | Value | Source | +|--------|-------|--------| +| Total rewards paid | $14.8M+ | [Sherlock Docs](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) | +| Prize pool range | $30k - $200k per contest | [Sherlock Docs](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) | +| Premium contests | Up to $700k (Optimism) | [Sherlock Docs](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) | +| Lead Senior Watson pay | ~$10k per audit week | [Sherlock Docs](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) | + +**nSLOC Guidelines** (from Sherlock): +| Lines of Code | Audit Duration | +|---------------|----------------| +| 500 nSLOC | 3 days | +| 2,000 nSLOC | 14 days | +| 6,000 nSLOC | 38 days | + +#### Code4rena + +| Metric | Value | Source | +|--------|-------|--------| +| 2023 total awards | $4,823,059 | [Code4rena 2024](https://medium.com/code4rena/welcome-to-2024-at-code4rena-f0929a6ae3a8) | +| Contests in 2023 | 114 protocols | [Code4rena 2024](https://medium.com/code4rena/welcome-to-2024-at-code4rena-f0929a6ae3a8) | +| Average prize pool | ~$42,307 per contest | Calculated | +| Top warden (cmichel) | 395,626 LOC audited, $1M earned | [cmichel stats](https://cmichel.io/code4rena-first-1m-stats/) | + +**Derived Cost Per Line of Code**: +$$C_{audit}/SLOC = \frac{\$1,000,000}{395,626 \text{ LOC}} \approx \$2.53/\text{LOC}$$ + +#### Immunefi + +| Metric | Value | Source | +|--------|-------|--------| +| Total payouts (3 years) | $100M+ | [The Block](https://www.theblock.co/post/301025/web3-immunefi-ethical-hacker-payouts) | +| Smart contract bugs | $77.97M (77.5%) | [The Block](https://www.theblock.co/post/301025/web3-immunefi-ethical-hacker-payouts) | +| Highest single bounty | $10M (Wormhole) | [The Block](https://www.theblock.co/post/301025/web3-immunefi-ethical-hacker-payouts) | + +### Traditional Audit Firms + +| Firm Tier | Cost Range | Source | +|-----------|------------|--------| +| Top-tier (Trail of Bits, OpenZeppelin, ConsenSys) | $100k - $500k+ | [Ulam Labs](https://www.ulam.io/blog/smart-contract-audit) | +| Mid-tier | $20k - $75k | [Ulam Labs](https://www.ulam.io/blog/smart-contract-audit) | +| Simple ERC-20 | $10k - $20k | [Medium/Predict](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) | +| Complex DeFi | $75k - $150k | [Medium/Predict](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) | +| Cross-chain bridges | $100k - $300k+ | [Medium/Predict](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) | + +### Cost Per Line of Code Summary + +| Derivation Method | $C_{audit}/SLOC$ | Source | +|-------------------|------------------|--------| +| cmichel competitive audits | $2.53/LOC | [cmichel](https://cmichel.io/code4rena-first-1m-stats/) | +| Simple contracts (industry) | $3-4/LOC | [Ulam Labs](https://www.ulam.io/blog/smart-contract-audit) | +| Complex DeFi protocols | $15-20/LOC | [Medium/Predict](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) | +| Sherlock nSLOC-based (median) | $10-50/nSLOC | [Sherlock Docs](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) | +| **Recommended for model** | **$25-50/SLOC** | Weighted average | + +--- + +## Developer Labor Cost ($C_{dev}$) + +### Solidity Developer Rates + +| Level | Hourly Rate | Source | +|-------|-------------|--------| +| Junior | $40-65/hr | [Arc](https://arc.dev/freelance-developer-rates/solidity) | +| Mid-level | $65-100/hr | [Web3.career](https://web3.career/web3-salaries/solidity-developer) | +| Senior | $100-150/hr | [Alchemy](https://www.alchemy.com/overviews/solidity-developer-salary) | +| Expert/Specialist | $150-350/hr | [Arc](https://arc.dev/freelance-developer-rates/solidity) | +| Freelance average | $78-100/hr | [Arc](https://arc.dev/freelance-developer-rates/solidity) | + +### DeFi-Specific Skill Premiums + +| Specialization | Premium | Source | +|----------------|---------|--------| +| Solidity expertise | +30% | Industry estimate | +| Uniswap V4 hook experience | +50% | Industry estimate | +| Security background | +40% | Industry estimate | + +--- + +## Audit Cost Formula + +$$C_{audit}(h) = \tau_{audit} \cdot r_{auditor} \cdot \text{SLOC}(h) \cdot \kappa(h)$$ + +Where: +- $\tau_{audit}$: Time per line of code (auditor throughput) +- $r_{auditor}$: Auditor hourly rate ($200-500/hr for top firms) +- $\text{SLOC}(h)$: Source lines of code +- $\kappa(h)$: Complexity multiplier (1.0 - 3.0) + +### DeFi-Specific Cost Multipliers + +| Factor | Additional Cost | Source | +|--------|-----------------|--------| +| Reentrancy analysis | +20-40% | [Ulam Labs](https://www.ulam.io/blog/smart-contract-audit) | +| Cross-contract interactions | +30-50% | [Ulam Labs](https://www.ulam.io/blog/smart-contract-audit) | +| Token standard compliance | +10-20% | [Medium/Predict](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) | +| Formal verification | +100-200% | [Medium/Predict](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) | + +--- + +## The Self-Build Trade-off + +### Protocol Self-Builds Hook + +When protocol $p$ builds hook $h$ internally: + +| Cost Component | Value | Reason | +|----------------|-------|--------| +| $C_{int}$ | $\sim 0$ | Full control over $d_j$ | +| $C_{audit}$ | Full ($10k-100k+) | Required for trust | +| $C_{dev}$ | Full ($5k-50k+) | In-house or contracted | +| $C_{opp}$ | High | Weeks to months delay | +| $C_{test}$ | Full ($2k-20k) | Required for safety | + +**Total (self-build)**: +$$C_{total}^{self} \approx C_{prod} = C_{audit} + C_{dev} + C_{opp} + C_{test}$$ + +**Empirical estimate**: $17k - $170k+ + +### Protocol Uses Hook Bazaar (HaaS Model) + +When protocol $p$ purchases hook $h$ from Hook Bazaar: + +| Cost Component | Value | Reason | +|----------------|-------|--------| +| $C_{int}$ | Reduced | Standardized interfaces | +| $C_{audit}$ | $\sim 0$ | Pre-audited | +| $C_{dev}$ | $\sim 0$ | Pre-built | +| $C_{opp}$ | Low | Minutes to deploy | +| $C_{test}$ | Reduced | Battle-tested | +| $C_{purchase}$ | New | Hook purchase price | + +**Total (Hook Bazaar)**: +$$C_{total}^{HB} = C_{int}^{reduced} + C_{purchase}$$ + +--- + +## Hook Distance Minimization + +### Hook Bazaar's Primary Objective + +Hook Bazaar minimizes the **Hook Distance Metric**: + +$$D(h; p_1, p_2) = \|\mathbf{r}_{p_1} - \mathbf{r}_{p_2}\|$$ + +Where $\mathbf{r}_p$ is the **requirement vector** for pool $p$: + +$$\mathbf{r}_p = \begin{pmatrix} r_p^{callback} \\ r_p^{state} \\ r_p^{gas} \\ r_p^{security} \end{pmatrix}$$ + +### Standardization Reduces Distance + +Hook Bazaar implements standardization through: + +| Dimension | Mechanism | Distance Reduction | +|-----------|-----------|-------------------| +| Callback interfaces | IHooks compliance | 70-85% | +| State schemas | Diamond storage patterns | 60-75% | +| Flow patterns | MasterHook routing | 55-70% | + +### Distance-Cost Relationship + +$$C_{int}(h, p) \propto D(h; p, p_{native})$$ + +Minimizing $D$ directly minimizes integration cost $C_{int}$. + +--- + +## Connection to HaaS Pricing Solution + +### Hook Bazaar Pricing Models + +From [market/solutionSpec.md](../hook-pkg/market/solutionSpec.md): + +| Model | Formula | Use Case | +|-------|---------|----------| +| **Fixed Price** | $\pi_h$ | One-time licensing | +| **Revenue Share** | $\theta_h \cdot \phi_p \cdot V_p$ | Ongoing % of swap fees | +| **Hybrid** | $\pi_h + \theta_h \cdot \phi_p \cdot V_p$ | Combined | + +### Optimal Hook Price Constraint + +For Hook Bazaar to provide value: + +$$C_{purchase} < C_{prod}$$ + +Expanding: + +$$\underbrace{\pi_h + \int_0^T \theta_h \cdot \phi_p \cdot V_p \, dt}_{\text{Hook Bazaar Price (HaaS)}} < \underbrace{C_{audit} + C_{dev} + C_{opp} + C_{test}}_{\text{Self-Build Cost}}$$ + +### Protocol's Cost Optimization + +The protocol solves: + +$$\min_{h \in \mathcal{H}_{HB}} \left[ C_{int}(h, p) + C_{purchase}(h) \right]$$ + +Where $\mathcal{H}_{HB}$ is the set of hooks available in Hook Bazaar. + +### HaaS Pricing Model Details + +From [market_structure_docs.md](../hook-market-pkg/market_structure_docs.md): + +**Fixed Price (v1)**: +- Simple user experience +- Predictable developer income +- No dependency on pool performance + +**Revenue Share (v1)**: +- Aligns developer incentives with pool performance +- No large upfront cost for protocols +- Uses [Splits Protocol](https://splits.org/) for distribution +- **Safeguard**: Max developer share capped at 30% + +**Hybrid (v1)**: +- Combines upfront payment with ongoing revenue +- Balances risk between developer and protocol + +--- + +## Cost Function by Hook Complexity + +### Simple Hooks (Fee adjustment, basic oracle) + +| Component | Self-Build | Hook Bazaar | Sources | +|-----------|-----------|-------------|---------| +| $C_{int}$ | $0 | $100-500 | - | +| $C_{audit}$ | $5k-15k | $0 | [Sherlock](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) | +| $C_{dev}$ | $3k-10k | $0 | [Arc](https://arc.dev/freelance-developer-rates/solidity) | +| $C_{opp}$ | 2-4 weeks | Minutes | - | +| **Total** | **$8k-25k** | **$100-500** | - | + +### Complex Hooks (MEV protection, dynamic rebalancing) + +| Component | Self-Build | Hook Bazaar | Sources | +|-----------|-----------|-------------|---------| +| $C_{int}$ | $0 | $500-2k | - | +| $C_{audit}$ | $30k-100k | $0 | [Code4rena](https://code4rena.com/), [Trail of Bits](https://www.trailofbits.com/) | +| $C_{dev}$ | $20k-60k | $0 | [Web3.career](https://web3.career/web3-salaries/solidity-developer) | +| $C_{opp}$ | 2-6 months | Minutes | - | +| **Total** | **$50k-160k** | **$500-2k** | - | + +--- + +## Risk-Adjusted Cost + +### Expected Cost with Risk + +$$E[C_{total}] = C_{total} + \sum_i P_i \cdot L_i$$ + +Where: +- $P_i$: Probability of risk event $i$ +- $L_i$: Loss from risk event $i$ + +| Risk | Self-Build $P$ | Hook Bazaar $P$ | Potential Loss | Source | +|------|---------------|-----------------|----------------|--------| +| Undiscovered vulnerability | 5-15% | 0.5-2% | $100k-$10M+ | [Immunefi](https://immunefi.com/) | +| Integration bug | 10-20% | 2-5% | $10k-$1M | - | +| Delayed launch | 30-50% | <5% | Variable | - | + +--- + +## Hook Bazaar's Two-Pronged Strategy + +### 1. Minimize Hook Distance $D(h; p_1, p_2)$ + +Through standardization: +- **IHooks interface compliance** - Standardized callbacks +- **Diamond storage patterns** - Common state schemas +- **MasterHook routing** - Consistent flow patterns + +Result: $D \to 0$ as ecosystem adoption increases. + +### 2. Eliminate Production Cost $C_{prod}$ + +Through HaaS model: +- **Pre-audited code** - $C_{audit} \to 0$ +- **Production-ready implementations** - $C_{dev} \to 0$ +- **Battle-tested deployments** - $C_{test} \to 0$ +- **Instant deployment** - $C_{opp} \to 0$ + +--- + +## Value Creation Formula + +$$\Delta C = C_{total}^{self} - C_{total}^{HB}$$ + +Using empirical estimates: + +| Hook Type | Self-Build | Hook Bazaar | Savings | +|-----------|-----------|-------------|---------| +| Simple | $8k-25k | $100-500 | **$7.5k-24.5k** | +| Complex | $50k-160k | $500-2k | **$49.5k-158k** | + +--- + +## Conclusion + +The total cost function for DeFi hook deployment: + +$$C_{total} = C_{int} + C_{audit} + C_{dev} + C_{opp} + C_{test} + C_{maint}$$ + +**Hook Bazaar's value proposition**: + +1. **Minimizes $D(h; p_1, p_2)$** through standardized interfaces $\to$ reduces $C_{int}$ +2. **Eliminates $C_{audit}$** through pre-audited code +3. **Eliminates $C_{dev}$** through marketplace offerings (HaaS) +4. **Minimizes $C_{opp}$** through instant deployment +5. **Reduces $C_{test}$** through battle-tested code + +Protocol costs drop from **$10k-$160k+** to **$100-$2k**, with time-to-market from **weeks/months** to **minutes**. + +--- + +## References + +### Audit Platforms +1. Sherlock Protocol. (2024). Audit Pricing and Timeline. https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline +2. Code4rena. (2024). Welcome to 2024 at Code4rena. https://medium.com/code4rena/welcome-to-2024-at-code4rena-f0929a6ae3a8 +3. cmichel. (2023). Code4rena First $1M Stats. https://cmichel.io/code4rena-first-1m-stats/ +4. Immunefi. (2024). Web3 Ethical Hacker Payouts. The Block. https://www.theblock.co/post/301025/web3-immunefi-ethical-hacker-payouts + +### Audit Cost Analysis +5. Ulam Labs. (2024). Smart Contract Audit Costs. https://www.ulam.io/blog/smart-contract-audit +6. Predict. (2024). Smart Contract Audit Costs and Processes: A Detailed Breakdown. https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa + +### Developer Rates +7. Arc. (2024). Freelance Solidity Developer Rates. https://arc.dev/freelance-developer-rates/solidity +8. Web3.career. (2024). Solidity Developer Salaries. https://web3.career/web3-salaries/solidity-developer +9. Alchemy. (2024). Solidity Developer Salary Guide. https://www.alchemy.com/overviews/solidity-developer-salary + +### Hook Bazaar Internal Documentation +10. [Hooks.md](./Hooks.md) - Hook Redeployability and Integration Cost +11. [market/solutionSpec.md](../hook-pkg/market/solutionSpec.md) - HaaS Pricing Models +12. [market_structure_docs.md](../hook-market-pkg/market_structure_docs.md) - Market Structure + +### Economic Theory +13. Williamson, O. E. (2009). Transaction Cost Economics: The Natural Progression. Nobel Prize Lecture. +14. Kim, H., & Kung, H. (2017). The Asset Redeployability Channel. Review of Financial Studies, 30(1), 245-280. +15. Gathmann, C., & Schonberg, U. (2010). How General Is Human Capital? Journal of Labor Economics, 28(1), 1-49. diff --git a/docs/problem-description/faq_slides_spec.md b/docs/problem-description/faq_slides_spec.md new file mode 100644 index 00000000..58ef3d2d --- /dev/null +++ b/docs/problem-description/faq_slides_spec.md @@ -0,0 +1,471 @@ +# Hook Bazaar FAQ Slides: Market Design Questions (Gamma Spec) + +## Overview + +**Story**: Animated FAQ - skeptical questions appear, then answers reveal with sponsor solutions (Fhenix FHE, EigenLayer AVS). + +**Tool**: Gamma Pro +**Duration**: ~60 seconds (4 slides) +**Format**: Animated Q&A - each question animates in, then answer reveals +**Source**: [market_design_questions.md](./market_design_questions.md) + +**IMPORTANT - Slide Titles**: Only Slide 1 has a title: **"But Wait..."**. All other slides have NO title. + +--- + +## Animated FAQ Flow + +``` +SLIDE 1: Question appears animatedly → "Bytecode risk?" +SLIDE 2: Answer reveals animatedly → "Fhenix FHE encrypts it!" +SLIDE 3: Question appears animatedly → "How verify compliance?" +SLIDE 4: Answer reveals animatedly → "AVS attestation!" +``` + +--- + +## Scene Breakdown + +### Scene 1: Question - Bytecode Risk +**Duration**: 15 seconds + +**Slide Title**: "But Wait..." (ONLY slide with a title) + +**Animation Flow**: +``` +[ANIMATED SEQUENCE] + +1. Skeptical stick figure draws in (2s) +2. Speech bubble appears: "A marketplace for hooks is great, but..." (2s) +3. Second bubble draws: "Once deployed on-chain..." (2s) +4. Bytecode appears on screen: "0x608060405234..." (2s) +5. Question draws in: "Can't someone just DECOMPILE it?" (3s) +6. Warning box appears: "BYTECODE EXPOSED" (2s) +7. Question marks float around head (2s) +``` + +**Gamma Prompt**: +``` +Create an ANIMATED whiteboard FAQ slide. + +SLIDE TITLE: "But Wait..." (ONLY this slide has a title) + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +ANIMATE IN SEQUENCE: +1. Draw skeptical stick figure (hand on chin pose) +2. Speech bubble writes: "A marketplace is great, but..." +3. Second bubble writes: "Once deployed on-chain..." +4. Bytecode draws on screen: "0x608060405234..." (deep blue #003366 edge) +5. Big question writes: "Can't someone DECOMPILE it?" +6. Warning box draws: "BYTECODE EXPOSED" (orange-red #E85A4F edge) +7. Question marks float around head + +Colors: Black lines, orange-red (#E85A4F) for warning, deep blue (#003366) for code +Each element draws in 2-3 seconds, building the concern + +NOTE: All other slides have NO title. +``` + +--- + +### Scene 2: Answer - Fhenix FHE Solution +**Duration**: 15 seconds + +**Animation Flow**: +``` +[ANIMATED SEQUENCE] + +1. Stick figure with lightbulb draws in (2s) +2. "SOLUTION:" header writes (1s) +3. "Fhenix FHE" writes with gold underline (2s) +4. BEFORE section draws: "Readable bytecode" then X crosses it (2s) +5. AFTER section draws: Lock icon + "ENCRYPTED" (2s) +6. Cost comparison animates: + "Before: $100-1,000" (crossed out) (1s) + "After: $1,000,000+" with rocket (2s) +7. Speech bubble: "Decompiling cost goes to the moon!" (2s) +8. Celebration marks appear (1s) +``` + +**Gamma Prompt**: +``` +Create an ANIMATED whiteboard answer slide. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +ANIMATE IN SEQUENCE: +1. Draw stick figure with lightbulb above head (gold #FFD700) +2. Write "SOLUTION:" header (gold edge) +3. Write "Fhenix FHE" with gold underline (sponsor highlight) +4. Draw BEFORE: "Readable bytecode" then animate X crossing it (orange-red #E85A4F) +5. Draw AFTER: Lock icon + "ENCRYPTED" (gold edge) +6. Animate cost comparison: + - "Before: $100-1,000" draws then crosses out + - "After: $1,000,000+" draws with rocket icon (gold) +7. Speech bubble writes: "Cost goes to the moon!" +8. Celebration marks pop around + +Colors: Black lines, gold (#FFD700) for solution, orange-red (#E85A4F) for old problem +Transformation feel - problem becomes solution +``` + +--- + +### Scene 3: Question - Compliance Verification +**Duration**: 15 seconds + +**Animation Flow**: +``` +[ANIMATED SEQUENCE] + +1. Protocol team (2-3 stick figures) draws in (2s) +2. Document draws in their hands: "Hook Spec" (2s) +3. Speech bubble: "Looks like a good fit!" (2s) +4. Second bubble: "But wait..." (1s) +5. Third bubble: "How do I verify it COMPLIES?" (2s) +6. Comparison draws: + "Spec: ✓ Can read" (gold) (1s) + "Code: ❌ No access" (red) (1s) +7. Big question circles: "How do I TRUST it?" (2s) +8. Question marks appear above team (2s) +``` + +**Gamma Prompt**: +``` +Create an ANIMATED whiteboard question slide. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +ANIMATE IN SEQUENCE: +1. Draw 2-3 stick figures (protocol team) +2. Draw document in hands labeled "Hook Spec" (deep blue #003366 edge) +3. Speech bubble writes: "Looks like a good fit!" +4. Second bubble writes: "But wait..." +5. Third bubble writes: "How verify it COMPLIES?" +6. Comparison draws: + - "Spec: ✓ Can read" (gold #FFD700 checkmark) + - "Code: ❌ No access" (orange-red #E85A4F X) +7. Big question circles in: "How do I TRUST it?" (orange-red edge) +8. Question marks float above team heads + +Colors: Black lines, gold (#FFD700) for what they have, orange-red (#E85A4F) for gap +Building legitimate trust concern +``` + +--- + +### Scene 4: Answer - AVS Attestation Solution +**Duration**: 15 seconds + +**Animation Flow**: +``` +[ANIMATED SEQUENCE] + +1. AVS Operator stick figure draws with shield icon (2s) +2. "SOLUTION:" header writes (1s) +3. "EigenLayer AVS" writes with gold underline (2s) +4. Attestation list animates (checkmarks appear): + ✓ "Compliance Score" (1s) + ✓ "Developer Reputation" (1s) + ✓ "Audit History" (1s) +5. Verification list animates: + ✓ "Fuzzing Tests" (1s) + ✓ "Compatibility Check" (1s) + ✓ "Adapter Recommendations" (1s) +6. Result circles in: "Trust WITHOUT source code!" (2s) +7. Celebration marks appear (1s) +``` + +**Gamma Prompt**: +``` +Create an ANIMATED whiteboard answer slide. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +ANIMATE IN SEQUENCE: +1. Draw stick figure "AVS Operator" with shield icon (gold #FFD700) +2. Write "SOLUTION:" header (gold edge) +3. Write "EigenLayer AVS" with gold underline (sponsor highlight) +4. Animate attestation checkmarks appearing one by one: + ✓ "Compliance Score" (gold checkmark) + ✓ "Developer Reputation" (gold checkmark) + ✓ "Audit History" (gold checkmark) +5. Animate verification checkmarks: + ✓ "Fuzzing Tests" (gold checkmark) + ✓ "Compatibility Check" (gold checkmark) + ✓ "Adapter Recommendations" (gold checkmark) +6. Circle draws around: "Trust WITHOUT source code!" (gold edge) +7. Celebration marks pop around + +Colors: Black lines, gold (#FFD700) for all checkmarks and solution +Each checkmark animates in sequence - satisfying reveal +``` + +--- + +## Animation Timing Summary + +| Slide | Type | Duration | Transition | +|-------|------|----------|------------| +| 1. Bytecode Risk | Question | 15s | Fade In | +| 2. Fhenix Solution | Answer | 15s | Morph (Q→A) | +| 3. Compliance Question | Question | 15s | Wipe Left | +| 4. AVS Solution | Answer | 15s | Morph (Q→A) | +| **Total** | | **60s** | | + +--- + +## Visual Style (Black & White + Colored Edges) + +**Colors aligned with Hook Bazaar Design System (from frontend.md)** + +| Element | Specification | +|---------|---------------| +| Background | Pure white (#FFFFFF) | +| All elements | Black (#000000) | +| Problems/Concerns edges | Orange-Red outline (#E85A4F) - from logo | +| Technical/Code edges | Deep Blue outline (#003366) - from logo | +| Solutions/Success edges | Gold outline (#FFD700) - primary brand color | + +**Key Rule**: Everything is BLACK on WHITE. Color appears ONLY as edge highlights, outlines, or underlines - never as fills. + +**Logo-Inspired Palette Reference**: +``` +Gold (Primary): #FFD700 - Solutions, success, checkmarks, sponsor highlights +Orange-Red (Accent): #E85A4F - Problems, concerns, warnings, old methods +Deep Blue: #003366 - Technical elements, code, neutral +Terracotta: #CD853F - Secondary accent (optional) +``` + +--- + +## Whiteboard Animation Aesthetics + +### 1. Hand-Drawn Look ✍️ + +| Principle | Implementation | +|-----------|----------------| +| Lines drawn in real-time | Elements appear as if sketched by marker/pen | +| Intentional imperfections | Slight wobble, uneven lines = human feel | +| Sequential reveal | Each element draws after the previous | +| **STICK FIGURES** | All characters MUST be stick-figure style | + +**Stick-Figure Requirements**: +- All human characters as simple stick figures (circle head, line body, line limbs) +- No detailed faces - simple dots for eyes, line for mouth if needed +- Expressive through posture and gesture, not facial detail +- Skeptical pose: hand on chin, question marks above head +- Solution pose: arms presenting, lightbulb above head +- Consistent stick-figure proportions throughout all slides + +**Gamma Prompt Addition**: +``` +Style: Whiteboard animation / hand-drawn sketch look +BLACK AND WHITE ONLY - all elements drawn in black on white background +ALL CHARACTERS MUST BE STICK FIGURES - simple circle head, line body, line limbs +Color appears ONLY as edge highlights/outlines (Hook Bazaar brand colors): + - Orange-Red (#E85A4F) edges for problems, concerns, warnings + - Deep Blue (#003366) edges for code, technical elements + - Gold (#FFD700) edges for solutions, success, sponsor highlights +ANIMATE EACH ELEMENT IN SEQUENCE - draw one element at a time +Lines should appear as if being drawn by a marker in real-time +No detailed faces - express emotion through posture and gesture +``` + +### 2. Minimalist Visual Language + +| Element | Style | +|---------|-------| +| Background | Pure white (#FFFFFF) | +| Lines | Black (#000000) | +| Characters | **STICK FIGURES ONLY** (circle head, line body) | +| Icons | Hand-drawn style | +| Color | EDGES/OUTLINES ONLY | + +**Color Palette (Black & White + Logo-Inspired Colored Edges)**: +``` +Background: #FFFFFF (pure white) - SLIDE BACKGROUND IS WHITE +Lines/Fill: #000000 (black) - all main elements +Edges only (from Hook Bazaar logo/brand): + - Orange-Red edge (#E85A4F) - problems, concerns, warnings + - Deep Blue edge (#003366) - code, technical elements + - Gold edge (#FFD700) - solutions, success, sponsors + +Rule: Elements are BLACK with COLORED OUTLINES/EDGES only +No filled colors - only edge highlights +``` + +**Edge Color Application (Logo-Aligned)**: +| Element Type | Fill | Edge/Outline | +|--------------|------|--------------| +| Question text | Black text | Orange-Red (#E85A4F) outline | +| Code/Bytecode | Black text | Deep Blue (#003366) outline | +| Checkmarks | Black | Gold (#FFD700) edge | +| Solution headers | Black text | Gold (#FFD700) outline | +| Sponsor names | Black text | Gold (#FFD700) underline | +| Warning items | Black | Orange-Red (#E85A4F) edge | + +### 3. Progressive Revelation + +| Technique | When to Use | +|-----------|-------------| +| Draw step-by-step | Each element appears as it's explained | +| Slow, deliberate | ~2-3 seconds per element | +| Sequential | One element finishes before next starts | +| Building tension | Questions build concern, answers provide relief | + +**Animation Timing**: +``` +Element draw-in: 2-3 seconds +Pause after element: 0.5 seconds +Checkmark appear: 1 second each +Total per slide: 15 seconds +``` + +### 4. Educational Clarity + +| Element | Purpose | +|---------|---------| +| Before/After | Show transformation (problem → solution) | +| Checkmark lists | Satisfying sequential reveals | +| Speech bubbles | Character dialogue animates in | +| Icons | Lock (encryption), Shield (attestation) | + +**Visual Hierarchy**: +``` +Large: Question text, Solution headers +Medium: Feature lists, checkmark items +Small: Technical details, sponsor names +Spacing: Generous whitespace between elements +``` + +### 5. Friendly, Neutral Tone + +| Aspect | Approach | +|--------|----------| +| Characters | Simple stick figures - skeptical → satisfied | +| Language | Technical but accessible FAQ format | +| Pacing | Question builds, Answer releases | +| Rhythm | Q → A → Q → A pattern | + +### 6. Low Visual Noise + +**Avoid**: +- Complex textures +- Shadows +- 3D effects +- Gradients +- Busy backgrounds + +**Use**: +- Flat colors +- High contrast +- Clean lines +- Focused composition + +### 7. Rhythm Over Realism + +| Gesture | When to Use | +|---------|-------------| +| Drawing in | Each new element | +| Circling | Highlighting key questions | +| Crossing out | Old problem (before FHE) | +| Underlining | Sponsor names (gold) | +| Checkmarks | Service features (one by one) | +| Question marks | Floating above skeptic | +| Celebration marks | After solution reveals | + +--- + +## Gamma Implementation Instructions + +### Step 1: Create 4 Slides +``` +Slide 1: "But Wait..." (Question - Bytecode) +Slide 2: (Answer - Fhenix FHE) +Slide 3: (Question - Compliance) +Slide 4: (Answer - EigenLayer AVS) +``` + +### Step 2: Apply Animations Per Slide +Each slide should have elements animate in SEQUENCE (not all at once). + +### Step 3: Set Transitions +``` +Slide 1 → 2: Morph (question transforms to answer) +Slide 2 → 3: Wipe Left (new question appears) +Slide 3 → 4: Morph (question transforms to answer) +``` + +### Step 4: Timing +- Each element: 2-3 seconds to draw in +- Each slide total: ~15 seconds +- Transitions: 1-2 seconds each + +--- + +## Scene-to-Slide Transition Guide + +| Slide | Content | Transition In | Duration | +|-------|---------|---------------|----------| +| 1 | Question: Bytecode risk | Fade In | 15s | +| 2 | Answer: Fhenix FHE | Morph | 15s | +| 3 | Question: Compliance | Wipe Left | 15s | +| 4 | Answer: AVS Attestation | Morph | 15s | + +### Gamma Prompt for Full Presentation +``` +Create an ANIMATED FAQ presentation with 4 slides. + +FORMAT: Animated Q&A +- Questions animate in building concern +- Answers animate in revealing solutions + +SLIDE 1: "But Wait..." - Bytecode decompilation question +SLIDE 2: Fhenix FHE solution (sponsor highlight) +SLIDE 3: Compliance verification question +SLIDE 4: EigenLayer AVS solution (sponsor highlight) + +TRANSITIONS: +Slide 1 → 2: Morph (Q becomes A) +Slide 2 → 3: Wipe Left (new Q) +Slide 3 → 4: Morph (Q becomes A) + +STYLE: +- Whiteboard animation, hand-drawn +- ALL characters are STICK FIGURES +- Black & white with colored edges only +- Gold (#FFD700) for solutions/sponsors +- Orange-Red (#E85A4F) for concerns +- Deep Blue (#003366) for code + +ANIMATION: +- Each element draws in sequence (2-3 seconds each) +- Checkmarks appear one by one +- Questions build tension, answers provide relief +``` + +--- + +## Sponsor Integration + +### Fhenix (Slide 2) +- Name appears with **gold underline** +- Solution to bytecode decompilation +- Lock icon represents encryption + +### EigenLayer AVS (Slide 4) +- Name appears with **gold underline** +- Solution to compliance verification +- Shield icon represents attestation + +--- + +## Files Referenced + +- [market_design_questions.md](./market_design_questions.md) - Source Q&A content diff --git a/docs/problem-description/market_design_questions.md b/docs/problem-description/market_design_questions.md new file mode 100644 index 00000000..47652f49 --- /dev/null +++ b/docs/problem-description/market_design_questions.md @@ -0,0 +1,7 @@ + +- Ok, Is great to have a market for hooks, but wait, At some point the hook is connected to a pool who bought it's license, so hook bytecode is deployed on chain, best case if you do not verify it, deecompiling the bytecode can be triky but is just a matter time beefore those tools become cheaper to use and dcompiling is way more encorouaged than paying for the subscription fee? + +---> Solution --> Let's encode Hook fucntions calldata types with fhenix FHE (Fully homomorphic encription). THe bytecode deployed on chain has encrypted calldata, Thus decompiling cost goes to the moon + +- (Protocol) Ok, here is the description and formal spec document of what it does, seems like a good fit for my pool. How can I be sure it fully complies with it's spec. I do not have access to the source code. ---> AVS off-chain operator provides attestation (prover) services that gives compliance score on how well the source code complies with it's spec. This is not a single number but a whole set of detailed metrics subject on how developer reputation, audits done on the hook, etc. Since all protocols can have different semantics and desgin patterns. The AVS handles I/O services where fuzzing integration tests are done against the developer's code to verify comopantibility and indicate adapters needed to be developed + diff --git a/docs/problem-description/user_story_hookdev.md b/docs/problem-description/user_story_hookdev.md new file mode 100644 index 00000000..8b3cb266 --- /dev/null +++ b/docs/problem-description/user_story_hookdev.md @@ -0,0 +1,824 @@ +# Hook Developer User Story: The Distribution Challenge (Gamma Spec) + +## Overview + +**Story**: A skilled smart contract developer builds a valuable Uniswap V4 hook, but struggles to find protocols willing to use it, monetize their work, and establish trust in a fragmented market. + +**Tool**: Gamma Pro +**Duration**: ~90 seconds (6 scenes) +**Tone**: Frustrated, hopeful talent facing systemic barriers +**Source**: Hook developer economics and market fragmentation + +**IMPORTANT - Slide Titles**: Only Slide 1 has a title: **"Meet @eth1000xSuperDev"**. All other slides have NO title. + +--- + +## Hook Developer Economics + +### Investment vs. Return Challenge +| Aspect | Reality | +|--------|---------| +| Development cost | $5k-$20k+ (self-funded) | +| Audit cost | $10k-$50k (if they want credibility) | +| Marketing | $0-$5k (usually $0, developers hate marketing) | +| Revenue | $0 until someone uses it | +| Discovery | Near impossible without connections | + +### Market Fragmentation Problem +| Channel | Success Rate | Problem | +|---------|--------------|---------| +| Twitter/Discord | ~1% | Noise, no trust signal | +| Direct outreach | ~0.5% | "Who are you?" | +| Hackathon wins | ~5% | One-time visibility | +| Word of mouth | ~10% | Requires existing network | +| **Marketplace** | **N/A** | **Doesn't exist yet** | + +--- + +## Scene Breakdown + +### Scene 1: The Hook Developer +**Duration**: 10-15 seconds + +**Slide Title**: "Meet @eth1000xSuperDev" (ONLY slide with a title) + +**Visual**: Solo developer at home setup, coding + +**Content**: +``` +[Developer at desk with multiple monitors] + +@eth1000xSuperDev: "I've built an amazing anti-snipe hook + that protects LBP launches from bots." + +[Shows code on screen] + +@eth1000xSuperDev: "30% better protection than anything out there. + Now I just need to find protocols who need it..." + +[Scratches head, looks at empty inbox] +``` + +**Elements**: +- Single stick figure at developer setup +- Code editor on screen showing hook code +- Speech bubbles with dialogue +- Hook icon with sparkle (indicating quality) +- Empty notification/inbox icon + +**Gamma Prompt**: +``` +Create a slide showing a solo hook developer. + +SLIDE TITLE: "Meet @eth1000xSuperDev" (this is the ONLY slide with a title) + +Scene: Home office with single stick figure at computer. + +Dialogue (as speech bubbles): +- "I built an amazing anti-snipe hook!" +- "30% better protection than anything out there" +- "Now I just need to find protocols..." + +Show code on screen (scribbled lines representing code). +Show a hook icon with sparkle/star indicating quality. +Show empty inbox/notification icon. + +Mood: Proud but uncertain. + +Use simple stick figure (circle head, line body). +Animate dialogue appearing sequentially. + +NOTE: No other slides should have titles - only this first slide. +``` + +--- + +### Scene 2: The Outreach Struggle +**Duration**: 20-25 seconds + +**Visual**: Developer trying multiple outreach channels, all failing. + +**Animation Flow**: +``` +[Developer at computer, trying different channels] + +CHANNEL 1: Twitter +- Posts about hook +- [tumbleweeds animation] +- "0 retweets, 2 likes" + +CHANNEL 2: Discord +- Joins 10 protocol servers +- Posts in #general +- "Message deleted: No self-promotion" + +CHANNEL 3: Cold Email +- "Hi, I built a hook..." +- [No response icons pile up] +- "Seen" but no reply + +TIME COUNTER (right side): +Week 1 → Week 2 → Week 3 → Week 4 + +REJECTION COUNTER: +0 → 5 → 15 → 30+ protocols contacted +0 responses +``` + +**Final State**: +``` +┌─────────────────────────────────┐ +│ [Frustrated developer] │ +│ │ +│ Twitter: 0 engagement │ +│ Discord: Banned from 3 servers │ +│ Emails: 0/30 responses │ +│ Week 4 │ +│ ████████ │ +│ "Maybe I'm doing this wrong?" │ +└─────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a slide showing failed outreach attempts. + +Left side: Stick figure at computer looking increasingly frustrated. +Show three channel attempts: + +1. Twitter: Post icon → tumbleweeds → "0 engagement" +2. Discord: Chat icon → X mark → "Banned: no self-promo" +3. Email: Letter icon → pile of "no reply" icons + +Right side: Two counters: +1. TIME: Week 1 → Week 4 +2. REJECTIONS: "30+ protocols contacted, 0 responses" + +End with speech bubble: "Maybe I'm doing this wrong?" + +Black and white, use red edge for rejections, blue edge for time. +Draw elements appearing one by one showing the struggle. +``` + +--- + +### Scene 3: The Trust Problem +**Duration**: 15-20 seconds + +**Visual**: Protocol team questioning the unknown developer. + +**Animation Flow**: +``` +[Split view: Developer on left, Protocol team on right] + +DEVELOPER: +"My hook is audited and battle-tested!" + +PROTOCOL TEAM: +"Who audited it?" +"Never heard of them." +"How do we know it's secure?" +"Do you have references?" + +[Trust meter shows: 0%] + +COMPARISON: +Unknown developer ❌ + vs +Big auditing firm ✓ (but $50k+) +``` + +**Final State**: +``` +┌─────────────────────────────────┐ +│ [Dev] [Protocol team] │ +│ 😊 ←?→ 😐😐😐 │ +│ │ +│ "It's secure!" "Prove it." │ +│ │ +│ TRUST BARRIER: ████████████ │ +│ Without reputation: ❌ │ +│ Audit from top firm: $50k+ │ +└─────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a slide showing the trust barrier. + +Split view: +- Left: Stick figure developer saying "It's secure!" +- Right: 3 stick figures (protocol team) looking skeptical + +Show dialogue exchange: +Developer: "My hook is audited!" +Team: "Who audited it?" "Never heard of them" + +Show a TRUST METER at 0% or very low. + +Add comparison: +- "Unknown developer: ❌" +- "Top audit firm: $50k+" + +Black and white, red edge around trust barrier. +Draw skeptical expressions through posture (arms crossed, question marks). +``` + +--- + +### Scene 4: The Monetization Maze +**Duration**: 15-20 seconds + +**Visual**: Developer trying to figure out pricing and payment. + +**Animation Flow**: +``` +[Developer with thought bubbles showing pricing confusion] + +PRICING DILEMMA: +"Free? Then why did I spend months building this?" +"$1000 flat? Too cheap for complex hooks" +"Per-transaction? How do I enforce it?" +"Revenue share? No infrastructure for that" + +PAYMENT PROBLEM: +- No standard payment rails +- No smart contract for licensing +- Trust issue: "Pay now, deliver later?" +- Can't prove usage for rev-share + +COMPETITOR CHECK: +"I could open-source it and hope for tips... + but that's not sustainable." +``` + +**Final State**: +``` +┌─────────────────────────────────┐ +│ [Developer with $ question marks]│ +│ │ +│ 💰 Free tier? = no income │ +│ 💰 Flat fee? = trust needed │ +│ 💰 Per-tx? = no enforcement │ +│ 💰 Rev-share? = no infrastructure│ +│ │ +│ "How do I even get paid?" │ +└─────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a slide showing monetization confusion. + +Center: Stick figure surrounded by dollar signs and question marks. + +Show four pricing options, each crossed out: +1. "Free tier" → "= no income" (red X) +2. "Flat fee" → "= trust needed" (red X) +3. "Per-transaction" → "= no enforcement" (red X) +4. "Revenue share" → "= no infrastructure" (red X) + +Speech bubble at bottom: "How do I even get paid?" + +Black and white, red edges for problems/X marks. +Draw question marks appearing around developer's head. +Show each option appearing then getting crossed out. +``` + +--- + +### Scene 5: The Investment Reality +**Duration**: 15-20 seconds + +**Visual**: Cost breakdown showing developer's self-investment with zero return. + +**Animation Flow**: +``` +[Cost bars building up with no revenue counter] + +DEVELOPER'S COSTS: +Development time: 200 hours × $50/hr = $10,000 (opportunity cost) +Personal audit: $15,000 (to gain ANY credibility) +Marketing: $500 (ads, didn't work) +───────────────────────────────── +Total invested: $25,500 + +REVENUE TO DATE: +$0 + +ROI CALCULATOR: +-$25,500 / 6 months = still waiting... + +[Sad face on developer] +"I'm subsidizing the ecosystem with my time" +``` + +**Final State**: +``` +┌─────────────────────────────────┐ +│ @eth1000xSuperDev's LEDGER │ +│ │ +│ Dev time: $10,000 (200 hrs) │ +│ Audit: $15,000 │ +│ Marketing: $500 │ +│ ─────────────────── │ +│ TOTAL: $25,500 │ +│ │ +│ REVENUE: $0 │ +│ TIME: 6 months │ +│ │ +│ "Subsidizing DeFi with my time"│ +└─────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a cost vs. revenue slide for the developer. + +Show a ledger-style breakdown: +- "Dev time: $10,000 (200 hrs)" +- "Audit: $15,000" +- "Marketing: $500" +- Line underneath +- "TOTAL: $25,500" (red, circled) + +Separate section: +- "REVENUE: $0" (large, red, emphasized) +- "TIME: 6 months" (blue) + +End with speech bubble: "Subsidizing DeFi with my time" + +Black and white, red edge for costs/losses, blue for time. +Draw cost items appearing one by one, stacking. +Circle the zero revenue dramatically. +``` + +--- + +### Scene 6: The Fragmented Market +**Duration**: 15-20 seconds + +**Visual**: Summary showing the broken market with no marketplace connecting hooks to protocols. + +**Animation Flow**: +``` +[Map showing disconnected entities] + +LEFT SIDE: Hook Developers +- 100s of talented developers +- Building valuable hooks +- Can't find protocols +- "We build, but can't sell" + +RIGHT SIDE: Protocols +- 1000s of protocols +- Need specialized hooks +- Can't find developers +- "We need, but can't find" + +CENTER: Gap / Missing piece +- No discovery +- No trust system +- No payment rails +- No standards + +"The market exists... but it's invisible." +``` + +**Final State**: +``` +┌─────────────────────────────────────────┐ +│ │ +│ DEVELOPERS ❓ PROTOCOLS│ +│ 👤👤👤 [NO BRIDGE] 👤👤👤 │ +│ 👤👤👤 👤👤👤 │ +│ │ +│ ✓ Build hooks ✓ Need hooks │ +│ ✗ Can't reach ✗ Can't find │ +│ ✗ Can't monetize ✗ Can't trust │ +│ │ +│ "We're both here... but invisible" │ +└─────────────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a summary slide showing market fragmentation. + +Split the slide in three parts: + +LEFT: Group of stick figures labeled "Hook Developers" +- Show 6-9 small stick figures +- Checkmark: "Build hooks" +- Red X: "Can't reach protocols" +- Red X: "Can't monetize" + +CENTER: Big question mark or gap +- Label: "NO BRIDGE" +- "No discovery" +- "No trust" +- "No payment" + +RIGHT: Group of stick figures labeled "Protocols" +- Show 6-9 small stick figures +- Checkmark: "Need hooks" +- Red X: "Can't find developers" +- Red X: "Can't verify quality" + +Bottom: "We're both here... but invisible to each other" + +Black and white, red edges for X marks, gold edge for checkmarks. +Draw the two groups, then show the gap between them. +End with the question: "Who will bridge this gap?" +``` + +--- + +## Animation Timing Summary + +| Scene | Duration | Cumulative | +|-------|----------|------------| +| 1. The Hook Developer | 12s | 12s | +| 2. Outreach Struggle | 22s | 34s | +| 3. Trust Problem | 18s | 52s | +| 4. Monetization Maze | 18s | 70s | +| 5. Investment Reality | 18s | 88s | +| 6. Fragmented Market | 15s | **103s** | + +**Total runtime**: ~1:43 + +--- + +## Visual Style (Black & White + Colored Edges) + +**Colors aligned with Hook Bazaar Design System (from frontend.md)** + +| Element | Specification | +|---------|---------------| +| Background | Pure white (#FFFFFF) | +| All elements | Black (#000000) | +| Cost/Warning/Rejection edges | Orange-Red outline (#E85A4F) - from logo | +| Time edges | Deep Blue outline (#003366) - from logo | +| Success edges | Gold outline (#FFD700) - primary brand color | + +**Key Rule**: Everything is BLACK on WHITE. Color appears ONLY as edge highlights, outlines, or underlines - never as fills. + +**Logo-Inspired Palette Reference**: +``` +Gold (Primary): #FFD700 - Success, checkmarks, positive +Orange-Red (Accent): #E85A4F - Costs, warnings, problems, rejections +Deep Blue: #003366 - Time, neutral elements +Terracotta: #CD853F - Secondary accent (optional) +``` + +--- + +## Whiteboard Animation Aesthetics + +### 1. Hand-Drawn Look ✍️ + +| Principle | Implementation | +|-----------|----------------| +| Lines drawn in real-time | Elements appear as if sketched by marker/pen | +| Intentional imperfections | Slight wobble, uneven lines = human feel | +| Visible hand | Optional: show hand drawing elements | +| **STICK FIGURES** | All characters MUST be stick-figure style | + +**Stick-Figure Requirements**: +- All human characters as simple stick figures (circle head, line body, line limbs) +- No detailed faces - simple dots for eyes, line for mouth if needed +- Expressive through posture and gesture, not facial detail +- Consistent stick-figure proportions throughout all scenes + +**Gamma Prompt Addition**: +``` +Style: Whiteboard animation / hand-drawn sketch look +BLACK AND WHITE ONLY - all elements drawn in black on white background +ALL CHARACTERS MUST BE STICK FIGURES - simple circle head, line body, line limbs +Color appears ONLY as edge highlights/outlines (Hook Bazaar brand colors): + - Orange-Red (#E85A4F) edges for costs, rejections, and warnings + - Deep Blue (#003366) edges for time elements + - Gold (#FFD700) edges for success/checkmarks +Lines should appear as if being drawn by a marker in real-time +Slight imperfections are welcome - keep it human and informal +No detailed faces - express emotion through posture and gesture +``` + +### 2. Minimalist Visual Language + +| Element | Style | +|---------|-------| +| Background | White or very light neutral | +| Lines | Black with 1-2 accent colors only | +| Characters | **STICK FIGURES ONLY** (circle head, line body) | +| Icons | Hand-drawn style, not polished | + +**Color Palette (Black & White + Logo-Inspired Colored Edges)**: +``` +Background: #FFFFFF (pure white) - SLIDE BACKGROUND IS WHITE +Lines/Fill: #000000 (black) - all main elements +Edges only (from Hook Bazaar logo/brand): + - Orange-Red edge (#E85A4F) - costs, warnings, rejections, problems + - Deep Blue edge (#003366) - time elements + - Gold edge (#FFD700) - success, checkmarks + +Rule: Elements are BLACK with COLORED OUTLINES/EDGES only +No filled colors - only edge highlights +``` + +**Edge Color Application (Logo-Aligned)**: +| Element Type | Fill | Edge/Outline | +|--------------|------|--------------| +| Cost numbers | Black text | Orange-Red (#E85A4F) outline/underline | +| Time counters | Black text | Deep Blue (#003366) outline/underline | +| Checkmarks | Black | Gold (#FFD700) edge | +| Warning/Rejection items | Black | Orange-Red (#E85A4F) edge | +| Success items | Black | Gold (#FFD700) edge | +| Neutral elements | Black | Black (no color) | + +### 3. Progressive Revelation + +| Technique | When to Use | +|-----------|-------------| +| Draw step-by-step | Each element appears as it's explained | +| Slow, deliberate | ~2-3 seconds per element | +| Linear motion | Left-to-right, top-to-bottom flow | +| No spectacle | Movement supports explanation | + +**Animation Timing**: +``` +Element draw-in: 2-3 seconds +Pause after element: 1 second +Transition: 1-2 seconds +Total per concept: 4-6 seconds +``` + +### 4. Educational Clarity + +| Element | Purpose | +|---------|---------| +| Diagrams | Simplify complex concepts | +| Flowcharts | Show process steps | +| Labels | Always label key elements | +| Arrows | Connect related concepts | +| Metaphors | Use familiar visuals | + +**Visual Hierarchy**: +``` +Large: Headlines, totals, key numbers +Medium: Labels, descriptions +Small: Details, sources +Spacing: Generous whitespace between elements +``` + +### 5. Friendly, Neutral Tone + +| Aspect | Approach | +|--------|----------| +| Characters | Simple stick figures - emotion via posture | +| Language | Simple, accessible | +| Complexity | Reduced to essentials | +| Voiceover ready | Calm, narrative pacing | + +### 6. Low Visual Noise + +**Avoid**: +- Complex textures +- Shadows +- 3D effects +- Gradients +- Busy backgrounds + +**Use**: +- Flat colors +- High contrast +- Clean lines +- Focused composition + +### 7. Rhythm Over Realism + +| Gesture | When to Use | +|---------|-------------| +| Drawing | Introducing new elements | +| Erasing | Correcting or transitioning | +| Circling | Emphasizing key points | +| Underlining | Highlighting important text | +| Arrows | Connecting concepts | +| Checkmarks | Completing steps | +| X marks | Showing problems/rejections | + +--- + +## Updated Scene Prompts (Whiteboard Style) + +### Scene 1: The Hook Developer (Whiteboard) +``` +Create a whiteboard-style slide showing a solo developer. + +SLIDE TITLE: "Meet @eth1000xSuperDev" (ONLY this slide has a title) + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Draw single stick figure at desk with computer +- Speech bubbles appear as if being written +- "I built an amazing anti-snipe hook!" underlined in gold +- Hook icon drawn with wobbling lines, sparkle beside it +- Empty inbox icon with red X + +Animation: Elements drawn one-by-one, 2-3 seconds each +Colors: Black lines, gold accent for hook quality +Keep it minimal and friendly + +NOTE: All other slides have NO title - only this first slide. +``` + +### Scene 2: Outreach Struggle (Whiteboard) +``` +Create a whiteboard-style slide showing failed outreach. + +Style: Hand-drawn, progressive revelation +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Draw stick figure at desk first (simple: O for head, | for body, lines for arms) +- Three channel boxes appearing and getting X marks: + - Twitter icon → tumbleweeds → "0 engagement" (red X) + - Discord icon → ban hammer → "Banned" (red X) + - Email icon → pile up → "0/30 responses" (red X) +- Time counter in BLUE: "Week 1" → "Week 4" + +Draw each element step-by-step +Circle all the X marks with red marker +End with speech bubble: "Maybe I'm doing this wrong?" +``` + +### Scene 3: Trust Problem (Whiteboard) +``` +Create a whiteboard-style trust barrier scene. + +Style: Sketch on white background +- Split view: Developer on left, Protocol team on right +- Draw single stick figure (developer) with speech bubble +- Draw 3 stick figures (protocol team) with question marks above heads +- Trust meter drawn as empty bar (0%) +- Dialogue exchange written as if by hand: + "It's secure!" vs "Prove it." +- Comparison box: "Unknown dev: ❌" vs "Top audit: $50k+" + +Hand draws question marks around protocol team +Circle "TRUST BARRIER" in red +``` + +### Scene 4: Monetization Maze (Whiteboard) +``` +Create a whiteboard-style monetization confusion scene. + +Style: Hand-drawn with emphasis on confusion +- Draw stick figure in center surrounded by $ and ? marks +- Four pricing options written and crossed out: + "Free?" → "= no income" (red X) + "Flat fee?" → "= trust needed" (red X) + "Per-tx?" → "= no enforcement" (red X) + "Rev-share?" → "= no infrastructure" (red X) +- Question marks drawn floating around head + +Draw each option appearing then getting crossed out +Big speech bubble: "How do I even get paid?" +``` + +### Scene 5: Investment Reality (Whiteboard) +``` +Create a dramatic whiteboard cost summary. + +Style: Hand-drawn ledger/accounting style +- Draw three cost items being sketched: + Dev time: $10,000 (200 hrs) + Audit: $15,000 + Marketing: $500 +- Hand draws a line underneath +- Writes total: "$25,500" (red, circled) +- Separate box: "REVENUE: $0" (large, red, double-circled) +- Writes "6 MONTHS" (blue, underlined) + +Progressive: items drawn top-to-bottom +Final $0 revenue circled emphatically with wobbling red line +Speech bubble: "Subsidizing DeFi with my time" +``` + +### Scene 6: Fragmented Market (Whiteboard) +``` +Create a whiteboard conclusion scene. + +Style: Simple sketch showing the gap +- Draw group of stick figures on left labeled "DEVELOPERS" + - Checkmark: "Build hooks" (gold) + - X mark: "Can't reach" (red) + - X mark: "Can't monetize" (red) +- Draw big gap in center with "NO BRIDGE" and "?" +- Draw group of stick figures on right labeled "PROTOCOLS" + - Checkmark: "Need hooks" (gold) + - X mark: "Can't find" (red) + - X mark: "Can't trust" (red) +- Bottom: "We're both here... but invisible" + +End with question: "Who will bridge this gap?" (circled) +Slight pause on the uncertainty +``` + +--- + +## Gamma Tips + +1. **Use "Cards" layout** for the split scenes - allows side-by-side content +2. **Stick figure style** - all characters as simple stick figures (circle head, line body, line limbs) +3. **Smart animation** - Gamma auto-animates between similar layouts +4. **Embed counters** - Use Gamma's number highlight feature for rejection counts +5. **Export to video** for the smoothest playback + +--- + +## Scene-to-Slide Transition Guide + +**CRITICAL**: Each scene = ONE slide. To enforce scene transitions as slide transitions in Gamma: + +### Structuring for Transitions + +| Scene | Slide # | Transition Type | Gamma Instruction | +|-------|---------|-----------------|-------------------| +| 1. Hook Developer | 1 | Fade In | First slide, fade from black | +| 2. Outreach Struggle | 2 | Wipe Left | "Continue with left wipe showing journey" | +| 3. Trust Problem | 3 | Split | "Split view showing two sides" | +| 4. Monetization Maze | 4 | Morph | "Morph from previous frustration" | +| 5. Investment Reality | 5 | Zoom In | "Zoom into the financial reality" | +| 6. Fragmented Market | 6 | Dissolve | "Dissolve to show the big picture" | + +### Gamma Prompt for Transitions + +``` +Create a presentation with 6 SLIDES (one per scene). +Each slide should have a distinct transition to the next: + +Slide 1 → 2: Wipe left (starting the struggle) +Slide 2 → 3: Push right (confronting reality) +Slide 3 → 4: Morph (same developer, new frustration) +Slide 4 → 5: Zoom in (financial truth revealed) +Slide 5 → 6: Dissolve (seeing the big picture) + +Do NOT combine scenes into single slides. +Each scene is a separate slide with its own transition. +``` + +### Transition Timing per Scene + +| Scene | Content Duration | Transition Duration | Total | +|-------|------------------|---------------------|-------| +| 1 | 10s | 2s fade in | 12s | +| 2 | 20s | 2s wipe | 22s | +| 3 | 16s | 2s push | 18s | +| 4 | 16s | 1.5s morph | 17.5s | +| 5 | 16s | 2s zoom | 18s | +| 6 | 13s | 2s dissolve | 15s | +| **Total** | **91s** | **11.5s** | **102.5s** | + +### Manual Transition Setup in Gamma + +If Gamma doesn't auto-apply transitions: + +1. **Click on slide** in the left panel +2. **Click "Transition"** button (or find in slide settings) +3. **Select transition type** for each slide: + - **Fade**: For opening/closing slides + - **Wipe**: For progression/journey feel + - **Morph**: For similar layouts with element changes + - **Push**: For time-based progression + - **Zoom**: For dramatic reveals + - **Dissolve**: For soft endings + +4. **Set duration**: 1-2 seconds per transition +5. **Preview**: Watch full presentation to verify timing + +### Alternative: Gamma "Story Mode" + +For more control, use Gamma's Story Mode: +1. Create presentation in Story Mode (not deck mode) +2. Each "card" becomes a scene +3. Transitions are more fluid in Story Mode +4. Better for narrative/animation-heavy content + +--- + +## Key Differences from Protocol Story + +| Aspect | Protocol Story | Hook Developer Story | +|--------|----------------|---------------------| +| Title Slide | "Meet DeFiSuperStars" | "Meet @eth1000xSuperDev" | +| Main character | Protocol team (3-4 people) | Solo developer (1 person) | +| Core problem | Building is expensive | Distribution is impossible | +| Cost focus | Dev + Test + Audit | Self-investment with $0 return | +| Emotional arc | Surprise at costs | Frustration at invisibility | +| Ending question | "Was it worth it?" | "Who will bridge this gap?" | + +--- + +## Files Referenced + +- Protocol_Cost_Function.md - Market cost data +- Hook developer economics research diff --git a/docs/problem-description/user_story_protocol.md b/docs/problem-description/user_story_protocol.md new file mode 100644 index 00000000..b41c817c --- /dev/null +++ b/docs/problem-description/user_story_protocol.md @@ -0,0 +1,770 @@ +# Protocol User Story: Self-Building a Hook (Gamma Spec) + +## Overview + +**Story**: A protocol team decides to build their own Uniswap V4 hook. We follow their journey through build → test → audit, watching costs and time accumulate. + +**Tool**: Gamma Pro +**Duration**: ~90 seconds (6 scenes) +**Tone**: Realistic, slightly tense as costs mount +**Source**: [Protocol_Cost_Function.md](./Protocol_Cost_Function.md) + +**IMPORTANT - Slide Titles**: Only Slide 1 has a title: **"Meet DeFiSuperStars"**. All other slides have NO title. + +--- + +## Cost Figures (from Protocol_Cost_Function.md) + +### Developer Rates +| Level | Hourly Rate | +|-------|-------------| +| Mid-level | $65-100/hr | +| Senior | $100-150/hr | +| Expert | $150-350/hr | +| **Average used** | **$100/hr** (~$2.35/min for animation) | + +### Cost Targets (Simple Hook) +| Phase | Cost | Time | +|-------|------|------| +| C_dev | $3k - $10k | 1-2 weeks | +| C_test | $1k - $3k | 3-5 days | +| C_audit | $5k - $15k | 1-2 weeks | +| **C_total** | **$8k - $25k** | **2-4 weeks** | + +### Cost Targets (Complex Hook) +| Phase | Cost | Time | +|-------|------|------| +| C_dev | $20k - $60k | 4-8 weeks | +| C_test | $5k - $15k | 1-2 weeks | +| C_audit | $30k - $100k | 2-4 weeks | +| **C_total** | **$50k - $170k** | **2-6 months** | + +--- + +## Scene Breakdown + +### Scene 1: The Decision +**Duration**: 10-15 seconds + +**Slide Title**: "Meet DeFiSuperStars" (ONLY slide with a title) + +**Visual**: Conference room / video call with protocol team + +**Content**: +``` +[Team around table or on video call] + +CTO: "We're launching a liquidity bootstrapping pool + for our yield-bearing token sDeFiSuperStars next month." + +Dev Lead: "We need a dynamic fee hook to stay competitive. + Let's build it ourselves - how hard can it be?" + +[Everyone nods confidently] +``` + +**Elements**: +- 3-4 stick figures (simple developer style) +- Speech bubbles with dialogue +- DeFiSuperStars logo/icon in background +- sDeFiSuperStars token symbol +- Hook icon appears when mentioned + +**Gamma Prompt**: +``` +Create a slide showing a protocol team meeting. + +SLIDE TITLE: "Meet DeFiSuperStars" (this is the ONLY slide with a title) + +Scene: Video call or conference room with 3-4 stick figures. + +Dialogue (as speech bubbles or text overlays): +- "We're launching a liquidity bootstrapping pool for sDeFiSuperStars" +- "We need a dynamic fee hook to stay competitive" +- "Let's build it ourselves!" + +Show DeFiSuperStars logo and sDeFiSuperStars token symbol. +Show a Uniswap V4 hook icon appearing. +Mood: Optimistic, confident. + +Use simple stick figures for all characters (circle head, line body). +Animate dialogue appearing sequentially. + +NOTE: No other slides should have titles - only this first slide. +``` + +--- + +### Scene 2: Building Phase +**Duration**: 20-25 seconds + +**Visual**: Developer at desk, coding. Two counters on the side. + +**Animation Flow**: +``` +[Developer typing at computer] + +COST COUNTER (right side): +$0 → $100 → $500 → $1,000 → ... → $10,000 +(increments by ~$2.35/tick, representing $100/hr) + +TIME COUNTER (right side): +Day 1 → Day 3 → Day 7 → Day 10 → Day 14 +(2 weeks total) + +CODE ELEMENTS appearing: +- "Setting up infra..." +- "Building API..." +- "Integrating AI oracle..." +- "Implementing callbacks..." +``` + +**Final State**: +``` +┌─────────────────────────────────┐ +│ [Developer coding] $10,000 │ +│ ████████ │ +│ > deploy hook... Week 2 │ +│ ████████ │ +│ │ +│ C_dev = $10,000 ✓ │ +└─────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create an animated slide showing a developer building a hook. + +Left side: Stick figure at computer (simple: O head, | body), typing animation. +Code snippets appearing: +- "Setting up infrastructure..." +- "Building hook API..." +- "Implementing callbacks..." + +Right side: Two animated counters: +1. COST: Starting at $0, incrementing to $10,000 + - Show dollar amounts growing: $0 → $2,500 → $5,000 → $7,500 → $10,000 + +2. TIME: Starting at Day 1, reaching Week 2 + - Show: Day 1 → Day 7 → Day 14 + +End state: "C_dev = $10,000 ✓" with checkmark + +Dark theme, green progress bars, monospace font for code. +Animate counters incrementing smoothly. +``` + +--- + +### Scene 3: Testing Phase +**Duration**: 15-20 seconds + +**Visual**: Same developer, now running tests. Counters continue. + +**Animation Flow**: +``` +[Terminal showing test output] + +COST COUNTER continues: +$10,000 → $11,000 → $12,000 → $13,000 +(+$3,000 for testing) + +TIME COUNTER continues: +Week 2 → Week 2.5 → Week 3 + +TEST ELEMENTS: +- "Running fuzzers... 🔄" +- "Formal verification... 🔄" +- "Integration tests... ✓" +- "Edge cases... ✓" +``` + +**Final State**: +``` +┌─────────────────────────────────┐ +│ [Terminal with tests] $13,000 │ +│ ████████│ +│ ✓ 247 tests passed Week 3 │ +│ ████████│ +│ │ +│ C_test = $3,000 ✓ │ +│ Running total: $13,000 │ +└─────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a slide showing the testing phase. + +Left side: Terminal/console showing test output: +- "Running fuzzer... 1000 iterations" +- "Formal verification... checking invariants" +- "✓ 247 tests passed" + +Right side: Counters (continuing from previous): +1. COST: $10,000 → $13,000 (adding $3,000) +2. TIME: Week 2 → Week 3 + +Show test tools mentioned: +- Foundry fuzzer icon +- Formal methods icon + +End state: "C_test = $3,000 ✓" +Show running total: "$13,000" + +Dark theme, terminal green text (#00FF00), animate test results appearing. +``` + +--- + +### Scene 4: Audit Phase +**Duration**: 20-25 seconds + +**Visual**: Handoff to auditors, waiting, receiving report. + +**Animation Flow**: +``` +[Calendar pages flipping / Clock spinning] + +COST COUNTER jumps: +$13,000 → $15,000 → $20,000 → $25,000 → $28,000 +(Audit costs $15,000) + +TIME COUNTER: +Week 3 → Week 4 → Week 5 → Week 6 + +AUDIT ELEMENTS: +- "Submitting to Sherlock... 📤" +- "Waiting for auditors... ⏳" +- "Review in progress... 🔍" +- "3 findings: 1 high, 2 medium" +- "Fixes applied... ✓" +``` + +**Final State**: +``` +┌─────────────────────────────────┐ +│ [Audit report icon] $28,000 │ +│ ████████│ +│ AUDIT COMPLETE Week 6 │ +│ 1 High (fixed) ████████│ +│ 2 Medium (fixed) │ +│ │ +│ C_audit = $15,000 ✓ │ +│ Running total: $28,000 │ +└─────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a slide showing the audit phase. + +Visual progression: +1. "Submitting to auditors..." with upload icon +2. Calendar/clock showing time passing (weeks) +3. "Audit in progress..." with magnifying glass +4. Audit report appearing with findings + +Right side counters: +1. COST: $13,000 → $28,000 (adding $15,000 for audit) +2. TIME: Week 3 → Week 6 + +Show audit findings: +- "1 High severity (fixed)" +- "2 Medium severity (fixed)" + +End state: "C_audit = $15,000 ✓" +Running total prominently: "$28,000" + +Dark theme, use red for "High severity", orange for "Medium". +Animate calendar pages flipping to show time passing. +``` + +--- + +### Scene 5: Total Cost Reveal +**Duration**: 10-15 seconds + +**Visual**: All costs stack up, final total revealed dramatically. + +**Animation Flow**: +``` +[Cost components fly in and stack] + +C_dev = $10,000 ████████████ +C_test = $3,000 ████ +C_audit = $15,000 ██████████████████ +───────────────────────────────── +C_total = $28,000 + +TIME: 6 weeks + +[Numbers pulse/glow on final reveal] +``` + +**Gamma Prompt**: +``` +Create a dramatic cost summary slide. + +Show three cost bars stacking vertically: +- C_dev = $10,000 (blue bar) +- C_test = $3,000 (yellow bar) +- C_audit = $15,000 (red bar, largest) + +Animate bars flying in from left, stacking. + +Below the stack, reveal total: +"C_total = $28,000" +(Large, bold, slight glow effect) + +Side callout: "TIME: 6 weeks" + +Add context: "This was a SIMPLE hook. Complex hooks cost $50k-$170k+" + +Dark theme, dramatic reveal animation for the total. +``` + +--- + +### Scene 6: Success... But At What Cost? +**Duration**: 10-15 seconds + +**Visual**: Hook successfully integrated into pool, but cost/time prominently shown. + +**Animation Flow**: +``` +[Pool diagram with hook integrated] + + ┌──────────────────────────────┐ + │ sDeFiSuperStars LBP Pool │ + │ ┌───────┐ │ + │ │ HOOK │ ✓ │ + │ └───────┘ │ + └──────────────────────────────┘ + +FINAL STATS (overlay): +✓ Hook deployed to sDeFiSuperStars pool +✓ $28,000 spent +✓ 6 weeks elapsed +? Was it worth it? +``` + +**Gamma Prompt**: +``` +Create a final slide showing successful hook integration. + +Center: Simple pool diagram with hook inside: +- Rectangle labeled "sDeFiSuperStars LBP Pool" +- Smaller rectangle inside labeled "HOOK" with checkmark + +Overlay stats (bottom or side): +- "✓ Hook deployed successfully" +- "✓ $28,000 spent" +- "✓ 6 weeks elapsed" + +End with question: "Was it worth it?" +(This sets up the Hook Bazaar solution in next presentation) + +Dark theme, green checkmarks, slight tension in the "Was it worth it?" text. +Animate: Pool appears, hook slides in, stats reveal one by one. +``` + +--- + +## Animation Timing Summary + +| Scene | Duration | Cumulative | +|-------|----------|------------| +| 1. Decision | 12s | 12s | +| 2. Building | 22s | 34s | +| 3. Testing | 18s | 52s | +| 4. Audit | 22s | 74s | +| 5. Total Reveal | 12s | 86s | +| 6. Success | 12s | **98s** | + +**Total runtime**: ~1:40 + +--- + +## Counter Animation Specs + +### Cost Counter +``` +Start: $0 +Increment: ~$2.35 per tick (representing $100/hr developer rate) +Milestones: +- $10,000 (end of build) +- $13,000 (end of test) +- $28,000 (end of audit) +Format: "$XX,XXX" with comma separator +Color: White, turns red when exceeding $20k +``` + +### Time Counter +``` +Start: Day 1 +Format: "Day X" → "Week X" +Milestones: +- Day 14 / Week 2 (end of build) +- Day 21 / Week 3 (end of test) +- Day 42 / Week 6 (end of audit) +Color: White, progress bar underneath +``` + +--- + +## Visual Style (Black & White + Colored Edges) + +**Colors aligned with Hook Bazaar Design System (from frontend.md)** + +| Element | Specification | +|---------|---------------| +| Background | Pure white (#FFFFFF) | +| All elements | Black (#000000) | +| Cost/Warning edges | Orange-Red outline (#E85A4F) - from logo | +| Time edges | Deep Blue outline (#003366) - from logo | +| Success edges | Gold outline (#FFD700) - primary brand color | + +**Key Rule**: Everything is BLACK on WHITE. Color appears ONLY as edge highlights, outlines, or underlines - never as fills. + +**Logo-Inspired Palette Reference**: +``` +Gold (Primary): #FFD700 - Success, checkmarks, positive +Orange-Red (Accent): #E85A4F - Costs, warnings, problems +Deep Blue: #003366 - Time, neutral elements +Terracotta: #CD853F - Secondary accent (optional) +``` + +--- + +## Whiteboard Animation Aesthetics + +### 1. Hand-Drawn Look ✍️ + +| Principle | Implementation | +|-----------|----------------| +| Lines drawn in real-time | Elements appear as if sketched by marker/pen | +| Intentional imperfections | Slight wobble, uneven lines = human feel | +| Visible hand | Optional: show hand drawing elements | +| **STICK FIGURES** | All characters MUST be stick-figure style | + +**Stick-Figure Requirements**: +- All human characters as simple stick figures (circle head, line body, line limbs) +- No detailed faces - simple dots for eyes, line for mouth if needed +- Expressive through posture and gesture, not facial detail +- Consistent stick-figure proportions throughout all scenes + +**Gamma Prompt Addition**: +``` +Style: Whiteboard animation / hand-drawn sketch look +BLACK AND WHITE ONLY - all elements drawn in black on white background +ALL CHARACTERS MUST BE STICK FIGURES - simple circle head, line body, line limbs +Color appears ONLY as edge highlights/outlines (Hook Bazaar brand colors): + - Orange-Red (#E85A4F) edges for costs and warnings + - Deep Blue (#003366) edges for time elements + - Gold (#FFD700) edges for success/checkmarks +Lines should appear as if being drawn by a marker in real-time +Slight imperfections are welcome - keep it human and informal +No detailed faces - express emotion through posture and gesture +``` + +### 2. Minimalist Visual Language + +| Element | Style | +|---------|-------| +| Background | White or very light neutral | +| Lines | Black with 1-2 accent colors only | +| Characters | **STICK FIGURES ONLY** (circle head, line body) | +| Icons | Hand-drawn style, not polished | + +**Color Palette (Black & White + Logo-Inspired Colored Edges)**: +``` +Background: #FFFFFF (pure white) - SLIDE BACKGROUND IS WHITE +Lines/Fill: #000000 (black) - all main elements +Edges only (from Hook Bazaar logo/brand): + - Orange-Red edge (#E85A4F) - costs, warnings, problems + - Deep Blue edge (#003366) - time elements + - Gold edge (#FFD700) - success, checkmarks + +Rule: Elements are BLACK with COLORED OUTLINES/EDGES only +No filled colors - only edge highlights +``` + +**Edge Color Application (Logo-Aligned)**: +| Element Type | Fill | Edge/Outline | +|--------------|------|--------------| +| Cost numbers | Black text | Orange-Red (#E85A4F) outline/underline | +| Time counters | Black text | Deep Blue (#003366) outline/underline | +| Checkmarks | Black | Gold (#FFD700) edge | +| Warning items | Black | Orange-Red (#E85A4F) edge | +| Success items | Black | Gold (#FFD700) edge | +| Neutral elements | Black | Black (no color) | + +### 3. Progressive Revelation + +| Technique | When to Use | +|-----------|-------------| +| Draw step-by-step | Each element appears as it's explained | +| Slow, deliberate | ~2-3 seconds per element | +| Linear motion | Left-to-right, top-to-bottom flow | +| No spectacle | Movement supports explanation | + +**Animation Timing**: +``` +Element draw-in: 2-3 seconds +Pause after element: 1 second +Transition: 1-2 seconds +Total per concept: 4-6 seconds +``` + +### 4. Educational Clarity + +| Element | Purpose | +|---------|---------| +| Diagrams | Simplify complex concepts | +| Flowcharts | Show process steps | +| Labels | Always label key elements | +| Arrows | Connect related concepts | +| Metaphors | Use familiar visuals | + +**Visual Hierarchy**: +``` +Large: Headlines, totals, key numbers +Medium: Labels, descriptions +Small: Details, sources +Spacing: Generous whitespace between elements +``` + +### 5. Friendly, Neutral Tone + +| Aspect | Approach | +|--------|----------| +| Characters | Simple stick figures - emotion via posture | +| Language | Simple, accessible | +| Complexity | Reduced to essentials | +| Voiceover ready | Calm, narrative pacing | + +### 6. Low Visual Noise + +**Avoid**: +- Complex textures +- Shadows +- 3D effects +- Gradients +- Busy backgrounds + +**Use**: +- Flat colors +- High contrast +- Clean lines +- Focused composition + +### 7. Rhythm Over Realism + +| Gesture | When to Use | +|---------|-------------| +| Drawing | Introducing new elements | +| Erasing | Correcting or transitioning | +| Circling | Emphasizing key points | +| Underlining | Highlighting important text | +| Arrows | Connecting concepts | +| Checkmarks | Completing steps | +| X marks | Showing problems/costs | + +--- + +## Updated Scene Prompts (Whiteboard Style) + +### Scene 1: The Decision (Whiteboard) +``` +Create a whiteboard-style slide showing a team meeting. + +SLIDE TITLE: "Meet DeFiSuperStars" (ONLY this slide has a title) + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Draw 3-4 stick figures around a table +- Speech bubbles appear as if being written +- "We need a hook for sDeFiSuperStars!" underlined in blue +- Hook icon drawn with wobbling lines + +Animation: Elements drawn one-by-one, 2-3 seconds each +Colors: Black lines, blue accent for "hook" +Keep it minimal and friendly + +NOTE: All other slides have NO title - only this first slide. +``` + +### Scene 2: Building Phase (Whiteboard) +``` +Create a whiteboard-style slide showing developer coding. + +Style: Hand-drawn, progressive revelation +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Draw stick figure at desk first (simple: O for head, | for body, lines for arms) +- Computer screen sketched in +- Code lines appearing as scribbles +- Cost counter drawn in RED, numbers written as if by hand: + "$0" → "$2,500" → "$5,000" → "$10,000" +- Time counter in BLUE: "Day 1" → "Week 2" + +Draw each element step-by-step +Circle the final cost "$10,000" with red marker +Add label: "C_dev" with arrow pointing to cost +``` + +### Scene 3: Testing Phase (Whiteboard) +``` +Create a whiteboard-style testing scene. + +Style: Sketch on white background +- Terminal drawn as simple rectangle +- Test results written line-by-line: + "✓ test 1" (drawn checkmark) + "✓ test 2" + "✓ 247 tests passed" +- Cost counter continues: $10k → $13k (red) +- Time: Week 2 → Week 3 (blue) + +Hand draws checkmarks one by one +Circle "C_test = $3,000" at the end +``` + +### Scene 4: Audit Phase (Whiteboard) +``` +Create a whiteboard-style audit scene. + +Style: Hand-drawn with emphasis on time passing +- Draw calendar pages flipping (simple rectangles) +- Clock being drawn, hands moving +- Auditor stick figure with magnifying glass +- Report document sketched +- Finding labels written: "1 High" (circled in red) +- Cost jumps: $13k → $28k (red, underlined) + +Draw calendar days being crossed out +Big red circle around "$28,000" +``` + +### Scene 5: Total Cost Reveal (Whiteboard) +``` +Create a dramatic whiteboard cost summary. + +Style: Hand-drawn stacked bar chart +- Draw three horizontal bars being sketched: + C_dev ████████ $10,000 + C_test ███ $3,000 + C_audit █████████████ $15,000 +- Hand draws a line underneath +- Writes total: "$28,000" (large, red, circled twice) +- Writes "6 WEEKS" (blue, underlined) + +Progressive: bars drawn left-to-right +Final total circled emphatically with wobbling red line +``` + +### Scene 6: Success...? (Whiteboard) +``` +Create a whiteboard conclusion scene. + +Style: Simple sketch with mixed emotions +- Draw pool as simple rectangle labeled "sDeFiSuperStars Pool" +- Draw hook inside (small box labeled "h") +- Add checkmark (green) +- But then draw the stats next to it: + "$28,000" (red, with sad face) + "6 weeks" (blue) + "5-15% risk" (red, underlined) +- Hand writes: "Was it worth it?" (circled) + +End with question mark being drawn large +Slight pause on the uncertainty +``` + +--- + +## Gamma Tips + +1. **Use "Cards" layout** for the counter scenes - allows side-by-side content +2. **Stick figure style** - all characters as simple stick figures (circle head, line body, line limbs) +3. **Smart animation** - Gamma auto-animates between similar layouts +4. **Embed counters** - Use Gamma's number highlight feature for cost figures +5. **Export to video** for the smoothest playback + +--- + +## Scene-to-Slide Transition Guide + +**CRITICAL**: Each scene = ONE slide. To enforce scene transitions as slide transitions in Gamma: + +### Structuring for Transitions + +| Scene | Slide # | Transition Type | Gamma Instruction | +|-------|---------|-----------------|-------------------| +| 1. Decision | 1 | Fade In | First slide, fade from black | +| 2. Building | 2 | Wipe Left | "Continue from previous with left wipe" | +| 3. Testing | 3 | Morph | "Morph from previous slide layout" | +| 4. Audit | 4 | Push Right | "Push transition showing time passing" | +| 5. Total Reveal | 5 | Zoom In | "Zoom into the final totals" | +| 6. Success | 6 | Dissolve | "Dissolve to final state" | + +### Gamma Prompt for Transitions + +When prompting Gamma, explicitly state: +``` +Create a presentation with 6 SLIDES (one per scene). +Each slide should have a distinct transition to the next: + +Slide 1 → 2: Wipe left (starting the journey) +Slide 2 → 3: Morph (same dev, different activity) +Slide 3 → 4: Push right (time progression) +Slide 4 → 5: Zoom in (dramatic reveal) +Slide 5 → 6: Dissolve (resolution) + +Do NOT combine scenes into single slides. +Each scene is a separate slide with its own transition. +``` + +### Manual Transition Setup in Gamma + +If Gamma doesn't auto-apply transitions: + +1. **Click on slide** in the left panel +2. **Click "Transition"** button (or find in slide settings) +3. **Select transition type** for each slide: + - **Fade**: For opening/closing slides + - **Wipe**: For progression/journey feel + - **Morph**: For similar layouts with element changes + - **Push**: For time-based progression + - **Zoom**: For dramatic reveals + - **Dissolve**: For soft endings + +4. **Set duration**: 1-2 seconds per transition +5. **Preview**: Watch full presentation to verify timing + +### Transition Timing per Scene + +| Scene | Content Duration | Transition Duration | Total | +|-------|------------------|---------------------|-------| +| 1 | 10s | 2s fade in | 12s | +| 2 | 20s | 2s wipe | 22s | +| 3 | 16s | 1.5s morph | 17.5s | +| 4 | 20s | 2s push | 22s | +| 5 | 10s | 2s zoom | 12s | +| 6 | 10s | 1.5s dissolve | 11.5s | +| **Total** | **86s** | **11s** | **97s** | + +### Alternative: Gamma "Story Mode" + +For more control, use Gamma's Story Mode: +1. Create presentation in Story Mode (not deck mode) +2. Each "card" becomes a scene +3. Transitions are more fluid in Story Mode +4. Better for narrative/animation-heavy content + +--- + +## Files Referenced + +- [Protocol_Cost_Function.md](./Protocol_Cost_Function.md) - All cost data and formulas +- [Hooks.md](./Hooks.md) - Hook integration details \ No newline at end of file diff --git a/docs/research/audit-cost-metrics.md b/docs/research/audit-cost-metrics.md new file mode 100644 index 00000000..8820f182 --- /dev/null +++ b/docs/research/audit-cost-metrics.md @@ -0,0 +1,402 @@ +# DeFi Smart Contract Audit Cost Metrics: Empirical Research + +This document compiles empirical data on smart contract audit costs to derive cost-per-line-of-code metrics for use in the Hook Bazaar economic model. + +## Executive Summary + +| Metric | Value | Source | +|--------|-------|--------| +| **Competitive Audit Platforms** | | | +| Sherlock average prize pool | $30k - $200k per contest | Sherlock Docs | +| Code4rena 2023 total awards | $4,823,059 | Code4rena | +| Immunefi total payouts | $100M+ (3 years) | The Block | +| **Traditional Auditors** | | | +| Top-tier (ToB, OZ, CD) | $100k - $500k+ | Industry Reports | +| Mid-tier firms | $20k - $75k | Industry Reports | +| **Cost per SLOC** | | | +| Derived from cmichel data | ~$2.53/LOC | cmichel.io | +| Simple contracts | $3-4/LOC | Calculated | +| Complex DeFi protocols | $15-20/LOC | Calculated | +| **Developer Rates** | | | +| Freelance Solidity | $50-150/hour | Arc, Web3.career | +| Senior/Expert | $150-350/hour | Arc, ZipRecruiter | + +--- + +## 1. Competitive Audit Platforms + +### 1.1 Sherlock + +**Platform Statistics:** +- Total rewards paid: **$14.8M+** to security researchers (Watsons) +- Registered auditors: **10,000+** +- Typical contest participation: **200-400** independent auditors + +**Prize Pool Structure:** +- Prize pool range: **$30,000 - $200,000** per contest +- Fixed pay for Lead Senior Watson: **~$10,000 per audit week** +- Large flagship contests (e.g., Optimism): up to **$700,000** + +**nSLOC Guidelines (Audit Duration):** + +| nSLOC | Audit Duration | Implied $/nSLOC (at $50k pool) | +|-------|----------------|--------------------------------| +| ~500 | ~3 days | ~$100/nSLOC | +| ~1,000 | ~6 days | ~$50/nSLOC | +| ~2,000 | ~12 days | ~$25/nSLOC | +| ~3,000 | ~18 days | ~$16.67/nSLOC | +| ~4,000 | ~25 days | ~$12.50/nSLOC | +| ~5,000 | ~32 days | ~$10/nSLOC | +| ~6,000 | ~38 days | ~$8.33/nSLOC | + +**Coverage Note:** Sherlock retains discretion for codebases exceeding 6,000 nSLOC due to "exponential complexity." + +**Sources:** +- [Sherlock Audit Pricing and Timeline](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) +- [Sherlock Platform](https://sherlock.xyz/) + +--- + +### 1.2 Code4rena + +**Platform Statistics:** +- Registered wardens: **10,000+** +- 2023 total contests: **114 protocols audited** +- 2023 total bug submissions: **31,512** +- 2023 High severity findings: **3,005** +- 2023 Medium severity findings: **4,003** + +**2023 Financial Data:** +- **Total awards to wardens:** $4,823,059 +- **High severity awards:** $1,586,018 +- **Medium severity awards:** $2,604,054 +- **Highest single payout:** $71,500 + +**Average Prize Pool Calculation (2023):** +$$\bar{P}_{C4A} = \frac{\$4,823,059}{114 \text{ contests}} \approx \$42,307 \text{ per contest}$$ + +**Notable 2024 Prize Pools:** +- Monad: **$500,000** (largest unconditional pool in history) +- Chainlink Payment Abstraction: **$100,000** +- Salty.io: **$80,000** +- PoolTogether: **$37,700** +- Reserve Core Mitigation: **$17,500** + +**Per-Line Metrics (from cmichel.io analysis):** +- Total lines audited by top warden: **395,626 LOC** across 97 contests +- Average per contest: **~4,000 LOC** +- First $1M earned in **14 months** (951 hours) +- **Effective hourly rate:** $1,057.80/hour +- **Implied cost per LOC:** $1,000,000 / 395,626 = **$2.53/LOC** + +**Sources:** +- [Code4rena 2024 Welcome](https://medium.com/code4rena/welcome-to-2024-at-code4rena-f0929a6ae3a8) +- [cmichel Code4rena Stats](https://cmichel.io/code4rena-first-1m-stats/) +- [Code4rena Audits](https://code4rena.com/audits) + +--- + +### 1.3 Immunefi + +**Platform Statistics:** +- Total payouts facilitated: **$100M+** (surpassed in 2024) +- Time period: ~3 years (December 2020 - mid 2024) +- Total paid reports: **3,000+** +- Registered researchers: **45,000+** +- Funds protected: **$25B+** across protocols + +**Payout Breakdown by Category:** + +| Category | Amount | Percentage | +|----------|--------|------------| +| Smart Contract Bugs | $77.97M | 77.5% | +| Blockchain/DLT Protocols | $18.76M | 18.6% | +| Website/Application | $3.85M | 3.9% | +| **Total** | **$100.21M** | 100% | + +**Notable Bounty Payouts:** +- **Highest:** $10M (Wormhole cross-chain vulnerability) +- **Second highest:** $14.82M (critical vulnerability, Jan 2021) +- **Lowest:** $25 + +**Typical Bug Bounty Structures:** +- Critical smart contract bugs: Up to **$1,000,000** (e.g., 0x protocol) +- Direct theft vulnerabilities: **10% of affected funds** up to cap +- Standard critical cap: **$50,000 - $500,000** + +**Sources:** +- [Immunefi $100M Milestone - The Block](https://www.theblock.co/post/301025/web3-immunefi-ethical-hacker-payouts) +- [Immunefi Bug Bounty Programs](https://immunefi.com/bug-bounty/) + +--- + +## 2. Traditional Audit Firms + +### 2.1 Top-Tier Firms (Trail of Bits, OpenZeppelin, ConsenSys Diligence) + +**Pricing Tiers:** + +| Contract Type | Complexity | Price Range | +|---------------|------------|-------------| +| Basic ERC-20 Token | Low | $10,000 - $20,000 | +| Mid-level dApp (staking, governance) | Medium | $20,000 - $50,000 | +| DeFi Exchange/Lending | Medium-High | $50,000 - $90,000 | +| Complex Protocol/Ecosystem | High | $75,000 - $150,000 | +| Cross-chain Bridges | Very High | $100,000 - $300,000+ | +| Flagship Projects (Uniswap-scale) | Enterprise | $100,000 - $500,000+ | + +**Specific Firm Notes:** + +**Trail of Bits:** +- Pioneer in blockchain security (Web 2.0 transition) +- Holistic SDLC approach +- Custom tooling development included +- Typical timeline: Project-dependent + +**OpenZeppelin:** +- Over $50B in secured value +- Specialized ZK-Proof audits available +- AI-powered Contracts MCP tool +- Industry-standard library maintainer + +**ConsenSys Diligence:** +- Typical audit duration: 2-4 weeks +- Fuzzing-as-a-service offering +- Formal verification available (extends timeline) + +**Re-audit Costs:** 10-30% of initial audit price + +**Sources:** +- [Understanding Smart Contract Audit Costs - Ulam](https://www.ulam.io/blog/smart-contract-audit) +- [Smart Contract Audit Cost Breakdown - Medium](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) +- [OpenZeppelin Forum Discussion](https://forum.openzeppelin.com/t/cost-of-an-audit/38646) + +### 2.2 Mid-Tier and Budget Firms + +| Firm | Approximate Cost | Notes | +|------|-----------------|-------| +| CertiK | $30,000 - $100,000+ | Automated + manual review | +| Hacken | $20,000 - $50,000 | Budget-friendly option | +| Omniscia | ~$30,000 | Mid-tier positioning | +| Quantstamp | Project-dependent | Custom quoting | + +**Market Conditions Impact:** +- Bull market: Up to **3x** premium +- Bear market: Discounts to **~$20k** from top firms + +--- + +## 3. Cost Per Line of Code (C_audit/SLOC) + +### 3.1 Derived Metrics + +**From Competitive Audits (Code4rena cmichel data):** +$$C_{audit}/LOC = \frac{\$1,000,000}{395,626 \text{ LOC}} = \$2.53/LOC$$ + +**From Industry Pricing Examples:** + +| Project Type | Typical SLOC | Cost Range | Implied $/SLOC | +|--------------|--------------|------------|----------------| +| ERC-20 Token | 200-500 | $10k-$20k | $20-100 | +| Simple dApp | 500-1,000 | $15k-$30k | $15-60 | +| Mid-level DeFi | 1,000-2,000 | $30k-$50k | $15-50 | +| Complex DeFi | 2,000-5,000 | $50k-$100k | $10-50 | +| Large Protocol | 5,000-10,000+ | $100k-$300k | $10-60 | + +**Specific Example (from industry data):** +- 500 LOC simple contract: $1,500-$2,000 (pre-audit) = **$3-4/LOC** +- 2,000 LOC DeFi protocol: $30,000-$40,000 = **$15-20/LOC** + +### 3.2 Sherlock nSLOC-Based Calculation + +Using Sherlock's guidelines with a $50k median prize pool: + +$$C_{audit}/nSLOC = \frac{Prize Pool}{nSLOC}$$ + +| nSLOC | C/nSLOC | +|-------|---------| +| 500 | $100 | +| 1,000 | $50 | +| 2,000 | $25 | +| 3,000 | $16.67 | +| 5,000 | $10 | + +**Regression Analysis (log-linear fit):** +$$C_{audit} = \alpha \cdot (nSLOC)^\beta$$ + +Where empirically: $\alpha \approx 2,500$ and $\beta \approx 0.7$ (sublinear scaling due to economies of scale) + +### 3.3 Recommended Values for Hook Bazaar Model + +For Uniswap V4 hooks specifically: + +| Hook Complexity | Estimated SLOC | Audit Cost Range | C/SLOC | +|-----------------|----------------|------------------|--------| +| Simple (Counter, Basic Fee) | 100-300 | $5k-$15k | $17-150 | +| Moderate (TWAMM, Limit Orders) | 300-800 | $15k-$40k | $19-133 | +| Complex (Custom AMM, Oracle) | 800-2,000 | $40k-$80k | $20-100 | + +**Central Estimate for Model:** +$$\bar{C}_{audit}/SLOC \approx \$25-50/SLOC$$ + +This accounts for: +- Premium for DeFi/AMM complexity +- Uniswap V4 novel architecture risk +- Required formal verification for critical components + +--- + +## 4. Developer Costs + +### 4.1 Hourly Rates + +**Freelance Solidity Developers:** + +| Experience Level | Hourly Rate (USD) | Source | +|------------------|-------------------|--------| +| Junior | $40-65 | ZipRecruiter, Arc | +| Mid-level | $65-100 | Arc, Web3.career | +| Senior | $100-150 | Arc, Web3.career | +| Expert/Specialist | $150-350 | Arc, Industry | + +**Geographic Variation:** +- US/Western Europe: $80-200/hour +- Eastern Europe: $50-100/hour +- Asia/South America: $30-80/hour + +**Averages:** +- Arc freelance average: **$81-100/hour** +- ZipRecruiter US average: **$58.08/hour** +- Web3.career average: **$78/hour** + +### 4.2 Annual Salaries + +| Role | Salary Range | Notes | +|------|--------------|-------| +| Junior Solidity Dev | $65k-$100k | Entry level | +| Mid-level | $100k-$150k | 2-4 years experience | +| Senior | $150k-$200k | 4+ years | +| Principal/Lead | $175k-$257k | Expert level | + +**DeFi/NFT Specialist Premium:** +10-30% above base + +### 4.3 Hook Development Time Estimates + +**Based on industry data:** + +| Project Complexity | Development Time | Typical Hours | +|--------------------|------------------|---------------| +| Simple smart contract | 2-4 weeks | 80-160 hours | +| Basic Uniswap V4 hook | 2-4 weeks | 80-160 hours | +| Complex DeFi protocol | 8-12 weeks | 320-480 hours | +| Sophisticated DEX/Lending | 12-20 weeks | 480-800 hours | + +**Hook-Specific Estimates:** + +| Hook Type | Dev Time | Audit Time | Total Cost | +|-----------|----------|------------|------------| +| Simple fee hook | 1-2 weeks | 1 week | $15k-$30k | +| TWAMM implementation | 4-6 weeks | 2-3 weeks | $50k-$100k | +| Custom oracle hook | 3-5 weeks | 2 weeks | $40k-$80k | +| Full-range liquidity | 2-4 weeks | 1-2 weeks | $25k-$50k | + +**Sources:** +- [Solidity Developer Salary Guide - Alchemy](https://www.alchemy.com/overviews/solidity-developer-salary) +- [Solidity Developer Hourly Rate - Arc](https://arc.dev/freelance-developer-rates/solidity) +- [Web3 Salaries - Web3.career](https://web3.career/web3-salaries/solidity-developer) +- [DeFi Development - Synodus](https://synodus.com/blog/blockchain/defi-smart-contract-development/) + +--- + +## 5. Total Cost Function Components + +### 5.1 Hook Development Cost Model + +$$C_{hook} = C_{dev} + C_{audit} + C_{deploy} + C_{maintenance}$$ + +Where: +- $C_{dev} = r_{dev} \cdot h_{dev}$ (hourly rate * development hours) +- $C_{audit} = c_{SLOC} \cdot SLOC$ (cost per line * lines of code) +- $C_{deploy}$ = Gas costs (typically $500-$5,000 on mainnet) +- $C_{maintenance}$ = Ongoing monitoring and updates + +### 5.2 Parameterized Estimates + +| Parameter | Low Estimate | Central | High Estimate | +|-----------|--------------|---------|---------------| +| $r_{dev}$ (hourly) | $60 | $100 | $200 | +| $h_{dev}$ (hours) | 80 | 200 | 500 | +| $c_{SLOC}$ ($/LOC) | $15 | $35 | $75 | +| SLOC (hook) | 200 | 500 | 1,500 | + +**Example Calculation (moderate hook):** +- Development: $100/hr * 200 hrs = $20,000 +- Audit: $35/LOC * 500 LOC = $17,500 +- Deploy + misc: $2,500 +- **Total: $40,000** + +### 5.3 Hook Bazaar Economic Implications + +For a marketplace of hooks: +1. **Minimum viable hook cost:** ~$15,000-$25,000 (simple, audited) +2. **Average hook cost:** ~$40,000-$60,000 (moderate complexity) +3. **Complex hook cost:** ~$80,000-$150,000+ (novel mechanisms) + +**Break-even analysis:** +- At 1% hook fee and $1M daily volume: ~$10,000/day revenue +- Simple hook break-even: 2-3 days +- Complex hook break-even: 10-15 days + +--- + +## 6. Data Quality and Limitations + +### 6.1 Data Sources + +| Source | Type | Reliability | Date | +|--------|------|-------------|------| +| Code4rena 2024 blog | Primary | High | Jan 2024 | +| cmichel.io stats | Primary | High | May 2022 | +| Sherlock docs | Primary | High | 2024 | +| Immunefi - The Block | Secondary | High | Jul 2024 | +| Industry pricing guides | Aggregated | Medium | 2024-2025 | +| OpenZeppelin forum | User-reported | Medium | Various | + +### 6.2 Limitations + +1. **Pricing opacity:** Top-tier firms do not publish fixed rates +2. **Market volatility:** Crypto market conditions affect demand/pricing +3. **Scope variability:** SLOC alone does not capture complexity +4. **Geographic variance:** Rates differ significantly by region +5. **Temporal decay:** Data from 2022-2024 may not reflect current market + +### 6.3 Recommended Updates + +- Re-survey competitive audit platforms quarterly +- Track Code4rena/Sherlock prize pool trends +- Monitor Immunefi annual reports +- Index against ETH price for gas cost stability + +--- + +## References + +1. [Sherlock Audit Pricing and Timeline](https://docs.sherlock.xyz/audits/protocols/audit-pricing-and-timeline) +2. [Code4rena Welcome to 2024](https://medium.com/code4rena/welcome-to-2024-at-code4rena-f0929a6ae3a8) +3. [cmichel Code4rena First 1M Stats](https://cmichel.io/code4rena-first-1m-stats/) +4. [Immunefi $100M Milestone - The Block](https://www.theblock.co/post/301025/web3-immunefi-ethical-hacker-payouts) +5. [Understanding Smart Contract Audit Costs - Ulam](https://www.ulam.io/blog/smart-contract-audit) +6. [Smart Contract Audit Cost Breakdown - Medium/Predict](https://medium.com/predict/smart-contract-audit-costs-and-processes-a-detailed-breakdown-1a70cecf12aa) +7. [Solidity Developer Salary Guide - Alchemy](https://www.alchemy.com/overviews/solidity-developer-salary) +8. [Solidity Developer Hourly Rate - Arc](https://arc.dev/freelance-developer-rates/solidity) +9. [Web3 Salaries - Web3.career](https://web3.career/web3-salaries/solidity-developer) +10. [DeFi Smart Contract Development - Synodus](https://synodus.com/blog/blockchain/defi-smart-contract-development/) +11. [Crypto Security Audit Costs 2025 - HashUltra](https://hashultra.com/crypto-security-audit-costs-in-2025-pricing-guide-for-smart-contracts) +12. [OpenZeppelin Audit Cost Discussion](https://forum.openzeppelin.com/t/cost-of-an-audit/38646) +13. [Uniswap V4 Hooks Documentation](https://docs.uniswap.org/contracts/v4/concepts/hooks) +14. [ConsenSys Diligence Blog](https://diligence.consensys.io/blog/) + +--- + +*Document prepared for Hook Bazaar economic model justification.* +*Last updated: December 2024* diff --git a/docs/slides-utils/FINAL.pdf b/docs/slides-utils/FINAL.pdf new file mode 100644 index 00000000..40c06460 Binary files /dev/null and b/docs/slides-utils/FINAL.pdf differ diff --git a/docs/slides-utils/FINAL_backup.pdf b/docs/slides-utils/FINAL_backup.pdf new file mode 100644 index 00000000..51d703b1 Binary files /dev/null and b/docs/slides-utils/FINAL_backup.pdf differ diff --git a/docs/slides-utils/HookBazaarIntro.pdf b/docs/slides-utils/HookBazaarIntro.pdf new file mode 100755 index 00000000..7e0ce1c4 Binary files /dev/null and b/docs/slides-utils/HookBazaarIntro.pdf differ diff --git a/docs/slides-utils/Roadmap.pdf b/docs/slides-utils/Roadmap.pdf new file mode 100755 index 00000000..33cd638c Binary files /dev/null and b/docs/slides-utils/Roadmap.pdf differ diff --git a/docs/slides-utils/Thanks.pdf b/docs/slides-utils/Thanks.pdf new file mode 100755 index 00000000..2e5958aa Binary files /dev/null and b/docs/slides-utils/Thanks.pdf differ diff --git a/docs/slides-utils/page1.pdf b/docs/slides-utils/page1.pdf new file mode 100644 index 00000000..3acbd3fb Binary files /dev/null and b/docs/slides-utils/page1.pdf differ diff --git a/docs/solution_overview/user_story_hookdev.md b/docs/solution_overview/user_story_hookdev.md new file mode 100644 index 00000000..081a3248 --- /dev/null +++ b/docs/solution_overview/user_story_hookdev.md @@ -0,0 +1,987 @@ +# Hook Developer User Story: Using Hook Bazaar (Gamma Spec) + +## Overview + +**Story**: A skilled hook developer discovers Hook Bazaar's formal specification system. We follow their journey: write formal spec → submit for SystemStateModel validation → mint HookLicense → deploy source code → get discovered by protocols, researchers, and auditors. + +**Tool**: Gamma Pro +**Duration**: ~90 seconds (7 scenes) +**Tone**: Technical empowerment, professional validation, structured success +**Contrast**: This follows the "Problem" story - same developer, now with proper infrastructure +**Source**: [user_story_hookdev.md](../problem-description/user_story_hookdev.md) + +**IMPORTANT - Slide Titles**: Only Slide 1 has a title: **"Meet @eth1000xSuperDev"**. All other slides have NO title. + +--- + +## Technical Flow Overview + +### The Hook Bazaar Developer Journey + +``` +1. FORMAL SPEC → Define hook state variables & IHooks entry points +2. VALIDATION → SystemStateModel compatibility check +3. MINT LICENSE → HookMintLicense grants submission rights +4. SUBMIT CODE → Source code with automatic tagging & metadata +5. DISCOVERY → Visible to Protocols, Researchers, Auditors +6. INTEGRATION → AVS operators help verify requirements +7. REVENUE → Built-in payment rails +``` + +### Key Technical Concepts + +| Concept | Purpose | +|---------|---------| +| IStateView | Canonical pool state variables | +| IHooks | Entry point for hook services | +| SystemStateModel | Validates hook spec compatibility | +| HookMintLicense | NFT granting submission rights | +| AVS Operator | Helps protocols verify integration | + +--- + +## Scene Breakdown + +### Scene 1: The Formal Approach +**Duration**: 10-15 seconds + +**Slide Title**: "Meet @eth1000xSuperDev" (ONLY slide with a title) + +**Visual**: Developer realizes they need formal specs, not just code + +**Content**: +``` +[Developer at desk with formal specification document] + +@eth1000xSuperDev: "I have a formal document showing how my hook + state variables interact with PoolManager context." + +[Shows IStateView interface on screen] + +@eth1000xSuperDev: "IStateView defines the canonical pool state variables. + IHooks is my entry point. + Let me build this properly with Hook Bazaar." +``` + +**Elements**: +- Single stick figure with formal spec document +- IStateView / IHooks code snippets on screen +- State variable diagram (hook ↔ PoolManager) +- Hook Bazaar portal appearing + +**Gamma Prompt**: +``` +Create a whiteboard-style slide showing developer with formal specification. + +SLIDE TITLE: "Meet @eth1000xSuperDev" (this is the ONLY slide with a title) + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +Scene: Developer at desk with formal spec document +- Stick figure holding document labeled "Hook Spec" +- Computer screen showing code snippets: + "IStateView" (canonical state variables) + "IHooks" (entry point) +- Simple diagram: Hook ↔ PoolManager arrows + +Speech bubbles: +- "Formal spec for state variable interactions" +- "IHooks is my entry point" + +Hook Bazaar logo appears with lightbulb + +Animation: Spec document → code snippets → platform discovery +Colors: Black lines, gold edge for Hook Bazaar +Mood: Professional, methodical approach + +NOTE: All other slides have NO title - only this first slide. +``` + +--- + +### Scene 2: Write the Hook Specification +**Duration**: 15-20 seconds + +**Visual**: Developer writing formal hook specification + +**Content**: +``` +[Hook Specification Editor] + +WRITING HOOK SPEC: +┌─────────────────────────────────────────────┐ +│ HOOK SPECIFICATION │ +│ │ +│ Target: IHooks entry points │ +│ State Variables: │ +│ - Maps to IStateView canonical vars │ +│ - PoolManager context interactions │ +│ │ +│ Service Definition: │ +│ - Anti-snipe protection for LBP pools │ +│ - beforeSwap callback implementation │ +│ │ +│ Formal Invariants: │ +│ - State consistency guarantees │ +│ - AMM theory compliance │ +└─────────────────────────────────────────────┘ + +"Building top-down from IHooks to achieve my goals." +``` + +**Gamma Prompt**: +``` +Create a whiteboard-style slide showing spec writing. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +- Stick figure developer writing specification document +- Show key elements appearing: + "IHooks entry points" (underlined, deep blue edge) + "IStateView canonical variables" (underlined, deep blue edge) + "PoolManager context" (with arrows, deep blue edge) + +- Draw state variable diagram: + Hook State ↔ Pool State ↔ PoolManager + +- Show service definition (gold edge): + "Anti-snipe protection" + "beforeSwap callback" + +Speech bubble: "Top-down from IHooks" + +Animation: Elements drawn step-by-step as spec builds +Colors: Black lines, deep blue (#003366) for technical, gold (#FFD700) for service +Keep technical but accessible +``` + +--- + +### Scene 3: SystemStateModel Validation +**Duration**: 15-20 seconds + +**Visual**: Submitting spec for compatibility validation + +**Content**: +``` +[Hook Bazaar Validation Portal] + +SUBMIT HOOK SPEC: +┌─────────────────────────────────────────────┐ +│ SystemStateModel Compatibility Check │ +│ │ +│ Validating... │ +│ │ +│ ✓ State variables mapped correctly │ +│ ✓ IHooks interface compliant │ +│ ✓ PoolManager interactions valid │ +│ ✓ AMM theory constraints satisfied │ +│ ✓ No state conflicts detected │ +│ │ +│ RESULT: ✓ COMPATIBLE │ +│ │ +│ "Your spec is compatible with │ +│ the SystemStateModel!" │ +└─────────────────────────────────────────────┘ + +[Celebration marks] +``` + +**Demo Video Placeholder**: +``` + +- Upload hook specification +- Automatic compatibility analysis +- State variable mapping check +- Validation result +``` + +**Gamma Prompt**: +``` +Create a whiteboard-style validation scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +- Stick figure developer watching validation portal (rectangle) +- Header: "SystemStateModel Compatibility Check" + +- Show validation steps appearing with checkmarks: + ✓ "State variables mapped" (gold #FFD700 checkmark) + ✓ "IHooks compliant" (gold checkmark) + ✓ "PoolManager valid" (gold checkmark) + ✓ "AMM theory satisfied" (gold checkmark) + ✓ "No conflicts" (gold checkmark) + +- Big result: "COMPATIBLE ✓" (gold edge, circled with wobbling line) +- Stick figure celebrates with arms up + +Include placeholder: "[DEMO VIDEO: Validation]" + +Animation: Validation steps appear one by one → final result celebration +Colors: Black lines, gold (#FFD700) for checkmarks and success +This is a key milestone - formal validation! +``` + +--- + +### Scene 4: Mint HookLicense +**Duration**: 10-15 seconds + +**Visual**: Minting the HookMintLicense NFT + +**Content**: +``` +[HookMintLicense Portal] + +YOUR SPEC IS VALIDATED! +Now mint your HookMintLicense to submit source code. + +┌─────────────────────────────────────────────┐ +│ 🪝 HOOK MINT LICENSE │ +│ │ +│ License ID: #4721 │ +│ Developer: @eth1000xSuperDev │ +│ Spec Hash: 0x7a3f... │ +│ Validated: ✓ SystemStateModel │ +│ │ +│ RIGHTS GRANTED: │ +│ ✓ Submit source code │ +│ ✓ Automatic tagging │ +│ ✓ Metadata generation │ +│ ✓ Marketplace listing │ +│ │ +│ [Mint License] → ✓ Minted! │ +└─────────────────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a whiteboard-style license minting scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +- Stick figure developer clicking mint button +- Draw HookMintLicense as certificate/NFT card (gold #FFD700 edge) +- Show license details: + "License ID: #4721" + "@eth1000xSuperDev" + "Spec Hash: 0x7a3f..." + "✓ SystemStateModel validated" (gold checkmark) + +- Draw rights granted list (gold checkmarks): + ✓ "Submit source code" + ✓ "Automatic tagging" + ✓ "Metadata generation" + ✓ "Marketplace listing" + +- Mint button → "Minted!" with celebration marks +- Stick figure receives the license card + +Animation: License card appears → rights unlock → mint success +Colors: Black lines, gold (#FFD700) edge for license (valuable asset) +``` + +--- + +### Scene 5: Submit Source Code +**Duration**: 15-20 seconds + +**Visual**: Submitting code with automatic processing + +**Content**: +``` +[Source Code Submission] + +SUBMIT WITH HOOKMINTLICENSE: +┌─────────────────────────────────────────────┐ +│ Upload Source Code │ +│ │ +│ [AntiSnipeHook.sol] ✓ Uploaded │ +│ │ +│ AUTOMATIC PROCESSING: │ +│ ✓ Code matches spec │ +│ ✓ Compiles successfully │ +│ ✓ Tests pass (247/247) │ +│ │ +│ AUTO-GENERATED: │ +│ ✓ Tags: [MEV-Protection] [LBP] [beforeSwap] │ +│ ✓ Metadata: Category, compatibility, docs │ +│ ✓ Integration guide created │ +│ │ +│ STATUS: ✓ LIVE ON MARKETPLACE │ +└─────────────────────────────────────────────┘ + +"The system tagged it automatically and generated + the metadata for me. Now visible on my dashboard!" +``` + +**Demo Video Placeholder**: +``` + +- Upload with HookMintLicense +- Automatic code-spec matching +- Tag and metadata generation +- Marketplace listing +``` + +**Gamma Prompt**: +``` +Create a whiteboard-style code submission scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +- Stick figure developer uploading file +- Draw upload interface +- Show file: "AntiSnipeHook.sol ✓" (gold checkmark) + +- Draw automatic processing steps (gold checkmarks): + ✓ "Code matches spec" + ✓ "Compiles" + ✓ "Tests pass" + +- Show AUTO-GENERATED section (gold edge, emphasized): + "Tags: [MEV-Protection] [LBP]" (drawn as labels) + "Metadata: auto-created" + "Integration guide: auto-generated" + +- Big "LIVE ON MARKETPLACE" with celebration (gold edge, circled) +- Stick figure with arms up celebrating + +Include placeholder: "[DEMO VIDEO: Submission]" + +Animation: Upload → processing → auto-generation → live! +Speech bubble: "System tagged it automatically!" +Colors: Black lines, gold (#FFD700) edge for success and automation benefits +``` + +--- + +### Scene 6: Multi-Stakeholder Discovery +**Duration**: 15-20 seconds + +**Visual**: Different stakeholders discovering and interacting with the hook + +**Content**: +``` +[Hook Bazaar Dashboard - Discovery] + +YOUR HOOK IS DISCOVERABLE BY: + +┌─────────────────────────────────────────────┐ +│ 👥 PROTOCOLS │ +│ "DeFiSuperStars wants to integrate" │ +│ → AVS Operator verifies requirements ✓ │ +├─────────────────────────────────────────────┤ +│ 🔬 RESEARCHERS │ +│ "AMM Lab validated HookSpec soundness" │ +│ → Formal verification adds credibility ✓ │ +├─────────────────────────────────────────────┤ +│ 🔍 AUDITORS │ +│ "Sherlock team reviewing for audit" │ +│ → Access to code + spec + validation ✓ │ +└─────────────────────────────────────────────┘ + +DASHBOARD STATS: +- Protocol inquiries: 8 +- Research citations: 2 +- Audit requests: 3 + +"Multiple stakeholders, one platform!" +``` + +**Gamma Prompt**: +``` +Create a whiteboard-style multi-stakeholder scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +Draw three boxes stacked (deep blue #003366 edges): + +1. PROTOCOLS (top): +- 2-3 stick figures labeled "Protocols" +- "DeFiSuperStars wants to integrate" +- "AVS Operator verifies ✓" (gold #FFD700 checkmark) + +2. RESEARCHERS (middle): +- Stick figure with magnifying glass +- "HookSpec soundness validated" +- "AMM theory compliance ✓" (gold checkmark) + +3. AUDITORS (bottom): +- Stick figure with document +- "Sherlock reviewing" +- "Full access to code + spec ✓" (gold checkmark) + +Side stats (deep blue edge): +- "8 protocol inquiries" +- "2 research citations" +- "3 audit requests" + +Animation: Three sections reveal one by one +Colors: Black lines, deep blue (#003366) for sections, gold (#FFD700) for checkmarks +Show the ecosystem forming around the hook +``` + +--- + +### Scene 7: Call to Action +**Duration**: 10 seconds + +**Visual**: Hook Bazaar developer CTA + +**Content**: +``` +┌─────────────────────────────────────────────┐ +│ │ +│ 🪝 HOOK BAZAAR │ +│ For Hook Developers │ +│ │ +│ "Formal specs. Validated code. │ +│ Professional discovery." │ +│ │ +│ Write Spec → Validate → Mint → Deploy │ +│ │ +│ [Write Your Hook Spec] │ +│ [Mint HookLicense] │ +│ │ +│ hookbazaar.xyz/developers │ +│ │ +└─────────────────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a whiteboard-style closing CTA for developers. + +Style: Hand-drawn sketch, marker on white background +Clean, professional finish + +- Draw Hook Bazaar logo (simple hook icon, gold #FFD700 edge) +- Write "For Hook Developers" underneath + +- Write taglines: + "Formal specs. Validated code." + "Professional discovery." + +- Draw the flow as simple arrow chain (deep blue #003366 arrows): + Write Spec → Validate → Mint → Deploy + +- Draw two buttons (rectangles, gold edge): + [Write Your Hook Spec] + [Mint HookLicense] + +- Write URL: hookbazaar.xyz/developers (underlined, gold) + +Animation: Logo → flow diagram → CTA buttons +Colors: Black lines, gold (#FFD700) for logo/buttons, deep blue (#003366) for flow +Keep it professional and technical +``` + +--- + +## Animation Timing Summary + +| Scene | Duration | Cumulative | +|-------|----------|------------| +| 1. Formal Approach | 12s | 12s | +| 2. Write Specification | 18s | 30s | +| 3. SystemStateModel Validation | 18s | 48s | +| 4. Mint HookLicense | 12s | 60s | +| 5. Submit Source Code | 18s | 78s | +| 6. Multi-Stakeholder Discovery | 18s | 96s | +| 7. CTA | 10s | **106s** | + +**Total runtime**: ~1:46 + +--- + +## Demo Video Integration Points + +### Video 1: Spec Writing & Validation +**Location**: Scene 2-3 +**Content**: +- Hook specification editor +- SystemStateModel validation +- Compatibility check results +**Duration**: 30-45 seconds +**Format**: Loom embed or MP4 + +### Video 2: License Minting & Code Submission +**Location**: Scene 4-5 +**Content**: +- HookMintLicense minting +- Source code upload +- Automatic tagging demo +**Duration**: 30-45 seconds +**Format**: Loom embed or MP4 + +### Video 3: Dashboard & Discovery +**Location**: Scene 6 +**Content**: +- Developer dashboard +- Protocol inquiries +- AVS operator verification +**Duration**: 20-30 seconds +**Format**: Loom embed or MP4 + +--- + +## Key Technical Concepts Explained + +### IStateView - Canonical Pool State +``` +The variables defined on IStateView represent +canonical pool state variables, regardless of +protocol semantics. All hooks use these variables. + +Special cases: +- beforeSwap callbacks building AMMs +- Overwriting CFMM logic with custom logic +``` + +### SystemStateModel Validation +``` +Ensures hook spec is compatible with: +- Pool state variable interactions +- PoolManager context requirements +- AMM theory constraints +- State consistency guarantees +``` + +### HookMintLicense Rights +``` +NFT granting developer rights to: +1. Submit source code to platform +2. Automatic categorization & tagging +3. Metadata generation +4. Marketplace visibility +5. Revenue collection +``` + +### AVS Operator Role +``` +Helps protocols verify: +- Hook integration requirements +- Compatibility with their pools +- Security validation status +- Recommended configurations +``` + +--- + +## Visual Style (Black & White + Colored Edges) + +**Colors aligned with Hook Bazaar Design System (from frontend.md)** + +| Element | Specification | +|---------|---------------| +| Background | Pure white (#FFFFFF) | +| All elements | Black (#000000) | +| Validation/Success edges | Gold outline (#FFD700) - primary brand color | +| Technical/State edges | Deep Blue outline (#003366) - from logo | +| Warnings (if any) | Orange-Red outline (#E85A4F) - from logo | + +**Key Rule**: Everything is BLACK on WHITE. Color appears ONLY as edge highlights, outlines, or underlines - never as fills. + +**Logo-Inspired Palette Reference**: +``` +Gold (Primary): #FFD700 - Validation success, checkmarks, license, positive +Orange-Red (Accent): #E85A4F - Warnings, errors, problems (if any) +Deep Blue: #003366 - Technical elements, state variables, neutral +Terracotta: #CD853F - Secondary accent (optional) +``` + +--- + +## Whiteboard Animation Aesthetics + +### 1. Hand-Drawn Look ✍️ + +| Principle | Implementation | +|-----------|----------------| +| Lines drawn in real-time | Elements appear as if sketched by marker/pen | +| Intentional imperfections | Slight wobble, uneven lines = human feel | +| Visible hand | Optional: show hand drawing elements | +| **STICK FIGURES** | All characters MUST be stick-figure style | + +**Stick-Figure Requirements**: +- All human characters as simple stick figures (circle head, line body, line limbs) +- No detailed faces - simple dots for eyes, line for mouth if needed +- Expressive through posture and gesture, not facial detail +- Consistent stick-figure proportions throughout all scenes + +**Gamma Prompt Addition**: +``` +Style: Whiteboard animation / hand-drawn sketch look +BLACK AND WHITE ONLY - all elements drawn in black on white background +ALL CHARACTERS MUST BE STICK FIGURES - simple circle head, line body, line limbs +Color appears ONLY as edge highlights/outlines (Hook Bazaar brand colors): + - Deep Blue (#003366) edges for technical/state elements + - Gold (#FFD700) edges for validation success/checkmarks + - Orange-Red (#E85A4F) edges for any warnings +Lines should appear as if being drawn by a marker in real-time +Slight imperfections are welcome - keep it human and informal +No detailed faces - express emotion through posture and gesture +``` + +### 2. Minimalist Visual Language + +| Element | Style | +|---------|-------| +| Background | Pure white | +| Lines | Black only | +| Characters | **STICK FIGURES ONLY** (circle head, line body) | +| Icons | Black hand-drawn style | +| Color | EDGES/OUTLINES ONLY | + +**Color Palette (Black & White + Logo-Inspired Colored Edges)**: +``` +Background: #FFFFFF (pure white) - SLIDE BACKGROUND IS WHITE +Lines/Fill: #000000 (black) - all main elements +Edges only (from Hook Bazaar logo/brand): + - Deep Blue edge (#003366) - technical elements, state variables + - Gold edge (#FFD700) - validation, success, license + - Orange-Red edge (#E85A4F) - warnings (rare) + +Rule: Elements are BLACK with COLORED OUTLINES/EDGES only +No filled colors - only edge highlights +``` + +**Edge Color Application (Logo-Aligned)**: +| Element Type | Fill | Edge/Outline | +|--------------|------|--------------| +| State variables/Technical | Black text | Deep Blue (#003366) outline | +| Validation checkmarks | Black | Gold (#FFD700) edge | +| HookMintLicense | Black | Gold (#FFD700) edge | +| Success messages | Black text | Gold (#FFD700) outline | +| Stakeholder sections | Black | Deep Blue (#003366) edge | + +### 3. Progressive Revelation + +| Technique | When to Use | +|-----------|-------------| +| Draw step-by-step | Each element appears as it's explained | +| Slow, deliberate | ~2-3 seconds per element | +| Linear motion | Left-to-right, top-to-bottom flow | +| No spectacle | Movement supports explanation | + +**Animation Timing**: +``` +Element draw-in: 2-3 seconds +Pause after element: 1 second +Transition: 1-2 seconds +Total per concept: 4-6 seconds +``` + +### 4. Educational Clarity + +| Element | Purpose | +|---------|---------| +| Diagrams | Simplify complex concepts | +| Flowcharts | Show process steps | +| Labels | Always label key elements | +| Arrows | Connect related concepts | +| Metaphors | Use familiar visuals | + +**Visual Hierarchy**: +``` +Large: Headlines, validation results, license +Medium: Labels, descriptions +Small: Details, sources +Spacing: Generous whitespace between elements +``` + +### 5. Friendly, Neutral Tone + +| Aspect | Approach | +|--------|----------| +| Characters | Simple stick figures - emotion via posture | +| Language | Technical but accessible | +| Complexity | Reduced to essentials | +| Voiceover ready | Calm, narrative pacing | + +### 6. Low Visual Noise + +**Avoid**: +- Complex textures +- Shadows +- 3D effects +- Gradients +- Busy backgrounds + +**Use**: +- Flat colors +- High contrast +- Clean lines +- Focused composition + +### 7. Rhythm Over Realism + +| Gesture | When to Use | +|---------|-------------| +| Drawing | Introducing new elements | +| Erasing | Correcting or transitioning | +| Circling | Emphasizing validation success | +| Underlining | Highlighting important text | +| Arrows | Connecting concepts (state flows) | +| Checkmarks | Validation steps | +| Brackets | Grouping technical concepts | + +--- + +## Updated Scene Prompts (Whiteboard Style) + +### Scene 1: Formal Approach (Whiteboard) +``` +Create a whiteboard-style slide showing developer with formal spec. + +SLIDE TITLE: "Meet @eth1000xSuperDev" (ONLY this slide has a title) + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Stick figure holding document labeled "Hook Spec" +- Screen showing: "IStateView" and "IHooks" (deep blue #003366 edge) +- Simple diagram: Hook ↔ PoolManager with arrows +- Hook Bazaar logo appearing (gold #FFD700 edge) + +Animation: Document → code terms → platform discovery +Colors: Black lines, deep blue (#003366) for technical, gold (#FFD700) for Hook Bazaar +Mood: Professional, methodical + +NOTE: All other slides have NO title - only this first slide. +``` + +### Scene 2: Write Specification (Whiteboard) +``` +Create a whiteboard-style spec writing scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Stick figure developer writing spec document +- Key terms appearing: + "IHooks entry point" (deep blue #003366 underline) + "IStateView variables" (deep blue underline) + "Service: Anti-snipe protection" (gold #FFD700 edge) +- Simple state diagram: Hook State ↔ Pool State + +Animation: Spec builds piece by piece +Colors: Black lines, deep blue (#003366) for technical, gold (#FFD700) for service +Technical but clear +``` + +### Scene 3: Validation (Whiteboard) +``` +Create a whiteboard-style validation scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Stick figure developer watching validation +- Draw "SystemStateModel Check" header (deep blue #003366 edge) +- Validation steps with checkmarks: + ✓ State variables (gold #FFD700 checkmark) + ✓ IHooks compliant (gold checkmark) + ✓ PoolManager valid (gold checkmark) + ✓ AMM theory (gold checkmark) +- Big "COMPATIBLE ✓" result (circled in gold, wobbling line) +- Stick figure celebrates with arms up + +Animation: Checks appear one by one → celebration +Colors: Black lines, deep blue (#003366) for header, gold (#FFD700) for checkmarks +Key milestone moment +``` + +### Scene 4: Mint License (Whiteboard) +``` +Create a whiteboard-style license minting scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Stick figure developer clicking mint button +- Draw HookMintLicense card (gold #FFD700 edge - valuable) +- Details: ID, developer, spec hash +- Rights listed with checkmarks (gold checkmarks): + ✓ Submit code + ✓ Auto-tagging + ✓ Metadata + ✓ Marketplace +- "Minted!" with celebration marks +- Stick figure receives the license card + +Animation: License appears → rights unlock +Colors: Black lines, gold (#FFD700) edge for license (valuable asset) +``` + +### Scene 5: Submit Code (Whiteboard) +``` +Create a whiteboard-style submission scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Stick figure developer uploading file +- Draw file upload: "AntiSnipeHook.sol" (gold #FFD700 checkmark) +- Show automatic processing (gold checkmarks): + ✓ Matches spec + ✓ Compiles + ✓ Tests pass +- AUTO-GENERATED section (gold edge): + Tags appearing: [MEV] [LBP] + "Metadata created" +- "LIVE!" celebration (gold edge, circled) +- Stick figure with arms up celebrating + +Animation: Upload → auto-process → live +Colors: Black lines, gold (#FFD700) for success and automation benefits +Emphasize automation benefits +``` + +### Scene 6: Multi-Stakeholder (Whiteboard) +``` +Create a whiteboard-style stakeholder scene. + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) + +Three sections stacked (deep blue #003366 edges): +1. PROTOCOLS: 2-3 stick figures, "AVS verifies ✓" (gold #FFD700 checkmark) +2. RESEARCHERS: Stick figure + magnifying glass, "Soundness validated ✓" (gold checkmark) +3. AUDITORS: Stick figure + document, "Full access ✓" (gold checkmark) + +Side stats (deep blue edge): inquiries, citations, audit requests + +Animation: Sections reveal one by one +Colors: Black lines, deep blue (#003366) for sections, gold (#FFD700) for checkmarks +Show ecosystem forming +``` + +### Scene 7: CTA (Whiteboard) +``` +Create a whiteboard-style closing CTA. + +Style: Hand-drawn sketch, marker on white background +Clean, professional finish + +- Hook Bazaar logo (simple hook icon, gold #FFD700 edge) +- "For Hook Developers" +- Taglines: "Formal specs. Validated code." +- Flow: Spec → Validate → Mint → Deploy (deep blue #003366 arrows) +- Buttons: [Write Spec] [Mint License] (gold edge) +- URL: hookbazaar.xyz/developers (underlined, gold) + +Animation: Logo → flow → CTA +Colors: Black lines, gold (#FFD700) for logo/buttons, deep blue (#003366) for flow +Professional finish +``` + +--- + +## Gamma Tips for This Story + +1. **Technical diagrams** - Use simple boxes and arrows for state flows +2. **Stick figure style** - All characters as simple stick figures +3. **Validation emphasis** - Make SystemStateModel check feel like achievement +4. **License as NFT** - Draw HookMintLicense as valuable certificate +5. **Multi-stakeholder** - Show ecosystem value (not just protocols) +6. **Export to video** for smoothest playback + +--- + +## Scene-to-Slide Transition Guide + +**CRITICAL**: Each scene = ONE slide. To enforce scene transitions as slide transitions in Gamma: + +### Structuring for Transitions + +| Scene | Slide # | Transition Type | Gamma Instruction | +|-------|---------|-----------------|-------------------| +| 1. Formal Approach | 1 | Fade In | "Fade in from problem story" | +| 2. Write Spec | 2 | Wipe Left | "Wipe - building the spec" | +| 3. Validation | 3 | Morph | "Morph - spec to validation" | +| 4. Mint License | 4 | Zoom In | "Zoom into license mint" | +| 5. Submit Code | 5 | Push Up | "Push up - uploading code" | +| 6. Discovery | 6 | Split | "Split - multiple stakeholders" | +| 7. CTA | 7 | Dissolve | "Dissolve to final CTA" | + +### Gamma Prompt for Transitions + +When prompting Gamma, explicitly state: +``` +Create a presentation with 7 SLIDES (one per scene). +Each slide should have a distinct transition to the next: + +Slide 1 → 2: Wipe left (building spec) +Slide 2 → 3: Morph (spec becomes validated) +Slide 3 → 4: Zoom in (focus on license) +Slide 4 → 5: Push up (uploading code) +Slide 5 → 6: Split (multiple stakeholders) +Slide 6 → 7: Dissolve (to CTA) + +Do NOT combine scenes into single slides. +Each scene is a separate slide with its own transition. +``` + +### Manual Transition Setup in Gamma + +If Gamma doesn't auto-apply transitions: + +1. **Click on slide** in the left panel +2. **Click "Transition"** button (or find in slide settings) +3. **Select transition type** for each slide: + - **Fade**: For opening slide + - **Wipe**: For building/progression + - **Morph**: For transformations + - **Zoom**: For focus moments + - **Push**: For uploading feel + - **Split**: For multiple sections + - **Dissolve**: For soft endings + +4. **Set duration**: 1-1.5 seconds per transition +5. **Preview**: Watch full presentation to verify timing + +### Transition Timing per Scene + +| Scene | Content Duration | Transition Duration | Total | +|-------|------------------|---------------------|-------| +| 1 | 10s | 1.5s fade in | 11.5s | +| 2 | 16s | 1s wipe | 17s | +| 3 | 16s | 1s morph | 17s | +| 4 | 10s | 1s zoom | 11s | +| 5 | 16s | 1s push | 17s | +| 6 | 16s | 1.5s split | 17.5s | +| 7 | 8s | 1s dissolve | 9s | +| **Total** | **92s** | **8s** | **100s** | + +### Alternative: Gamma "Story Mode" + +For more control, use Gamma's Story Mode: +1. Create presentation in Story Mode (not deck mode) +2. Each "card" becomes a scene +3. Transitions are more fluid in Story Mode +4. Better for technical content flow +s +--- + +## Key Differences from Problem Story + +| Aspect | Problem Story | Solution Story | +|--------|---------------|----------------| +| Approach | Ad-hoc marketing | Formal specification | +| Validation | None | SystemStateModel | +| Rights | None | HookMintLicense | +| Discovery | 0 responses | Multi-stakeholder | +| Trust | "Who are you?" | Validated + Verified | +| Audience | Just protocols | Protocols + Researchers + Auditors | + +--- + +## Files Referenced + +- [user_story_hookdev.md (Problem)](../problem-description/user_story_hookdev.md) - Problem story spec +- Hook Bazaar developer portal documentation +- SystemStateModel technical specification +- IStateView / IHooks interface documentation diff --git a/docs/solution_overview/user_story_protocol.md b/docs/solution_overview/user_story_protocol.md new file mode 100644 index 00000000..a2593e70 --- /dev/null +++ b/docs/solution_overview/user_story_protocol.md @@ -0,0 +1,933 @@ +# Protocol User Story: Using Hook Bazaar (Gamma Spec) + +## Overview + +**Story**: Same protocol team needs a hook, but this time they use Hook Bazaar. We follow their journey: browse → purchase → deploy in minutes, showing massive cost/time savings. + +**Tool**: Gamma Pro +**Duration**: ~90 seconds (7 scenes) +**Tone**: Optimistic, efficient, relief +**Contrast**: This follows the "Problem" story - same team, different outcome +**Source**: [Protocol_Cost_Function.md](../problem-description/Protocol_Cost_Function.md) + +**IMPORTANT - Slide Titles**: Only Slide 1 has a title: **"Meet DeFiSuperStars"**. All other slides have NO title. + +--- + +## Cost Comparison (from Protocol_Cost_Function.md) + +### Self-Build vs Hook Bazaar + +| Hook Type | Self-Build | Hook Bazaar | Savings | +|-----------|-----------|-------------|---------| +| Simple | $8k - $25k | $100 - $500 | **$7.5k - $24.5k** | +| Complex | $50k - $170k | $500 - $2k | **$49.5k - $168k** | + +### Time Comparison + +| Hook Type | Self-Build | Hook Bazaar | Savings | +|-----------|-----------|-------------|---------| +| Simple | 2-4 weeks | Minutes | **~4 weeks** | +| Complex | 2-6 months | Minutes | **~6 months** | + +### The Key Formula + +``` +C_purchase(P_HaaS) < C_self + +Where: +- C_purchase = Integration cost + Hook price +- C_self = C_audit + C_dev + C_test + C_opp +``` + +**Hook Bazaar eliminates**: +- C_audit → $0 (pre-audited) +- C_dev → $0 (pre-built) +- C_test → reduced (battle-tested) +- C_opp → minutes (instant deploy) + +--- + +## Scene Breakdown + +### Scene 1: Same Decision, Different Path +**Duration**: 10-15 seconds + +**Slide Title**: "Meet DeFiSuperStars" (ONLY slide with a title) + +**Visual**: Same conference room / video call (callback to Problem story) + +**Content**: +``` +[Team around table or on video call] + +CTO: "We're launching a liquidity bootstrapping pool + for our yield-bearing token sDeFiSuperStars next month." + +Dev Lead: "We need a dynamic fee hook to stay competitive. + Wait - what about Hook Bazaar? + Pre-built, pre-audited hooks!" + +CTO: "Let's check it out." +``` + +**Elements**: +- Same 3-4 stick figures as Problem story +- Speech bubbles with dialogue +- DeFiSuperStars logo in background +- Hook Bazaar logo appears with lightbulb moment + +**Gamma Prompt**: +``` +Create a slide showing the same protocol team meeting from before. + +SLIDE TITLE: "Meet DeFiSuperStars" (this is the ONLY slide with a title) + +Scene: Video call or conference room with 3-4 stick figures (same as problem story). + +Dialogue (as speech bubbles or text overlays): +- "We're launching a liquidity bootstrapping pool for sDeFiSuperStars" +- "We need a dynamic fee hook to stay competitive" +- "Wait - what about Hook Bazaar?" +- "Pre-built, pre-audited hooks!" + +Show DeFiSuperStars logo, then Hook Bazaar logo appearing with a lightbulb icon. +Mood: Curious, hopeful - the "aha!" moment. + +Use simple stick figures (circle head, line body). +Animate dialogue sequentially, end with Hook Bazaar logo prominent. + +NOTE: No other slides should have titles - only this first slide. +``` + +--- + +### Scene 2: Register Protocol +**Duration**: 10-15 seconds + +**Visual**: Hook Bazaar interface - protocol registration + +**Content**: +``` +[Hook Bazaar Dashboard] + +STEP 1: Register Protocol +- Connect wallet ✓ +- Enter protocol name: "DeFiSuperStars" +- Submit registration ✓ + +"Welcome to Hook Bazaar!" + +TIME ELAPSED: 30 seconds +``` + +**Demo Video Placeholder**: +``` + +- Show actual Hook Bazaar UI +- Wallet connection +- Protocol registration form +- Success confirmation +``` + +**Gamma Prompt**: +``` +Create a slide showing Hook Bazaar protocol registration. + +Left side: Hook Bazaar dashboard mockup showing: +- "Register Your Protocol" header +- Wallet connect button (connected ✓) +- Protocol name field: "DeFiSuperStars" +- Submit button + +Right side: +- Checklist appearing: + ✓ Wallet connected + ✓ Protocol registered +- "Welcome to Hook Bazaar!" message + +Bottom: TIME ELAPSED: 30 seconds (small, subtle) + +Include placeholder text: "[DEMO VIDEO: Registration Flow]" + +Dark theme, green checkmarks, Hook Bazaar branding. +Animate steps completing quickly. +``` + +--- + +### Scene 3: Browse Hooks Marketplace +**Duration**: 15-20 seconds + +**Visual**: Hook Bazaar marketplace - browsing available hooks + +**Content**: +``` +[Hook Bazaar Marketplace] + +BROWSE HOOKS: +┌─────────────────────────────────────────────┐ +│ 🔍 Search: "dynamic fee" │ +├─────────────────────────────────────────────┤ +│ Dynamic Fee Hook v2.1 ⭐ 4.8 │ +│ By: HookDev.eth $299 │ +│ ✓ Audited by Sherlock │ +│ ✓ 47 pools using this hook │ +│ [View Details] [Purchase] │ +├─────────────────────────────────────────────┤ +│ MEV Shield Hook ⭐ 4.9 │ +│ By: SecureHooks.eth $499 │ +│ ✓ Audited by Trail of Bits │ +├─────────────────────────────────────────────┤ + +TIME ELAPSED: 2 minutes +``` + +**Demo Video Placeholder**: +``` + +- Show search functionality +- Filter by category, price, rating +- Hook details page +- Audit reports visible +``` + +**Gamma Prompt**: +``` +Create a slide showing Hook Bazaar marketplace browsing. + +Show marketplace UI mockup: +- Search bar with "dynamic fee" query +- List of hooks with: + - Hook name and version + - Developer name (ENS) + - Star rating + - Price ($299, $499) + - "✓ Audited" badges + - Pool usage count + +Highlight one hook: "Dynamic Fee Hook v2.1" +- Price: $299 +- "✓ Audited by Sherlock" +- "47 pools using this hook" + +Side counter: TIME ELAPSED: 2 minutes + +Include placeholder: "[DEMO VIDEO: Browse Hooks Flow]" + +Dark theme, card-based layout, green for audit badges. +Animate: search → results appear → highlight best match. +``` + +--- + +### Scene 4: Purchase & Deploy +**Duration**: 15-20 seconds + +**Visual**: Purchase flow and instant deployment + +**Content**: +``` +[Purchase Flow] + +SELECTED: Dynamic Fee Hook v2.1 +Price: $299 + +┌─────────────────────────────────────────────┐ +│ Purchase Summary │ +│ │ +│ Hook Price: $299 │ +│ Integration Cost: ~$200 │ +│ ───────────────────────────── │ +│ Total: $499 │ +│ │ +│ Compare to Self-Build: $28,000 │ +│ YOU SAVE: $27,501 (98%) │ +│ │ +│ [Confirm Purchase] │ +└─────────────────────────────────────────────┘ + +[Transaction confirmed ✓] +[Hook deployed to sDeFiSuperStars LBP Pool ✓] + +TIME ELAPSED: 5 minutes +``` + +**Key Formula Display**: +``` +C_purchase = $499 +C_self = $28,000 + +C_purchase << C_self ✓ +``` + +**Gamma Prompt**: +``` +Create a slide showing hook purchase and deployment. + +Left side: Purchase summary card: +- "Dynamic Fee Hook v2.1" +- Hook Price: $299 +- Integration Cost: ~$200 +- Total: $499 + +Right side: Dramatic comparison: +- "Self-Build Cost: $28,000" (crossed out, red) +- "Hook Bazaar: $499" (green, highlighted) +- "YOU SAVE: $27,501 (98%)" (large, glowing) + +Show formula: +C_purchase($499) << C_self($28,000) ✓ + +Bottom sequence: +- "Transaction confirmed ✓" +- "Hook deployed to Pool X ✓" + +TIME ELAPSED: 5 minutes + +Dark theme, green for savings, red strikethrough for self-build cost. +Animate: show costs → reveal comparison → confirm transaction. +``` + +--- + +### Scene 5: Instant Integration +**Duration**: 10-15 seconds + +**Visual**: Hook successfully integrated (same diagram as Problem story) + +**Content**: +``` +[Pool diagram with hook integrated - INSTANTLY] + + ┌──────────────────────────────┐ + │ sDeFiSuperStars LBP Pool │ + │ ┌───────┐ │ + │ │ HOOK │ ✓ │ + │ └───────┘ │ + └──────────────────────────────┘ + +DEPLOYMENT COMPLETE! + +Cost: $499 +Time: 5 minutes +Risk: Minimal (pre-audited) +``` + +**Gamma Prompt**: +``` +Create a slide showing instant hook integration. + +Center: Same pool diagram as problem story: +- Rectangle labeled "sDeFiSuperStars LBP Pool" +- Hook rectangle inside with checkmark +- But this time with celebration effect (confetti, glow) + +Stats overlay (contrasting with problem story): +- "Cost: $499" (vs $28,000) +- "Time: 5 minutes" (vs 6 weeks) +- "Risk: Minimal" (pre-audited) + +Big text: "DEPLOYMENT COMPLETE!" + +Dark theme, celebratory green, slight confetti animation. +Animate: Pool appears → Hook slides in fast → Stats pop up. +``` + +--- + +### Scene 6: The Comparison Reveal +**Duration**: 15-20 seconds + +**Visual**: Side-by-side comparison of both paths + +**Content**: +``` +┌─────────────────────┬─────────────────────┐ +│ SELF-BUILD │ HOOK BAZAAR │ +├─────────────────────┼─────────────────────┤ +│ │ │ +│ 💰 $28,000 │ 💰 $499 │ +│ │ │ +│ ⏱️ 6 weeks │ ⏱️ 5 minutes │ +│ │ │ +│ ⚠️ 5-15% risk │ ✅ Pre-audited │ +│ │ │ +│ 😰 Stressful │ 😊 Simple │ +│ │ │ +└─────────────────────┴─────────────────────┘ + +SAVINGS: +💰 $27,501 saved (98% reduction) +⏱️ 6 weeks saved +✅ Risk eliminated +``` + +**Gamma Prompt**: +``` +Create a dramatic side-by-side comparison slide. + +Two columns: + +SELF-BUILD (left, red tint): +- Cost: $28,000 +- Time: 6 weeks +- Risk: 5-15% vulnerability +- Experience: Stressful + +HOOK BAZAAR (right, green tint): +- Cost: $499 +- Time: 5 minutes +- Risk: Pre-audited ✓ +- Experience: Simple + +Below the comparison, reveal savings: +- "💰 $27,501 saved (98%)" +- "⏱️ 6 weeks saved" +- "✅ Risk eliminated" + +Dark theme, clear visual contrast between left (bad) and right (good). +Animate: Left column appears first → Right column appears → Savings reveal dramatically. +``` + +--- + +### Scene 7: Call to Action +**Duration**: 10 seconds + +**Visual**: Hook Bazaar branding with CTA + +**Content**: +``` +┌─────────────────────────────────────────────┐ +│ │ +│ 🪝 HOOK BAZAAR │ +│ │ +│ "From $170k to $2k" │ +│ "From months to minutes" │ +│ │ +│ [Browse Hooks] [Register Protocol] │ +│ │ +│ hookbazaar.xyz │ +│ │ +└─────────────────────────────────────────────┘ +``` + +**Gamma Prompt**: +``` +Create a closing call-to-action slide. + +Center: Hook Bazaar logo (large) + +Taglines: +- "From $170k to $2k" +- "From months to minutes" + +Two CTA buttons: +- "Browse Hooks" +- "Register Protocol" + +URL: hookbazaar.xyz + +Dark theme, Hook Bazaar brand colors, professional. +Animate: Logo appears → Taglines fade in → Buttons pulse. +``` + +--- + +## Animation Timing Summary + +| Scene | Duration | Cumulative | +|-------|----------|------------| +| 1. Decision (Hook Bazaar) | 12s | 12s | +| 2. Register Protocol | 12s | 24s | +| 3. Browse Marketplace | 18s | 42s | +| 4. Purchase & Deploy | 18s | 60s | +| 5. Instant Integration | 12s | 72s | +| 6. Comparison Reveal | 18s | 90s | +| 7. CTA | 10s | **100s** | + +**Total runtime**: ~1:40 + +--- + +## Demo Video Integration Points + +### Video 1: Registration Flow +**Location**: Scene 2 +**Content**: +- Wallet connection +- Protocol registration form +- Success confirmation +**Duration**: 15-30 seconds +**Format**: Loom embed or MP4 + +### Video 2: Browse Hooks Flow +**Location**: Scene 3 +**Content**: +- Search and filter hooks +- View hook details +- See audit reports +- Compare options +**Duration**: 30-45 seconds +**Format**: Loom embed or MP4 + +### Video 3: Purchase Flow (Optional) +**Location**: Scene 4 +**Content**: +- Select hook +- Confirm purchase transaction +- Deploy to pool +**Duration**: 20-30 seconds +**Format**: Loom embed or MP4 + +--- + +## Key Formula Animations + +### Scene 4: Cost Comparison +``` +Show this formula building up: + +C_purchase(P_HaaS) < C_self + +Expand to: + +($299 + $200) < ($10,000 + $3,000 + $15,000) + $499 < $28,000 + +✓ 98% savings +``` + +**Gamma Prompt for Formula**: +``` +Animate the cost comparison formula: + +Step 1: Show "C_purchase < C_self" +Step 2: Expand to "($299 + $200) < ($10,000 + $3,000 + $15,000)" +Step 3: Simplify to "$499 < $28,000" +Step 4: Big checkmark with "98% SAVINGS" + +Use monospace font for formulas, green for Hook Bazaar side, red for self-build. +``` + +--- + +## Visual Style (Black & White + Colored Edges) + +**Colors aligned with Hook Bazaar Design System (from frontend.md)** + +| Element | Specification | +|---------|---------------| +| Background | Pure white (#FFFFFF) | +| All elements | Black (#000000) | +| Hook Bazaar/Savings edges | Gold outline (#FFD700) - primary brand | +| Self-build/Cost edges | Orange-Red outline (#E85A4F) - from logo | +| Time edges | Deep Blue outline (#003366) - from logo | + +**Key Rule**: Everything is BLACK on WHITE. Color appears ONLY as edge highlights, outlines, or underlines - never as fills. + +**Logo-Inspired Palette Reference**: +``` +Gold (Primary): #FFD700 - Hook Bazaar, success, savings +Orange-Red (Accent): #E85A4F - Self-build costs, warnings +Deep Blue: #003366 - Time, neutral elements +Terracotta: #CD853F - Secondary accent (optional) +``` + +--- + +## Whiteboard Animation Aesthetics + +### 1. Hand-Drawn Look ✍️ + +| Principle | Implementation | +|-----------|----------------| +| Lines drawn in real-time | Elements appear as if sketched by marker/pen | +| Intentional imperfections | Slight wobble, uneven lines = human feel | +| Visible hand | Optional: show hand drawing elements | +| **STICK FIGURES** | All characters MUST be stick-figure style | + +**Stick-Figure Requirements**: +- All human characters as simple stick figures (circle head, line body, line limbs) +- No detailed faces - simple dots for eyes, line for mouth if needed +- Expressive through posture and gesture, not facial detail +- Consistent stick-figure proportions throughout all scenes + +**Gamma Prompt Addition**: +``` +Style: Whiteboard animation / hand-drawn sketch look +BLACK AND WHITE ONLY - all elements drawn in black on white background +ALL CHARACTERS MUST BE STICK FIGURES - simple circle head, line body, line limbs +Color appears ONLY as edge highlights/outlines (Hook Bazaar brand colors): + - Orange-Red (#E85A4F) edges for self-build costs (crossed out) + - Deep Blue (#003366) edges for time elements + - Gold (#FFD700) edges for Hook Bazaar success/savings +Lines should appear as if being drawn by a marker in real-time +Slight imperfections are welcome - keep it human and informal +No detailed faces - express emotion through posture and gesture +``` + +### 2. Minimalist Visual Language + +| Element | Style | +|---------|-------| +| Background | Pure white | +| Lines | Black only | +| Characters | **STICK FIGURES ONLY** (circle head, line body) | +| Icons | Black hand-drawn style | +| Color | EDGES/OUTLINES ONLY | + +**Color Palette (Black & White + Logo-Inspired Colored Edges)**: +``` +Background: #FFFFFF (pure white) - SLIDE BACKGROUND IS WHITE +Lines/Fill: #000000 (black) - all main elements +Edges only (from Hook Bazaar logo/brand): + - Orange-Red edge (#E85A4F) - self-build costs (to cross out) + - Deep Blue edge (#003366) - time elements + - Gold edge (#FFD700) - Hook Bazaar, savings, success + +Rule: Elements are BLACK with COLORED OUTLINES/EDGES only +No filled colors - only edge highlights +``` + +**Edge Color Application (Logo-Aligned)**: +| Element Type | Fill | Edge/Outline | +|--------------|------|--------------| +| Self-build costs | Black text | Orange-Red (#E85A4F) outline + strikethrough | +| Hook Bazaar costs | Black text | Gold (#FFD700) outline | +| Time counters | Black text | Deep Blue (#003366) outline | +| Checkmarks | Black | Gold (#FFD700) edge | +| X marks (crossing out) | Black | Orange-Red (#E85A4F) edge | +| Savings numbers | Black text | Gold (#FFD700) outline (circled) | + +### 3. Progressive Revelation + +| Technique | When to Use | +|-----------|-------------| +| Draw step-by-step | Each element appears as it's explained | +| Slow, deliberate | ~2-3 seconds per element | +| Linear motion | Left-to-right, top-to-bottom flow | +| No spectacle | Movement supports explanation | + +**Animation Timing**: +``` +Element draw-in: 2-3 seconds +Pause after element: 1 second +Transition: 1-2 seconds +Total per concept: 4-6 seconds +``` + +### 4. Educational Clarity + +| Element | Purpose | +|---------|---------| +| Diagrams | Simplify complex concepts | +| Flowcharts | Show process steps | +| Labels | Always label key elements | +| Arrows | Connect related concepts | +| Metaphors | Use familiar visuals | + +**Visual Hierarchy**: +``` +Large: Headlines, totals, key numbers +Medium: Labels, descriptions +Small: Details, sources +Spacing: Generous whitespace between elements +``` + +### 5. Friendly, Neutral Tone + +| Aspect | Approach | +|--------|----------| +| Characters | Simple stick figures - emotion via posture | +| Language | Simple, accessible | +| Complexity | Reduced to essentials | +| Voiceover ready | Calm, narrative pacing | + +### 6. Low Visual Noise + +**Avoid**: +- Complex textures +- Shadows +- 3D effects +- Gradients +- Busy backgrounds + +**Use**: +- Flat colors +- High contrast +- Clean lines +- Focused composition + +### 7. Rhythm Over Realism + +| Gesture | When to Use | +|---------|-------------| +| Drawing | Introducing new elements | +| Erasing | Correcting or transitioning | +| Circling | Emphasizing key points (savings!) | +| Underlining | Highlighting important text | +| Arrows | Connecting concepts | +| Checkmarks | Completing steps (fast!) | +| X marks | Crossing out self-build costs | + +--- + +## Updated Scene Prompts (Whiteboard Style) + +### Scene 1: Same Decision, Different Path (Whiteboard) +``` +Create a whiteboard-style slide showing the same team meeting. + +SLIDE TITLE: "Meet DeFiSuperStars" (ONLY this slide has a title) + +Style: Hand-drawn sketch, marker on white background +ALL CHARACTERS ARE STICK FIGURES (circle head, line body, line limbs) +- Same 3-4 stick figures from Problem story (O head, | body, lines for limbs) +- Speech bubbles being written: + "Launching sDeFiSuperStars LBP pool!" +- Lightbulb icon drawn above one character +- Hook Bazaar logo sketched in (simple) + +Animation: Dialogue written as if by hand +Colors: Black lines, green for "Hook Bazaar" +Mood shifts from uncertain to hopeful + +NOTE: All other slides have NO title - only this first slide. +``` + +### Scene 2: Register Protocol (Whiteboard) +> This slide has the create_protocol demo video +### Scene 3: Browse Marketplace (Whiteboard) +> This slidee has the browse_hook demo video + +### Scene 4: Purchase & Deploy (Whiteboard) +``` +Create a whiteboard-style purchase comparison scene. + +Style: Split-screen sketch +LEFT SIDE (crossed out in red): +- Write "Self-Build" +- Draw: "$28,000" (large) +- Draw big X through it + +RIGHT SIDE (highlighted in green): +- Write "Hook Bazaar" +- Draw: "$499" (large, circled) +- Draw checkmark + +BOTTOM: +- Hand writes formula: "$499 << $28,000" +- Circles "98% SAVINGS" multiple times in green +- Time: "5 minutes total" + +Animation: Left drawn first, then X through it +Right side drawn with enthusiasm +Savings circled emphatically +``` + +### Scene 5: Instant Integration (Whiteboard) +``` +Create a whiteboard-style success scene. + +Style: Simple, celebratory sketch +- Draw pool rectangle labeled "sDeFiSuperStars Pool" +- Draw hook box inside (quickly!) +- Add big green checkmark +- Draw simple celebration marks (lines radiating out) +- Stats written quickly: + "$499 ✓" (green) + "5 min ✓" (blue) + "Pre-audited ✓" (green) + +Animation: Pool drawn, hook "pops" in fast +Checkmarks drawn with enthusiasm +Contrast with slow, painful Problem story +``` + +### Scene 6: Comparison Reveal (Whiteboard) +``` +Create a whiteboard-style side-by-side comparison. + +Style: Two columns drawn and compared + +LEFT COLUMN (red): +- Header: "Self-Build" (underlined) +- "$28,000" with sad face +- "6 weeks" with clock +- "5-15% risk" (underlined twice) +- Draw X through entire column + +RIGHT COLUMN (green): +- Header: "Hook Bazaar" (underlined, circled) +- "$499" with happy face +- "5 minutes" with checkmark +- "Pre-audited" with shield icon + +BOTTOM: +- Draw arrow from left to right +- Write: "SAVE $27,501" (large, circled) +- Write: "SAVE 6 WEEKS" (underlined) + +Animation: Left column first (grimace) +Then right column (relief) +Then dramatic savings reveal +``` + +### Scene 7: Call to Action (Whiteboard) +``` +Create a whiteboard-style closing CTA. + +Style: Clean, simple finish +- Draw Hook Bazaar logo (simple hook icon) +- Write taglines as if by hand: + "From $170k to $2k" + "From months to minutes" +- Draw two buttons (rectangles): + [Browse Hooks] + [Register] +- Write URL: hookbazaar.xyz (underlined) + +Animation: Logo drawn first +Taglines written smoothly +URL underlined at the end +``` + +--- + +## Contrast Points with Problem Story + +| Aspect | Problem Story | Solution Story | +|--------|---------------|----------------| +| Opening mood | Optimistic → Stressed | Curious → Relieved | +| Counter direction | Costs climbing | Costs minimal | +| Time feeling | Weeks dragging | Minutes flying | +| Ending | "Was it worth it?" | "This is the way" | +| Color progression | Green → Red | Neutral → Green | + +--- + +## Gamma Tips for This Story + +1. **Reuse assets** from Problem story (same stick figures, pool diagram) +2. **Embed Loom videos** directly in Gamma slides for demos +3. **Use "Compare" layout** for Scene 6 side-by-side +4. **Number animations** - Gamma highlights numbers well, use for cost reveals +5. **Link both presentations** - Problem → Solution as a sequence + +--- + +## Scene-to-Slide Transition Guide + +**CRITICAL**: Each scene = ONE slide. To enforce scene transitions as slide transitions in Gamma: + +### Structuring for Transitions + +| Scene | Slide # | Transition Type | Gamma Instruction | +|-------|---------|-----------------|-------------------| +| 1. Decision | 1 | Fade In | "Fade in from previous story or black" | +| 2. Register | 2 | Wipe Left | "Quick wipe - fast action" | +| 3. Browse | 3 | Push Up | "Push up - scrolling through options" | +| 4. Purchase | 4 | Morph | "Morph - selection to purchase" | +| 5. Integration | 5 | Zoom In | "Zoom into the deployed pool" | +| 6. Comparison | 6 | Split | "Split screen comparison reveal" | +| 7. CTA | 7 | Dissolve | "Dissolve to final CTA" | + +### Gamma Prompt for Transitions + +When prompting Gamma, explicitly state: +``` +Create a presentation with 7 SLIDES (one per scene). +Each slide should have a distinct transition to the next: + +Slide 1 → 2: Wipe left (quick action) +Slide 2 → 3: Push up (browsing feel) +Slide 3 → 4: Morph (selection process) +Slide 4 → 5: Zoom in (focus on success) +Slide 5 → 6: Split (comparison reveal) +Slide 6 → 7: Dissolve (to CTA) + +Do NOT combine scenes into single slides. +Each scene is a separate slide with its own transition. +Transitions should feel FAST and SMOOTH - contrast with slow Problem story. +``` + +### Manual Transition Setup in Gamma + +If Gamma doesn't auto-apply transitions: + +1. **Click on slide** in the left panel +2. **Click "Transition"** button (or find in slide settings) +3. **Select transition type** for each slide: + - **Fade**: For opening/closing slides + - **Wipe**: For quick actions (fast!) + - **Push**: For scrolling/browsing feel + - **Morph**: For element transformations + - **Zoom**: For focus moments + - **Split**: For comparisons + - **Dissolve**: For soft endings + +4. **Set duration**: 0.5-1 seconds (FASTER than Problem story!) +5. **Preview**: Watch full presentation to verify timing + +### Transition Timing per Scene + +| Scene | Content Duration | Transition Duration | Total | +|-------|------------------|---------------------|-------| +| 1 | 10s | 1.5s fade in | 11.5s | +| 2 | 10s | 1s wipe | 11s | +| 3 | 16s | 1s push | 17s | +| 4 | 16s | 1s morph | 17s | +| 5 | 10s | 1s zoom | 11s | +| 6 | 16s | 1.5s split | 17.5s | +| 7 | 8s | 1s dissolve | 9s | +| **Total** | **86s** | **8s** | **94s** | + +**NOTE**: Transitions are intentionally FASTER than Problem story to convey speed/efficiency. + +### Alternative: Gamma "Story Mode" + +For more control, use Gamma's Story Mode: +1. Create presentation in Story Mode (not deck mode) +2. Each "card" becomes a scene +3. Transitions are more fluid in Story Mode +4. Better for narrative/animation-heavy content +5. Can link to Problem story as a "chapter" + +--- + +## Combined Presentation Flow + +For maximum impact, present both stories together: + +``` +PROBLEM STORY (1:40) +├── Scene 1: Decision to build +├── Scene 2: Building ($10k) +├── Scene 3: Testing ($3k) +├── Scene 4: Audit ($15k) +├── Scene 5: Total reveal ($28k) +└── Scene 6: "Was it worth it?" + +[TRANSITION: "There's a better way..."] + +SOLUTION STORY (1:40) +├── Scene 1: Decision to use Hook Bazaar +├── Scene 2: Register (30 sec) +├── Scene 3: Browse hooks (2 min) +├── Scene 4: Purchase ($499) +├── Scene 5: Instant integration (5 min) +├── Scene 6: Comparison reveal +└── Scene 7: CTA + +TOTAL: ~3:30 +``` + +--- + +## Files Referenced + +- [Protocol_Cost_Function.md](../problem-description/Protocol_Cost_Function.md) - Cost data and formulas +- [user_story_protocol.md (Problem)](../problem-description/user_story_protocol.md) - Problem story spec +- [Hooks.md](../problem-description/Hooks.md) - Integration details