ISuperToken

This is the technical reference related to the interface for Super Tokens.

Implementation addresses​

Super Token deployments work in a proxy pattern with the original implementation being comon between all super tokens for each chain. The implementation address for the SuperToken is different for each network and can be found in the SuperTokenFactory at the method getSuperTokenLogic.

To get the addresses of all the SuperTokenFactory contracts, you can use the Tagomi Explorer, section Protocol.

ABI​

In order to interact with any contract satistying the ISuperToken interface, you can use the following ABI:

Functions​

Fn initialize​

function initialize(
    contract IERC20 underlyingToken,
    uint8 underlyingDecimals,
    string n,
    string s
) 
    external

Initialize the contract

Parameters​

Fn initializeWithAdmin​

function initializeWithAdmin(
    contract IERC20 underlyingToken,
    uint8 underlyingDecimals,
    string n,
    string s,
    address admin
) 
    external

Initialize the contract with an admin

Parameters​

Fn changeAdmin​

function changeAdmin(
    address newAdmin
) 
    external

Only the current admin can call this function if admin is address(0), it is implicitly the host address

Parameters​

Changes the admin for the SuperToken

Fn getAdmin​

function getAdmin(
) 
    external 
    returns (address admin)

Returns the admin address for the SuperToken

Fn CONSTANT_OUTFLOW_NFT​

function CONSTANT_OUTFLOW_NFT(
) 
    external 
    returns (contract IConstantOutflowNFT)

Fn CONSTANT_INFLOW_NFT​

function CONSTANT_INFLOW_NFT(
) 
    external 
    returns (contract IConstantInflowNFT)

Fn POOL_ADMIN_NFT​

function POOL_ADMIN_NFT(
) 
    external 
    returns (contract IPoolAdminNFT)

Fn POOL_MEMBER_NFT​

function POOL_MEMBER_NFT(
) 
    external 
    returns (contract IPoolMemberNFT)

Fn name​

function name(
) 
    external 
    returns (string)

Returns the name of the token.

Fn symbol​

function symbol(
) 
    external 
    returns (string)

Returns the symbol of the token, usually a shorter version of the name.

Fn decimals​

function decimals(
) 
    external 
    returns (uint8)

_Returns the number of decimals used to get its user representation. For example, if decimals equals 2, a balance of 505 tokens should be displayed to a user as 5,05 (505 / 10 ** 2).

Tokens usually opt for a value of 18, imitating the relationship between Ether and Wei. This is the value ERC20 uses, unless setupDecimals is called.

Note​

SuperToken always uses 18 decimals.

This information is only used for display purposes: it in no way affects any of the arithmetic of the contract, including IBEP20-balanceOf and IBEP20-transfer.

Fn totalSupply​

function totalSupply(
) 
    external 
    returns (uint256)

See IBEP20-totalSupply.

Fn balanceOf​

function balanceOf(
    address account
) 
    external 
    returns (uint256 balance)

Returns the amount of tokens owned by an account (owner).

Parameters​

Fn transfer​

function transfer(
    address recipient,
    uint256 amount
) 
    external 
    returns (bool)

Moves amount tokens from the caller's account to recipient.

Parameters​

Return Values​

Emits​

a BEP20 Transfer event.

Fn allowance​

function allowance(
    address owner,
    address spender
) 
    external 
    returns (uint256)

Returns the remaining number of tokens that spender will be allowed to spend on behalf of owner through transferFrom. This is zero by default.

Parameters​

This value changes when approve or transferFrom are called.

Fn approve​

function approve(
    address spender,
    uint256 amount
) 
    external 
    returns (bool)

Sets amount as the allowance of spender over the caller's tokens.

Parameters​

Return Values​

Note​

Beware that changing an allowance with this method brings the risk that someone may use both the old and the new allowance by unfortunate transaction ordering. One possible solution to mitigate this race condition is to first reduce the spender's allowance to 0 and set the desired value afterwards

Emits​

an Approval event.

Fn transferFrom​

function transferFrom(
    address sender,
    address recipient,
    uint256 amount
) 
    external 
    returns (bool)

