The home for Hyperlane core contracts, sdk packages, and other infrastructure
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
hyperlane-monorepo/solidity/contracts/token/extensions/HypERC4626.sol

115 lines
3.5 KiB

feat: implementation of yield rebasing warp route contracts (#4203) ### Description - To reflect the rebased underlying asset, `_transferRemote` is overridden because we need to pass in the ERC4626 vault shares which on the synthetic `HypERC4626VaultYield` which change in value as the underlying vault shares accrue yield or receive a drawdown. - The exchangeRate (i.e., assets/shares) is encoded as metadata and sent to the synthetic token to calculate the value of the synthetic token. - On synthetic transfers, the overridden `ERC20.transfer()` function calculates the needed shares for the amount and transfers them instead. Design decisions - Do we need to rebase frequently? Yes, otherwise the exchangeRate on the synthetic token will be stale compared to the the actual vault claimable yield, which means a user who deposits later and right before the infrequent rebase will get disproportionate share of the yield. You can rebase by calling `rebase()` on the collateral token which makes a transferRemote call with 0 amount. - Why exchangeRate and not underlyingDepositedAmount on the synthetic? If a user withdraws (ie calls transferRemote on the synthetic) while a rebase is inflight, the underlyingDepositedAmount will get an inaccurate update (will be overreported and hence will derive inaccurate balance amounts on the synthetic. The exchangeRate doesn't change if the user is depositing or withdrawing. - Why override the `transfer` on the synthetic? Otherwise if a user A sends 100 USDC worth of shares to user B which has a exchange rate of 1.05, user A would have unwittingly sent 105 #tokens (5 excess). - What happens in a drawdown of the value? Once the user calls withdraws the the withdrawal they get out is accordingly discounted. If a user transfers on the synthetic, it will still gets the stale exchangeRate until rebase. - What if the owner of the vault charges a fee on the yield? In that case, you need to override the totalAssets to reflect the assets - feesByOwner and the warp route implementation will stay the same. One example implementation is `MockERC4626YieldSharing` and we have adequate tests to cover the functionality. - Rounding error? We're rounding down the exchangeRate as per the general recommendation for ERC4626 vault math. - Why not make the synthetic token an ERC4626 itself, given that there's some overlapping functionality? Even though, the assetsToShares and assetsToShares functions are the same, the synthetic token itself doesn't have an underlying token so it doesn't confer to the 4626 interface. - What if there are multiple synthetic tokens for a single rebasing collateral contract and what happens is the exchange rate is not in sync between the synthetics? Things to keep in mind for - How do I keep the exchangeRate in sync with the underlying vault? Keep calling rebase as a cron job frequently, or make a hook call in deposit, redeem, and withdraw function to automatically resync the exchangeRate. - 4626 math pitfalls: https://www.zellic.io/blog/exploring-erc-4626/ ### Drive-by changes - Renaming `HypERC20CollateralVaultDeposit` -> `HypERC4626OwnerYieldCollateral` ### Related issues - fixes https://github.com/hyperlane-xyz/issues/issues/1334 ### Backward compatibility Yes ### Testing Unit tests
3 months ago
// SPDX-License-Identifier: MIT OR Apache-2.0
pragma solidity >=0.8.0;
import {IXERC20} from "../interfaces/IXERC20.sol";
import {HypERC20} from "../HypERC20.sol";
import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
import {Message} from "../../libs/Message.sol";
import {TokenMessage} from "../libs/TokenMessage.sol";
import {TokenRouter} from "../libs/TokenRouter.sol";
/**
* @title Hyperlane ERC20 Rebasing Token
* @author Abacus Works
*/
contract HypERC4626 is HypERC20 {
using Math for uint256;
using Message for bytes;
using TokenMessage for bytes;
event ExchangeRateUpdated(uint256 newExchangeRate, uint32 rateUpdateNonce);
feat: implementation of yield rebasing warp route contracts (#4203) ### Description - To reflect the rebased underlying asset, `_transferRemote` is overridden because we need to pass in the ERC4626 vault shares which on the synthetic `HypERC4626VaultYield` which change in value as the underlying vault shares accrue yield or receive a drawdown. - The exchangeRate (i.e., assets/shares) is encoded as metadata and sent to the synthetic token to calculate the value of the synthetic token. - On synthetic transfers, the overridden `ERC20.transfer()` function calculates the needed shares for the amount and transfers them instead. Design decisions - Do we need to rebase frequently? Yes, otherwise the exchangeRate on the synthetic token will be stale compared to the the actual vault claimable yield, which means a user who deposits later and right before the infrequent rebase will get disproportionate share of the yield. You can rebase by calling `rebase()` on the collateral token which makes a transferRemote call with 0 amount. - Why exchangeRate and not underlyingDepositedAmount on the synthetic? If a user withdraws (ie calls transferRemote on the synthetic) while a rebase is inflight, the underlyingDepositedAmount will get an inaccurate update (will be overreported and hence will derive inaccurate balance amounts on the synthetic. The exchangeRate doesn't change if the user is depositing or withdrawing. - Why override the `transfer` on the synthetic? Otherwise if a user A sends 100 USDC worth of shares to user B which has a exchange rate of 1.05, user A would have unwittingly sent 105 #tokens (5 excess). - What happens in a drawdown of the value? Once the user calls withdraws the the withdrawal they get out is accordingly discounted. If a user transfers on the synthetic, it will still gets the stale exchangeRate until rebase. - What if the owner of the vault charges a fee on the yield? In that case, you need to override the totalAssets to reflect the assets - feesByOwner and the warp route implementation will stay the same. One example implementation is `MockERC4626YieldSharing` and we have adequate tests to cover the functionality. - Rounding error? We're rounding down the exchangeRate as per the general recommendation for ERC4626 vault math. - Why not make the synthetic token an ERC4626 itself, given that there's some overlapping functionality? Even though, the assetsToShares and assetsToShares functions are the same, the synthetic token itself doesn't have an underlying token so it doesn't confer to the 4626 interface. - What if there are multiple synthetic tokens for a single rebasing collateral contract and what happens is the exchange rate is not in sync between the synthetics? Things to keep in mind for - How do I keep the exchangeRate in sync with the underlying vault? Keep calling rebase as a cron job frequently, or make a hook call in deposit, redeem, and withdraw function to automatically resync the exchangeRate. - 4626 math pitfalls: https://www.zellic.io/blog/exploring-erc-4626/ ### Drive-by changes - Renaming `HypERC20CollateralVaultDeposit` -> `HypERC4626OwnerYieldCollateral` ### Related issues - fixes https://github.com/hyperlane-xyz/issues/issues/1334 ### Backward compatibility Yes ### Testing Unit tests
3 months ago
uint256 public constant PRECISION = 1e10;
uint32 public immutable collateralDomain;
uint256 public exchangeRate; // 1e10
uint32 public previousNonce;
feat: implementation of yield rebasing warp route contracts (#4203) ### Description - To reflect the rebased underlying asset, `_transferRemote` is overridden because we need to pass in the ERC4626 vault shares which on the synthetic `HypERC4626VaultYield` which change in value as the underlying vault shares accrue yield or receive a drawdown. - The exchangeRate (i.e., assets/shares) is encoded as metadata and sent to the synthetic token to calculate the value of the synthetic token. - On synthetic transfers, the overridden `ERC20.transfer()` function calculates the needed shares for the amount and transfers them instead. Design decisions - Do we need to rebase frequently? Yes, otherwise the exchangeRate on the synthetic token will be stale compared to the the actual vault claimable yield, which means a user who deposits later and right before the infrequent rebase will get disproportionate share of the yield. You can rebase by calling `rebase()` on the collateral token which makes a transferRemote call with 0 amount. - Why exchangeRate and not underlyingDepositedAmount on the synthetic? If a user withdraws (ie calls transferRemote on the synthetic) while a rebase is inflight, the underlyingDepositedAmount will get an inaccurate update (will be overreported and hence will derive inaccurate balance amounts on the synthetic. The exchangeRate doesn't change if the user is depositing or withdrawing. - Why override the `transfer` on the synthetic? Otherwise if a user A sends 100 USDC worth of shares to user B which has a exchange rate of 1.05, user A would have unwittingly sent 105 #tokens (5 excess). - What happens in a drawdown of the value? Once the user calls withdraws the the withdrawal they get out is accordingly discounted. If a user transfers on the synthetic, it will still gets the stale exchangeRate until rebase. - What if the owner of the vault charges a fee on the yield? In that case, you need to override the totalAssets to reflect the assets - feesByOwner and the warp route implementation will stay the same. One example implementation is `MockERC4626YieldSharing` and we have adequate tests to cover the functionality. - Rounding error? We're rounding down the exchangeRate as per the general recommendation for ERC4626 vault math. - Why not make the synthetic token an ERC4626 itself, given that there's some overlapping functionality? Even though, the assetsToShares and assetsToShares functions are the same, the synthetic token itself doesn't have an underlying token so it doesn't confer to the 4626 interface. - What if there are multiple synthetic tokens for a single rebasing collateral contract and what happens is the exchange rate is not in sync between the synthetics? Things to keep in mind for - How do I keep the exchangeRate in sync with the underlying vault? Keep calling rebase as a cron job frequently, or make a hook call in deposit, redeem, and withdraw function to automatically resync the exchangeRate. - 4626 math pitfalls: https://www.zellic.io/blog/exploring-erc-4626/ ### Drive-by changes - Renaming `HypERC20CollateralVaultDeposit` -> `HypERC4626OwnerYieldCollateral` ### Related issues - fixes https://github.com/hyperlane-xyz/issues/issues/1334 ### Backward compatibility Yes ### Testing Unit tests
3 months ago
constructor(
uint8 _decimals,
address _mailbox,
uint32 _collateralDomain
) HypERC20(_decimals, _mailbox) {
collateralDomain = _collateralDomain;
exchangeRate = 1e10;
_disableInitializers();
}
/// Override to send shares instead of assets from synthetic
/// @inheritdoc TokenRouter
function _transferRemote(
uint32 _destination,
bytes32 _recipient,
uint256 _amountOrId,
uint256 _value,
bytes memory _hookMetadata,
address _hook
) internal virtual override returns (bytes32 messageId) {
uint256 _shares = assetsToShares(_amountOrId);
_transferFromSender(_shares);
bytes memory _tokenMessage = TokenMessage.format(
_recipient,
_shares,
bytes("")
);
messageId = _Router_dispatch(
_destination,
_value,
_tokenMessage,
_hookMetadata,
_hook
);
emit SentTransferRemote(_destination, _recipient, _amountOrId);
}
function _handle(
uint32 _origin,
bytes32 _sender,
bytes calldata _message
) internal virtual override {
if (_origin == collateralDomain) {
(uint256 newExchangeRate, uint32 rateUpdateNonce) = abi.decode(
_message.metadata(),
(uint256, uint32)
);
// only update if the nonce is greater than the previous nonce
if (rateUpdateNonce > previousNonce) {
exchangeRate = newExchangeRate;
previousNonce = rateUpdateNonce;
emit ExchangeRateUpdated(exchangeRate, rateUpdateNonce);
}
feat: implementation of yield rebasing warp route contracts (#4203) ### Description - To reflect the rebased underlying asset, `_transferRemote` is overridden because we need to pass in the ERC4626 vault shares which on the synthetic `HypERC4626VaultYield` which change in value as the underlying vault shares accrue yield or receive a drawdown. - The exchangeRate (i.e., assets/shares) is encoded as metadata and sent to the synthetic token to calculate the value of the synthetic token. - On synthetic transfers, the overridden `ERC20.transfer()` function calculates the needed shares for the amount and transfers them instead. Design decisions - Do we need to rebase frequently? Yes, otherwise the exchangeRate on the synthetic token will be stale compared to the the actual vault claimable yield, which means a user who deposits later and right before the infrequent rebase will get disproportionate share of the yield. You can rebase by calling `rebase()` on the collateral token which makes a transferRemote call with 0 amount. - Why exchangeRate and not underlyingDepositedAmount on the synthetic? If a user withdraws (ie calls transferRemote on the synthetic) while a rebase is inflight, the underlyingDepositedAmount will get an inaccurate update (will be overreported and hence will derive inaccurate balance amounts on the synthetic. The exchangeRate doesn't change if the user is depositing or withdrawing. - Why override the `transfer` on the synthetic? Otherwise if a user A sends 100 USDC worth of shares to user B which has a exchange rate of 1.05, user A would have unwittingly sent 105 #tokens (5 excess). - What happens in a drawdown of the value? Once the user calls withdraws the the withdrawal they get out is accordingly discounted. If a user transfers on the synthetic, it will still gets the stale exchangeRate until rebase. - What if the owner of the vault charges a fee on the yield? In that case, you need to override the totalAssets to reflect the assets - feesByOwner and the warp route implementation will stay the same. One example implementation is `MockERC4626YieldSharing` and we have adequate tests to cover the functionality. - Rounding error? We're rounding down the exchangeRate as per the general recommendation for ERC4626 vault math. - Why not make the synthetic token an ERC4626 itself, given that there's some overlapping functionality? Even though, the assetsToShares and assetsToShares functions are the same, the synthetic token itself doesn't have an underlying token so it doesn't confer to the 4626 interface. - What if there are multiple synthetic tokens for a single rebasing collateral contract and what happens is the exchange rate is not in sync between the synthetics? Things to keep in mind for - How do I keep the exchangeRate in sync with the underlying vault? Keep calling rebase as a cron job frequently, or make a hook call in deposit, redeem, and withdraw function to automatically resync the exchangeRate. - 4626 math pitfalls: https://www.zellic.io/blog/exploring-erc-4626/ ### Drive-by changes - Renaming `HypERC20CollateralVaultDeposit` -> `HypERC4626OwnerYieldCollateral` ### Related issues - fixes https://github.com/hyperlane-xyz/issues/issues/1334 ### Backward compatibility Yes ### Testing Unit tests
3 months ago
}
super._handle(_origin, _sender, _message);
}
// Override to send shares locally instead of assets
function transfer(
address to,
uint256 amount
) public virtual override returns (bool) {
address owner = _msgSender();
_transfer(owner, to, assetsToShares(amount));
return true;
}
function shareBalanceOf(address account) public view returns (uint256) {
return super.balanceOf(account);
}
function balanceOf(
address account
) public view virtual override returns (uint256) {
uint256 _balance = super.balanceOf(account);
return sharesToAssets(_balance);
}
function assetsToShares(uint256 _amount) public view returns (uint256) {
return _amount.mulDiv(PRECISION, exchangeRate);
}
function sharesToAssets(uint256 _shares) public view returns (uint256) {
return _shares.mulDiv(exchangeRate, PRECISION);
}
}