dark

OpenSea 新協議Seaport 源碼解析

2022-07-05

一、Seaport 簡介

近期，NFT 市場OpenSea 宣布推出全新Web3 市場協議Seaport 協議，用於安全高效地買賣NFT。本文將深度分析其關鍵業務實現和接口實現。 SeaPort官方文檔https://docs.opensea.io/v2.0/reference/seaport-overview ， 可配合查閱，進一步加深理解。

Uniswap 用開源去中心化交易改變了加密貨幣交易的遊戲規則，這是我們現在所知的2020 年DeFi Summer的開始，也帶來了DEX 和DeFi 的大規模增長和創新。 OpenSea的新協議Seaport或許也有改變NFT交易遊戲規則的潛力，這也是我們分析Seaport協議的原因。

Seaport 是一個市場合約，用於安全有效地創建和執行ERC721 和ERC1155 代幣的訂單。每個訂單包含任意數量的供應商願意提供的物品（“報價(offer)”）以及任意數量的必須連同其各自的接收者一起接收的物品（“對價(consideration)”）。 Seaport 協議的6 大關鍵點，以及它對NFT 領域的意義：
（1）開源代碼：
有了Seaport 協議，任何人都可以使用該協議構建一個NFT 市場，因為它是去中心化和開源的。在未來幾年，我們應該會看到更多的NFT 市場建立起來。更多的競爭=更好+更快的創新
（2）去中心化：
OpenSea 說這個協議沒有合約所有者，任何人都可以更新或生成代碼。
（3）交易新範式：
與一些平台只能用加密貨幣換取NFT 不同，Seaport 協議允許用戶以一系列新方式獲取NFT，投標人（或報價者）可以捆綁不同的資產（如提供ETH/ERC20/ERC721/ERC1155 資產）以換取NFT。
（4）交易特定的NFT：
當交易NFT 時，你也可以設置NFT 必須具備的特定“條件”。
（5）荷蘭式拍賣列表：
在Seaport 協議中，你可以設置一個開始和結束價格，表明你希望拍賣持續多長時間。該列表將降低（或提高）價格，直到找到買家（或拍賣時間到）。
（6）更高的安全性：
OpenSea 正在進行為期兩週的協議審計競賽，獎金總額為100 萬美元。任何開發人員都可以審核代碼，提交他們發現的評審和錯誤，並獲得獎勵。

二、關鍵業務實現

1、NFT訂單

