Fungible tokens (Jettons) standard

[tolya-yanot]

⚠️ WARNING: Standards are now published and discussed in the TEPs repository. This page may be out of date.

Summary

A standard interface for Jettons (TON fungible tokens).

Motivation

A standard interface will greatly simplify interaction and display of different tokenized assets.

Jetton standard describes:

• The way of jetton transfers.

• The way of retrieving common information (name, circulating supply, etc) about given Jetton asset.

Specification

Here and following we use "Jetton" with capital J as designation for entirety of tokens of the same type, while "jetton" with j as designation of amount of tokens of some type.

Jettons are organized as follows: each Jetton has master smart-contract which is used to mint new jettons, account for circulating supply and provide common information.

At the same time information about amount of jettons owned by each user is stores in decentralized manner in individual (for each owner) smart-contracts called "jetton-wallets".

Example: if you release a Jetton with circulating supply of 200 jetton which are owned by 3 people, then you will deploy 4 contracts: 1 Jetton-master and 3 jetton-wallets.

Jetton wallet smart contract

Must implement:

Internal message handlers

1. transfer

Request

TL-B schema of inbound message:

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;

query_id - arbitrary request number.

amount - amount of transferred jettons in elementary units.

destination - address of the new owner of the jettons.

response_destination - address where to send a response with confirmation of a successful transfer and the rest of the incoming message Toncoins.

custom_payload - optional custom data (which is used by either sender or receiver jetton wallet for inner logic).

forward_ton_amount - the amount of nanotons to be sent to the destination address.

forward_payload - optional custom data that should be sent to the destination address.

Should be rejected if:

1. message is not from the owner.

2. there is no enough jettons on the sender wallet

3. there is no enough TON (with respect to jetton own storage fee guidelines and operation costs) to process operation, deploy receiver's jetton-wallet and send forward_ton_amount.

4. After processing the request, the receiver's jetton-wallet must send at least in_msg_value - forward_amount - 2 * max_tx_gas_price to the response_destination address.

   If the sender jetton-wallet cannot guarantee this, it must immediately stop executing the request and throw error.

   max_tx_gas_price is the price in Toncoins of maximum transaction gas limit of NFT habitat workchain. For the basechain it can be obtained from ConfigParam 21 from gas_limit field.

Otherwise should do:

1. decrease jetton amount on sender wallet by amount and send message which increase jetton amount on receiver wallet (and optionally deploy it).

2. if forward_amount > 0 ensure that receiver's jetton-wallet send message to destination address with forward_amount nanotons attached and with the following layout:

   TL-B schema:

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

`query_id` should be equal with request's `query_id`.

`amount` amount of transferred jettons.

`sender` is address of the previous owner of transferred jettons.

`forward_payload` should be equal with request's `forward_payload`.

If `forward_amount` is equal to zero, notification message should not be sent.

3. Receiver's wallet should send all excesses of incoming message coins to response_destination with the following layout:

   TL-B schema: excesses#d53276db query_id:uint64 = InternalMsgBody;

   query_id should be equal with request's query_id.

2. burn

Request

TL-B schema of inbound message:

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

query_id - arbitrary request number.

amount - amount of burned jettons

response_destination - address where to send a response with confirmation of a successful burn and the rest of the incoming message coins.

custom_payload - optional custom data.

Should be rejected if:

1. message is not from the owner.

2. there is no enough jettons on the sender wallet

3. There is no enough TONs to send after processing the request at least in_msg_value - max_tx_gas_price to the response_destination address.

   If the sender jetton-wallet cannot guarantee this, it must immediately stop executing the request and throw error.

Otherwise should do:

1. decrease jetton amount on burner wallet by amount and send notification to jetton master with information about burn.

2. Jetton master should send all excesses of incoming message coins to response_destination with the following layout:

   TL-B schema: excesses#d53276db query_id:uint64 = InternalMsgBody;

   query_id should be equal with request's query_id.

Get-methods

