TON SDK Overview

Complete guide to using Dynamic’s Node SDK for TON blockchain operations

Overview

Dynamic’s Node SDK provides comprehensive support for TON blockchain operations, including wallet creation, transaction signing, message signing, and key management. The SDK implements Multi-Party Computation (MPC) for enhanced security.

Key Features

• MPC Wallet Creation: Create secure TON wallets with threshold signature schemes
• Transaction Signing: Sign TON transactions (BOC format) without exposing private keys
• Message Signing: Sign messages using Ed25519, returned as base64 strings
• Key Import/Export: Import existing private keys and export wallet data
• Multiple Security Models: Choose between different threshold signature schemes

Available Threshold Signature Schemes

• TWO_OF_TWO: Maximum security - requires both server and Dynamic infrastructure
• TWO_OF_THREE: Balanced security and availability - requires 2 out of 3 shares
• THREE_OF_FIVE: High availability - requires 3 out of 5 shares

Quick Start

import { DynamicTonWalletClient } from '@dynamic-labs-wallet/node-ton';
import { ThresholdSignatureScheme } from '@dynamic-labs-wallet/node';

const client = new DynamicTonWalletClient({
  environmentId: process.env.DYNAMIC_ENVIRONMENT_ID!,
});

await client.authenticateApiToken(process.env.DYNAMIC_AUTH_TOKEN!);

// Create a new wallet
const wallet = await client.createWalletAccount({
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  backUpToDynamic: true,
});

console.log('Wallet created:', wallet.accountAddress);

Core Functions

Wallet Management

• createWalletAccount() - Create new TON wallet
• importPrivateKey() - Import existing private key
• getWallet() - Get specific wallet details
• getTonWallets() - Get all TON wallets
• deriveTonAddress() - Derive TON address from a public key (synchronous)

Signing Operations

• signMessage() - Sign messages (Ed25519, base64 output)
• signTransaction() - Sign TON transactions (BOC format)

Key Management

• exportKey() - Export wallet key data
• offlineExportPrivateKey() - Export private key from key shares offline
• encryptKeyShare() - Encrypt key shares
• decryptKeyShare() - Decrypt key shares

Backup and Recovery

• storeEncryptedBackupByWallet() - Store encrypted backup
• recoverEncryptedBackupByWallet() - Recover encrypted backup
• refreshWalletAccountShares() - Refresh wallet shares

Guides

• Create TON Wallet - Step-by-step wallet creation
• Import Private Keys - Import existing TON keys
• Sign Transactions - Sign TON transactions
• Sign Messages - Sign messages with your wallet
• Use Imported Wallets - Work with imported wallets
• Complete Example - Full working example

Prerequisites

Before using the TON SDK, ensure you have:

1. Dynamic Project Setup: Set up your Dynamic project
2. Environment Configuration: Configure your environment ID and auth token
3. TON Chain Enabled: Enable TON chain in your Dynamic developer console
4. Dependencies Installed: Install required packages

Installation

bun add @dynamic-labs-wallet/node-ton @ton/ton @ton/crypto @dynamic-labs-wallet/node

Environment Variables

DYNAMIC_AUTH_TOKEN=your_auth_token_here
DYNAMIC_ENVIRONMENT_ID=your_environment_id_here

TON-Specific Concepts

Address Format

TON addresses are user-friendly strings (e.g., EQD...), derived from the wallet contract. The SDK uses WalletContractV5R1 by default. You can also derive an address from a public key using deriveTonAddress().

Native Unit

TON uses nanotons as its smallest unit: 1 TON = 1,000,000,000 nanotons.

Transaction Format

TON transactions use BOC (Bag of Cells) serialization. The signTransaction() method accepts a Cell object built with @ton/ton helpers and returns a signed BOC.

Jettons

TON’s fungible token standard is called Jettons. Transferring Jettons requires interacting with Jetton wallet contracts on-chain.

Security Considerations

• MPC Architecture: Private keys are never stored in plain text
• Threshold Signing: Multiple parties must collaborate to sign transactions
• Key Share Backup: Use backUpToDynamic: true for secure storage
• Password Protection: Implement strong passwords for additional security layers

Network Support

The SDK currently supports TON Mainnet (workchain 0).

Error Handling

Always implement proper error handling:

try {
  const result = await tonClient.someFunction(params);
  console.log('Operation successful:', result);
} catch (error) {
  console.error('Operation failed:', error instanceof Error ? error.message : String(error));
}

Next Steps

• Get started with wallet creation
• Explore the complete example
• Learn about EVM support
• Learn about SVM support