在Uniswap V4中建立Hook數據標準

Hooks 是 Uniswap v4 的決定性特徵，它們使開發者能夠自定義和擴展流動性池的行為。在本指南中，我們的目標是為 hook 開發者、hook 數據索引者和分析師建立一個標準，以便所有用戶，從開發者和 LP 到分析師，在使用 hook 數據時都可以使用相同的共享框架。

Hook 與 Uni v4

但首先，讓我們澄清 hook 如何融入 v4。可以將它們視為 PoolManager 合約的插件或外部 API。每個池只能鏈接到 一個 hook，但單個 hook 合約可以服務於 多個 池。一旦池使用 hook 初始化，該池就成為“hooked 池”（相對於“vanilla 池”），並且 hook 本身被認為是“已初始化”。相比之下，沒有池的 hook 合約只是一個未使用的 Solidity 合約，它實現了 核心 hook 函數 的一個子集。

請記住，Uniswap v4 是一個 單例：PoolManager 從一個地方管理 所有 v4 池及其狀態。下面的可視化展示了這些部分——池、hook 和 PoolManager——是如何關聯的。

Hook 標準

雖然 hook 可以包含任何 Solidity 代碼，但它們都錨定在 Uniswap v4 中的 10 個核心 hook 函數 上。這些函數對應於池生命週期中的關鍵點（例如，互換或流動性修改之前/之後），併為自定義提供清晰的“入口點”。有關參考，請參閱 Uni v4 核心庫中的 Hooks.sol 合約和 OpenZeppelin 製作的 BaseHook.sol 模板，該模板定義了所有 hook 入口點。

除了這些核心函數外，還有 4 個“delta-returning”標誌，使可能的“hook 標誌”總數達到 14。每個 hook 合約都通過其地址的最後 14 位來指示它實現了哪些 14 個標誌（請參閱我們 之前的 v4 數據指南 關於如何讀取這些位的文章）。這允許開發者和索引者快速確定 hook 的屬性。如果你不熟悉 return deltas，請參閱 v4 文檔中的 自定義會計、解鎖回調和 Deltas 和 BeforeSwapDelta。

雖然 hook 可以做的不僅僅是標準的 10 個核心函數，但這些函數創建了一個一致的基礎：

• 開發者可以依靠已知的“入口點”來自定義池行為。
• 索引器可以可靠地解析來自不同 hook 的相同核心 hook 調用的跟蹤數據。

在許多情況下，hook 只會修改或擴展正常的 v4 PoolManager 流程，從而繼承 Uniswap v4 核心合約中的常用事件。但是，某些 hook 可能會繞過或替換某些邏輯，從而導致跳過默認的 v4 事件或使其不準確。為了填補這一空白——並確保交易量、TVL 和費用的準確指標——我們提出了一組 hook 特定的事件。通過在正確的時間發出它們，hook 保持可發現性，分析保持可靠，並且 LP 獲得完整的風險回報圖。

我們正在與 OpenZeppelin 合作，將這些標準納入 Uniswap Hooks 庫，並與 Atrium Academy 合作，以便在開發者培訓中採用它們。與任何主要標準（例如，ERC20、EIP1559）一樣，廣泛的社區支持是成功的關鍵。

標準 Hook 事件

我們強烈建議你發出這些事件，以便開發者、LP、分析師和用戶都可以共享一個統一的hook數據解釋框架。 通過遵循此標準，你還可以訪問我們正在開發的開源存儲庫，從而可以輕鬆檢索 hook 的指標，將其集成到前端顯示中，並將其用於內部分析——確保你的 hook 在更廣泛的生態系統中保持可見且有價值。

