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:

Click here to show ISuperToken ABI

Functions​

Fn initialize​

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

Initialize the contract

Parameters​

Name	Type	Description
underlyingToken	contract IERC20
underlyingDecimals	uint8
n	string
s	string

Fn initializeWithAdmin​

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

Initialize the contract with an admin

Parameters​

Name	Type	Description
underlyingToken	contract IERC20
underlyingDecimals	uint8
n	string
s	string
admin	address

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​

Name	Type	Description
newAdmin	address	New admin address

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​

Name	Type	Description
account	address

Fn transfer​

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

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

Parameters​

Name	Type	Description
recipient	address
amount	uint256

Return Values​

Name	Type	Description
[0]	bool	Returns Success a boolean value indicating whether the operation succeeded.

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​

Name	Type	Description
owner	address
spender	address

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​

Name	Type	Description
spender	address
amount	uint256

Return Values​

Name	Type	Description
[0]	bool	Returns Success a boolean value indicating whether the operation succeeded.

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​

Name	Type	Description
sender	address
recipient	address
amount	uint256

Return Values​

Name	Type	Description
[0]	bool	Returns Success a boolean value indicating whether the operation succeeded.

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​

Name	Type	Description
spender	address
addedValue	uint256

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​

Name	Type	Description
spender	address
subtractedValue	uint256

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​

Name	Type	Description
recipient	address
amount	uint256
userData	bytes

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​

Name	Type	Description
amount	uint256
userData	bytes

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​

Name	Type	Description
operator	address
tokenHolder	address

Fn authorizeOperator​

function authorizeOperator(
    address operator
) 
    external

_Make an account an operator of the caller.

See isOperatorFor._

Parameters​

Name	Type	Description
operator	address

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​

Name	Type	Description
operator	address

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​

Name	Type	Description
sender	address
recipient	address
amount	uint256
userData	bytes
operatorData	bytes

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​

Name	Type	Description
account	address
amount	uint256
userData	bytes
operatorData	bytes

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​

Name	Type	Description
account	address
amount	uint256
userData	bytes

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​

Name	Type	Description
account	address
amount	uint256
userData	bytes

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​

Name	Type	Description
sender	address
spender	address
recipient	address
amount	uint256

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​

Name	Type	Description
account	address
spender	address
amount	uint256

Fn transferAll​

function transferAll(
    address recipient
) 
    external

Transfer all available balance from msg.sender to recipient

Parameters​

Name	Type	Description
recipient	address

Fn getUnderlyingToken​

function getUnderlyingToken(
) 
    external 
    returns (address tokenAddr)

Return the underlying token contract

Return Values​

Name	Type	Description
tokenAddr	address	Underlying token address

Fn getUnderlyingDecimals​

function getUnderlyingDecimals(
) 
    external 
    returns (uint8 underlyingDecimals)

Return the underlying token decimals

Return Values​

Name	Type	Description
underlyingDecimals	uint8	Underlying token decimals

Fn toUnderlyingAmount​

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

Return the underlying token conversion rate

Parameters​

Name	Type	Description
amount	uint256	Number of tokens to be upgraded (in 18 decimals)

Return Values​

Name	Type	Description
underlyingAmount	uint256	The underlying token amount after scaling
adjustedAmount	uint256	The super token amount after scaling

Fn upgrade​

function upgrade(
    uint256 amount
) 
    external

Upgrade ERC20 to SuperToken.

Parameters​

Name	Type	Description
amount	uint256	Number of tokens to be upgraded (in 18 decimals)

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​

Name	Type	Description
to	address	The account to receive upgraded tokens
amount	uint256	Number of tokens to be upgraded (in 18 decimals)
userData	bytes	User data for the TokensRecipient callback

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​

Name	Type	Description
amount	uint256	Number of tokens to be downgraded

Fn downgradeTo​

function downgradeTo(
    address to,
    uint256 amount
) 
    external

Downgrade SuperToken to BEP20 and transfer immediately