Moves amount tokens from sender to recipient using the allowance mechanism. amount is then deducted from the caller's allowance.

Parameters​

Return Values​

Emits​

a Transfer event.

Fn increaseAllowance​

function increaseAllowance(
    address spender,
    uint256 addedValue
) 
    external 
    returns (bool)

_Atomically increases the allowance granted to spender by the caller.

This is an alternative to approve that can be used as a mitigation for problems described in IBEP20-approve._

Parameters​

Emits​

an Approval event indicating the updated allowance.

@custom:requirements

• `spender` cannot be the zero address.

Fn decreaseAllowance​

function decreaseAllowance(
    address spender,
    uint256 subtractedValue
) 
    external 
    returns (bool)

_Atomically decreases the allowance granted to spender by the caller.

This is an alternative to approve that can be used as a mitigation for problems described in IBEP20-approve._

Parameters​

Emits​

an Approval event indicating the updated allowance.

@custom:requirements

• `spender` cannot be the zero address.

• `spender` must have allowance for the caller of at least `subtractedValue`.

Fn granularity​

function granularity(
) 
    external 
    returns (uint256)

Returns the smallest part of the token that is not divisible. This means all token operations (creation, movement and destruction) must have amounts that are a multiple of this number.

Note​

For super token contracts, this value is always 1

Fn send​

function send(
    address recipient,
    uint256 amount,
    bytes userData
) 
    external

_Moves amount tokens from the caller's account to recipient.

If send or receive hooks are registered for the caller and recipient, the corresponding functions will be called with userData and empty operatorData. See IERC777Sender and IERC777Recipient._

Parameters​

Emits​

a Sent event.

@custom:requirements

• the caller must have at least `amount` tokens.

• `recipient` cannot be the zero address.

• if `recipient` is a contract, it must implement the IERC777Recipient interface.

Fn burn​

function burn(
    uint256 amount,
    bytes userData
) 
    external

_Destroys amount tokens from the caller's account, reducing the total supply and transfers the underlying token to the caller's account.

If a send hook is registered for the caller, the corresponding function will be called with userData and empty operatorData. See IERC777Sender._

Parameters​

Emits​

a Burned event.

@custom:requirements

• the caller must have at least `amount` tokens.

Fn isOperatorFor​

function isOperatorFor(
    address operator,
    address tokenHolder
) 
    external 
    returns (bool)

_Returns true if an account is an operator of tokenHolder. Operators can send and burn tokens on behalf of their owners. All accounts are their own operator.

See operatorSend and operatorBurn._

Parameters​

Fn authorizeOperator​

function authorizeOperator(
    address operator
) 
    external

_Make an account an operator of the caller.

See isOperatorFor._

Parameters​

Emits​

an AuthorizedOperator event.

@custom:requirements

• `operator` cannot be calling address.

Fn revokeOperator​

function revokeOperator(
    address operator
) 
    external

_Revoke an account's operator status for the caller.

See isOperatorFor and defaultOperators._

Parameters​

Emits​

a RevokedOperator event.

@custom:requirements

• `operator` cannot be calling address.

Fn defaultOperators​

function defaultOperators(
) 
    external 
    returns (address[])

_Returns the list of default operators. These accounts are operators for all token holders, even if authorizeOperator was never called on them.

This list is immutable, but individual holders may revoke these via revokeOperator, in which case isOperatorFor will return false._

Fn operatorSend​

function operatorSend(
    address sender,
    address recipient,
    uint256 amount,
    bytes userData,
    bytes operatorData
) 
    external

_Moves amount tokens from sender to recipient. The caller must be an operator of sender.

If send or receive hooks are registered for sender and recipient, the corresponding functions will be called with userData and operatorData. See IERC777Sender and IERC777Recipient._

Parameters​

Emits​

a Sent event.

@custom:requirements

• `sender` cannot be the zero address.

• `sender` must have at least `amount` tokens.

• the caller must be an operator for `sender`.

• `recipient` cannot be the zero address.

• if `recipient` is a contract, it must implement the IERC777Recipient interface.

Fn operatorBurn​

function operatorBurn(
    address account,
    uint256 amount,
    bytes userData,
    bytes operatorData
) 
    external

