Jetton: How it works

This article describes the basic ideas and processes behind the implementation of Jettons (aka tokens in Ethereum) in the TON Blockchain.

Related smart contracts

Standardized tokens on TON (see TEPs 0074 and 0089) are implemented using a set of smart contracts, including:

• Jetton master (that is also called Jetton minter) smart contract;
• Jetton wallet smart contract.

It is important to keep in mind that Jetton standards provide only a general scheme of interaction, leaving the specific implementation of related contracts to developers.

Jetton master

Jetton master smart contracts store general information about a particular jetton, such as total supply (the total number of tokens of this type), a metadata link (or the metadata itself), and the code of the standard jetton-wallet smart contract for this jetton. They also have an owner (admin) who, by sending suitable messages to them, mints new tokens, closes the minting, changes metadata, or transfers the admin rights to another contract.

Jetton master contracts also receive notifications about the burning of tokens. When they receive such a notification, they must adjust the total supply accordingly.

Jetton wallet

Jetton wallet smart contracts are used to transfer, receive, and burn jettons. Each jetton wallet contract stores the wallet balance information for a specific user (owner), the address of the Jetton master contract (for appropriate minting), and some additional information. In certain cases, Jetton wallets are used for individual token holders for each token type.

Difference between Jetton wallets and regular ones

Although both regular wallets and Jetton wallets are smart contracts, there are some significant differences between them.

The regular wallets’ smart contracts are designed for off-chain interaction with their owner. In most implementations, their main purpose is to receive external messages and perform the operations requested in them. It is through a regular wallet that the user sends requests for the transfer of tokens or their burning to the Jetton wallet smart contract. They are designed to store only the native TON Blockchain currency: Toncoin (or TON).

On the other hand, Jetton wallet smart contracts are designed only for storing and processing tokens. They ignore any external messages and accept only special internal ones. They execute commands received only from the Jetton master, another Jetton wallet, or their owner’s regular wallet smart contracts.

Message layouts

Interactions with Jetton contracts, which users and developers most often encounter, are:

• tokens transfer: sending tokens from one Jetton wallet to another;
• tokens minting: minting new tokens and transferring them to the Jetton wallet;
• tokens burning: burn a certain number of tokens on the Jetton wallet contract;
• wallet address providing: find the address of the Jetton wallet corresponding to a regular wallet.

Token transfer

Actor A regular wallet -> actor A Jetton wallet. Transfer message contains the following data:

Name	Type	Description
query_id	uint64	Links the three messaging types—transfer, transfer notification, and excesses—to each other. To ensure this process works correctly, always use a unique query ID.
amount	VarUInteger 16	The total jetton amount to transfer.
destination	MsgAddress	The address of the actor B’s regular wallet.
response_destination	MsgAddress	The wallet address used to return remaining Toncoin through the excesses message.
custom_payload	Maybe ^Cell	The optional custom data used by either the sender or receiver jetton wallet for internal logic.
forward_ton_amount	VarUInteger 16	Toncoin to forward to the recipient. Must > 0 to send a transfer notification with forward_payload and must be less than the amount attached to this message.
forward_payload	Either Cell ^Cell	Optional data. If the first 32 bits equal 0x00000000, it is a text comment.

that meet the TL-B scheme specified in TEP 0074:

transfer#0f8a7ea5 query_id:uint64 amount:(VarUInteger 16) destination:MsgAddress
                 response_destination:MsgAddress custom_payload:(Maybe ^Cell)
                 forward_ton_amount:(VarUInteger 16) forward_payload:(Either Cell ^Cell)
                 = InternalMsgBody;

Actor A Jetton wallet -> actor B Jetton wallet. Internal transfer message contains the following data:

Name	Type	Description
query_id	uint64	Links the three messaging types—transfer, transfer notification, and excesses—to each other. To ensure this process works correctly, always use a unique query ID.
amount	VarUInteger 16	The total jetton amount to transfer.
sender	MsgAddress	The address of the actor A regular wallet.
response_destination	Maybe MsgAddress	The optional wallet address used to return remaining Toncoin through the excesses message.
forward_ton_amount	VarUInteger 16	Toncoin to forward to the recipient. Must > 0 to send a transfer notification with forward_payload and must be less than the amount attached to this message.
forward_payload	Either Cell ^Cell	Optional data. If the first 32 bits equal 0x00000000, it is a text comment.

that is not specified, but has a recommended TL-B scheme in TEP 0074:

internal_transfer#178d4519  query_id:uint64 amount:(VarUInteger 16) from:MsgAddress
                     response_address:MsgAddress
                     forward_ton_amount:(VarUInteger 16)
                     forward_payload:(Either Cell ^Cell)
                     = InternalMsgBody;