每一個訂單都包含11個關鍵組件：

  • offerer 訂單的報價者提供了所有的供應代幣並且必須親自執行訂單（即msg.sender == offerer ）或者通過簽名（標準的65字節ECDSA，64字節EIP-2098 或EIP-1291 isValidSignature 檢查）或列舉鏈上訂單（即調用validate）來批准訂單。

  • zone 訂單的區域是附加到訂單的可選輔助帳戶，具有兩個額外的權限：

    • 該區域可以通過調用cancel來取消命名為該區域的訂單。 （注意，報價者仍可以取消他們自己的訂單，可以單獨取消，也可以通過調用incrementNonce 立刻取消由其當前nonce 簽名的所有訂單）。

    • “受限”訂單（有訂單類型聲明）必須由區域或報價者執行，或者必須通過調用區域上的isValidOrder 或isvalidOrderIncludingExtraData 視圖函數來獲得批准。

  • offer 報價包含可以從報價者帳戶轉移的一系列代幣，其中每個代幣由以下組件組成：

    • itemType 指定代幣類型，有效類型包括Ether（或者其他指定鏈的原生代幣）、ERC20、ERC721、ERC1155、ERC721、有“條件(criteria)”的ERC721 以及有“條件(criteria)”的ERC1155。

    • token 指定代幣合約的賬戶地址（空地址用於以太幣或其他原生代幣）。

    • identifierOrCriteria 表示ERC721 或ERC1155 代幣標識符，或者在基於條件的代幣類型的情況下，表示由代幣的有效代幣標識符集合組成的merkle 根。對於Ether 和ERC20 類型，該值會被忽略，並且對於基於條件的代幣類型，可以將值設置為0 以允許任何標識符。

    • startAmount 表示如果在訂單激活時完成訂單所需要的相關代幣的數量。

    • endAmount 表示如果在訂單到期時執行訂單所需要的相關代幣的數量。如果此值與startAmount 不同，則根據訂單激活後經歷的時間線性計算出實際的數量。

  • consideration 包含為完成訂單而必須接收的代幣數組。它包含所有與所提供代幣相同的組件，並且還包括一個用於接收每個代幣的recipient 組件。該數組可以由執行者在訂單執行時進行擴展，以支持“小費”（例如中繼費或推薦費）。

  • orderType 訂單類型，根據兩個不同的偏好，指定訂單的四種類型之一，：

    • FULL 表示不支持部分填充，而PARTIAL 允許填充訂單中的一部分，注意每個代幣必須被提供的分數完全整除（即除法後沒有餘數）。

    • OPEN 表示任意賬戶都可以提交執行訂單的調用，而RESTRICTED 則需要訂單必須由報價者或訂單所在區域執行，或者在區域上調用isValidOrder 或isValidOrderIncludingExtraData 視圖函數時返回表示訂單被批准的神奇的值。

  • startTime 表示訂單激活時的區塊鏈時間。

  • endTime 表示訂單到期的區塊鏈時間。該值與startTime 與每個代幣的startAmount 和endAmount 一起使用以得出它們的當前數量。

  • zoneHash 表示一個任意的32 字節值，當執行受限訂單時，該值將提供給區域，該區域在確定是否是授權訂單時可以使用該值。

  • salt 表示訂單的任意熵源。

  • conduitKey 是一個bytes32 類型的值，表示在執行轉移時應將哪個渠道(conduit)（如果有）用作代幣批准的來源。默認情況下（即當conduitKey 設置為零哈希時），報價方將直接向Seaport 授予ERC20、ERC721 和ERC1155 代幣批准，以便它可以在執行期間執行訂單指定的任何轉移。相反，選擇使用渠道的報價者將授予與提供的渠道密鑰相對應的渠道合約的代幣批准，然後Seaport 指示該渠道轉移相應的代幣。

  • nonce 表示必須與給定報價者的當前隨機數匹配的值。

2、訂單執行

訂單通過以下4種方式中的一種來執行：

  • 調用兩個“標準”函數fulfillOrder 和fulfillAdvancedOrder 中的一個，並且構造第二個隱含訂單，同時其調用者作為報價者(offerer)，已執行訂單的對價(consideration)作為報價(offer)，已執行訂單的報價作為對價（使用“高級”訂單包含應與一組“條件解析器”一起填寫的部分，這些“條件解析器”為已執行訂單上的每個基於條件的代幣指定一個標識符和相應的包含證明）。所有報價代幣將從訂單報價者轉移到執行者，然後所有對價代幣將從執行者轉移到指定的接收者。

  • 調用”基本”函數fulfillBasicOrder，並提供六種基本路線類型（ETH_TO_ERC721、ETH_TO_ERC1155、ERC20_TO_ERC721、ERC20_TO_ERC1155、ERC721_TO_ERC20 以及ERC1155_TO_ERC20）中的一種，將從組件子集派生要執行的訂單，假設相關訂單符合以下條件：

    • 該訂單僅包含一個報價代幣，並且包含至少一個對價(consideration)代幣。

    • 該訂單僅包含一個ERC721 或ERC1155 代幣，並且該代幣不是基於條件的。

    • 訂單的報價者是第一個對價代幣的接收者。

    • 所有其他代幣都具有相同的以太幣（或其他原生代幣）或ERC20 項目類型和代幣。

    • 該訂單不提供以以太幣（或其他原生代幣）作為其項目類型的項目。

    • 每個項目上的startAmount 必須與該項目的endAmount 匹配（即項目不能有升序/降序數量）。

    • 所有“忽略”的項目字段（即token 和原生代幣項目中的identifierOrCriteria 以及ERC20 項目中的identifierOrCriteria）都設置為空地址或零。

    • 如果訂單中有ERC721 項目，則該項目的數量為.1

    • 如果訂單有多個對價(consideration)項目，且除了第一個對價項目以外的所有對價項目與報價項目的項目類型相同，報價項目數量不小於除了第一個對價項目數量外的所有對價項目數量之和。

  • 調用兩個“可用執行”函數（fulfillAvailableOrders 和fulfillAvailableAdvancedOrders）中的一個，並且提供一組訂單與一組執行聲明，其中的執行聲明指定哪些報價項目可以聚合到不同的轉移中，相應地哪些對價項目可以聚合在一起，以及其中已經取消的訂單是因為時間無效，或者已經完全成交的訂單將被跳過，而不會導致其餘可用訂單回滾。此外，一旦鎖定maximumFulfilled 可用訂單，剩餘的所有訂單都將被跳過。與標準執行函數類似，所有報價項目將從各自的報價者轉移到執行者，然後所有對價項目將從執行者轉移到指定的接收者。

  • 調用兩個“匹配”函數（matchOrders 和matchAdvancedOrders）中的一個，並且提供一組明確的訂單以及一組執行，該執行指定了哪些報價項目應用於哪些對價項目（並且“高級”案例以類似的方式運行標準方法，但支持通過提供的分子numerator 和分母denominator 小數值以及可選的extraData 參數進行部分填充，當執行受限訂單類型時，這些參數將作為調用區域上的isValidOrderIncludingExtraData 視圖函數的一部分提供）。請注意，以這種方式執行的訂單沒有明確的執行者； 相反，Seaport 將簡單地確保每個訂單的需求一致。