_Destroys amount tokens from account, reducing the total supply. The caller must be an operator of account.

If a send hook is registered for account, the corresponding function will be called with userData and operatorData. See IERC777Sender._

Parameters​

Emits​

a Burned event.

@custom:requirements

• `account` cannot be the zero address.

• `account` must have at least `amount` tokens.

• the caller must be an operator for `account`.

Fn selfMint​

function selfMint(
    address account,
    uint256 amount,
    bytes userData
) 
    external

_Mint new tokens for the account If userData is not empty, the tokensReceived hook is invoked according to ERC777 semantics.

@custom:modifiers

• onlySelf_

Parameters​

Fn selfBurn​

function selfBurn(
    address account,
    uint256 amount,
    bytes userData
) 
    external

_Burn existing tokens for the account If userData is not empty, the tokensToSend hook is invoked according to ERC777 semantics.

@custom:modifiers

• onlySelf_

Parameters​

Fn selfTransferFrom​

function selfTransferFrom(
    address sender,
    address spender,
    address recipient,
    uint256 amount
) 
    external

_Transfer amount tokens from the sender to recipient. If spender isn't the same as sender, checks if spender has allowance to spend tokens of sender.

@custom:modifiers

• onlySelf_

Parameters​

Fn selfApproveFor​

function selfApproveFor(
    address account,
    address spender,
    uint256 amount
) 
    external

_Give spender, amount allowance to spend the tokens of account.

@custom:modifiers

• onlySelf_

Parameters​

Fn transferAll​

function transferAll(
    address recipient
) 
    external

Transfer all available balance from msg.sender to recipient

Parameters​

Fn getUnderlyingToken​

function getUnderlyingToken(
) 
    external 
    returns (address tokenAddr)

Return the underlying token contract

Return Values​

Fn getUnderlyingDecimals​

function getUnderlyingDecimals(
) 
    external 
    returns (uint8 underlyingDecimals)

Return the underlying token decimals

Return Values​

Fn toUnderlyingAmount​

function toUnderlyingAmount(
    uint256 amount
) 
    external 
    returns (uint256 underlyingAmount, uint256 adjustedAmount)

Return the underlying token conversion rate

Parameters​

Return Values​

Fn upgrade​

function upgrade(
    uint256 amount
) 
    external

Upgrade ERC20 to SuperToken.

Parameters​

Note​

It will use `transferFrom` to get tokens. Before calling this function you should `approve` this contract

Fn upgradeTo​

function upgradeTo(
    address to,
    uint256 amount,
    bytes userData
) 
    external

Upgrade BEP20 to SuperToken and transfer immediately

Parameters​

Note​

It will use `transferFrom` to get tokens. Before calling this function you should `approve` this contract

@custom:warning

• there is potential of reentrancy IF the "to" account is a registered ERC777 recipient. @custom:requirements

• if `userData` is NOT empty AND `to` is a contract, it MUST be a registered ERC777 recipient otherwise it reverts.

Fn downgrade​

function downgrade(
    uint256 amount
) 
    external

Downgrade SuperToken to ERC20. It will call transfer to send tokens

Parameters​

Fn downgradeTo​

function downgradeTo(
    address to,
    uint256 amount
) 
    external

Downgrade SuperToken to BEP20 and transfer immediately

Parameters​

Fn operationApprove​

function operationApprove(
    address account,
    address spender,
    uint256 amount
) 
    external

Perform BEP20 approve by host contract.

Parameters​

@custom:modifiers

• onlyHost |

Fn operationIncreaseAllowance​

function operationIncreaseAllowance(
    address account,
    address spender,
    uint256 addedValue
) 
    external

Parameters​

Fn operationDecreaseAllowance​

function operationDecreaseAllowance(
    address account,
    address spender,
    uint256 subtractedValue
) 
    external

Parameters​

Fn operationTransferFrom​

function operationTransferFrom(
    address account,
    address spender,
    address recipient,
    uint256 amount
) 
    external

Perform ERC20 transferFrom by host contract.

Parameters​

@custom:modifiers

• onlyHost |

Fn operationSend​