1. get_wallet_data() returns (int balance, slice owner, slice jetton, cell jetton_wallet_code)

   balance - (uint256) amount of jettons on wallet.
   owner - (MsgAddress) address of wallet owner;
   jetton - (MsgAddress) address of Jetton master-address;
   jetton_wallet_code - (cell) with code of this wallet;

Jetton master contract

Get-methods

1. get_jetton_data() returns (int total_supply, int mintable, slice admin_address, cell jetton_content, cell jetton_wallet_code)

   total_supply - (integer) - the total number of issues jettons

   mintable - (-1/0) - flag which indicates whether number of jettons can increase

   admin_address - (MsgAddressInt) - address of smart-contrac which control Jetton

   jetton_content - cell - data in accordance to Token Data Standard #64

   jetton_wallet_code - cell - code of wallet for that jetton

2. get_wallet_address(slice owner_address) return slice jetton_wallet_address

   Returns jetton wallet address (MsgAddressInt) for this owner address (MsgAddressInt).

Implementation example

https://github.com/ton-blockchain/token-contract/

TL-B schema

nothing$0 {X:Type} = Maybe X;
just$1 {X:Type} value:X = Maybe X;
left$0 {X:Type} {Y:Type} value:X = Either X Y;
right$1 {X:Type} {Y:Type} value:Y = Either X Y;
var_uint$_ {n:#} len:(#< n) value:(uint (len * 8))
         = VarUInteger n;

addr_none$00 = MsgAddressExt;
addr_extern$01 len:(## 9) external_address:(bits len) 
             = MsgAddressExt;
anycast_info$_ depth:(#<= 30) { depth >= 1 }
   rewrite_pfx:(bits depth) = Anycast;
addr_std$10 anycast:(Maybe Anycast) 
   workchain_id:int8 address:bits256  = MsgAddressInt;
addr_var$11 anycast:(Maybe Anycast) addr_len:(## 9) 
   workchain_id:int32 address:(bits addr_len) = MsgAddressInt;
_ _:MsgAddressInt = MsgAddress;
_ _:MsgAddressExt = MsgAddress;

transfer 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;

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

excesses query_id:uint64 = InternalMsgBody;

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

// ----- Unspecified by standard, but suggested format of internal message

internal_transfer  query_id:uint64 amount:(VarUInteger 16) from:MsgAddress
                     response_address:MsgAddress
                     forward_ton_amount:(VarUInteger 16)
                     forward_payload:(Either Cell ^Cell) 
                     = InternalMsgBody;
burn_notification query_id:uint64 amount:(VarUInteger 16) 
       sender:MsgAddress response_destination:MsgAddress
       = InternalMsgBody;  

crc32('transfer 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') = 0x8f8a7ea5 & 0x7fffffff = 0xf8a7ea5

crc32('transfer_notification query_id:uint64 amount:VarUInteger 16 sender:MsgAddress forward_payload:Either Cell ^Cell = InternalMsgBody') = 0xf362d09c & 0x7fffffff = 0x7362d09c

crc32('excesses query_id:uint64 = InternalMsgBody') = 0x553276db | 0x80000000 = 0xd53276db

crc32('burn query_id:uint64 amount:VarUInteger 16 response_destination:MsgAddress custom_payload:Maybe ^Cell = InternalMsgBody') = 0x595f07bc & 0x7fffffff = 0x595f07bc

crc32('internal_transfer query_id:uint64 amount:VarUInteger 16 from:MsgAddress response_address:MsgAddress forward_ton_amount:VarUInteger 16 forward_payload:Either Cell ^Cell = InternalMsgBody') = 0x978d4519 & 0x7fffffff = 0x178d4519

crc32('burn_notification query_id:uint64 amount:VarUInteger 16 sender:MsgAddress response_destination:MsgAddress = InternalMsgBody') = 0x7bdd97de & 0x7fffffff = 0x7bdd97de

[purp1le]

response_destination - in this case the jetton master smart-contract or recipient's wallet need to indicate?

If it is not jetton master smart-contract, how would it be possible to track which wallets own jettons? So if you minted 100 jettons to some wallet, it transferred 100 times to other wallets, it's hard to trace, isn't it?

Is it planned new version of the wallet in wherein wallet knows that it owns some jettons?

Why did you decide to go the route of creating separate smart-contracts that show that some wallet owns some jettons. Why couldn't this functionality be sewn into the new version of the wallet?

[DocInn]

Если это не смарт-контракт jetton master, как можно было бы отследить, какие кошельки владеют jettons? Итак, если вы отчеканили 100 jettons на какой-то кошелек, он 100 раз перешел на другие кошельки, его трудно отследить, не так ли?

В блокчейне всегда можно отследить все транзакции, соответственно и все движения всех 100 жетонов можно отследить будет в эксплорере.

[EmelyanenkoK]

@purp1le

1. response_destination is an arbitrary address which will receive excesses of TONs sent with message
2. why wallet-per-user, not ERC-20 (one big data-table), was chosen: check section "Why not a single smart contract with a token_id -> owner_address dictionary?" in rationale section here
3. when you send jettons to some address you may request that wallet associated with that address will notify address about jettons arrival (and also specify arbitrary payload, thus you can work with DEX by sending jettons to DEX address and also attaching payload which will say what to do with those jettons)

[ex3ndr]

Need an example of how to perform governance voting with these tokens. Voting is done via token balances at the time of proposal creation. Right now it is impossible without storing map of all owners with their balances.

[Oni-giri]

Hello, could you comment & explain your code for the jettons contract? Right now, even the title is a bit confusing.

[EmelyanenkoK]

Need an example of how to perform governance voting with these tokens. Voting is done via token balances at the time of proposal creation. Right now it is impossible without storing map of all owners with their balances.

There are many possible real-life cases with different suitable solutions. When we are talking about something like multisig (mutual fond between small number of known and friendly participants) dictionary-based solution looks indeed preferable.
When we are talking about large-scale DAO with adversarial participants situation is different. First, from theoretical perspective, right to vote in specific voting is itself a distinctive and immiscible token. So for some cases it is indeed necessary to mint voting-tokens for each voting. For other cases it is most suitable to make merkle-proof based votings. But, I believe that for most cases something like versioned_wallets will be enough. Note, this code was never tested and just serves to demonstrate an idea, DO NOT USE IT IN PRODUCTION.

The idea is to update inner storage of jetton-wallet as well as wallet-wallet and wallet-minter interaction protocol. Note that user interface is still the same, thus it still a standard jetton.

In particular, in addition to balance, jetton-wallet stores it's revision. This revision can only goes up. Revision represents the latest voting id this wallet has participated in. When wallet with revision X get the jettons from wallet with revision Y it should bounce jettons if they have less voting rights to not lose it's own voting right (that means bounce if X<Y and Y is still valid).

Now, it's easy to implement votings. Each voting has it's id (for simplicity time of creation) and every user with revision less than specific voting can vote by burning token with vote data receiving as result the same jettons but with higher revision.

This way jettons are indeed partially immiscible but only when it matters.

[DeFiTON]

Please stop using the name “Jetton”. So, no one in the world “speaks” and “does not write”. There is a common name Token all over the world on all blockchains. As standard. Change before it's too late.

[p0lunin]

@DeFiTON Maybe, there is some expectation that "Jettons" will have behaviour that will be different than "Tokens" have?

@tolya-yanot I think it would be better if a section with motivation why you named this concept "Jetton" instead of "Token" was added. This would be helpfull, because this will be a frequently asked question that needs an explanation.

[sasha1618]

It would be great to have op::get_wallet_addr in the minter's ops so any smart contract could validate its jetton wallet address. For the moment there is no way to do that. Am I missing something?

get_wallet_addr query_id:uint64 = InternalMsgBody;

This function just calculates jetton wallet address by sender_address and sends it back.

Smart contract can match sender_address with the jetton minter address and save its own wallet address.