Docs - some interfaces (#1702)

Synthetixio · Jul 6, 2023 · 1762828 · 1762828
1 parent 2049ad3
commit 1762828
Show file tree

Hide file tree

Showing 25 changed files with 479 additions and 87 deletions.
diff --git a/markets/perps-market/cannonfile.test.toml b/markets/perps-market/cannonfile.test.toml
@@ -31,18 +31,12 @@ artifact = "AsyncOrderModule"
 [contract.AsyncOrderSettlementModule]
 artifact = "AsyncOrderSettlementModule"
 
-[contract.AtomicOrderModule]
-artifact = "AtomicOrderModule"
-
 [contract.PerpsAccountModule]
 artifact = "PerpsAccountModule"
 
 [contract.PerpsMarketModule]
 artifact = "PerpsMarketModule"
 
-[contract.LimitOrderModule]
-artifact = "LimitOrderModule"
-
 [contract.LiquidationModule]
 artifact = "LiquidationModule"
 
@@ -74,11 +68,9 @@ contracts = [
   "PerpsMarketFactoryModule",
   "PerpsAccountModule",
   "PerpsMarketModule",
-  "AtomicOrderModule",
   "AsyncOrderModule",
   "AsyncOrderSettlementModule",
   "FeatureFlagModule",
-  "LimitOrderModule",
   "LiquidationModule",
   "MarketConfigurationModule",
   "GlobalPerpsMarketModule"
@@ -87,13 +79,11 @@ depends = [
   "import.synthetix",
   "contract.CoreModule",
   "contract.PerpsMarketFactoryModule",
-  "contract.AtomicOrderModule",
   "contract.AsyncOrderModule",
   "contract.AsyncOrderSettlementModule",
   "contract.PerpsAccountModule",
   "contract.PerpsMarketModule",
   "contract.FeatureFlagModule",
-  "contract.LimitOrderModule",
   "contract.LiquidationModule",
   "contract.MarketConfigurationModule",
   "contract.GlobalPerpsMarketModule"

diff --git a/markets/perps-market/cannonfile.toml b/markets/perps-market/cannonfile.toml
@@ -31,18 +31,12 @@ artifact = "AsyncOrderModule"
 [contract.AsyncOrderSettlementModule]
 artifact = "AsyncOrderSettlementModule"
 
-[contract.AtomicOrderModule]
-artifact = "AtomicOrderModule"
-
 [contract.PerpsAccountModule]
 artifact = "PerpsAccountModule"
 
 [contract.PerpsMarketModule]
 artifact = "PerpsMarketModule"
 
-[contract.LimitOrderModule]
-artifact = "LimitOrderModule"
-
 [contract.LiquidationModule]
 artifact = "LiquidationModule"
 
@@ -74,11 +68,9 @@ contracts = [
   "PerpsMarketFactoryModule",
   "PerpsAccountModule",
   "PerpsMarketModule",
-  "AtomicOrderModule",
   "AsyncOrderModule",
   "AsyncOrderSettlementModule",
   "FeatureFlagModule",
-  "LimitOrderModule",
   "LiquidationModule",
   "MarketConfigurationModule",
   "GlobalPerpsMarketModule"
@@ -87,13 +79,11 @@ depends = [
   "import.synthetix",
   "contract.CoreModule",
   "contract.PerpsMarketFactoryModule",
-  "contract.AtomicOrderModule",
   "contract.AsyncOrderModule",
   "contract.AsyncOrderSettlementModule",
   "contract.PerpsAccountModule",
   "contract.PerpsMarketModule",
   "contract.FeatureFlagModule",
-  "contract.LimitOrderModule",
   "contract.LiquidationModule",
   "contract.MarketConfigurationModule",
   "contract.GlobalPerpsMarketModule"

diff --git a/markets/perps-market/contracts/interfaces/IAccountModule.sol b/markets/perps-market/contracts/interfaces/IAccountModule.sol
@@ -7,25 +7,70 @@ import {AsyncOrder} from "../storage/AsyncOrder.sol";
  * @title Account module
  */
 interface IAccountModule {
-    error InvalidAmountDelta(int amountDelta);
-
+    /**
+     * @notice Gets fired when an account colateral is modified.
+     * @param accountId Id of the account.
+     * @param synthMarketId Id of the synth market used as collateral. Synth market id, 0 for snxUSD.
+     * @param amountDelta requested change in amount of collateral delegated to the account.
+     * @param sender address of the sender of the size modification. Authorized by account owner.
+     */
     event CollateralModified(
         uint128 indexed accountId,
         uint128 indexed synthMarketId,
-        int amountDelta,
+        int256 amountDelta,
         address indexed sender
     );
 
+    /**
+     * @notice Gets thrown when the amount delta is zero.
+     */
+    error InvalidAmountDelta(int amountDelta);
+
+    /**
+     * @notice Modify the collateral delegated to the account.
+     * @param accountId Id of the account.
+     * @param synthMarketId Id of the synth market used as collateral. Synth market id, 0 for snxUSD.
+     * @param amountDelta requested change in amount of collateral delegated to the account.
+     */
     function modifyCollateral(uint128 accountId, uint128 synthMarketId, int amountDelta) external;
 
+    /**
+     * @notice Gets the account's collateral value for a specific collateral.
+     * @param accountId Id of the account.
+     * @param synthMarketId Id of the synth market used as collateral. Synth market id, 0 for snxUSD.
+     * @return collateralValue collateral value of the account.
+     */
+    function getCollateralAmount(
+        uint128 accountId,
+        uint128 synthMarketId
+    ) external view returns (uint256);
+
+    /**
+     * @notice Gets the account's total collateral value.
+     * @param accountId Id of the account.
+     * @return collateralValue total collateral value of the account. USD denominated.
+     */
     function totalCollateralValue(uint128 accountId) external view returns (uint);
 
+    /**
+     * @notice Gets the account's total open interest value.
+     * @param accountId Id of the account.
+     * @return openInterestValue total open interest value of the account.
+     */
     function totalAccountOpenInterest(uint128 accountId) external view returns (uint);
 
+    /**
+     * @notice Gets the details of an open position.
+     * @param accountId Id of the account.
+     * @param marketId Id of the position market.
+     * @return pnl pnl of the position.
+     * @return accruedFunding accrued funding of the position.
+     * @return size size of the position.
+     */
     function getOpenPosition(
         uint128 accountId,
         uint128 marketId
-    ) external view returns (int, int, int);
+    ) external view returns (int pnl, int accruedFunding, int size);
 
     /**
      * @notice Get async order claim details
@@ -38,10 +83,10 @@ interface IAccountModule {
         uint128 marketId
     ) external view returns (AsyncOrder.Data memory);
 
+    /**
+     * @notice Gets the available margin of an account. It can be negative due to pnl.
+     * @param accountId Id of the account.
+     * @return availableMargin available margin of the position.
+     */
     function getAvailableMargin(uint128 accountId) external view returns (int);
-
-    function getCollateralAmount(
-        uint128 accountId,
-        uint128 synthMarketId
-    ) external view returns (uint256);
 }
diff --git a/markets/perps-market/contracts/interfaces/IAsyncOrderModule.sol b/markets/perps-market/contracts/interfaces/IAsyncOrderModule.sol
@@ -8,6 +8,18 @@ import {SettlementStrategy} from "../storage/SettlementStrategy.sol";
  * @title Module for committing and settling async orders.
  */
 interface IAsyncOrderModule {
+    /**
+     * @notice Gets fired when a new order is committed.
+     * @param marketId Id of the market used for the trade.
+     * @param accountId Id of the account used for the trade.
+     * @param orderType Should send 0 (at time of writing) that correlates to the transaction type enum defined in SettlementStrategy.Type.
+     * @param sizeDelta requested change in size of the order sent by the user.
+     * @param acceptablePrice maximum or minimum, depending on the sizeDelta direction, accepted price to settle the order, set by the user.
+     * @param settlementTime Time at which the order can be settled.
+     * @param expirationTime Time at which the order expired.
+     * @param trackingCode Optional code for integrator tracking purposes.
+     * @param sender address of the sender of the order. Authorized to commit by account owner.
+     */
     event OrderCommitted(
         uint128 indexed marketId,
         uint128 indexed accountId,
@@ -20,23 +32,51 @@ interface IAsyncOrderModule {
         address sender
     );
 
+    /**
+     * @notice Gets fired when a new order is canceled.
+     * @param marketId Id of the market used for the trade.
+     * @param accountId Id of the account used for the trade.
+     * @param acceptablePrice maximum or minimum, depending on the sizeDelta direction, accepted price to settle the order, set by the user.
+     * @param settlementTime Time at which the order can be settled.
+     */
+
     event OrderCanceled(
         uint128 indexed marketId,
         uint128 indexed accountId,
         uint256 settlementTime,
         uint256 acceptablePrice
     );
 
+    /**
+     * @notice Gets thrown when commit order is called when a pending order already exists.
+     */
     error OrderAlreadyCommitted(uint128 marketId, uint128 accountId);
 
+    /**
+     * @notice Commit an async order via this function
+     * @param commitment Order commitment data (see AsyncOrder.OrderCommitmentRequest struct).
+     * @return retOrder order details (see AsyncOrder.Data struct).
+     * @return fees order fees (protocol + settler)
+     */
     function commitOrder(
         AsyncOrder.OrderCommitmentRequest memory commitment
     ) external returns (AsyncOrder.Data memory retOrder, uint fees);
 
+    /**
+     * @notice Cancel an expired order via this function
+     * @param marketId Id of the market used for the trade.
+     * @param accountId Id of the account used for the trade.
+     */
+    function cancelOrder(uint128 marketId, uint128 accountId) external;
+
+    /**
+     * @notice Get an order details via this function
+     * @param marketId Id of the market used for the trade.
+     * @param accountId Id of the account used for the trade.
+     * @return order order details (see AsyncOrder.Data struct).
+     */
     function getOrder(
         uint128 marketId,
         uint128 accountId
-    ) external returns (AsyncOrder.Data memory);
-
-    function cancelOrder(uint128 marketId, uint128 accountId) external;
+    ) external returns (AsyncOrder.Data memory order);
 }
diff --git a/markets/perps-market/contracts/interfaces/IAsyncOrderSettlementModule.sol b/markets/perps-market/contracts/interfaces/IAsyncOrderSettlementModule.sol
@@ -3,7 +3,13 @@ pragma solidity >=0.8.11 <0.9.0;
 import {SettlementStrategy} from "../storage/SettlementStrategy.sol";
 
 interface IAsyncOrderSettlementModule {
+    /**
+     * @notice Gets thrown when settle order is called with invalid settlement strategy.
+     */
     error SettlementStrategyNotFound(SettlementStrategy.Type strategyType);
+    /**
+     * @notice Gets thrown when settle order is called as a signal to the client to perform offchain lookup.
+     */
     error OffchainLookup(
         address sender,
         string[] urls,
@@ -12,6 +18,18 @@ interface IAsyncOrderSettlementModule {
         bytes extraData
     );
 
+    /**
+     * @notice Gets fired when a new order is settled.
+     * @param marketId Id of the market used for the trade.
+     * @param accountId Id of the account used for the trade.
+     * @param fillPrice Price at which the order was settled.
+     * @param accountPnlRealized Realized PnL of the position at the time of settlement.
+     * @param newSize New size of the position after settlement.
+     * @param collectedFees Amount of fees collected by the protocol.
+     * @param settelementReward Amount of fees collected by the settler.
+     * @param trackingCode Optional code for integrator tracking purposes.
+     * @param settler address of the settler of the order.
+     */
     event OrderSettled(
         uint128 indexed marketId,
         uint128 indexed accountId,
@@ -36,7 +54,17 @@ interface IAsyncOrderSettlementModule {
         bytes32 trackingCode;
     }
 
+    /**
+     * @notice Settles an offchain order. It's expected to revert with the OffchainLookup error with the data needed to perform the offchain lookup.
+     * @param marketId Id of the market used for the trade.
+     * @param accountId Id of the account used for the trade.
+     */
     function settle(uint128 marketId, uint128 accountId) external view;
 
+    /**
+     * @notice Settles an offchain order using the offchain retrieved data from pyth.
+     * @param result the blob of data retrieved offchain.
+     * @param extraData Extra data from OffchainLookupData.
+     */
     function settlePythOrder(bytes calldata result, bytes calldata extraData) external payable;
 }
diff --git a/markets/perps-market/contracts/interfaces/ICollateralModule.sol b/markets/perps-market/contracts/interfaces/ICollateralModule.sol
@@ -1,13 +1,21 @@
 //SPDX-License-Identifier: MIT
 pragma solidity >=0.8.11 <0.9.0;
 
+/**
+ * @title Module for setting max collateral distribution.
+ */
 interface ICollateralModule {
     /**
-     * @notice Gets fired when max collateral amount for synth is set by owner.
-     * @param synthId Synth market id, 0 for snxUSD.
-     * @param maxCollateralAmount max amount that was set for the synth
+     * @notice Gets fired when max collateral amount for synth collateral for the system is set by owner.
+     * @param synthMarketId Synth market id, 0 for snxUSD.
+     * @param collateralAmount max amount that was set for the synth
      */
-    event MaxCollateralSet(uint128 indexed synthId, uint256 maxCollateralAmount);
+    event MaxCollateralSet(uint128 indexed synthMarketId, uint256 collateralAmount);
 
-    function setMaxCollateralAmount(uint128 synthId, uint maxCollateralAmount) external;
+    /**
+     * @notice Set the max collateral amoutn via this function
+     * @param synthMarketId Synth market id, 0 for snxUSD.
+     * @param collateralAmount max amount that for the synth
+     */
+    function setMaxCollateralAmount(uint128 synthMarketId, uint collateralAmount) external;
 }