@pendle/core-v2 0.16.5-testnet → 0.17.0-daily

package/contracts/offchain-helpers/RouterStatic.sol

@@ -12,7 +12,7 @@ import "./MarketMathStatic.sol";
 import "../core/libraries/BoringOwnableUpgradeable.sol";
 import "../LiquidityMining/libraries/VeBalanceLib.sol";
 
-import "@openzeppelin/contracts/proxy/utils/Initializable.sol";
+import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
 import "@openzeppelin/contracts/proxy/utils/UUPSUpgradeable.sol";
 
 /// EXCLUDED FROM ALL AUDITS, TO BE CALLED ONLY BY PENDLE's SDK
@@ -20,9 +20,10 @@ contract RouterStatic is Initializable, BoringOwnableUpgradeable, UUPSUpgradeabl
     using Math for uint256;
     using VeBalanceLib for VeBalance;
     using VeBalanceLib for LockedPosition;
+    using BulkSellerMathCore for BulkSellerState;
 
     uint128 public constant MAX_LOCK_TIME = 104 weeks;
-    uint128 public constant MIN_LOCK_TIME = 1 weeks;
+    uint128 public constant MIN_LOCK_TIME = 1 days;
 
     struct TokenAmount {
         address token;
@@ -85,7 +86,7 @@ contract RouterStatic is Initializable, BoringOwnableUpgradeable, UUPSUpgradeabl
                 guessMax: type(uint256).max,
                 guessOffchain: 0,
                 maxIteration: 256,
-                eps: 1e15
+                eps: 1e14
             });
     }
 
@@ -155,7 +156,7 @@ contract RouterStatic is Initializable, BoringOwnableUpgradeable, UUPSUpgradeabl
 
         pt = address(PT);
         sy = address(SY);
-        state = _market.readState();
+        state = _market.readState(address(this));
         impliedYield = getPtImpliedYield(market);
         exchangeRate = MarketMathStatic.getExchangeRate(market);
     }
@@ -244,7 +245,7 @@ contract RouterStatic is Initializable, BoringOwnableUpgradeable, UUPSUpgradeabl
         (userMarketInfo.assetBalance.assetType, userMarketInfo.assetBalance.assetAddress, ) = SY
             .assetInfo();
 
-        MarketState memory state = _market.readState();
+        MarketState memory state = _market.readState(address(this));
         uint256 totalLp = uint256(state.totalLp);
 
         if (totalLp == 0) {
@@ -733,7 +734,8 @@ contract RouterStatic is Initializable, BoringOwnableUpgradeable, UUPSUpgradeabl
         address bulk
     ) public view returns (uint256 amountSy) {
         if (bulk != address(0)) {
-            return IPBulkSeller(bulk).calcSwapExactTokenForSy(amountToken);
+            BulkSellerState memory state = IPBulkSeller(bulk).readState();
+            return state.calcSwapExactTokenForSy(amountToken);
         } else {
             return SY.previewDeposit(baseToken, amountToken);
         }
@@ -746,7 +748,8 @@ contract RouterStatic is Initializable, BoringOwnableUpgradeable, UUPSUpgradeabl
         address bulk
     ) public view returns (uint256 amountBaseToken) {
         if (bulk != address(0)) {
-            return IPBulkSeller(bulk).calcSwapExactSyForToken(amountSy);
+            BulkSellerState memory state = IPBulkSeller(bulk).readState();
+            return state.calcSwapExactSyForToken(amountSy);
         } else {
             return SY.previewRedeem(baseToken, amountSy);
         }
@@ -852,8 +855,45 @@ contract RouterStatic is Initializable, BoringOwnableUpgradeable, UUPSUpgradeabl
         bulk = IPBulkSellerFactory(bulkFactory).get(token, SY);
         if (bulk != address(0)) {
             BulkSellerState memory state = IPBulkSeller(bulk).readState();
-            totalToken = state.totalToken;
-            totalSy = state.totalSy;
+            if (state.rateTokenToSy != 0 || state.rateSyToToken != 0) {
+                totalToken = state.totalToken;
+                totalSy = state.totalSy;
+            }
+        }
+    }
+
+    function getBulkSellerInfo(
+        address token,
+        address SY,
+        uint256 netTokenIn,
+        uint256 netSyIn
+    )
+        external
+        view
+        returns (
+            address bulk,
+            uint256 totalToken,
+            uint256 totalSy
+        )
+    {
+        bulk = IPBulkSellerFactory(bulkFactory).get(token, SY);
+        if (bulk != address(0)) {
+            BulkSellerState memory state = IPBulkSeller(bulk).readState();
+            if (state.rateTokenToSy != 0 || state.rateSyToToken != 0) {
+                totalToken = state.totalToken;
+                totalSy = state.totalSy;
+            }
+
+            uint256 postFeeRateTokenToSy = state.rateTokenToSy.mulDown(Math.ONE - state.feeRate);
+            uint256 postFeeRateSyToToken = state.rateSyToToken.mulDown(Math.ONE - state.feeRate);
+            if (
+                netTokenIn.mulDown(postFeeRateTokenToSy) > state.totalSy ||
+                netSyIn.mulDown(postFeeRateSyToToken) > state.totalToken
+            ) {
+                bulk = address(0);
+                totalToken = 0;
+                totalSy = 0;
+            }
         }
     }
 }

