IUsdn
Inherits: IERC20, IERC20Metadata, IERC20Permit, IUsdnEvents, IUsdnErrors
Implements the ERC-20 token standard as well as the EIP-2612 permit extension. Additional functions related to the specifics of this token are included below.
Functions
totalShares
Returns the total number of shares in existence.
function totalShares() external view returns (uint256 shares_);
Returns
| Name | Type | Description |
|---|---|---|
shares_ | uint256 | The number of shares. |
sharesOf
Returns the number of shares owned by account.
function sharesOf(address account) external view returns (uint256 shares_);
Parameters
| Name | Type | Description |
|---|---|---|
account | address | The account to query. |
Returns
| Name | Type | Description |
|---|---|---|
shares_ | uint256 | The number of shares. |
transferShares
Transfers a given amount of shares from the msg.sender to to.
function transferShares(address to, uint256 value) external returns (bool success_);
Parameters
| Name | Type | Description |
|---|---|---|
to | address | Recipient of the shares. |
value | uint256 | Number of shares to transfer. |
Returns
| Name | Type | Description |
|---|---|---|
success_ | bool | Indicates whether the transfer was successfully executed. |
transferSharesFrom
Transfers a given amount of shares from the from to to.
There should be sufficient allowance for the spender. Be mindful of the rebase logic. The allowance is in
tokens. So, after a rebase, the same amount of shares will be worth a higher amount of tokens. In that case,
the allowance of the initial approval will not be enough to transfer the new amount of tokens. This can
also happen when your transaction is in the mempool and the rebase happens before your transaction. Also note
that the amount of tokens deduced from the allowance is rounded up, so the convertToTokensRoundUp function
should be used when converting shares into an allowance value.
function transferSharesFrom(address from, address to, uint256 value) external returns (bool success_);
Parameters
| Name | Type | Description |
|---|---|---|
from | address | The owner of the shares. |
to | address | Recipient of the shares. |
value | uint256 | Number of shares to transfer. |
Returns
| Name | Type | Description |
|---|---|---|
success_ | bool | Indicates whether the transfer was successfully executed. |
mint
Mints new shares, providing a token value.
Caller must have the MINTER_ROLE.
function mint(address to, uint256 amount) external;
Parameters
| Name | Type | Description |
|---|---|---|
to | address | Account to receive the new shares. |
amount | uint256 | Amount of tokens to mint, is internally converted to the proper shares amounts. |
mintShares
Mints new shares, providing a share value.
Caller must have the MINTER_ROLE.
function mintShares(address to, uint256 amount) external returns (uint256 mintedTokens_);
Parameters
| Name | Type | Description |
|---|---|---|
to | address | Account to receive the new shares. |
amount | uint256 | Amount of shares to mint. |
Returns
| Name | Type | Description |
|---|---|---|
mintedTokens_ | uint256 | Amount of tokens that were minted (informational). |
burn
Destroys a value amount of tokens from the caller, reducing the total supply.
function burn(uint256 value) external;
Parameters
| Name | Type | Description |
|---|---|---|
value | uint256 | Amount of tokens to burn, is internally converted to the proper shares amounts. |
burnFrom
Destroys a value amount of tokens from account, deducting from the caller's allowance.
function burnFrom(address account, uint256 value) external;
Parameters
| Name | Type | Description |
|---|---|---|
account | address | Account to burn tokens from. |
value | uint256 | Amount of tokens to burn, is internally converted to the proper shares amounts. |
burnShares
Destroys a value amount of shares from the caller, reducing the total supply.
function burnShares(uint256 value) external;
Parameters
| Name | Type | Description |
|---|---|---|
value | uint256 | Amount of shares to burn. |
burnSharesFrom
Destroys a value amount of shares from account, deducting from the caller's allowance.
There should be sufficient allowance for the spender. Be mindful of the rebase logic. The allowance is in
tokens. So, after a rebase, the same amount of shares will be worth a higher amount of tokens. In that case,
the allowance of the initial approval will not be enough to transfer the new amount of tokens. This can
also happen when your transaction is in the mempool and the rebase happens before your transaction. Also note
that the amount of tokens deduced from the allowance is rounded up, so the convertToTokensRoundUp function
should be used when converting shares into an allowance value.
function burnSharesFrom(address account, uint256 value) external;
Parameters
| Name | Type | Description |
|---|---|---|
account | address | Account to burn shares from. |
value | uint256 | Amount of shares to burn. |
convertToShares
Converts a number of tokens to the corresponding amount of shares.
The conversion reverts with UsdnMaxTokensExceeded if the corresponding amount of shares overflows.
function convertToShares(uint256 amountTokens) external view returns (uint256 shares_);
Parameters
| Name | Type | Description |
|---|---|---|
amountTokens | uint256 | The amount of tokens to convert to shares. |
Returns
| Name | Type | Description |
|---|---|---|
shares_ | uint256 | The corresponding amount of shares. |
convertToTokens
Converts a number of shares to the corresponding amount of tokens.
The conversion never overflows as we are performing a division. The conversion rounds to the nearest amount of tokens that minimizes the error when converting back to shares.
function convertToTokens(uint256 amountShares) external view returns (uint256 tokens_);
Parameters
| Name | Type | Description |
|---|---|---|
amountShares | uint256 | The amount of shares to convert to tokens. |
Returns
| Name | Type | Description |
|---|---|---|
tokens_ | uint256 | The corresponding amount of tokens. |
convertToTokensRoundUp
Converts a number of shares to the corresponding amount of tokens, rounding up.
Use this function to determine the amount of a token approval, as we always round up when deducting from a token transfer allowance.
function convertToTokensRoundUp(uint256 amountShares) external view returns (uint256 tokens_);
Parameters
| Name | Type | Description |
|---|---|---|
amountShares | uint256 | The amount of shares to convert to tokens. |
Returns
| Name | Type | Description |
|---|---|---|
tokens_ | uint256 | The corresponding amount of tokens, rounded up. |
maxTokens
Returns the current maximum tokens supply, given the current divisor.
This function is used to check if a conversion operation would overflow.
function maxTokens() external view returns (uint256 maxTokens_);
Returns
| Name | Type | Description |
|---|---|---|
maxTokens_ | uint256 | The maximum number of tokens that can exist. |
rebase
Decreases the global divisor, which effectively grows all balances and the total supply.
If the provided divisor is larger than or equal to the current divisor value, no rebase will happen
If the new divisor is smaller than MIN_DIVISOR, the value will be clamped to MIN_DIVISOR.
Caller must have the REBASER_ROLE.
function rebase(uint256 newDivisor)
external
returns (bool rebased_, uint256 oldDivisor_, bytes memory callbackResult_);
Parameters
| Name | Type | Description |
|---|---|---|
newDivisor | uint256 | The new divisor, should be strictly smaller than the current one and greater or equal to MIN_DIVISOR. |
Returns
| Name | Type | Description |
|---|---|---|
rebased_ | bool | Whether a rebase happened. |
oldDivisor_ | uint256 | The previous value of the divisor. |
callbackResult_ | bytes | The result of the callback, if a rebase happened and a callback handler is defined. |
setRebaseHandler
Sets the rebase handler address.
Emits a RebaseHandlerUpdated event.
If set to the zero address, no handler will be called after a rebase.
Caller must have the DEFAULT_ADMIN_ROLE.
function setRebaseHandler(IRebaseCallback newHandler) external;
Parameters
| Name | Type | Description |
|---|---|---|
newHandler | IRebaseCallback | The new handler address. |
divisor
Gets the current value of the divisor that converts between tokens and shares.
function divisor() external view returns (uint256 divisor_);
Returns
| Name | Type | Description |
|---|---|---|
divisor_ | uint256 | The current divisor. |
rebaseHandler
Gets the rebase handler address, which is called whenever a rebase happens.
function rebaseHandler() external view returns (IRebaseCallback rebaseHandler_);
Returns
| Name | Type | Description |
|---|---|---|
rebaseHandler_ | IRebaseCallback | The rebase handler address. |
MINTER_ROLE
Gets the minter role signature.
function MINTER_ROLE() external pure returns (bytes32 minter_role_);
Returns
| Name | Type | Description |
|---|---|---|
minter_role_ | bytes32 | The role signature. |
REBASER_ROLE
Gets the rebaser role signature.
function REBASER_ROLE() external pure returns (bytes32 rebaser_role_);
Returns
| Name | Type | Description |
|---|---|---|
rebaser_role_ | bytes32 | The role signature. |
MAX_DIVISOR
Gets the maximum value of the divisor, which is also the initial value.
function MAX_DIVISOR() external pure returns (uint256 maxDivisor_);
Returns
| Name | Type | Description |
|---|---|---|
maxDivisor_ | uint256 | The maximum divisor. |
MIN_DIVISOR
Gets the minimum acceptable value of the divisor.
The minimum divisor that can be set. This corresponds to a growth of 1B times. Technically, 1e5 would still work without precision errors.
function MIN_DIVISOR() external pure returns (uint256 minDivisor_);
Returns
| Name | Type | Description |
|---|---|---|
minDivisor_ | uint256 | The minimum divisor. |