Jetton token standard development on TON

Jetton Token Development on TON

If you've developed tokens on EVM—TON requires mental reframe. Not cosmetic, but fundamental. Account model here is opposite: instead of central contract with mapping(address → balance), each token holder has own smart contract—Jetton Wallet. This is asynchronous, sharded architecture with message-passing instead of direct calls. And it has specific development consequences.

Jetton Architecture: Two Contracts

Jetton Master—central contract, stores token metadata (name, symbol, decimals, total_supply) and can mint new Jetton Wallets.

Jetton Wallet—one instance per holder. Stores specific address balance. On transfer—Jetton Wallet of sender sends message to Jetton Wallet of receiver.

Transfer flow (TEP-74):
User A → [internal message] → Jetton Wallet A → [internal message] → Jetton Wallet B → User B notified

Not one atomic function call like EVM—chain of async messages. If recipient's Jetton Wallet doesn't exist—it's created on first token receipt, sender pays for deployment (~0.04 TON storage deposit).

TEP-74 and TEP-64 Standards

TEP-74 (Fungible tokens)—main Jetton standard. Defines message structure:

;; Jetton Wallet: handle transfer message
() recv_internal(int my_balance, int msg_value, cell in_msg_full, slice in_msg_body) impure {
    ;; op::transfer = 0xf8a7ea5
    if (op == op::transfer()) {
        int query_id = in_msg_body~load_uint(64);
        int jetton_amount = in_msg_body~load_coins();
        slice to_owner_address = in_msg_body~load_msg_addr();
        slice response_address = in_msg_body~load_msg_addr();
        cell custom_payload = in_msg_body~load_maybe_ref();
        int forward_ton_amount = in_msg_body~load_coins();
        slice forward_payload = in_msg_body;
        
        ;; Check balance
        throw_unless(error::not_enough_jettons, jetton_amount <= balance);
        
        balance -= jetton_amount;
        save_data();
        
        ;; Send message to recipient's Jetton Wallet
        var msg_body = begin_cell()
            .store_uint(op::internal_transfer(), 32)
            .store_uint(query_id, 64)
            .store_coins(jetton_amount)
            .store_slice(my_address())   ;; from_address
            .store_slice(response_address)
            .store_coins(forward_ton_amount)
            .store_slice(forward_payload)
            .end_cell();
        
        ;; Recipient's Jetton Wallet address calculated deterministically
        var to_wallet_address = calc_jetton_wallet_address(to_owner_address);
        
        send_raw_message(
            begin_cell()
                .store_uint(0x18, 6)
                .store_slice(to_wallet_address)
                .store_coins(forward_ton_amount + min_ton_for_storage)
                .store_uint(1, 107)
                .store_ref(msg_body)
            .end_cell(),
            64  ;; carry remaining gas
        );
    }
}

TEP-64 (Token Data Standard)—metadata standard. Metadata can be on-chain (in cell structures) or off-chain (snake-encoded URI):

;; Jetton Master: get-method for metadata
cell get_jetton_data() method_id {
    return begin_cell()
        .store_coins(total_supply)
        .store_int(mintable, 1)
        .store_slice(admin_address)
        .store_ref(jetton_content)    ;; cell with metadata
        .store_ref(jetton_wallet_code)
    .end_cell();
}

Metadata in jetton_content—either off-chain URI (0x01 prefix) or on-chain snake-encoded dictionary:

# On-chain metadata cell structure:
{
  "name": "My Token",
  "description": "Token description", 
  "symbol": "MTK",
  "decimals": "9",
  "image": "https://example.com/logo.png"
}

Tact vs FunC: Language Choice

FunC—native TON language. Low-level, like C. Full control over gas and cell structure. Maximum performance, minimum code readability.

Tact—high-level language, compiles to FunC. Syntax closer to TypeScript. Significantly easier for EVM developers. Today (2024–2025)—recommended choice for new projects:

// Jetton Master in Tact
import "@stdlib/deploy";
import "@stdlib/jetton";