雖然標準方法在技術上可用於執行任何訂單，但在某些情況下存在關鍵的效率限制：

  • 與簡單的“熱路徑(hot path)”的基本方法相比，它需要額外的調用數據。

  • 它要求執行者批准每個對價項目，即使對價項目可以使用報價項目來執行（在執行為ERC721 或ERC1155 項目提供ERC20 項目並且還包括具有相同的考慮對價的訂單時通常是這種情況用於支付費用的ERC20 項目類型）。

  • 它可能導致不必要的轉移，而在“匹配”情況下，這些轉移可以減少到更小的集合。

3、檢查餘額和批准交易

創建報價時，應檢查以下要求以確保訂單可以執行：

  • 報價者應在所有報價項目中有足夠的餘額。

  • 如果訂單未指明使用渠道，則報價者應為所有提供的ERC20、ERC721 和ERC1155 項目的Seaport 合約設置足夠的批准。

  • 如果訂單確實指明了使用渠道，則報價者應為所有提供的ERC20、ERC721 和ERC1155 項目的相應渠道合約設置足夠的批准。

執行基本訂單時，需要檢查以下要求以確保訂單可以執行：

  • 需要執行上述檢查以確保報價者仍有足夠的餘額和批准。

  • 執行者應該對所有對價項目有足夠的餘額，除了那些項目類型與訂單提供的項目類型相匹配的項目——例如，如果執行的訂單提供ERC20 項目，並且要求向報價者提供ERC721 項目並且向另一個接受者提供相同的ERC20 項目，那麼執行者需要擁有ERC721 項目，但不需要擁有ERC20 項目，因為它將來自報價者。

  • 如果執行者不選擇使用渠道，他們需要為已執行訂單上所有的ERC20、ERC721 和ERC1155 對價項目設置足夠的Seaport 合約批准，項目類型與訂單提供的項目類型匹配的ERC20 項目除外。

  • 如果執行者確實選擇使用渠道，則他們需要為已執行訂單上的所有ERC20、ERC721 和ERC1155 對價項目為其各自的渠道設置足夠的批准，項目類型與訂單提供的項目類型匹配的ERC20 項目除外.

  • 如果已執行的訂單將以太幣（或其他原生代幣）指定為對價項目，則執行者必須能夠將這些項目的總金額提供為msg.value

執行標準訂單時，需要檢查以下要求以確保訂單可以執行：

  • 需要執行上述檢查以確保報價者有足夠的餘額和批准。

  • 在收到所有的報價項目後，執行者應該對所有的報價項目有足夠的餘額——例如，如果執行的訂單提供了ERC20 項目，並且需要向報價者提供ERC721 項目，並且向另一個接收者提供相同的ERC20 項目，其數量小於或等於提供的數量，執行者不需要擁有ERC20 項目，因為它將最先從報價者處接收到。

  • 如果執行者不選擇使用渠道，他們需要為已執行訂單上的所有ERC20、ERC721 和ERC1155 對價項目的Seaport 合約設置足夠的批准。

  • 如果執行者確實選擇使用渠道，則他們需要為已執行訂單上的所有ERC20、ERC721 和ERC1155 對價項目其各自的渠道設置足夠的批准。

  • 如果已執行的訂單將以太幣（或其他原生代幣）指定為對價項目，則執行者必須能夠將這些項目的總數量提供為msg.value