Actor B Jetton wallet → actor B regular wallet. The transfer notification message. This is sent only if forward_ton_amount is not zero and contains the following data:

Name	Type	Description
query_id	uint64	Links the three messaging types—transfer, transfer notification, and excesses—to each other. To ensure this process works correctly, always use a unique query ID.
amount	VarUInteger 16	The total jetton amount were transferred.
sender	MsgAddress	The address of the actor A regular wallet.
forward_payload	Either Cell ^Cell	Some data.

that meet the TL-B scheme specified in TEP 0074:

transfer_notification#7362d09c query_id:uint64 amount:(VarUInteger 16)
           sender:MsgAddress forward_payload:(Either Cell ^Cell)
           = InternalMsgBody;

Actor B Jetton wallet -> actor C smart contract. Excess message body. This is sent only if there are remaining Toncoin after paying the fees. Contains the following data:

Name	Type
query_id	uint64

that meet the TL-B scheme specified in TEP 0074:

excesses#d53276db query_id:uint64 = InternalMsgBody;

Token minting

Admin regular wallet -> Jetton master contract. Mint message contains the following data:

Name	Type	Description
query_id	uint64	To ensure this process works correctly, always use a unique query ID.
receiver	MsgAddress	The address of the actor A regular wallet.
mintMessage	Cell	The rest of the data as in an internal transfer message, except the query_id field.

The rest of the messages have already been described above when analyzing the transfer process.

Token burning

Actor A regular wallet -> actor A Jetton wallet. Burn message contains the following data:

Name	Type	Description
query_id	uint64	To ensure this process works correctly, always use a unique query ID.
amount	VarUInteger 16	The total jetton amount to burn.
response_destination	MsgAddress	The wallet address used to return remaining Toncoin through the excesses message.
custom_payload	Maybe ^Cell	The optional custom data used by the receiver jetton wallet for internal logic.

that meet a TL-B scheme in TEP 0074:

burn#595f07bc query_id:uint64 amount:(VarUInteger 16)
       response_destination:MsgAddress custom_payload:(Maybe ^Cell)
       = InternalMsgBody;

Actor A Jetton wallet -> Jetton master contract. Burn notification message contains the following data:

Name	Type	Description
query_id	uint64	To ensure this process works correctly, always use a unique query ID.
amount	VarUInteger 16	The total jetton amount was burned.
sender	MsgAddress	The address of the actor A regular wallet.
response_destination	MsgAddress	The wallet address used to return remaining Toncoin through the excesses message.

that is not specified but has a recommended TL-B scheme in TEP 0074:

burn_notification#7bdd97de query_id:uint64 amount:(VarUInteger 16)
       sender:MsgAddress response_destination:MsgAddress
       = InternalMsgBody;

Wallet address providing

This process is straightforward. Some actor sends to the Jetton master contract provide_wallet_address message that contains the following fields:

Name	Type	Description
query_id	uint64	To ensure this process works correctly, always use a unique query ID.
owner_address	MsgAddress	The address of the actor for which the Jetton wallet address is needed.
include_address	Bool	Whether to include the address of the actor himself in the output message.

Then, the Jetton master contract sends to the actor a message that contains the following fields:

Name	Type	Description
query_id	uint64	To ensure this process works correctly, always use a unique query ID.
wallet_address	MsgAddress	The Jetton wallet contract address.
owner_address	Maybe ^MsgAddress	The address of the owner.

These messages meet the corresponding TL-B schemes in TEP 0089:

provide_wallet_address#2c76b973 query_id:uint64 owner_address:MsgAddress
include_address:Bool = InternalMsgBody;

take_wallet_address#d1735400 query_id:uint64 wallet_address:MsgAddress
owner_address:(Maybe ^MsgAddress) = InternalMsgBody;

Interaction from UI

There are three actions that can be performed through the UI:

• getting wallet balance;
• transfer jettons;
• indexing available jettons.

Applications

The most popular user wallet applications, such as TonKeeper, use their own SQL-like database. When the user receives a new jetton for the first time, the application processes the transfer_notification message. Next, information about the number of jettons received is taken from it, and it is checked if there is information about this jetton in the applications database. If there is, information is added to the database stating that the user has a new type of jetton in the amount received. If not, the database starts indexing this new jetton, and after the validation process begins to show data about it to users. This is how all the jettons that a given user has and their amounts are listed.

For a user to transfer a given amount of a token to another user, they only need to fill in the destination and amount fields through the application. Next, it will automatically generate a transfer message and send it to the Jetton wallet associated with the user.

Web services

Various web services, such as Tonviewer, can also be used to obtain information about the types of user jettons and their amounts. Unlike wallet applications, they also have the ability to directly invoke the get methods of related smart contracts. However, they are not designed to generate and send messages.