From 3c14d90f7da68e6aa9b7df027a3a6fde7a0fc479 Mon Sep 17 00:00:00 2001 From: Roman Date: Wed, 4 Oct 2023 21:46:56 +0400 Subject: [PATCH 1/3] Add docstrings --- contracts/compound/WidoCollateralSwap_Aave.sol | 2 ++ contracts/compound/WidoCollateralSwap_ERC3156.sol | 2 ++ contracts/compound/libraries/LibCollateralSwap.sol | 2 ++ 3 files changed, 6 insertions(+) diff --git a/contracts/compound/WidoCollateralSwap_Aave.sol b/contracts/compound/WidoCollateralSwap_Aave.sol index 664fcba..98991ec 100644 --- a/contracts/compound/WidoCollateralSwap_Aave.sol +++ b/contracts/compound/WidoCollateralSwap_Aave.sol @@ -11,6 +11,8 @@ import {IComet} from "./interfaces/IComet.sol"; import {LibCollateralSwap} from "./libraries/LibCollateralSwap.sol"; import {IWidoCollateralSwap} from "./interfaces/IWidoCollateralSwap.sol"; +/// @title WidoCollateralSwap_Aave +/// @notice Contract enables swaps between arbitrary tokens and leverages Aave's flash loan services. contract WidoCollateralSwap_Aave is IFlashLoanSimpleReceiver, IWidoCollateralSwap { using SafeMath for uint256; diff --git a/contracts/compound/WidoCollateralSwap_ERC3156.sol b/contracts/compound/WidoCollateralSwap_ERC3156.sol index 926976e..1688d23 100644 --- a/contracts/compound/WidoCollateralSwap_ERC3156.sol +++ b/contracts/compound/WidoCollateralSwap_ERC3156.sol @@ -9,6 +9,8 @@ import {IComet} from "./interfaces/IComet.sol"; import {LibCollateralSwap} from "./libraries/LibCollateralSwap.sol"; import {IWidoCollateralSwap} from "./interfaces/IWidoCollateralSwap.sol"; +/// @title WidoCollateralSwap_ERC3156 +/// @notice Contract enables swaps between arbitrary tokens and integrates ERC-3156 compliant flash loan services. contract WidoCollateralSwap_ERC3156 is IERC3156FlashBorrower, IWidoCollateralSwap { using SafeMath for uint256; diff --git a/contracts/compound/libraries/LibCollateralSwap.sol b/contracts/compound/libraries/LibCollateralSwap.sol index 3b61c8d..3f5749a 100644 --- a/contracts/compound/libraries/LibCollateralSwap.sol +++ b/contracts/compound/libraries/LibCollateralSwap.sol @@ -6,6 +6,8 @@ import {IERC20} from "@openzeppelin/contracts/interfaces/IERC20.sol"; import {SafeMath} from "@openzeppelin/contracts/utils/math/SafeMath.sol"; import {IComet} from "../interfaces/IComet.sol"; +/// @title LibCollateralSwap Library +/// @notice Supports swapping collateral assets on Compound V3 via Wido's contracts, flash loans and Aave's services. library LibCollateralSwap { using SafeMath for uint256; From 2fc86ba6e17bf00429e2409f60647294e1b1cc2b Mon Sep 17 00:00:00 2001 From: Roman Date: Fri, 6 Oct 2023 12:09:31 +0400 Subject: [PATCH 2/3] Add docstrings to public functions --- contracts/compound/WidoCollateralSwap_ERC3156.sol | 11 +++++++++-- contracts/compound/libraries/LibCollateralSwap.sol | 4 ++++ 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/contracts/compound/WidoCollateralSwap_ERC3156.sol b/contracts/compound/WidoCollateralSwap_ERC3156.sol index 1688d23..04aca91 100644 --- a/contracts/compound/WidoCollateralSwap_ERC3156.sol +++ b/contracts/compound/WidoCollateralSwap_ERC3156.sol @@ -55,8 +55,15 @@ contract WidoCollateralSwap_ERC3156 is IERC3156FlashBorrower, IWidoCollateralSwa ); } - /// @notice Callback to be executed by the flash loan provider - /// @dev Only allow-listed providers should have access + /// @notice The function performs a collateral swap, after checking the legitimacy of the loan provider. + /// After the swap, it approves the loan provider to withdraw the borrowed amount and the fee. + /// @dev This function is the callback executed by the flash loan provider after loan disbursement. + /// Only allowed providers can initiate the callback. + /// @param borrowedAsset The address of the asset that has been borrowed. + /// @param borrowedAmount The amount of the asset that has been borrowed. + /// @param fee The fee associated with the borrowed asset. + /// @param data Encoded payload provided by the flash loan initiator containing details for the swap. + /// @return Returns the standard flash loan response of the callback function. function onFlashLoan( address /* initiator */, address borrowedAsset, diff --git a/contracts/compound/libraries/LibCollateralSwap.sol b/contracts/compound/libraries/LibCollateralSwap.sol index 3f5749a..4b7680c 100644 --- a/contracts/compound/libraries/LibCollateralSwap.sol +++ b/contracts/compound/libraries/LibCollateralSwap.sol @@ -36,6 +36,10 @@ library LibCollateralSwap { } /// @dev Performs all the steps to swap collaterals on the Comet contract + /// @param borrowedAsset The address of the asset that has been borrowed. + /// @param borrowedAmount The amount of the asset that has been borrowed. + /// @param fee The fee associated with the borrowed asset. + /// @param data The encoded payload containing details required for the swap. function performCollateralSwap( address borrowedAsset, uint256 borrowedAmount, From f487ebb2ce83adf40d2d5f08e6cee35ab0c11717 Mon Sep 17 00:00:00 2001 From: Kunal Date: Sat, 7 Oct 2023 06:14:53 +0000 Subject: [PATCH 3/3] Update comments --- contracts/compound/WidoCollateralSwap_Aave.sol | 10 ++++++---- contracts/compound/WidoCollateralSwap_ERC3156.sol | 11 ++++++----- contracts/compound/libraries/LibCollateralSwap.sol | 8 ++++---- 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/contracts/compound/WidoCollateralSwap_Aave.sol b/contracts/compound/WidoCollateralSwap_Aave.sol index bc8dd32..e8e1263 100644 --- a/contracts/compound/WidoCollateralSwap_Aave.sol +++ b/contracts/compound/WidoCollateralSwap_Aave.sol @@ -14,7 +14,9 @@ import {IWidoCollateralSwap} from "./interfaces/IWidoCollateralSwap.sol"; import {WidoRouter} from "../core/WidoRouter.sol"; /// @title WidoCollateralSwap_Aave -/// @notice Contract enables swaps between arbitrary tokens and leverages Aave's flash loan services. +/// @notice Contract allows swapping Compound collateral from one token (TokenA) to the other (TokenB) without +/// closing the borrowing position. The contract makes use of flash loans to first supply TokenB, +/// then withdraws TokenA and swaps it for TokenB and closes the flash loan. contract WidoCollateralSwap_Aave is IFlashLoanSimpleReceiver, IWidoCollateralSwap, ReentrancyGuard { using SafeMath for uint256; @@ -44,7 +46,7 @@ contract WidoCollateralSwap_Aave is IFlashLoanSimpleReceiver, IWidoCollateralSwa WIDO_TOKEN_MANAGER = address(WidoRouter(_widoRouter).widoTokenManager()); } - /// @notice Performs a collateral swap with Aave + /// @notice Performs a Compound collateral swap using flash loan from Aave. /// @param existingCollateral The collateral currently locked in the Comet contract /// @param finalCollateral The final collateral desired collateral /// @param sigs The required signatures to allow and revoke permission to this contract @@ -72,13 +74,13 @@ contract WidoCollateralSwap_Aave is IFlashLoanSimpleReceiver, IWidoCollateralSwa ); } - /// @notice Executes an operation after receiving the flash-borrowed asset + /// @notice Executes the collateral swap after receiving the flash-borrowed asset /// @dev Ensure that the contract can return the debt + premium, e.g., has /// enough funds to repay and has approved the Pool to pull the total amount /// @param asset The address of the flash-borrowed asset /// @param amount The amount of the flash-borrowed asset /// @param premium The fee of the flash-borrowed asset - /// @param params The byte-encoded params passed when initiating the flashloan + /// @param params The byte-encoded params for the collateral swap passed when initiating the flashloan /// @return True if the execution of the operation succeeds, false otherwise function executeOperation( address asset, diff --git a/contracts/compound/WidoCollateralSwap_ERC3156.sol b/contracts/compound/WidoCollateralSwap_ERC3156.sol index 015cd4c..8558003 100644 --- a/contracts/compound/WidoCollateralSwap_ERC3156.sol +++ b/contracts/compound/WidoCollateralSwap_ERC3156.sol @@ -12,7 +12,9 @@ import {IWidoCollateralSwap} from "./interfaces/IWidoCollateralSwap.sol"; import {WidoRouter} from "../core/WidoRouter.sol"; /// @title WidoCollateralSwap_ERC3156 -/// @notice Contract enables swaps between arbitrary tokens and integrates ERC-3156 compliant flash loan services. +/// @notice Contract allows swapping Compound collateral from one token (TokenA) to the other (TokenB) without +/// closing the borrowing position. The contract makes use of flash loans to first supply TokenB, +/// then withdraws TokenA and swaps it for TokenB and closes the flash loan. contract WidoCollateralSwap_ERC3156 is IERC3156FlashBorrower, IWidoCollateralSwap, ReentrancyGuard { using SafeMath for uint256; @@ -41,7 +43,7 @@ contract WidoCollateralSwap_ERC3156 is IERC3156FlashBorrower, IWidoCollateralSwa WIDO_TOKEN_MANAGER = address(WidoRouter(_widoRouter).widoTokenManager()); } - /// @notice Performs a collateral swap + /// @notice Performs a Compound collateral swap using an ERC3156 compliant flash loan provider. /// @param existingCollateral The collateral currently locked in the Comet contract /// @param finalCollateral The final collateral desired collateral /// @param sigs The required signatures to allow and revoke permission to this contract @@ -68,14 +70,13 @@ contract WidoCollateralSwap_ERC3156 is IERC3156FlashBorrower, IWidoCollateralSwa ); } - /// @notice The function performs a collateral swap, after checking the legitimacy of the loan provider. - /// After the swap, it approves the loan provider to withdraw the borrowed amount and the fee. + /// @notice Executes the collateral swap after receiving the flash-borrowed asset /// @dev This function is the callback executed by the flash loan provider after loan disbursement. /// Only allowed providers can initiate the callback. /// @param borrowedAsset The address of the asset that has been borrowed. /// @param borrowedAmount The amount of the asset that has been borrowed. /// @param fee The fee associated with the borrowed asset. - /// @param data Encoded payload provided by the flash loan initiator containing details for the swap. + /// @param params The byte-encoded params for the collateral swap passed when initiating the flashloan /// @return Returns the standard flash loan response of the callback function. function onFlashLoan( address initiator, diff --git a/contracts/compound/libraries/LibCollateralSwap.sol b/contracts/compound/libraries/LibCollateralSwap.sol index c63dad1..69933cf 100644 --- a/contracts/compound/libraries/LibCollateralSwap.sol +++ b/contracts/compound/libraries/LibCollateralSwap.sol @@ -7,7 +7,7 @@ import {SafeMath} from "@openzeppelin/contracts/utils/math/SafeMath.sol"; import {IComet} from "../interfaces/IComet.sol"; /// @title LibCollateralSwap Library -/// @notice Supports swapping collateral assets on Compound V3 via Wido's contracts, flash loans and Aave's services. +/// @notice Helper functions to swap collateral assets on Compound V3. library LibCollateralSwap { using SafeMath for uint256; @@ -36,7 +36,7 @@ library LibCollateralSwap { bytes callData; } - /// @dev Performs all the steps to swap collaterals on the Comet contract + /// @dev Performs supply, withdraw and swap steps to swap collaterals on the Comet contract /// @param borrowedAsset The address of the asset that has been borrowed. /// @param borrowedAmount The amount of the asset that has been borrowed. /// @param fee The fee associated with the borrowed asset. @@ -119,8 +119,8 @@ library LibCollateralSwap { } /// @dev This function withdraws the collateral from the user. - /// It requires two consecutive EIP712 signatures to allow and revoke - /// permissions to and from this contract. + /// It requires two consecutive EIP712 signatures to allow and revoke + /// permissions to and from this contract. function _withdrawFrom( IComet comet, address user,