智慧合約
本頁介紹 Protocol v1.1.0 中主要的資金池和代金券合約。合約行為提供結算機制，但不能取代特定用途所適用的發行方披露、資金池規則或其他交易條款。
請透過 概念和術語 區分受治理的承諾資金池與 SwapPool，並區分交換結算與兌付出示、履約和核銷。
代金券（GiftableToken）
GiftableToken 是一種 ERC20 代幣，包含發行方可用於代金券的機制：
- 授權鑄造——所有者可以指定寫入方，由其透過
mintTo發行代幣。 - 可選到期時間——到期時間為
0表示合約層面永不過期。否則，在配置的時間戳到達或超過後，轉移、鑄造和銷燬都會回滾。任何人都可以直接呼叫expired，永久記錄最終的applyExpiry狀態。 - 供應量記賬——
totalMinted和totalBurned顯示累計供應活動。僅所有者可呼叫的burn函式會銷燬所有者地址持有的代幣。
代幣合約 不會 說明發行方提供哪些商品或服務、設定兌付價值、證明發行方能力，或承諾現金兌換。GiftableToken 只有在發行方另行公佈條款並依照條款行事時，才成為可兌付的承諾。發行方仍須準確說明並履行這些條款。
承諾資金池（SwapPool）
SwapPool 是代幣保管庫和交換結算引擎。它雖然公開資金池名稱、符號和小數位等 ERC20 元資料，但 v1.1.0 合約不會鑄造資金池份額代幣。流動性透過把代幣轉入資金池來提供，合約所有者可以提取可用流動性。
組成與可選依賴項
| 配置 | 未配置時 | 可封存地址槽位 |
|---|---|---|
tokenRegistry | 任何代幣都能透過資金池篩選檢查 | 是 |
tokenLimiter | 存入沒有合約層面的餘額上限 | 是 |
quoter | 原始輸入數量被視為原始報價輸出數量 | 是 |
feePolicy | 資金池費用為零 | 是 |
feeAddress | 資金池費用不會累計為指定接收方可提取的費用 | 是 |
protocolFeeController | 不收取協議費 | 否 |
五個封存位會永久鎖定當前的 feePolicy、feeAddress、quoter、tokenRegistry 和 tokenLimiter 地址，使相應設定函式無法替換它們。protocolFeeController 和 feesDecoupled 是初始化值，不在這五個封存位之內。
封存地址槽位不會凍結該地址上的合約。已封存的登錄檔、限制器、報價器或費用政策，以及已配置的協議費控制器，如果自身治理允許，仍然可以發生變化。ERC-1967 代理管理員也能升級資金池實現。因此，任何有意義的不可變性宣告都取決於資金池所有者、代理管理員以及每個已配置依賴項的治理。
交換結算
進行交換時，SwapPool 會：
- 檢查輸入和輸出代幣是否透過可選登錄檔，並對請求的輸入應用可選的資金池餘額限制。
- 從呼叫者處轉入輸入代幣，並測量實際收到的數量。定價使用這一實收數量，包括收取轉賬費的代幣。
- 從已配置報價器獲取總報價；如未配置報價器，則使用實際收到的原始數量。
- 計算資金池費用和任何額外協議費，然後檢查輸出代幣的可用流動性。
- 把協議費直接傳送給已配置的協議費接收方，把名義淨輸出轉給接收方，並在已配置費用地址時記錄資金池費用。
- 發出舊版
Swap事件以及資訊更詳細的SwapSettlement事件。
SwapSettlement 會記錄發起方、兩種代幣、實收輸入、總報價輸出、傳送的名義輸出、接收方實際觀察到的輸出、資金池費用和協議費。如果輸出代幣本身收取轉賬費，名義輸出和實收輸出可能不同。舊版 fee 事件中的 Swap 欄位只表示資金池費用。
六引數過載 withdraw(tokenOut, tokenIn, value, recipient, minAmountOut, deadline) 是帶邊界保護的執行路徑。如果超過截止時間，或接收方觀察到的餘額增量低於 minAmountOut，它就會回滾。整合方應優先使用此過載，因為介面顯示的報價只是暫時的：報價器狀態、費用政策、流動性、限制和預言機資料都可能在執行前變化。較舊的三引數和四引數過載不提供這些資金池層面的邊界。
疊加費用計算
資金池費用和協議費都會從總報價輸出中扣除。協議費 不是從資金池費用中劃出；資金池仍保留其完整計算費用。
例如，總報價為 100 個單位時：
- 2% 的資金池費用會為資金池累計 2 個單位；
- 如果協議費率為資金池費用的 10%，則另有 0.2 個單位直接傳送給協議費接收方；以及
- 使用者收到 97.8 個單位。
協議費計算以計算出的資金池費用和假設的 1% 費用基數兩者中較高者為準。這樣可以防止過低的資金池費用把協議費計算降到接近零。無效的合併費率會以 FeeTooHigh 回滾，而結算輸出為零的報價會以 InsufficientOutput 回滾。
所有者與升級許可權
合約所有者可以收取已累計的資金池費用，並呼叫 withdrawLiquidity，把任意可用的資金池代幣轉移到所選的非零地址。費用解耦時，已累計費用會從該流動性提取路徑中預留；否則，它們仍屬於資金池餘額的一部分。除非另有可驗證的治理控制建立這一結果，參與者不應把已存入的流動性理解為永久鎖定。
配置封存不會移除這項流動性提取許可權，也不會移除 ERC-1967 代理管理員單獨擁有的升級許可權。
估值模組
三個報價器都實現了 SwapPool 和 SwapRouter 使用的正向與反向報價函式：
DecimalQuoter——在價值按一比一對應的假設下進行無狀態的小數位標準化。RelativeQuoter——進行小數位標準化，並應用由所有者管理的相對價格指數。未設定的代幣指數預設按一比一對應。OracleQuoter——透過已配置的預言機為每種代幣定價，使用全域性或逐代幣的陳舊度上限，並可選應用 0.9 至 1.0 的輸出乘數。
OracleQuoter 的可靠性取決於資料來源選擇和管理。資料來源的計價單位和方向必須一致，小數位必須正確，更新值必須為正且足夠新；治理方可以替換資料來源或更改新鮮度設定。資料來源被操縱、更新延遲、網路中斷、交易對配置錯誤或預言機所有者金鑰丟失，都可能導致錯誤報價或使交換回滾。
OracleRelay 是可選的單資料來源最新輪次中繼器，與預言機介面相容。指定寫入方重新發布源資料；這裡沒有跨鏈證明，也不會儲存輪次歷史。中繼器除檢查時間戳不能在未來外，會接受寫入方提交的數值。OracleQuoter 會另行拒絕非正數或陳舊答案，而中繼器所有者可以更換寫入方或使當前輪次失效。因此，使用者必須評估源資料、寫入方、中繼器所有者和監測流程。
費用政策與限制
FeePolicy 以百萬分之一為單位儲存預設費率，並可為特定方向的交易對設定覆蓋費率。除非合約外治理限制該許可權，其所有者可以更改這些費率。
Limiter 儲存特定資金池地址中某種代幣的最大余額。所有者或獲授權寫入方可以更改上限。限制器啟用時，上限為零會阻止存入；未配置限制器時，存入不設上限。
這些限制描述資金池中已配置的 代幣風險敞口。它們本身不能把代幣餘額歸類為貸款或法律債務，不能證明發行方能力，也不能保證履約。這些問題取決於發行方條款、資金池規則、向用戶顯示的交易以及適用法律。
協議費控制器
ProtocolFeeController 是可選的部署級費用元件。其所有者可以更改協議費率和接收方，或停用費用。多個資金池可以共用一個控制器，但協議並不要求每個網路只能使用一個控制器。
當控制器已啟用並正確配置時，每次交換成功都會直接以輸出代幣向接收方支付費用。接收方如何使用這些資金——例如用於運營、監測、流動性支援或其他已公佈目的——屬於治理事項，不是合約作出的保證。