package/contracts/router/ActionAddRemoveLiq.sol

@@ -6,6 +6,14 @@ import "../interfaces/IPActionAddRemoveLiq.sol";
 import "../interfaces/IPMarket.sol";
 import "../core/libraries/Errors.sol";
 
+/**
+ * @dev If market is expired, all actions will revert, except for the following:
+ * - removeLiquidityDualSyAndPt()
+ * - removeLiquidityDualTokenAndPt()
+ * - removeLiquiditySingleSy()
+ * - removeLiquiditySingleToken()
+ * This is because swapping and adding liquidity are not allowed on an expired market.
+ */
 contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
     using Math for uint256;
     using Math for int256;
@@ -20,6 +28,13 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         ActionBaseMintRedeem(_kyberScalingLib) //solhint-disable-next-line no-empty-blocks
     {}
 
+    /**
+     * @notice Adds liquidity to the SY/PT market, granting LP tokens in return
+     * @dev Will mint as much LP as possible given no more than `netSyDesired` and `netPtDesired`,
+     * while not changing the market's price
+     * @dev Only the necessary SY/PT amount will be transferred
+     * @dev Reverts if market is expired
+     */
     function addLiquidityDualSyAndPt(
         address receiver,
         address market,
@@ -37,7 +52,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         (IStandardizedYield SY, IPPrincipalToken PT, ) = IPMarket(market).readTokens();
 
         // calculate the amount of SY and PT to be used
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
         (, netLpOut, netSyUsed, netPtUsed) = state.addLiquidity(
             netSyDesired,
             netPtDesired,
@@ -60,7 +75,15 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
     }
 
     /**
-     * @dev this function assumes that netTokenDesired = netTokenUsed, and fails if this does not hold
+     * @notice Adds liquidity to SY/PT market using PT + any token.
+     * @dev Input token is first swapped to SY-mintable token using Kyber, then SY is minted from 
+     * such. Finally the SY/PT pair is added to the market
+     * @param input data for input token, see {`./kyberswap/KyberSwapHelper.sol`}
+     * @param netPtDesired maximum PT to be used
+     * @dev Only the necessary PT amount will be transferred
+     * @dev All SY minted must be used, otherwise the call will revert. Therefore it is recommended
+     * that `netPtDesired` is slightly higher than actual expected.
+     * @dev Reverts if market is expired
      */
     function addLiquidityDualTokenAndPt(
         address receiver,
@@ -84,7 +107,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
 
         {
             // calc the amount of SY and PT to be used
-            MarketState memory state = IPMarket(market).readState();
+            MarketState memory state = IPMarket(market).readState(address(this));
             (, netLpOut, netSyUsed, netPtUsed) = state.addLiquidity(
                 netSyDesired,
                 netPtDesired,
@@ -108,14 +131,22 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         emit AddLiquidityDualTokenAndPt(
             msg.sender,
             market,
-            receiver,
             input.tokenIn,
+            receiver,
             netTokenUsed,
             netPtUsed,
             netLpOut
         );
     }
 
+    /**
+     * @notice Swaps partial PT to SY, then use them to add liquidity to SY/PT pair
+     * @param netPtIn amount of PT to be transferred in from caller
+     * @param guessPtSwapToSy approximate info for the swap
+     * @return netLpOut actual LP output, will not be lower than `minLpOut`
+     * @return netSyFee amount of SY fee incurred from the swap
+     * @dev Reverts if market is expired
+     */
     function addLiquiditySinglePt(
         address receiver,
         address market,
@@ -126,7 +157,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         (, IPPrincipalToken PT, IPYieldToken YT) = IPMarket(market).readTokens();
 
         // calculate the amount of PT to swap
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
 
         (uint256 netPtSwap, , ) = state.approxSwapPtToAddLiquidity(
             YT.newIndex(),
@@ -153,6 +184,14 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         emit AddLiquiditySinglePt(msg.sender, market, receiver, netPtIn, netLpOut);
     }
 
+    /**
+     * @notice Swaps partial SY to PT, then use them to add liquidity to SY/PT pair
+     * @param netSyIn amount of SY to be transferred in from caller
+     * @param guessPtReceivedFromSy approx. output PT from the swap
+     * @return netLpOut actual LP output, will not be lower than `minLpOut`
+     * @return netSyFee amount of SY fee incurred from the swap
+     * @dev Reverts if market is expired
+     */
     function addLiquiditySingleSy(
         address receiver,
         address market,
@@ -178,6 +217,15 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         emit AddLiquiditySingleSy(msg.sender, market, receiver, netSyIn, netLpOut);
     }
 
+    /**
+     * @notice Adds liquidity using a single token input. The input token is first swapped through 
+     * Kyberswap to a SY-mintable token, the rest is the same as `addLiquiditySingleSy()`
+     * @param guessPtReceivedFromSy approximate PT output for the SY-to-PT swap
+     * @param input data for input token, see {`./kyberswap/KyberSwapHelper.sol`}
+     * @return netLpOut actual LP output, will not be lower than `minLpOut`
+     * @return netSyFee amount of SY fee incurred from the swap
+     * @dev Reverts if market is expired
+     */
     function addLiquiditySingleToken(
         address receiver,
         address market,
@@ -210,6 +258,11 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         );
     }
 
+    /**
+     * @notice Burns LP token to remove SY/PT liquidity
+     * @param netLpToRemove amount of LP to be burned from caller
+     * @dev Will work even if market is expired
+     */
     function removeLiquidityDualSyAndPt(
         address receiver,
         address market,
@@ -234,6 +287,13 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         );
     }
 
+    /**
+     * @notice Burns LP token to remove SY/PT liquidity, then redeems SY, finally (if needed)
+     * swaps SY redeemings through Kyberswap to desired output token.
+     * @param netLpToRemove amount of LP to be burned from caller
+     * @param output data for desired output token, see {`./kyberswap/KyberSwapHelper.sol`}
+     * @dev Will work even if market is expired
+     */
     function removeLiquidityDualTokenAndPt(
         address receiver,
         address market,
@@ -261,31 +321,39 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         emit RemoveLiquidityDualTokenAndPt(
             msg.sender,
             market,
+            output.tokenOut,
             receiver,
             netLpToRemove,
             netPtOut,
-            output.tokenOut,
             netTokenOut
         );
     }
 
+    /**
+     * @notice Removes SY/PT liquidity, then swaps all resulting SY to return only PT
+     * @param netLpToRemove amount of LP to be burned from caller
+     * @param guessPtReceivedFromSy approximate info for the swap
+     * @return netPtOut total PT output, will not be lower than `minPtOut`
+     * @return netSyFee amount of SY fee incurred from the swap
+     * @dev Reverts if market is expired
+     */
     function removeLiquiditySinglePt(
         address receiver,
         address market,
         uint256 netLpToRemove,
         uint256 minPtOut,
-        ApproxParams calldata guessPtOut
+        ApproxParams calldata guessPtReceivedFromSy
     ) external returns (uint256 netPtOut, uint256 netSyFee) {
         (, , IPYieldToken YT) = IPMarket(market).readTokens();
 
         // calculate the total amount of PT received from burning & selling SY
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
         (uint256 syFromBurn, uint256 ptFromBurn) = state.removeLiquidity(netLpToRemove);
         (uint256 ptFromSwap, ) = state.approxSwapExactSyForPt(
             YT.newIndex(),
             syFromBurn,
             block.timestamp,
-            guessPtOut
+            guessPtReceivedFromSy
         );
 
         if (ptFromBurn + ptFromSwap < minPtOut)
@@ -305,6 +373,14 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         emit RemoveLiquiditySinglePt(msg.sender, market, receiver, netLpToRemove, netPtOut);
     }
 
+    /**
+     * @notice Removes SY/PT liquidity, then converts all resulting PT to return only SY
+     * @dev Conversion is done with market swap if not expired, or with PT redeeming if expired
+     * @param netLpToRemove amount of LP to be burned from caller
+     * @return netSyOut total SY output, will not be lower than `minSyOut`
+     * @return netSyFee amount of SY fee incurred from the swap
+     * @dev Will work even if market is expired
+     */
     function removeLiquiditySingleSy(
         address receiver,
         address market,
@@ -320,6 +396,18 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         emit RemoveLiquiditySingleSy(msg.sender, market, receiver, netLpToRemove, netSyOut);
     }
 
+    /**
+     * @notice Removes SY/PT liquidity, then converts all to desired output token.
+     * @dev inner workings of this function:
+        - Removes SY/PT liquidity to only SY (see `removeLiquiditySingleSy()`)
+        - Burns SY to redeem SY-mintable tokens
+        - (If needed) swaps resulting tokens to desired output token using Kyberswap
+     * @param netLpToRemove amount of LP to be burned from caller
+     * @param output data for desired output token, see {`./kyberswap/KyberSwapHelper.sol`}
+     * @return netTokenOut total token output, will not be lower than `output.minTokenOut`
+     * @return netSyFee amount of SY fee incurred from the swap
+     * @dev Will work even if market is expired
+     */
     function removeLiquiditySingleToken(
         address receiver,
         address market,
@@ -353,6 +441,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         );
     }
 
+    /// @dev swaps SY to PT, then adds liquidity
     function _addLiquiditySingleSy(
         address receiver,
         address market,
@@ -361,7 +450,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         uint256 minLpOut,
         ApproxParams calldata guessPtReceivedFromSy
     ) internal returns (uint256 netLpOut, uint256 netSyFee) {
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
 
         // calculate the PT amount needed to add liquidity
         (uint256 netPtFromSwap, , ) = state.approxSwapSyToAddLiquidity(
@@ -384,6 +473,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         if (netLpOut < minLpOut) revert Errors.RouterInsufficientLpOut(netLpOut, minLpOut);
     }
 
+    /// @dev removes SY/PT liquidity, then converts PT to SY
     function _removeLiquiditySingleSy(
         address receiver,
         address market,
@@ -399,6 +489,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         if (netSyOut < minSyOut) revert Errors.RouterInsufficientSyOut(netSyOut, minSyOut);
     }
 
+    /// @dev converts PT to SY post-expiry
     function __removeLpToSyAfterExpiry(
         address receiver,
         address market,
@@ -409,6 +500,7 @@ contract ActionAddRemoveLiq is IPActionAddRemoveLiq, ActionBaseMintRedeem {
         netSyOut = syFromBurn + IPYieldToken(YT).redeemPY(receiver);
     }
 
+    /// @dev swaps PT to SY pre-expiry
     function __removeLpToSyBeforeExpiry(
         address receiver,
         address market,

package/contracts/router/ActionMintRedeem.sol

@@ -16,6 +16,10 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         ActionBaseMintRedeem(_kyberScalingLib) //solhint-disable-next-line no-empty-blocks
     {}
 
+    /**
+     * @notice swaps input token for SY-mintable tokens (if needed), then mints SY from such
+     * @param input data for input token, see {`./kyberswap/KyberSwapHelper.sol`}
+     */
     function mintSyFromToken(
         address receiver,
         address SY,
@@ -23,9 +27,14 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         TokenInput calldata input
     ) external payable returns (uint256 netSyOut) {
         netSyOut = _mintSyFromToken(receiver, SY, minSyOut, input);
-        emit MintSyFromToken(msg.sender, receiver, SY, input.tokenIn, input.netTokenIn, netSyOut);
+        emit MintSyFromToken(msg.sender, input.tokenIn, SY, receiver, input.netTokenIn, netSyOut);
     }
 
+    /**
+     * @notice redeems SY for SY-mintable tokens, then (if needed) swaps resulting tokens for 
+     * desired output token through Kyberswap
+     * @param output data for desired output token, see {`./kyberswap/KyberSwapHelper.sol`}
+     */
     function redeemSyToToken(
         address receiver,
         address SY,
@@ -33,9 +42,16 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         TokenOutput calldata output
     ) external returns (uint256 netTokenOut) {
         netTokenOut = _redeemSyToToken(receiver, SY, netSyIn, output, true);
-        emit RedeemSyToToken(msg.sender, receiver, SY, netSyIn, output.tokenOut, netTokenOut);
+        emit RedeemSyToToken(msg.sender, output.tokenOut, SY, receiver, netSyIn, netTokenOut);
     }
 
+    /**
+     * @notice mints PY from any input token
+     * @dev swaps input token through Kyberswap to SY-mintable tokens first, then mints SY, finally 
+     * mints PY from SY
+     * @param input data for input token, see {`./kyberswap/KyberSwapHelper.sol`}
+     * @dev reverts if PY is expired
+     */
     function mintPyFromToken(
         address receiver,
         address YT,
@@ -47,9 +63,15 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         uint256 netSyToMint = _mintSyFromToken(YT, SY, 0, input);
         netPyOut = _mintPyFromSy(receiver, YT, netSyToMint, minPyOut, false);
 
-        emit MintPyFromToken(msg.sender, receiver, YT, input.tokenIn, input.netTokenIn, netPyOut);
+        emit MintPyFromToken(msg.sender, input.tokenIn, YT, receiver, input.netTokenIn, netPyOut);
     }
 
+    /**
+     * @notice redeems PY for token
+     * @dev redeems PT(+YT) for SY first, then redeems SY, finally swaps resulting tokens to output 
+     * token through Kyberswap (if needed)
+     * @param output data for desired output token, see {`./kyberswap/KyberSwapHelper.sol`}
+     */
     function redeemPyToToken(
         address receiver,
         address YT,
@@ -61,9 +83,13 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         uint256 netSyToRedeem = _redeemPyToSy(_syOrBulk(SY, output), YT, netPyIn, 1);
         netTokenOut = _redeemSyToToken(receiver, SY, netSyToRedeem, output, false);
 
-        emit RedeemPyToToken(msg.sender, receiver, YT, netPyIn, output.tokenOut, netTokenOut);
+        emit RedeemPyToToken(msg.sender, output.tokenOut, YT, receiver, netPyIn, netTokenOut);
     }
 
+    /**
+     * @notice mints PT+YT from input SY
+     * @dev reverts if the PY pair is expired
+     */
     function mintPyFromSy(
         address receiver,
         address YT,
@@ -74,6 +100,7 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         emit MintPyFromSy(msg.sender, receiver, YT, netSyIn, netPyOut);
     }
 
+    /// @notice redeems PT(+YT) for its corresponding SY
     function redeemPyToSy(
         address receiver,
         address YT,
@@ -84,6 +111,11 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         emit RedeemPyToSy(msg.sender, receiver, YT, netPyIn, netSyOut);
     }
 
+    /**
+     * @notice A unified interface for redeeming rewards and interests for any SYs,
+     * YTs, and markets alike for `user`.
+     * @dev returns arrays of amounts claimed for each asset.
+     */
     function redeemDueInterestAndRewards(
         address user,
         address[] calldata sys,
@@ -134,6 +166,14 @@ contract ActionMintRedeem is IPActionMintRedeem, ActionBaseMintRedeem {
         uint256[] amounts;
     }
 
+    /** 
+     * @notice A function to:
+        - Redeem all of caller's due interest and rewards in SYs, YTs, and markets
+        - Redeem SYs themselves
+        - Finally swaps all resulting tokens to `dataSwap.outputToken`
+     * @return netTokenOut total token output amount, will not be lower than `dataSwap.minTokenOut`
+     * @return amountsSwapped the amounts swapped for each token defined in `dataSwap.tokens`
+     */
     function redeemDueInterestAndRewardsThenSwapAll(
         address[] calldata sys,
         RouterYtRedeemStruct calldata dataYT,

package/contracts/router/ActionSwapPT.sol

@@ -6,6 +6,7 @@ import "../interfaces/IPActionSwapPT.sol";
 import "../interfaces/IPMarket.sol";
 import "../core/libraries/Errors.sol";
 
+/// @dev All swap actions will revert if market is expired
 contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
     using MarketMathCore for MarketState;
     using MarketApproxPtInLib for MarketState;
@@ -19,6 +20,12 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
         ActionBaseMintRedeem(_kyberScalingLib) //solhint-disable-next-line no-empty-blocks
     {}
 
+    /**
+     * @notice swaps exact amount of PT for SY
+     * @param exactPtIn will always consume this exact amount of PT for as much SY as possible
+     * @return netSyOut amount SY output, will not be less than `minSyOut`
+     * @return netSyFee amount SY fee incurred
+     */
     function swapExactPtForSy(
         address receiver,
         address market,
@@ -36,8 +43,13 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
     }
 
     /**
-     * @notice Note that the amount of SY out will be a bit more than `exactSyOut`, since an approximation is used. It's
-        guaranteed that the `netSyOut` is at least `exactSyOut`
+     * @notice swaps some amount of PT for the desired SY amount
+     * @param guessPtIn approximation data for input PT amount
+     * @param exactSyOut will consume as little PT as possible for this much SY amount
+     * @return netPtIn amount of PT used, will not be more than `maxPtIn`
+     * @return netSyFee amount SY fee incurred
+     * @dev the SY output might be slightly more than `exactSyOut` since an approximation is used. 
+     * It is guaranteed that exactSyOut <= actualSyOut <= exactSyOut*(100% + guessPtIn.eps) 
      */
     function swapPtForExactSy(
         address receiver,
@@ -46,7 +58,7 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
         uint256 maxPtIn,
         ApproxParams calldata guessPtIn
     ) external returns (uint256 netPtIn, uint256 netSyFee) {
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
         (, IPPrincipalToken PT, IPYieldToken YT) = IPMarket(market).readTokens();
 
         (netPtIn, , ) = state.approxSwapPtForExactSy(
@@ -69,16 +81,23 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
         emit SwapPtAndSy(msg.sender, market, receiver, netPtIn.neg(), exactSyOut.Int());
     }
 
+    /**
+     * @notice swaps SY for exact amount of PT
+     * @param exactPtOut will always consume as little SY as possible for this much amount of PT
+     * @return netSyIn amount SY used, will not be more than `maxSyIn`
+     * @return netSyFee amount SY fee incurred
+     * @dev the output amount of PT here is exact, no approximation is used
+     */
     function swapSyForExactPt(
         address receiver,
         address market,
         uint256 exactPtOut,
         uint256 maxSyIn
     ) external returns (uint256 netSyIn, uint256 netSyFee) {
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
         (IStandardizedYield SY, , IPYieldToken YT) = IPMarket(market).readTokens();
 
-        (netSyIn, ) = state.swapSyForExactPt(YT.newIndex(), exactPtOut, block.timestamp);
+        (netSyIn, , ) = state.swapSyForExactPt(YT.newIndex(), exactPtOut, block.timestamp);
 
         if (netSyIn > maxSyIn) revert Errors.RouterExceededLimitSyIn(netSyIn, maxSyIn);
 
@@ -90,6 +109,13 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
         emit SwapPtAndSy(msg.sender, market, receiver, exactPtOut.Int(), netSyIn.neg());
     }
 
+    /**
+     * @notice swaps exact amount of SY for as much PT as possible
+     * @param exactSyIn will always consume this much amount of SY
+     * @param guessPtOut approximation data for output PT amount
+     * @return netPtOut amount of PT output, will not be less than `minPtOut`
+     * @return netSyFee amount SY fee incurred
+     */
     function swapExactSyForPt(
         address receiver,
         address market,
@@ -114,9 +140,10 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
     }
 
     /**
-     * @notice swap from any ERC20 tokens, through Uniswap's forks, to get baseTokens to make SY, then swap
-        from SY to PT
-     * @dev simply a combination of _mintSyFromToken & _swapExactSyForPt
+     * @notice swap (through Kyberswap) from any input token for SY-mintable tokens, then mints SY 
+     * and swaps said SY for PT
+     * @param input data for input token, see {`./kyberswap/KyberSwapHelper.sol`}
+     * @dev is a combination of `_mintSyFromToken()` and `_swapExactSyForPt()`
      */
     function swapExactTokenForPt(
         address receiver,
@@ -151,8 +178,11 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
     }
 
     /**
-     * @notice swap from PT to SY, then redeem SY to baseToken & swap through Uniswap's forks to get tokenOut
-     * @dev simply a combination of _swapExactPtForSy & _redeemSyToToken
+     * @notice swap from exact amount of PT to SY, then redeem SY for assets, finally swaps 
+     * resulting assets through Kyberswap to get desired output token
+     * @param exactPtIn will always consume this much PT for as much SY as possible
+     * @param output data for desired output token, see {`./kyberswap/KyberSwapHelper.sol`}
+     * @dev is a combination of `_swapExactPtForSy()` and `_redeemSyToToken()`
      */
     function swapExactPtForToken(
         address receiver,
@@ -193,7 +223,7 @@ contract ActionSwapPT is IPActionSwapPT, ActionBaseMintRedeem {
         uint256 minPtOut,
         ApproxParams calldata guessPtOut
     ) internal returns (uint256 netPtOut, uint256 netSyFee) {
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
 
         (netPtOut, ) = state.approxSwapExactSyForPt(
             YT.newIndex(),