@pendle/core-v2 0.16.6-testnet → 0.17.0-testnet

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(),

package/contracts/router/ActionSwapPTYT.sol

@@ -5,6 +5,7 @@ import "../interfaces/IPActionSwapPTYT.sol";
 import "../interfaces/IPMarket.sol";
 import "./base/CallbackHelper.sol";
 
+/// @dev All swap actions will revert if market is expired
 contract ActionSwapPTYT is IPActionSwapPTYT, CallbackHelper, TokenHelper {
     using MarketMathCore for MarketState;
     using MarketApproxPtInLib for MarketState;
@@ -19,6 +20,18 @@ contract ActionSwapPTYT is IPActionSwapPTYT, CallbackHelper, TokenHelper {
 
     }
 
+    /**
+     * @notice swap exact PT to YT with the help of flashswaps & YT tokenization / redemption
+     * @dev inner working of this function:
+     - `exactPtIn` PT is transferred to market contract
+     - `market.swapExactPtForSy` is called, which will transfer SY directly to YT contract & callback is invoked.
+        Note that we will owe PT, the amount before is not sufficient
+     - in callback, all SY in YT contract is used to mint PT + YT, with PT used to pay the rest of the loan, and YT
+        transferred to the receiver
+     * @param exactPtIn will always consume this amount of PT for as much YT as possible
+     * @param guessTotalPtToSwap approximation data for PT used for the PT-to-SY flashswap
+     * @dev this function works in conjunction with ActionCallback
+     */
     function swapExactPtForYt(
         address receiver,
         address market,
@@ -27,7 +40,7 @@ contract ActionSwapPTYT is IPActionSwapPTYT, CallbackHelper, TokenHelper {
         ApproxParams calldata guessTotalPtToSwap
     ) external returns (uint256 netYtOut, uint256 netSyFee) {
         (, IPPrincipalToken PT, IPYieldToken YT) = IPMarket(market).readTokens();
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
 
         _transferFrom(IERC20(PT), msg.sender, market, exactPtIn);
 
@@ -50,31 +63,43 @@ contract ActionSwapPTYT is IPActionSwapPTYT, CallbackHelper, TokenHelper {
         emit SwapPtAndYt(msg.sender, market, receiver, exactPtIn.neg(), netYtOut.Int());
     }
 
+    /**
+     * @notice swap exact YT to PT with the help of flashswaps & YT tokenization / redemption
+     * @dev inner working of this function:
+     - `exactYtIn` YT is transferred to yield contract
+     - `market.swapSyForExactPt` is called, which will transfer PT directly to this contract & callback is invoked.
+        Note that we now owe SY
+     - in callback, a portion of PT + YT is used to redeem SY, which is then used to payback the loan. The rest of 
+       of the PT is transferred to `receiver`
+     * @param exactYtIn will always consume this amount of YT for as much PT as possible
+     * @param guessTotalPtFromSwap approximation data for PT output of the SY-to-PT flashswap
+     * @dev this function works in conjunction with ActionCallback
+     */
     function swapExactYtForPt(
         address receiver,
         address market,
         uint256 exactYtIn,
         uint256 minPtOut,
-        ApproxParams calldata guessTotalPtSwapped
+        ApproxParams calldata guessTotalPtFromSwap
     ) external returns (uint256 netPtOut, uint256 netSyFee) {
         (, , IPYieldToken YT) = IPMarket(market).readTokens();
-        MarketState memory state = IPMarket(market).readState();
+        MarketState memory state = IPMarket(market).readState(address(this));
 
         _transferFrom(IERC20(YT), msg.sender, address(YT), exactYtIn);
 
-        uint256 totalPtSwapped;
-        (netPtOut, totalPtSwapped, netSyFee) = state.approxSwapExactYtForPt(
+        uint256 totalPtFromSwap;
+        (netPtOut, totalPtFromSwap, netSyFee) = state.approxSwapExactYtForPt(
             YT.newIndex(),
             exactYtIn,
             block.timestamp,
-            guessTotalPtSwapped
+            guessTotalPtFromSwap
         );
 
         if (netPtOut < minPtOut) revert Errors.RouterInsufficientPtOut(netPtOut, minPtOut);
 
         IPMarket(market).swapSyForExactPt(
             address(this),
-            totalPtSwapped,
+            totalPtFromSwap,
             _encodeSwapExactYtForPt(receiver, exactYtIn, minPtOut)
         );