Internally-owned fungible Token Interface (TIP-3.2)

Requires: TIP-3.1

Abstract

The following standard describes token, where token wallets are owned internally by any Venom contract (e.g. multisignature wallet). Any operation, such as burn or transfer, can be initiated with the internal message from the owner contract.

Motivation

The TIP-3.1 standard describes the key architecture principles and some common methods for token contracts in the Venom network. While it does not answer the following questions:

• How to create token wallet
• How token wallets are owned
• How to transfer, mint or burn tokens
• How the tokens recipient can handle the incoming transfer, etc

Specification

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Notes

• Zero address is 0:0000000000000000000000000000000000000000000000000000000000000000

Token root

Token wallet address

Returns token wallet address, owned by owner. MUST NOT deploy token wallet.

function walletOf(address owner) external view responsible returns (address);

Deploy token wallet

Deploys token wallet, owned by owner. Returns token wallet address.

function deployWallet(
    address owner,
    uint128 deployWalletValue
) external responsible returns (address);

Mint tokens

Mints amount amount of tokens to the token wallet, owned by recipient.

If deployWalletValue is greater than 0, token root MUST deploy token wallet for recipient. Otherwise, it mints tokens without deploying token wallet, which may lead to failed minting.

Calls the acceptMint method on the recipient token wallet. If notify is true, than the onAcceptTokensMint callback message will be sent to the recipient.

function mint(
    uint128 amount,
    address recipient,
    uint128 deployWalletValue,
    address remainingGasTo,
    bool notify,
    TvmCell payload
) external;

Accept burn

Accepts burning amount amount of tokens from the token wallet, owned by walletOwner.

If callbackTo is zero address, than all the remaining gas is transferred to the remainingGasTo. Otherwise, message with onAcceptTokensBurn callback is sent to the callbackTo address.

Decreases the totalSupply by amount.

function acceptBurn(
    uint128 amount,
    address walletOwner,
    address remainingGasTo,
    address callbackTo,
    TvmCell payload
) external functionID(0x192B51B1);

Callbacks

Burn callback

Notifies the contract that the burn was accepted. MUST BE called from the token root.

function onAcceptTokensBurn(
    uint128 amount,
    address walletOwner,
    address wallet,
    address remainingGasTo,
    TvmCell payload
) external;

Token wallet

Owner

Returns the owner of the token wallet.

function owner() external view responsible returns (address);

Balance

Returns the token balance of the token wallet.

function balance() external view responsible returns (uint128);

Transfer tokens to the recipient

Transfers amount amount of tokens to the token wallet, owned by recipient. Token wallet address is derived automatically.

If deployWalletValue is greater than 0, token wallet MUST deploy token wallet for recipient.

Calls the acceptTransfer on the recipient token wallet. If notify is true, than the onAcceptTokensTransfer callback message will be sent to the recipient.

function transfer(
    uint128 amount,
    address recipient,
    uint128 deployWalletValue,
    address remainingGasTo,
    bool notify,
    TvmCell payload
) external;

Transfer tokens to the token wallet

Transfers amount amount of tokens to the recipientTokenWallet.

Calls the acceptTransfer on the recipientTokenWallet.

Decreases the token wallet balance by amount.

function transferToWallet(
    uint128 amount,
    address recipientTokenWallet,
    address remainingGasTo,
    bool notify,
    TvmCell payload
) external;

Burn tokens by token wallet owner

Decreases the token wallet balance by amount.

function burn(
    uint128 amount,
    address remainingGasTo,
    address callbackTo,
    TvmCell payload
) external;

Burn token by token root

Decreases the token wallet balance by amount.

function burnByRoot(
    uint128 amount,
    address remainingGasTo,
    address callbackTo,
    TvmCell payload
) external;

Accept mint

Accepts incoming mint for amount amount of tokens. MUST be reverted if msg.sender is not root.

Increases the token wallet balance by amount.

function acceptMint(
    uint128 amount,
    address remainingGasTo,
    bool notify,
    TvmCell payload
) external functionID(0x4384F298);

Accept transfer

Accepts incoming transfer for amount amount of tokens from token wallet, owned sender.

If notify is false, than the remaining gas MUST be sent to the remainingGasTo. Otherwise, the onAcceptTokensTransfer callback MUST be sent to the token wallet owner with the same remainingGasTo and payload.

Increases the token wallet balance by amount.

function acceptTransfer(
    uint128 amount,
    address sender,
    address remainingGasTo,
    bool notify,
    TvmCell payload
) external functionID(0x67A0B95F);

Callbacks

Incoming transfer callback

Notifies token wallet's owner that an incoming transfer was accepted.

function onAcceptTokensTransfer(
    address tokenRoot,
    uint128 amount,
    address sender,
    address senderWallet,
    address remainingGasTo,
    TvmCell payload
) external;

Mint callback

Notifies token wallet's owner that mint was accepted.

function onAcceptTokensMint(
    address tokenRoot,
    uint128 amount,
    address remainingGasTo,
    TvmCell payload
) external;

Bounced transfer callback

Notifies token wallet's owner that token transfer was bounced.

function onBounceTokensTransfer(
    address tokenRoot,
    uint128 amount,
    address revertedFrom
) external;

Bounced burn callback

Notifies token wallet's owner that burn was bounced.

function onBounceTokensBurn(
    address tokenRoot,
    uint128 amount
) external;

Implementation

• TIP-3 implementation by Broxus

References

info

The original TIP-3.2 standard was developed and maintained by the Everscale network community.