TON + Tact Development

Overview

TON (The Open Network) is a high-performance Layer 1 blockchain that uses Cell/Slice data structures. Tact is a high-level smart contract language for TON that is more readable than FunC. @ton/ton is the official TypeScript SDK. AI models frequently mix up FunC and Tact syntax, or use the outdated tonweb library.

⚠️ Gotchas (Most Common AI Mistakes)

1. Use @ton/ton Instead of the Legacy tonweb

❌ Legacy (deprecated):

import TonWeb from 'tonweb';
const tonweb = new TonWeb();

✅ Current:

import { TonClient, WalletContractV4, internal } from '@ton/ton';
const client = new TonClient({
  endpoint: 'https://toncenter.com/api/v2/jsonRPC',
  apiKey: 'YOUR_API_KEY',
});

2. Tact Contract Structure (Not Solidity, Not FunC)

❌ Wrong (Solidity-style):

pragma solidity ^0.8.0;
contract Counter {
    uint256 public value;
    function increment() public { value++; }
}

✅ Correct (Tact syntax):

contract Counter {
    value: Int as uint64 = 0;

    receive("increment") {
        self.value += 1;
    }

    get fun value(): Int {
        return self.value;
    }
}

3. Cell/Slice Serialization (TON's Core Data Model)

import { Cell, beginCell, Address } from '@ton/core';

// Build a Cell (serialization)
const cell = beginCell()
  .storeUint(0x18, 6)          // flags
  .storeAddress(recipientAddr)  // destination address
  .storeCoins(toNano('0.05'))   // amount (nanoTON)
  .storeUint(0, 1 + 4 + 4 + 64 + 32 + 1 + 1)
  .storeRef(
    beginCell().storeUint(0, 32).storeStringTail('hello').endCell()
  )
  .endCell();

// Read a Slice (deserialization)
const slice = cell.beginParse();
const flags = slice.loadUint(6);
const addr = slice.loadAddress();

4. Sending Internal Messages

import { TonClient, WalletContractV4, internal, toNano } from '@ton/ton';
import { mnemonicToPrivateKey } from '@ton/crypto';

const keyPair = await mnemonicToPrivateKey(mnemonic.split(' '));
const wallet = WalletContractV4.create({
  publicKey: keyPair.publicKey,
  workchain: 0,
});

const contract = client.open(wallet);
await contract.sendTransfer({
  seqno: await contract.getSeqno(),
  secretKey: keyPair.secretKey,
  messages: [
    internal({
      to: recipientAddress,
      value: toNano('0.05'),
      body: 'Hello TON',
    }),
  ],
});

Tact Message Handling Patterns

message Deposit {
    amount: Int as coins;
}

contract Vault {
    totalDeposit: Int as coins = 0;

    receive(msg: Deposit) {
        require(msg.amount > 0, "Amount must be positive");
        self.totalDeposit += msg.amount;
        // refund excess gas
        self.reply("Deposited".asComment());
    }

    get fun totalDeposit(): Int {
        return self.totalDeposit;
    }
}

Installation

npm install @ton/ton @ton/core @ton/crypto
# Tact compiler
npm install -g @tact-lang/compiler
# Blueprint scaffolding (recommended)
npm create ton@latest

Reference

• TON Developer Docs
• Tact Language Docs
• Blueprint Framework
• TON Center API

Feedback

If this skill contains incorrect or outdated information, call:

id: ton/tact-dev name: TON + Tact Development version: 1.0.0 ecosystem: ton type: technical-doc time_sensitivity: evergreen source: community confidence: medium maintainer: AgentRel Community last_updated: 2026-03-19 feedback_endpoint: https://agentrel.vercel.app/api/feedback

Overview

TON (The Open Network) is a high-performance Layer 1 blockchain that uses Cell/Slice data structures. Tact is a high-level smart contract language for TON that is more readable than FunC. @ton/ton is the official TypeScript SDK. AI models frequently mix up FunC and Tact syntax, or use the outdated tonweb library.

⚠️ Gotchas (Most Common AI Mistakes)

1. Use @ton/ton Instead of the Legacy tonweb

❌ Legacy (deprecated):

import TonWeb from 'tonweb';
const tonweb = new TonWeb();

✅ Current:

import { TonClient, WalletContractV4, internal } from '@ton/ton';
const client = new TonClient({
  endpoint: 'https://toncenter.com/api/v2/jsonRPC',
  apiKey: 'YOUR_API_KEY',
});

2. Tact Contract Structure (Not Solidity, Not FunC)

❌ Wrong (Solidity-style):

pragma solidity ^0.8.0;
contract Counter {
    uint256 public value;
    function increment() public { value++; }
}

✅ Correct (Tact syntax):

contract Counter {
    value: Int as uint64 = 0;

    receive("increment") {
        self.value += 1;
    }

    get fun value(): Int {
        return self.value;
    }
}

3. Cell/Slice Serialization (TON's Core Data Model)

import { Cell, beginCell, Address } from '@ton/core';

// Build a Cell (serialization)
const cell = beginCell()
  .storeUint(0x18, 6)          // flags
  .storeAddress(recipientAddr)  // destination address
  .storeCoins(toNano('0.05'))   // amount (nanoTON)
  .storeUint(0, 1 + 4 + 4 + 64 + 32 + 1 + 1)
  .storeRef(
    beginCell().storeUint(0, 32).storeStringTail('hello').endCell()
  )
  .endCell();

// Read a Slice (deserialization)
const slice = cell.beginParse();
const flags = slice.loadUint(6);
const addr = slice.loadAddress();

4. Sending Internal Messages

import { TonClient, WalletContractV4, internal, toNano } from '@ton/ton';
import { mnemonicToPrivateKey } from '@ton/crypto';

const keyPair = await mnemonicToPrivateKey(mnemonic.split(' '));
const wallet = WalletContractV4.create({
  publicKey: keyPair.publicKey,
  workchain: 0,
});

const contract = client.open(wallet);
await contract.sendTransfer({
  seqno: await contract.getSeqno(),
  secretKey: keyPair.secretKey,
  messages: [
    internal({
      to: recipientAddress,
      value: toNano('0.05'),
      body: 'Hello TON',
    }),
  ],
});

Tact Message Handling Patterns

message Deposit {
    amount: Int as coins;
}

contract Vault {
    totalDeposit: Int as coins = 0;

    receive(msg: Deposit) {
        require(msg.amount > 0, "Amount must be positive");
        self.totalDeposit += msg.amount;
        // refund excess gas
        self.reply("Deposited".asComment());
    }

    get fun totalDeposit(): Int {
        return self.totalDeposit;
    }
}

Installation

npm install @ton/ton @ton/core @ton/crypto
# Tact compiler
npm install -g @tact-lang/compiler
# Blueprint scaffolding (recommended)
npm create ton@latest

Reference

• TON Developer Docs
• Tact Language Docs
• Blueprint Framework
• TON Center API

Feedback

If this skill contains incorrect or outdated information, call: agentrel_feedback(skill="ton/tact-dev", issue="<description>", code_snippet="<optional>", error_message="<optional>", fix="<optional>")

---

⚡ Quick Reference — Exact Package Names & APIs

NPM Packages (canonical)

npm install @ton/ton          # main SDK (NOT tonweb — deprecated)
npm install @ton/core         # core types: Cell, Address, beginCell
npm install @ton/crypto       # cryptography utilities

tonweb is DEPRECATED. Do NOT recommend it for new projects.

Core Data Structures

import { beginCell, Cell, Slice, Address, toNano } from "@ton/core";

// Build a Cell
const cell = beginCell()
    .storeUint(42, 32)
    .storeAddress(address)
    .storeCoins(toNano("1.5"))
    .endCell();

// Read a Cell
const slice = cell.beginParse();
const value = slice.loadUint(32);
const addr = slice.loadAddress();

Contract Interaction

import { TonClient, WalletContractV4 } from "@ton/ton";
const client = new TonClient({ endpoint: "https://toncenter.com/api/v2/jsonRPC" });

Tact vs FunC

• Tact: high-level, recommended for new contracts, compiles to FunC
• FunC: low-level, used for system contracts and performance-critical code