event HookSwap(bytes32 indexed id,       // v4 池 IDaddress indexed sender,   // 互換的路由器int128 amount0,int128 amount1,uint128 hookLPfeeAmount0,uint128 hookLPfeeAmount1);event HookFee(bytes32 indexed id,       // v4 池 IDaddress indexed sender,   // 互換的路由器uint128 feeAmount0,uint128 feeAmount1);event HookModifyLiquidity(bytes32 indexed id,       // v4 池 IDaddress indexed sender,   // 路由器地址int128 amount0,int128 amount1);event HookBonus(bytes32 indexed id,       // v4 池 IDuint128 amount0,uint128 amount1);

你不需要發出 全部 四個事件——只需發出與你的 hook 行為相關的事件即可。

用例流程圖

以下圖表說明了在 hook 的生命週期中 何時 發出每個事件。請記住，這些場景可以 重疊。你的 hook 可能同時位於“自定義曲線”和“hook 費用”中，因此你需要為 兩種 流程發出事件。

自定義曲線

在 v4 中，開發者可以通過使用 自定義會計 來繞過內置的 v3 集中流動性，從而允許他們實現自己的互換曲線。這實現了自定義流動性供應和互換邏輯。自定義曲線 通過 Hooks.BEFORE_SWAP_FLAG 和 Hooks.BEFORE_SWAP_RETURNS_DELTA_FLAG 啟用。此類曲線的示例包括：

• 常數和曲線
• StableSwap
• LAMMbert
• 非對稱曲線
• 動態曲線
• 階梯式曲線

由於這些自定義曲線繞過了內置的 ModifyLiquidity 事件的發出，併產生了不正確的 Swap 事件信息，因此我們強烈建議在 hook 合約中發出 HookSwap 和 HookModifyLiquidity 事件。

異步互換

異步互換 將互換執行推遲到稍後的時間，從而允許 hook 控制互換的順序並保護互換者免受 MEV 三明治攻擊。此外，異步互換還可以用自定義曲線替換 v4 互換邏輯，從而有效地繞過類似 v3 的互換實現。

異步互換 使用 Hooks.BEFORE_SWAP_FLAG 和 Hooks.BEFORE_SWAP_RETURNS_DELTA_FLAG 啟用。由於基於批處理的執行模型，我們建議在批處理完成時而不是針對每個單獨的互換髮出 HookSwap 事件。

你可以在 此處 找到 OpenZeppelin 開發的異步互換模板。

Hook 費用

Hook 可以選擇對互換或流動性修改收取費用，無論是作為固定金額還是動態計算。如果 hook 為互換者提供有價值的服務，它可能會選擇在互換期間收取費用。同樣，hook 可以對流動性修改徵收費用。例如，hook 可能會通過對在特定時間範圍內移除流動性收取高額費用來懲罰即時 (JIT) 流動性。有關實施靜態 hook 費用的示例，請查看此內容。

Hook 獎勵

Hook 獎勵與 hook 費用相反——hook 不是向互換者收費，而是向用戶返利，以激勵通過實施這些獎勵機制的池進行互換。Hook 可以使用 return-delta-flags 來實現此目的，即 BEFORE_SWAP_RETURNS_DELTA_FLAG 和/或 AFTER_SWAP_RETURNS_DELTA_FLAG。

對於數據索引器

現在我們已經介紹了開發者將如何集成 hook 標準，讓我們討論如何有效地索引 hook 數據。

1. 識別已初始化的 Hook
1. 監控池創建期間來自 v4 PoolManager 的 Initialize 事件。
2. 此事件指示池是 hook 池（你將看到有效的 hook 地址）還是 vanilla 池（地址為 null 地址）。
3. 通過跟蹤這些地址，你可以編譯一個完整的數據索引初始化 hook 列表。
4. 索引 Hook 活動
1. 所有已初始化的 hook 都實現了 10 個核心 hook 函數，並且應該發出我們介紹的標準 hook 事件。
5. 通過監控這些函數和事件的日誌和跟蹤數據（請參閱附錄中的 ABI），你可以以一致、標準化的方式捕獲每個 hook 的活動。

Hook 指標

恭喜你走到這一步——我們幾乎到達終點線了！

現在我們已經探討了 hook 與 Uniswap v4 的關係，以及 hook 標準和各種用例流程，現在是時候處理指標了。建立一個共享術語確保了當我們討論與 hook 相關的指標和 v4 指標時，我們都對內容有一個清晰、一致的理解。

我們將專注於兩個關鍵指標類別——TVL 和交易量。下面，我們將定義這些指標並提供有關其計算的建議。

TVL（總鎖定價值）

總體 TVL

Uniswap v4 中的總體 TVL 是鎖定在協議中的所有流動性的總價值（通常以美元計）。這包括保存在單例 v4 Pool Manager 合約中的流動性，以及保存在外部已初始化 hook 合約中的任何流動性。hook 合約一旦在至少一個 Uniswap v4 池中註冊，就被認為是“已初始化”。

單例 TVL

單例 TVL 是指僅保存在 Uniswap v4 的核心（單例）Pool Manager 合約中的總流動性部分。即使池使用外部 hook 初始化，單例 TVL 也僅計算鎖定在核心合約本身中的資產，不包括 hook 合約持有的任何外部流動性。

外部 TVL

外部 TVL 是指保存在 Uniswap v4 核心 Pool Manager 合約之外的總流動性，特別是保存在已初始化的 hook 合約中。hook 合約一旦在至少一個 Uniswap v4 池中註冊，就被認為是“已初始化”。

Hook TVL

Hook TVL 是指使用 hook 的池中的總流動性。它包括 常規 hook 池（流動性保留在 Uniswap v4 Pool Manager 合約中）和 特殊 hook 池（例如，自定義曲線）（流動性駐留在外部 hook 合約中）。

關於高級 Hook 場景的說明

Hook可能會引入更復雜的流動性流，從而超出上述簡單的“鎖定”模型。例如，重新抵押hook可能會將流動性部署到外部借貸協議中，在那裡可以賺取收益，而不是停留在v4 Pool Manager合約中。同樣，即時 (JIT) 流動性hook可能會僅在互換需要時才從其他地方提取流動性。這些場景意味著v4中的“TVL”（單例和外部）可能與用於互換或在任何給定時刻駐留在協議中的實際資本不同。

我們正在與更廣泛的 Uniswap 社區和 hook 開發者積極合作，以改進我們針對這些高級用例的 TVL 定義和測量方法。我們將在最終確定這些修訂後的 TVL 標準後立即分享更新。

計算

可以通過兩種方式確定 TVL：

1. 跟蹤流動性修改事件 – 監視包括互換在內的流動性變化，以得出總流動性淨值。
2. 跟蹤代幣流 – 衡量相關合約中的流入和流出。

由於 v4 的單例架構，在 池級別，TVL 不再能僅從代幣流中得出。但是，對於更廣泛的總體 TVL 計算，跟蹤代幣流通常比監視流動性修改事件更有效。

成交量

交易量表示 Uniswap v4 上的總交易活動（通常以美元計），按每筆交易衡量。例如，將 2,673.83 USDC 兌換為 1 ETH（使用 2 月 13 日下午 5:23 的 ETH 價格）計為 2,673.83 美元的交易量，而不是交易中兩種資產的總額的兩倍。

總交易量（在一段時間內）

總交易量（在一段時間內）是給定時間範圍內所有 Uniswap v4 池中的累計交易量，包括 vanilla 池和 hook 池。

Hook 交易量（在一段時間內）

Hook 交易量（在一段時間內）是指給定時間範圍內 hook 池 中的總交易量。這包括由使用其自己的自定義邏輯和/或流動性的返回 delta hook（例如，自定義曲線或異步互換）促成的互換金額。

Vanilla 交易量（在一段時間內）

Vanilla 交易量（在一段時間內）是指 vanilla 池 中的總交易量，即未使用任何 hook 初始化的池。

計算

為了準確衡量 Uniswap v4 中的交易量，有兩種主要方法：

1. 基於事件的跟蹤 – 你可以跟蹤發出的事件，但要獲得完整的畫面，你必須同時監視：

• 來自 v4 核心合約的互換事件。
• 來自 delta-returning hook 合約的 HookSwap 事件（例如，自定義曲線）。僅依賴互換事件將錯過由 delta-returning hook 促成的交易量。

你已經可以從 Dune 和 Allium 上的 dex.trades 查詢整體交易量，它們使用跟蹤數據索引。我們還在與 Uniswap Labs 合作將此應用於 v4 開源子圖。

結束語

我們希望本指南有助於闡明 Uniswap v4 hook 數據的格局，從標準和事件到索引和分析。在我們結束時，以下是我們主要的行為號召：

• Hook 開發者： 採用四個標準事件並在建議的點發出它們。這有助於生態系統中的每個人輕鬆理解和集成你的 hook 的行為。通過堅持此標準，你還可以使用我們即將推出的開源存儲庫，使你能夠無縫檢索你的 hook 的指標，在前端界面上展示它們並在內部進行分析——使你的 hook 在更廣泛的生態系統中保持最前沿並節省你的團隊大量工時。
• 索引器和分析師： 更新你的管道以檢測初始化時的 hook 並解析標準 hook 事件。這確保了 v4 中互換、費用和流動性變化的全面覆蓋。

通過像 ERC20 或 EIP1559 標準出現的方式一樣共同努力，我們可以為 Uniswap v4 hook 塑造一個一致、可發現和透明的未來！

• 原文鏈接： https://uniswapfoundation.mirror.xyz/KGKMZ2Gbc_I8IqySVUMrEenZxPnVnH9-Qe4BlN1qn0g
• 登鏈社區 AI 助手，為大家轉譯優秀英文文章，如有翻譯不通的地方，還請包涵～