在執行一組匹配訂單時，需要檢查以下要求以確保訂單可以執行：

  • 作為執行的一部分執行，執行採購ERC20、ERC721 或ERC1155 項目的每個帳戶必須在觸發執行時在Seaport 或指定的渠道上具有足夠的餘額和批准。請注意，先前的執行可能會為後續執行提供必要的餘衡。

  • 涉及以太幣（或其他原生代幣）的所有執行的總和必須以msg.value 的形式提供. 請注意，提供者和接收者是同一帳戶的執行將從最終執行集中被過濾掉。

部分成交

在構建訂單時，報價者可以選擇通過設置適當的訂單類型來啟用部分成交。然後，支持部分執行的訂單可以在相應訂單的某一部分中執行，從而允許後續執行繞過簽名驗證。總結一下部分填充的幾個關鍵點：

  • 當創建支持部分成交的訂單或確定這些訂單要成交的部分時，訂單上的所有項目（報價和對價）數量必須能被提供的部分項目數量完全整除（即除法後沒有餘數）。

  • 如果要填寫的所需部分會導致要填寫的訂單數量超過全部訂單金額，則該部分將減少為剩餘要填寫的數量。這適用於部分填充嘗試和完全填充嘗試。如果不需要這種行為（即填充應該是“全部或無”），則執行者可以使用“基本”訂單方法（如果可用）（這需要填寫全部訂單數量），或使用“匹配” 訂單方法，並明確提供一個要求收到全部所需金額的訂單。

    • 舉例來說：如果一個執行者嘗試執行訂單的1/2，但另一個執行者首先執行訂單的3/4，則原始執行者最終將執行訂單的1/4。

  • 如果部分可成交訂單上的任一項目指定了不同的startAmount 和endAmount（例如，它們是遞增數量或遞減數量的項目），則在確定當前價格之前，該分數將應用於這兩個數量。這確保了在構建訂單時可以選擇完全可分的金額，而不依賴於最終完成訂單的時間。

  • 部分成交可以與基於條件的項目進行組合，以支持構建提供或接收多個項目的訂單，否則這些項目將無法部分成交（例如ERC721 項目）。

    • 舉個例子：報價者可以創建一個部分可成交的訂單，為給定集合中最多10 個ERC721 項目提供最多10 個ETH；然後，任何執行者都可以執行該訂單的一部分，直到它被完全執行（或取消）。

5、業務關鍵步驟

5.1 執行訂單