function operationSend(
    address spender,
    address recipient,
    uint256 amount,
    bytes userData
) 
    external

Perform ERC777 send by host contract.

Parameters​

@custom:modifiers

• onlyHost |

Fn operationUpgrade​

function operationUpgrade(
    address account,
    uint256 amount
) 
    external

Upgrade ERC20 to SuperToken by host contract.

Parameters​

@custom:modifiers

• onlyHost |

Fn operationDowngrade​

function operationDowngrade(
    address account,
    uint256 amount
) 
    external

Downgrade ERC20 to SuperToken by host contract.

Parameters​

@custom:modifiers

• onlyHost |

Events​

Event AdminChanged​

event AdminChanged(
    address oldAdmin,
    address newAdmin
)

Parameters​

Event TokenUpgraded​

event TokenUpgraded(
    address account,
    uint256 amount
)

Token upgrade event

Parameters​

Event TokenDowngraded​

event TokenDowngraded(
    address account,
    uint256 amount
)

Token downgrade event

Parameters​

Event ConstantOutflowNFTCreated​

event ConstantOutflowNFTCreated(
    contract IConstantOutflowNFT constantOutflowNFT
)

Constant Outflow NFT proxy created event

Parameters​

Event ConstantInflowNFTCreated​

event ConstantInflowNFTCreated(
    contract IConstantInflowNFT constantInflowNFT
)

Constant Inflow NFT proxy created event

Parameters​

Event PoolAdminNFTCreated​

event PoolAdminNFTCreated(
    contract IPoolAdminNFT poolAdminNFT
)

Pool Admin NFT proxy created event

Parameters​

Event PoolMemberNFTCreated​

event PoolMemberNFTCreated(
    contract IPoolMemberNFT poolMemberNFT
)

Pool Member NFT proxy created event

Parameters​

Error Codes​

SUPER_TOKEN_CALLER_IS_NOT_OPERATOR_FOR_HOLDER​

error SUPER_TOKEN_CALLER_IS_NOT_OPERATOR_FOR_HOLDER()

SUPER_TOKEN_NOT_ERC777_TOKENS_RECIPIENT​

error SUPER_TOKEN_NOT_ERC777_TOKENS_RECIPIENT()

SUPER_TOKEN_INFLATIONARY_DEFLATIONARY_NOT_SUPPORTED​

error SUPER_TOKEN_INFLATIONARY_DEFLATIONARY_NOT_SUPPORTED()

SUPER_TOKEN_NO_UNDERLYING_TOKEN​

error SUPER_TOKEN_NO_UNDERLYING_TOKEN()

SUPER_TOKEN_ONLY_SELF​

error SUPER_TOKEN_ONLY_SELF()

SUPER_TOKEN_ONLY_ADMIN​

error SUPER_TOKEN_ONLY_ADMIN()

SUPER_TOKEN_ONLY_GOV_OWNER​

error SUPER_TOKEN_ONLY_GOV_OWNER()

SUPER_TOKEN_APPROVE_FROM_ZERO_ADDRESS​

error SUPER_TOKEN_APPROVE_FROM_ZERO_ADDRESS()

SUPER_TOKEN_APPROVE_TO_ZERO_ADDRESS​

error SUPER_TOKEN_APPROVE_TO_ZERO_ADDRESS()

SUPER_TOKEN_BURN_FROM_ZERO_ADDRESS​

error SUPER_TOKEN_BURN_FROM_ZERO_ADDRESS()

SUPER_TOKEN_MINT_TO_ZERO_ADDRESS​

error SUPER_TOKEN_MINT_TO_ZERO_ADDRESS()

SUPER_TOKEN_TRANSFER_FROM_ZERO_ADDRESS​

error SUPER_TOKEN_TRANSFER_FROM_ZERO_ADDRESS()

SUPER_TOKEN_TRANSFER_TO_ZERO_ADDRESS​

error SUPER_TOKEN_TRANSFER_TO_ZERO_ADDRESS()

SUPER_TOKEN_NFT_PROXY_ADDRESS_CHANGED​

error SUPER_TOKEN_NFT_PROXY_ADDRESS_CHANGED()