contract JettonMaster with Deployable, Jetton {
    totalSupply: Int as coins;
    owner: Address;
    content: Cell;
    mintable: Bool;
    
    init(owner: Address, content: Cell) {
        self.totalSupply = 0;
        self.owner = owner;
        self.content = content;
        self.mintable = true;
    }
    
    receive(msg: TokenMint) {
        require(sender() == self.owner, "Not owner");
        require(self.mintable, "Not mintable");
        
        self.totalSupply += msg.amount;
        
        // Deploy Jetton Wallet for receiver
        let winit: StateInit = self.getJettonWalletInit(msg.receiver);
        let walletAddress: Address = contractAddress(winit);
        
        send(SendParameters{
            to: walletAddress,
            value: ton("0.05"),
            mode: SendIgnoreErrors,
            bounce: false,
            body: TokenTransferInternal{
                queryId: 0,
                amount: msg.amount,
                from: myAddress(),
                responseAddress: msg.receiver,
                forwardTonAmount: 0,
                forwardPayload: emptySlice(),
            }.toCell(),
            code: winit.code,
            data: winit.data,
        });
    }
}

Gas and Storage: TON Specifics

TON gas works differently than EVM. Key differences:

Storage fee—accounts pay rent for data storage. If Jetton Wallet TON balance falls to zero—account freezes, data lost. Real problem for small-balance holders. Standard minimum for Jetton Wallet: ~0.05 TON.

Forward TON—when sending Jetton with forward_ton_amount > 0, recipient contract receives notification with attached TON. Pattern for TON DeFi integration: instead of approve + transferFrom you do transfer with payload in forward_payload, which target contract processes on Jetton receipt.

// Transfer with payload for DeFi integration
// Analog of ERC-20 approve+transferFrom, but TON-style
message(0x7362d09c) TokenNotification {
    queryId: Int as uint64;
    amount: Int as coins;
    from: Address;
    forwardPayload: Slice as remaining;  // custom data
}

// In target contract (e.g., DEX)
receive(msg: TokenNotification) {
    // Tokens received, msg.forwardPayload contains instructions
    // e.g.: "swap to another token"
    let swapInstruction: SwapPayload = SwapPayload.fromSlice(msg.forwardPayload);
    self.executeSwap(msg.from, msg.amount, swapInstruction);
}

Testing

Sandbox (Blueprint)—official framework for testing TON contracts in TypeScript:

import { Blockchain, SandboxContract, TreasuryContract } from '@ton/sandbox';
import { JettonMaster } from '../wrappers/JettonMaster';
import { JettonWallet } from '../wrappers/JettonWallet';
import '@ton/test-utils';

describe('Jetton', () => {
    let blockchain: Blockchain;
    let deployer: SandboxContract<TreasuryContract>;
    let jettonMaster: SandboxContract<JettonMaster>;

    beforeEach(async () => {
        blockchain = await Blockchain.create();
        deployer = await blockchain.treasury('deployer');
        
        jettonMaster = blockchain.openContract(
            await JettonMaster.fromInit(deployer.address, buildMetadataCell())
        );
        
        await jettonMaster.send(deployer.getSender(), { value: toNano('0.1') }, {
            $$type: 'Deploy',
            queryId: 0n,
        });
    });

    it('should mint tokens', async () => {
        const receiver = await blockchain.treasury('receiver');
        
        const mintResult = await jettonMaster.send(
            deployer.getSender(),
            { value: toNano('0.2') },
            {
                $$type: 'TokenMint',
                queryId: 0n,
                amount: toNano('1000'),
                receiver: receiver.address,
            }
        );
        
        expect(mintResult.transactions).toHaveTransaction({
            from: jettonMaster.address,
            deploy: true,  // Jetton Wallet deployed
            success: true,
        });
        
        const walletAddress = await jettonMaster.getGetWalletAddress(receiver.address);
        const wallet = blockchain.openContract(JettonWallet.fromAddress(walletAddress));
        
        const data = await wallet.getGetWalletData();
        expect(data.balance).toBe(toNano('1000'));
    });
});

Custom Jetton Features

Jetton customization—modifying Jetton Wallet contract. All additional features (transfer tax, whitelist, vesting) implemented in recv_internal of Jetton Wallet, not Master. Atypical for EVM developers.

Transfer tax:

;; In Jetton Wallet, before sending internal_transfer
if (has_transfer_tax()) {
    int tax_amount = (jetton_amount * tax_bps) / 10000;
    int send_amount = jetton_amount - tax_amount;
    
    ;; Send tax to treasury wallet
    send_jettons(treasury_wallet_address, tax_amount, query_id);
    ;; Send remainder to recipient
    send_jettons(to_wallet_address, send_amount, query_id);
}

What's Included

Jetton Master + Jetton Wallet development in Tact (or FunC if required), testing via Blueprint sandbox, mainnet deployment, verification via tonviewer.com, TypeScript wrapper scripts for integration. Timeline: 5–10 days for standard Jetton without custom logic, 2–4 weeks for Jetton with custom mechanics (vesting, whitelist, tax).