From 2bf33b524ffe4183f6e0a581f3ff6b6109ec24ae Mon Sep 17 00:00:00 2001 From: Jeff Wu Date: Fri, 17 Dec 2021 06:13:13 -0800 Subject: [PATCH] adding some additional documentation --- .../mainnet/connectors/notional/helpers.sol | 62 +++++++++++-------- .../mainnet/connectors/notional/interface.sol | 6 ++ 2 files changed, 43 insertions(+), 25 deletions(-) diff --git a/contracts/mainnet/connectors/notional/helpers.sol b/contracts/mainnet/connectors/notional/helpers.sol index 6f76fad3..2eba6522 100644 --- a/contracts/mainnet/connectors/notional/helpers.sol +++ b/contracts/mainnet/connectors/notional/helpers.sol @@ -14,38 +14,44 @@ contract Helpers is Basic { uint8 internal constant BORROW_TRADE = 1; int256 internal constant INTERNAL_TOKEN_PRECISION = 1e8; uint256 internal constant ETH_CURRENCY_ID = 1; + uint256 internal constant MAX_DEPOSIT = uint256(-1); + /// @dev Contract address is different on Kovan: 0x0EAE7BAdEF8f95De91fDDb74a89A786cF891Eb0e NotionalInterface internal constant notional = NotionalInterface(0x1344A36A1B56144C3Bc62E7757377D288fDE0369); + /// @notice Returns the address of the underlying token for a given currency id, function getUnderlyingToken(uint16 currencyId) internal returns (address) { - (, Token memory underlyingToken) = notional.getCurrency(currencyId); + ( + /* Token memory assetToken */, + Token memory underlyingToken + ) = notional.getCurrency(currencyId); return underlyingToken.tokenAddress; } + /// @notice Returns the address of the asset token for a given currency id function getAssetToken(uint16 currencyId) internal returns (address) { - (Token memory assetToken, ) = notional.getCurrency(currencyId); + ( + Token memory assetToken, + /* Token memory underlyingToken */ + ) = notional.getCurrency(currencyId); return assetToken.tokenAddress; } - function getCashBalance(uint16 currencyId) - internal - returns (int256 cashBalance) - { - (cashBalance, , ) = notional.getAccountBalance( - currencyId, - address(this) - ); + function getCashBalance(uint16 currencyId) internal returns (int256 cashBalance) { + ( + cashBalance, + /* int256 nTokenBalance */, + /* int256 lastClaimTime */ + ) = notional.getAccountBalance(currencyId, address(this)); } - function getNTokenBalance(uint16 currencyId) - internal - returns (int256 nTokenBalance) - { - (, nTokenBalance, ) = notional.getAccountBalance( - currencyId, - address(this) - ); + function getNTokenBalance(uint16 currencyId) internal returns (int256 nTokenBalance) { + ( + /* int256 cashBalance */, + nTokenBalance, + /* int256 lastClaimTime */ + ) = notional.getAccountBalance(currencyId, address(this)); } function convertToInternal(uint16 currencyId, int256 amount) @@ -56,7 +62,7 @@ contract Helpers is Basic { // down to the internal precision. Resulting dust will accumulate to the protocol. // If token decimals is less than INTERNAL_TOKEN_PRECISION then this will add zeros to the // end of amount and will not result in dust. - (Token memory assetToken, ) = notional.getCurrency(currencyId); + (Token memory assetToken, /* underlyingToken */) = notional.getCurrency(currencyId); if (assetToken.decimals == INTERNAL_TOKEN_PRECISION) return amount; return amount.mul(INTERNAL_TOKEN_PRECISION).div(assetToken.decimals); } @@ -85,6 +91,8 @@ contract Helpers is Basic { (bytes32(uint256(maxBorrowRate)) << 120); } + /// @dev Uses getId to set approval for the given token up to the specified deposit + /// amount only function getDepositAmountAndSetApproval( uint256 getId, uint16 currencyId, @@ -92,16 +100,18 @@ contract Helpers is Basic { uint256 depositAmount ) internal returns (uint256) { depositAmount = getUint(getId, depositAmount); - if (currencyId == ETH_CURRENCY_ID && useUnderlying) - return - depositAmount == uint256(-1) - ? address(this).balance - : depositAmount; + if (currencyId == ETH_CURRENCY_ID && useUnderlying) { + // No approval required for ETH so we can return the deposit amount + return depositAmount == MAX_DEPOSIT + ? address(this).balance + : depositAmount; + } address tokenAddress = useUnderlying ? getUnderlyingToken(currencyId) : getAssetToken(currencyId); - if (depositAmount == uint256(-1)) { + + if (depositAmount == MAX_DEPOSIT) { depositAmount = TokenInterface(tokenAddress).balanceOf( address(this) ); @@ -132,6 +142,7 @@ contract Helpers is Basic { : getAssetToken(currencyId); } + /// @dev Executes a trade action and sets the balance change to setId function executeTradeActionWithBalanceChange( BalanceActionWithTrades[] memory action, uint256 msgValue, @@ -157,6 +168,7 @@ contract Helpers is Basic { } } + /// @dev Executes a balance action and sets the balance change to setId function executeActionWithBalanceChange( BalanceAction[] memory action, uint256 msgValue, diff --git a/contracts/mainnet/connectors/notional/interface.sol b/contracts/mainnet/connectors/notional/interface.sol index e6430d1a..a86c894f 100644 --- a/contracts/mainnet/connectors/notional/interface.sol +++ b/contracts/mainnet/connectors/notional/interface.sol @@ -66,10 +66,16 @@ struct BalanceAction { } struct Token { + // Address of the token address tokenAddress; + // True if the token has a transfer fee which is used internally to determine + // the proper balance change bool hasTransferFee; + // Decimal precision of the token as a power of 10 int256 decimals; + // Type of token, enumerated above TokenType tokenType; + // Used internally for tokens that have a collateral cap, zero if there is no cap uint256 maxCollateralBalance; }