TON application development

TON Application Development

TON is one of few blockchains where platform architecture fundamentally affects application architecture. Infinite sharding, actor model, asynchronous messages — these aren't implementation details you can ignore. They're constraints around which entire system is built. Developer coming from EVM without diving into TON specifics will likely get application that works on testnet and breaks on mainnet under parallel requests.

Architectural Base: Actor Model and Message Passing

In TON, each smart contract is an actor. It processes incoming messages sequentially, but different contracts execute parallel and independently. No global state, no synchronous calls — only messages with one or more block delay.

This means: atomicity of complex operations impossible through synchronous call chain. Instead — commit-confirm-rollback pattern:

1. Contract A fixes preliminary state (commit) and sends request to contract B
2. B processes request and sends confirm or reject
3. A receives response and finalizes or rolls back state

Bounce messages — mechanism by which TON signals error on processing. If B returned error, message "bounced" back to A. Without bounce-handler in contract A, funds lost or state diverges.

Smart Contracts: FunC vs Tact, When What

For most application components use Tact — strict typing, built-in checks, readable syntax. Jetton (TEP-74 standard), NFT (TEP-62), custom business logic — all on Tact.

FunC reserve for cases where maximum gas optimization or non-standard cell layout work needed. Contracts with high transaction volume, where every nanoton gas matters — FunC candidates.

Standard tokens (Jetton Minter + Jetton Wallet) deploy based on audited TON Foundation templates — don't reinvent wheel where standard covers task.

Gas and Storage Costs

TON charges for data storage in contract (storage fee). Contract that accumulates data without cleanup mechanism eventually exhausts balance and "freezes". Design contract state with this in mind: store only necessary, use data sharding via child contracts (one contract per user — standard TON pattern).

TON Connect: Wallet Integration

TON Connect 2.0 — protocol for connecting wallet to dApp. Works with Tonkeeper, MyTonWallet, Tonhub. Integration via @tonconnect/sdk or @tonconnect/ui-react (if React).

Typical session: user scans QR or clicks deeplink → wallet confirms connection → dApp gets address and can send transaction sign requests.

Nuance: TON Connect transmits transaction to wallet for signing, but transaction executes asynchronously. dApp doesn't know result at signing moment — need polling transaction status via TON API or WebSocket subscription to contract events.

import { useTonConnectUI } from '@tonconnect/ui-react';

const [tonConnectUI] = useTonConnectUI();

const sendTransaction = async () => {
  const result = await tonConnectUI.sendTransaction({
    messages: [{
      address: contractAddress,
      amount: toNano('0.05').toString(),
      payload: beginCell()
        .storeUint(0x1234, 32) // op code
        .storeAddress(userAddress)
        .endCell()
        .toBoc()
        .toString('base64')
    }]
  });
  // result contains only signed transaction boc
  // status must be checked separately
};

Backend and Event Indexing

TON doesn't have event log like EVM. Transactions and their results read via TON HTTP API (toncenter.com) or tonapi.io. For production use tonapi.io — more reliable, higher rate limits, webhooks available.

For complex indexing (user operation history, aggregated data) — own indexer based on ton-index-worker or TON Index API. Write data to PostgreSQL, build API on Node.js/FastAPI.

Alternative — The Open Network Indexer (TONX) and GetBlock for managed indexing, if data volume doesn't require custom logic.

Frontend: Stack and Features

React + TypeScript + wagmi not suitable for TON — EVM stack. For TON use:

• @ton/core — basic cell, address, builder work
• @ton/ton — HTTP client for TON API
• @tonconnect/ui-react — wallet connection components
• tonweb — outdated, but still found in projects

Telegram Mini App (TMA) — separate context for TON. TMA works inside Telegram WebView, has access to Telegram user data and can open wallet via @telegram-apps/sdk. This is main UX pattern for TON apps with mass audience.

Development Process

Design (3-5 days). Draw message flow diagram — all contracts and messages between them. Define storage model of each contract. Calculate approximate storage fees for 1 year.

Contract development (1-2 weeks). Tact/FunC, tests via Blueprint + sandbox, cover bounce scenarios.

Backend (1-2 weeks). API, indexer, TON API integration.

Frontend + TON Connect (1-2 weeks). React / TMA, wallet integration, transaction status polling.

Deployment and monitoring. Contracts deployed via npx blueprint run, mainnet addresses fixed in repository. Monitoring via tonapi.io webhooks.

Overall timeline for full TON application (contracts + backend + frontend): 2-4 weeks. Depends on business logic complexity and number of contracts in system.

Common TON Development Mistakes

Ignore bounce. Any contract sending funds or calling another contract must handle bounced messages. Otherwise on any downstream failure, funds hang.

Store everything in one contract. TON shards data, placing contracts in different shards. One large contract with all user data — anti-pattern contradicting TON architecture. Correct pattern: master + per-user contracts (like jetton minter + jetton wallet).

Not account for storage fees. Contract with insufficient balance freezes. Need mechanism to replenish or limit data volume.