Parameters​

Name	Type	Description
to	address	The account to receive downgraded tokens
amount	uint256	Number of tokens to be downgraded (in 18 decimals)

Fn operationApprove​

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

Perform BEP20 approve by host contract.

Parameters​

Name	Type	Description
account	address	The account owner to be approved.
spender	address	The spender of account owner's funds.
amount	uint256	Number of tokens to be approved.

@custom:modifiers

• onlyHost |

Fn operationIncreaseAllowance​

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

Parameters​

Name	Type	Description
account	address
spender	address
addedValue	uint256

Fn operationDecreaseAllowance​

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

Parameters​

Name	Type	Description
account	address
spender	address
subtractedValue	uint256

Fn operationTransferFrom​

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

Perform ERC20 transferFrom by host contract.

Parameters​

Name	Type	Description
account	address	The account to spend sender's funds.
spender	address	The account where the funds is sent from.
recipient	address	The recipient of the funds.
amount	uint256	Number of tokens to be transferred.

@custom:modifiers

• onlyHost |

Fn operationSend​

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

Perform ERC777 send by host contract.

Parameters​

Name	Type	Description
spender	address	The account where the funds is sent from.
recipient	address	The recipient of the funds.
amount	uint256	Number of tokens to be transferred.
userData	bytes	Arbitrary user inputted data

@custom:modifiers

• onlyHost |

Fn operationUpgrade​

function operationUpgrade(
    address account,
    uint256 amount
) 
    external

Upgrade ERC20 to SuperToken by host contract.

Parameters​

Name	Type	Description
account	address	The account to be changed.
amount	uint256	Number of tokens to be upgraded (in 18 decimals)

@custom:modifiers

• onlyHost |

Fn operationDowngrade​

function operationDowngrade(
    address account,
    uint256 amount
) 
    external

Downgrade ERC20 to SuperToken by host contract.

Parameters​

Name	Type	Description
account	address	The account to be changed.
amount	uint256	Number of tokens to be downgraded (in 18 decimals)

@custom:modifiers

• onlyHost |

Events​

Event AdminChanged​

event AdminChanged(
    address oldAdmin,
    address newAdmin
)

Parameters​

Name	Type	Description
oldAdmin	address
newAdmin	address

Event TokenUpgraded​

event TokenUpgraded(
    address account,
    uint256 amount
)

Token upgrade event

Parameters​

Name	Type	Description
account	address	Account where tokens are upgraded to
amount	uint256	Amount of tokens upgraded (in 18 decimals)

Event TokenDowngraded​

event TokenDowngraded(
    address account,
    uint256 amount
)

Token downgrade event

Parameters​

Name	Type	Description
account	address	Account whose tokens are downgraded
amount	uint256	Amount of tokens downgraded

Event ConstantOutflowNFTCreated​

event ConstantOutflowNFTCreated(
    contract IConstantOutflowNFT constantOutflowNFT
)

Constant Outflow NFT proxy created event

Parameters​

Name	Type	Description
constantOutflowNFT	contract IConstantOutflowNFT	constant outflow nft address

Event ConstantInflowNFTCreated​

event ConstantInflowNFTCreated(
    contract IConstantInflowNFT constantInflowNFT
)

Constant Inflow NFT proxy created event

Parameters​

Name	Type	Description
constantInflowNFT	contract IConstantInflowNFT	constant inflow nft address

Event PoolAdminNFTCreated​

event PoolAdminNFTCreated(
    contract IPoolAdminNFT poolAdminNFT
)

Pool Admin NFT proxy created event

Parameters​

Name	Type	Description
poolAdminNFT	contract IPoolAdminNFT	pool admin nft address

Event PoolMemberNFTCreated​

event PoolMemberNFTCreated(
    contract IPoolMemberNFT poolMemberNFT
)

Pool Member NFT proxy created event

Parameters​

Name	Type	Description
poolMemberNFT	contract IPoolMemberNFT	pool member nft address

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()