當通過fulfillOrder 或fulfillAdvancedOrder 來執行訂單時：

  1. 計算訂單哈希值

  • 計算報價項目和對價項目的哈希值

  • 檢索報價者的當前計數器

  • 計算訂單哈希值

  • 執行初始化校驗

    • 確保當前時間在訂單有效時間內

    • 確保調用者對於當前訂單類型是有效的； 如果訂單類型收到限制且調用者不是offerer 或者zone，調用zone 判斷訂單是否有效

  • 檢索並更新訂單狀態

    • 確保訂單未被取消

    • 確保訂單沒有被全部執行

      • 如果訂單是部分執行的，如有必要，減少提供的執行數量，以免訂單被過度執行

    • 若訂單簽名尚未驗證，則驗證訂單簽名

    • 根據偏好+ 可用金額(preference + available amount) 確定要執行的分數

    • 更新訂單狀態（已驗證+執行分數）

  • 確定每個項目的金額

    • 比較初始金額startAmount 和結束金額endAmount

      • 若相等，將執行分數應用於該金額，確保結果是整數，然後使用該結果

      • 若不等，對這兩個金額都應用執行分數，確保兩個結果都是整數，然後根據當前時間找到這兩個結果的現行擬合值

  • 應用條件解析器

    • 確保每一個條件解析器都應用於一個基於條件的訂單項目

    • 如果項目具有一個非零的條件根值(a non-zero criteria root)，確保為每個項目提供的標識符是有效的

    • 更新每個項目的類型和標識符

    • 確保所有剩餘的項目都不是基於條件的項目

  • 觸發OrderFulfilled 事件

    • 包括更新的項目（即在金額調整和條件解決之後）

  • 將報價項目（代幣）由報價者轉移到調用者

    • 使用渠道或Seaport 直接獲得批准，具體取決於訂單的類型

  • 將對價項目（代幣）有調用者轉移到對應的接受者

    • 使用渠道或Seaport 直接獲得批准，具體取決於執行者聲明的偏好

    5.2 匹配訂單

    當通過matchOrders 或者matchAdvancedOrders 來匹配一組訂單時，步驟1 到6 幾乎完全相同，但針對每個提供的訂單執行。從這裡開始，執行與上面的標準執行不同：

  1. 應用執行

  • 確保每次執行都涉及一個或多個報價項目和一個或多個對價項目，所有這些項目都具有相同的類型和代幣，並且每個報價項目具有相同的批准源以及每個對價項目具有相同接受者

  • 將每個報價項目和對價項目的金額減少到零，並跟踪其總減少金額

  • 比較每個項目的總金額，並將剩餘金額加回相應訂單一側（報價項目或對價項目）的第一個項目

  • 為每個成交返回一個執行

  • 掃描每個對價項目並確保沒有一個對價項目仍然有非零的剩餘金額

  • 作為每次執行的一部分進行轉賬

    • 根據原始訂單類型，直接使用渠道或Seaport 獲得批准

    • 忽略to == from 或amount == 0 時的每次執行（注意：當前實現不執行最後一次優化）

    三、關鍵接口

    Seaport 是一個通用的ETH/ERC20/ERC721/ERC1155 市場。它最大限度地減少了外部調用，並為普通路由提供了輕量級的方法，以及更靈活的方法來組合高級訂單。

    ConsiderationInterface 包含Seaport 的所有外部函數接口。

    fulfillBasicOrder

    執行基本訂單，僅支持Ether（或指定鏈的原生代幣）與ERC721 之間的交易。

    實現邏輯

    1. 提取訂單類型和基本訂單路由，並且對其進行校驗

    2. 準備執行基本訂單
      （1）添加重入鎖
      （2）校驗時間正確
      （3）檢驗參數正確
      （4）計算併校驗訂單的哈希值
      （5）更新訂單狀態

    3. 若使用了渠道，則根據訂單路由導出渠道

    4. 根據訂單路由，執行原生代幣以及ERC721代幣的轉賬，完成訂單

    5. 刪除重入鎖

    fulfillOrder & fulfillAdvancedOrder

    • fulfillOrder 執行普通訂單，不支持訂單部分執行，不支持條件解析器；普通訂單作為特殊的高級訂單進行執行。

    • fulfillAdvancedOrder 執行高級訂單。

    實現邏輯

    1. 添加重入鎖

    2. _validateOrderAndUpdateStatus：根據參數，驗證訂單，更新狀態併計算訂單哈希值orderHash 、需要執行訂單的分子numerator 和分母denominator
      （1）時間校驗：startTime <= block.time <= endTime
      （2）分子與分母校驗：

    • numerator <= denominator && denominator != 0;

    • 若numerator == denominator ，需要支持部分執行(Support Partial Fills)

    （3）對價項目長度校驗以及計算訂單哈希值orderHash :

      • 訂單長度校驗：orderParameters.consideration.length >= orderParameters.totalOriginalConsiderationItems，即參數中consideration 數組實際長度要大於或等於參數中直接傳遞的原始對價項目總數

      • 計算訂單哈希值orderHash

    （4）校驗高級訂單的有效性：訂單類型為2 或3 要求zone 或offerer 是caller 或者zone 批准。
    （5）校驗訂單狀態orderStauts = _orderStatus[orderHash]，保證訂單沒有被取消並且是可執行的

      • 訂單未取消，即：保證orderStauts.isCancelled == false

      • 訂單可執行，即：若orderStatus.numerator != 0，保證orderStatus.numerator < orderStatus.denominator。

    （6）校驗訂單簽名，即若orderStatus.isValidated == false，則調用_verifySignature 函數
    （7）計算需要執行訂單的分子fillNumerator 和分母fillDenominator
    （8）更新狀態變量orderStatus

    1. _applyCriteriaResolvers：用條件解析器，對每個生成的訂單類型以及條件解析器的綁定進行校驗，確保提交的待執行訂單是有效的

    2. _applyFractionsAndTransferEach：以指定的分數值執行每個項目的轉賬

    3. _emitOrderFulfilledEvent：發出一個表明訂單已完成的事件。

    4. 刪除重入鎖

    fulfillAvailableOrders & fulfillAvailableAdvancedOrders

    • fulfillAvailableOrders 執行可用普通訂單，不支持訂單部分執行，不支持條件解析器；可用普通訂單作為特殊的可用高級訂單進行執行

    • fulfillAvailableAdvancedOrders 執行可用的高級訂單

    實現邏輯

    1. _validateOrdersAndPrepareToFulfill：校驗訂單（若有無效訂單則跳過）、更新其狀態、通過先前填充的分數減少金額、應用條件解析器並觸發OrderFulfilled 事件。
      （1）添加重入鎖
      （2）聲明並設置一個錯誤緩衝區變量，指明任何本地報價項目的狀態。
      （3）循環遍歷每一個訂單，校驗訂單，更新每一個訂單中的參數：

    • _validateOrderAndUpdateStatus：根據參數，驗證訂單，更新狀態併計算訂單哈希值orderHash 、需要執行訂單的分子numerator 和分母denominator

    • 循環遍歷訂單中的每一個報價項目，更新報價項目中的startAmount 和endAmount

    • 循環遍歷訂單中的每一個對價項目，更新對價項目中的startAmount 和endAmount

    （4）校驗錯誤緩衝區變量
    （5）_applyCriteriaResolvers：應用條件解析器，對每個生成的訂單類型以及條件解析器的綁定進行校驗，確保提交的待執行訂單是有效的聚合已使用的報價和對價項目並執行轉賬
    （6）觸發OrderFulfilled 事件

    1. _executeAvailableFulfillments：完全或部分執行通過了校驗的訂單，每個訂單具有任意數量的要約和考慮項目，並執行轉移。任何當前未激活、已完全成交或已取消的訂單都將被忽略。然後，剩餘的報價和考慮項目將在可能的情況下聚合，如所提供的報價和考慮組件數組所示，並且聚合的項目將分別轉移到履行者或每個預期的接收者。請注意，失敗的項目轉移或訂單格式問題將導致整個批次失敗。
      （1）為每一個訂單的報價和對價項目的執行分配一個Execution 結構，構造為一個Execution 結構數組executions ，任何當前未激活、已完全成交或已取消的無效訂單都將被忽略。
      （2）校驗executions 的長度
      （3）對executions 中的每一個Execution 結構對象進行校驗，過濾掉當前未激活、已完全成交或已取消的所有訂單。
      （4）_performFinalChecksAndExecuteOrders：對高級訂單以及executions 進行最後的校驗，然後執行訂單，完成執行轉賬，刪除重入鎖。

    matchOrders & matchAdvancedOrders

    • matchOrders ：對普通訂單中的報價和對價項目按參數fulfillments 提供的報價組件分配給對價組件的條件求進行匹配然後執行，不支持訂單部分執行，不支持條件解析器；普通訂單作為特殊的高級訂單進行處理

    • matchAdvancedOrders：對高級訂單中的報價和對價項目按參數fulfillments 提供的報價組件分配給對價組件的要求進行匹配然後執行

    實現邏輯

    1. _validateOrdersAndPrepareToFulfill：校驗訂單（若有無效訂單則回滾）、更新其狀態、通過先前填充的分數減少金額、應用條件解析器並觸發OrderFulfilled 事件。若有無效訂單，則回滾。

    2. _fulfillAdvancedOrders：在驗證、調整金額和應用條件解析器之後，執行高級訂單
      （1）為每一個訂單的報價和對價項目的執行分配一個Execution 結構，構造為一個Execution 結構數組executions
      （2）循環遍歷參數fulfillments ，將executions 中的每一個元素對應到fulfillments 的每一個元素，若報價人者（offerer）和接受者（recipient）是相同的，則跳過。
      （3）_performFinalChecksAndExecuteOrders：對高級訂單以及executions 進行最後的校驗，然後執行訂單，完成執行轉賬，刪除重入鎖。

    Total
    0
    Shares
    Share 0
    Tweet 0
    Share 0
    Related Posts