---
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):
```typescript
import TonWeb from 'tonweb';
const tonweb = new TonWeb();
```

✅ Current:
```typescript
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):
```solidity
pragma solidity ^0.8.0;
contract Counter {
    uint256 public value;
    function increment() public { value++; }
}
```

✅ Correct (Tact syntax):
```tact
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)
```typescript
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
```typescript
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
```tact
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
```bash
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](https://docs.ton.org)
- [Tact Language Docs](https://docs.tact-lang.org)
- [Blueprint Framework](https://github.com/ton-org/blueprint)
- [TON Center API](https://toncenter.com/api/v2/)

## 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):
```typescript
import TonWeb from 'tonweb';
const tonweb = new TonWeb();
```

✅ Current:
```typescript
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):
```solidity
pragma solidity ^0.8.0;
contract Counter {
    uint256 public value;
    function increment() public { value++; }
}
```

✅ Correct (Tact syntax):
```tact
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)
```typescript
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
```typescript
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
```tact
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
```bash
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](https://docs.ton.org)
- [Tact Language Docs](https://docs.tact-lang.org)
- [Blueprint Framework](https://github.com/ton-org/blueprint)
- [TON Center API](https://toncenter.com/api/v2/)

## 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)
```bash
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
```typescript
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
```typescript
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