ERC3156 - Flash Loans

EIPS/eip-3156.md

@@ -0,0 +1,283 @@
+---
+eip: 3156
+title: Flash Loans
+author: Alberto Cuesta Cañada (@albertocuestacanada), Fiona Kobayashi (@fifikobayashi), fubuloubu (@fubuloubu)
+discussions-to: https://ethereum-magicians.org/t/flash-loan-eip-early-draft/4993/2
+status: Draft
+type: Standards Track
+category: ERC
+created: 2020-11-15
+---
+
+## Simple Summary
+
+This ERC provides standard interfaces and processes for flash lenders and borrowers, allowing for flash loan integration without a need to consider each particular implementation.
+
+## Motivation
+
+Flash loans allow smart contracts to lend an amount of tokens without a requirement for collateral, with the condition that they must be returned within the same transaction.
+
+Early adopters of the flash loan pattern, such as [Aave](https://github.com/aave/aave-protocol/blob/e8d020e9752fbd4807a3b55f9cf98a88dcfb674d/contracts/flashloan), [DxDy](https://help.dydx.exchange/en/articles/3724602-flash-loans), [Uniswap](https://uniswap.org/docs/v2/core-concepts/flash-swaps/) and the [Yield Protocol](https://github.com/yieldprotocol/fyDai/blob/master/contracts/FYDai.sol) have produced different interfaces and different use patterns. The diversification is expected to intensify, and with it the technical debt required to integrate with diverse flash lending patterns.
+
+Some of the high level diferences in the approaches across the protocols include:
+- Repayment approaches at the end of the transaction, where Aave V2 pulls the flash loaned amount plus the flash fee off the flash smart contract, compared to other protocols where the contract needs to explicitly calculate the debt+fee amount and manually return it to the lending pool.
+- Uniswap's Flash Swaps offer the ability to repay the flash transaction using a token that is different to what was originally flash borrowed, which can reduce the overall complexity of the flash transaction and gas fees, depending on the purpose of the flash swap (i.e. the second last step in flash self liquidation to swap back into the repayment token).
+- DyDx offering a single entry point into the protocol regardless of whether you're buying, selling, depositing or chaining them together as a flash loan, whereas other protocols offer discrete entry points (e.g. Uniswap V2's swap() and Aave V2's flashLoan() methods).
+- The Yield Protocol allows to flash mint any amount of its native token without charging a fee, effectively allowing flash loans bounded by computational constraints instead of asset ownership constraints.
+
+## Specification
+
+A flash lending feature integrates two smart contracts using a callback pattern. These are called the LENDER and the RECEIVER in this EIP.
+
+A `receiver` of flash mints MUST implement an `onFlashLoan` callback:
+
+```
+interface FlashBorrowerLike {
+    function onFlashLoan(address sender, uint256 amount, uint256 fee, bytes calldata) external;
+}
+```
+
+On the callback execution the `receiver` MUST have received `amount` tokens from the caller. The `receiver` can trust that `sender` is the account that initiated the flash loan in the caller. For the transaction to not revert, `receiver` MUST send `amount + fee` to the caller. Before that, the `receiver` can implement any logic it desires.
+
+The token contract implementing a flash lending feature MUST implement a `flashLoan` function:
+
+```
+function flashLoan(address receiver, uint256 amount, bytes calldata data) external {
+  ...
+  FlashBorrowerLike(receiver).onFlashLoan(msg.sender, amount, fee, data);
+  ...
+}
+```
+
+The `flashLoan` function MUST execute the equivalent of an `ERC20.transfer` operation before calling `FlashBorrowerLike(receiver).onFlashLoan(...)`.
+
+The lender contract MAY `mint` the tokens lended, instead of executing a `transfer` of tokens it holds.
+
+The `flashLoan` function MUST verify that the tokens lended were returned, and MUST NOT take them from the `receiver`.
+
+The `receiver` MUST take an action to return `amount + fee` tokens and allow the transaction to resolve.
+
+If the `flashLoan` used tokens generated by a `mint`, they SHOULD be the target of a `burn` before the end of the transaction.
+
+If a fee is charged, the contract implementing `flashLoan` MAY use it in any desired way (e.g. the fee can be burned or transferred to any other party).
+
+## Rationale
+
+The interfaces described in this ERC have been chosen as to cover the known flash lending use cases, while allowing for safe and gas efficient implementations.
+
+`flashLoan(address receiver, uint256 amount, bytes calldata data)`
+
+`flashLoan` has been chosen as descriptive enough, unlikely to clash with other functions in the lender, and including both the use cases in which the tokens lended are held or minted by the lender.
+
+`receiver` is taken as a parameter to allow `flashLoan` to be called by EOAs, as opposed to the pattern in which `onFlashLoan` is called on `msg.sender`. This allows the lender to inform the `receiver` which address called `flashLoan`. This particular setup allows the `receiver` to implement an account based platform.
+
+A `bytes calldata data` parameter is included for the caller to pass arbitrary information to the `receiver`, without impacting the utility of the `flashMint` standard.
+
+`onFlashLoan(msg.sender, amount, fee, data)`
+
+`onFlashLoan` has been chosen as descriptive enough, unlikely to clash with other functions in the `receiver`, and following the `onAction` naming pattern used as well in EIP-667.
+
+A `user` will often be required in the `onFlashLoan` function, which the lender knows as `msg.sender`. An alternative implementation which would embed the `user` in the `data` parameter by the caller would require an additional mechanism for the receiver to verify its accuracy, and is not advisable.
+
+The `amount` will be required in the `onFlashLoan` function, which the lender took as a parameter. An alternative implementation which would embed the `amount` in the `data` parameter by the caller would require an additional mechanism for the receiver to verify its accuracy, and is not advisable.
+
+A `fee` will often be calculated in the `flashMint` function, which the `receiver` must be aware of for repayment. Passing the `fee` as a parameter instead of appended to `data` is simple and effective.
+
+
+## Backwards Compatibility
+
+No backwards compatibility issues identified.
+
+## Test Cases
+
+The test cases of the reference implementation are available from the [ERC20Flash repository](https://github.com/albertocuestacanada/ERC20Flash/tree/main/test).
+
+## Implementation
+
+The reference implementations included inline can also be found at the [ERC20Flash repository](https://github.com/albertocuestacanada/ERC20Flash).
+
+Other implementations include [WETH10](https://github.com/WETH10/WETH10/pull/81) and [MakerDAO MIP-25](https://github.com/hexonaut/dss-flash/pull/18).
+
+### Flash Mint Reference Implementation
+
+```
+// SPDX-License-Identifier: GPL-3.0-or-later
+pragma solidity ^0.7.5;
+
+import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
+import "@openzeppelin/contracts/math/SafeMath.sol";
+
+
+interface flashBorrowerLike {
+    function onFlashLoan(address user, uint256 value, uint256 fee, bytes calldata) external;
+}
+
+/**
+ * @author Alberto Cuesta Cañada
+ * @dev Extension of {ERC20} that allows flash minting.
+ */
+contract ERC20FlashMint is ERC20 {
+    using SafeMath for uint256;
+
+    uint256 public fee;
+
+    constructor (string memory name, string memory symbol, uint256 fee_) ERC20(name, symbol) {
+        fee = fee_;
+    }
+
+    /**
+     * @dev Loan `value` tokens to `receiver`, which needs to return them plus a 0.1% fee to this contract within the same transaction.
+     * @param receiver The contract receiving the tokens, needs to implement the `onFlashLoan(address user, uint256 value, uint256 fee, bytes calldata)` interface.
+     * @param value The amount of tokens lent.
+     * @param data A data parameter to be passed on to the `receiver` for any custom use.
+     */
+    function flashLoan(address receiver, uint256 value, bytes calldata data) external {
+        uint256 _fee = value.div(fee);
+        _mint(receiver, value);
+        flashBorrowerLike(receiver).onFlashLoan(msg.sender, value, _fee, data);
+        _burn(address(this), value.add(_fee));
+    }
+}
+```
+
+```
+// SPDX-License-Identifier: GPL-3.0-or-later
+pragma solidity ^0.7.5;
+
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "@openzeppelin/contracts/math/SafeMath.sol";
+
+contract FlashBorrower {
+  using SafeMath for uint256;
+  IERC20 public currency;
+
+  constructor (IERC20 currency_) {
+      currency = currency_;
+  }
+
+  function onFlashLoan(address user, uint256 value, uint256 fee, bytes calldata) external {
+    // do something with the tokens received
+
+    currency.transfer(msg.sender, value.add(fee));
+  }
+}
+```
+
+### Flash Loan Reference Implementation
+
+```
+// SPDX-License-Identifier: GPL-3.0-or-later
+pragma solidity ^0.7.5;
+
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "@openzeppelin/contracts/math/SafeMath.sol";
+
+
+interface flashBorrowerLike {
+    function onFlashLoan(address user, uint256 value, uint256 fee, bytes calldata) external;
+}
+
+/**
+ * @author Alberto Cuesta Cañada
+ * @dev Extension of {ERC20} that allows flash lending.
+ */
+contract FlashLender {
+    using SafeMath for uint256;
+
+    IERC20 public immutable currency;
+    uint256 public fee;
+
+    constructor(IERC20 currency_, uint256 fee_) {
+        currency = currency_;
+        fee = fee_;
+    }
+
+    /**
+     * @dev Loan `value` tokens to `receiver`, which needs to return them plus a 0.1% fee to this contract within the same transaction.
+     * @param receiver The contract receiving the tokens, needs to implement the `onFlashLoan(address user, uint256 value, uint256 fee, bytes calldata)` interface.
+     * @param value The amount of tokens lent.
+     * @param data A data parameter to be passed on to the `receiver` for any custom use.
+     */
+    function flashLoan(address receiver, uint256 value, bytes calldata data) external {
+        uint256 _fee = fee == type(uint256).max ? 0 : value.div(fee);
+        uint256 balanceTarget = currency.balanceOf(address(this)).add(_fee);
+        currency.transfer(receiver, value);
+        flashBorrowerLike(receiver).onFlashLoan(msg.sender, value, _fee, data);
+        require(currency.balanceOf(address(this)) >= balanceTarget, "FlashLender: unpaid loan");
+    }
+}
+```
+
+```
+// SPDX-License-Identifier: GPL-3.0-or-later
+pragma solidity ^0.7.5;
+
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "@openzeppelin/contracts/math/SafeMath.sol";
+
+contract FlashBorrower {
+  using SafeMath for uint256;
+  IERC20 public currency;
+
+  constructor (IERC20 flashLender_, IERC20 currency_) {
+      currency = currency_;
+  }
+
+  function onFlashLoan(address user, uint256 value, uint256 fee, bytes calldata) external {
+    // do something with the tokens received
+
+    currency.transfer(msg.sender, value.add(fee));
+  }
+}
+```
+
+## Security Considerations
+
+### Flash lending security considerations
+
+#### Example - Transfer from receiver
+An implementation that allows flash lending to an arbitrary target, and that also takes the flash loaned amount from such target at the end of the transaction can be used to drain assets of a smart contract that trades a pair of assets based on internal balances.
+1. The attacker triggers a flash loan of 1 million DAI to an AMM trading DAI/ETH.
+2. The attacker sells 1000 ETH to the AMM trading pair, obtaining a larger amount of DAI than the pre-transaction price would have returned.
+3. The flash lender burns the 1 million DAI (plus possibly a fee) from the receiver (AMM trading pair), which bears the loss of having sold DAI to the attacker at an artificially depressed price.
+
+The key takeaway being that smart contracts trading on balances should not give blanket transfer approvals to smart contracts with flash loan features, unless they can be certain of their implementation.    
+
+### Flash minting external security considerations
+
+The typical quantum of tokens involved in flash mint transactions will give rise to new innovative attack vectors.
+
+#### Example 1 - interest rate attack
+If there exists a lending protocol that offers stable interests rates, but it does not have floor/ceiling rate limits and it does not rebalance the fixed rate based on flash-induced liquidity changes, then it could be susceptible to the following scenario:
+
+FreeLoanAttack.sol
+1. Flash mint 1 quintillion DAI
+2. Deposit the 1 quintillion DAI + $1.5 million worth of ETH collateral
+3. The quantum of your total deposit now pushes the stable interest rate down to 0.00001% stable interest rate
+4. Borrow 1 million DAI on 0.00001% stable interest rate based on the 1.5M ETH collateral
+5. Withdraw and burn the 1 quint DAI to close the original flash mint
+6. You now have a 1 million DAI loan that is practically interest free for perpetuity ($0.10 / year in interest)
+
+The key takeaway being the obvious need to implement a flat floor/ceiling rate limit and to rebalance the rate based on short term liquidity changes.
+
+#### Example 2 - arithmetic overflow and underflow
+If the flash mint provider does not place any limits on the amount of flash mintable tokens in a transaction, then anyone can flash mint 2^256-1 amount of tokens. 
+
+The protocols on the receiving end of the flash mints will need to ensure their contracts can handle this. One obvious way is to leverage OpenZeppelin's SafeMath libraries as a catch-all safety net, however consideration should be given to when it is or isn't used given the gas tradeoffs.
+
+If you recall there was a series of incidents in 2018 where exchanges such as OKEx, Poloniex, HitBTC and Huobi had to shutdown deposits and withdrawls of ERC20 tokens due to integer overflows within the ERC20 token contracts.
+
+
+### Flash minting internal security considerations
+
+The coupling of flash minting with business specific features in the same platform can easily lead to unintended consequences.
+
+#### Example - Treasury draining
+In early implementations of the Yield Protocol flash loaned fyDai could be redeemed for Dai, which could be used to liquidate the Yield Protocol CDP vault in MakerDAO:
+1. Flash mint a very large amount of fyDai.
+2. Redeem for Dai as much fyDai as the Yield Protocol collateral would allow.
+3. Trigger a stability rate increase with a call to `jug.drip` which would make the Yield Protocol uncollateralized.
+4. Liquidate the Yield Protocol CDP vault in MakerDAO.
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).