ton_wallet_v4

A Flutter plugin for generating TON blockchain wallets, mnemonics, and fetching wallet assets. This plugin provides a simple, cross-platform interface for creating BIP39 mnemonics, generating V4R2 wallet addresses, and querying wallet balances and tokens on the TON blockchain.

Built by Macromodule Technologies — Open source; contributions welcome.

Features

• Mnemonic Generation: Generate secure 24-word BIP39 mnemonics
• V4 Wallet Creation: Create V4R2 wallet addresses from mnemonics
• Asset Fetching: Query wallet balances (TON and jettons) from the blockchain
• Cross-Platform: Native implementations for Android (Kotlin) and iOS (Swift)
• Simple API: Easy-to-use Dart interface with minimal configuration
• Type-Safe: Proper handling of dynamic native data with safe type conversions

Installation

Add ton_wallet_v4 to your pubspec.yaml:

dependencies:
  ton_wallet_v4: ^1.0.0

Then run:

flutter pub get

Usage

Basic Wallet Generation Example

import 'package:ton_wallet_v4/ton_wallet_bridge.dart';

final tonWallet = TonWallet();

// Generate a new mnemonic
final mnemonic = await tonWallet.generateMnemonic();
print('Generated mnemonic: $mnemonic');

// Create a V4 wallet from the mnemonic
final walletData = await tonWallet.generateV4Wallet(
  mnemonic,
  workchain: 0,
  useBip39: true,
  index: 0,
);

print('Wallet address: ${walletData['address']}');
print('Public key: ${walletData['public_key']}');

Fetch Wallet Assets Example

import 'package:ton_wallet_v4/ton_wallet_bridge.dart';

final tonWallet = TonWallet();

// Fetch assets for a wallet address
final assets = await tonWallet.fetchAssets(
  address: 'UQAYYvN_Sl3MJcjvwuZMvmBN2ZJqPHI2KxMYKYQWVZjlNRzG',
);

print('TON Balance: ${assets['tonBalance']} TON');
print('Nano Balance: ${assets['tonBalanceNano']}');

// Get list of tokens (jettons)
final jettons = assets['jettons'] as List<dynamic>;
for (final jetton in jettons) {
  print('${jetton['name']}: ${jetton['balance']} ${jetton['symbol']}');
}

API Reference

generateMnemonic()

Generates a new 24-word BIP39 mnemonic.

Future<List<String>> generateMnemonic()

Returns: A list of 24 mnemonic words.

generateV4Wallet(mnemonic, {workchain, useBip39, index})

Creates a V4 wallet from a mnemonic phrase.

Future<Map<String, dynamic>> generateV4Wallet(
  List<String> mnemonic,
  {
    int workchain = 0,
    bool useBip39 = true,
    int index = 0,
  }
)

Parameters:

• mnemonic: List of 24 BIP39 mnemonic words
• workchain: TON workchain ID (default: 0)
• useBip39: Whether to use BIP39 derivation (default: true)
• index: Wallet index for multi-wallet derivation (default: 0)

Returns: A map containing:

• address: Wallet address (non-bounceable format)
• bounceable: Bounceable variant
• non_bounceable: Non-bounceable variant
• raw: Raw address format
• public_key: Hex-encoded public key
• private_key: Hex-encoded private key
• workchain: Workchain ID
• success: Boolean indicating success

fetchAssets({address, testnet})

Fetches wallet balance and token information.

Future<Map<String, dynamic>> fetchAssets({
  required String address,
  bool testnet = false,
})

Parameters:

• address: TON wallet address (bounceable or non-bounceable format)
• testnet: Use testnet API (default: false)

Returns: A map containing:

• address: The queried address
• tonBalance: TON balance as a formatted string (e.g., "1.5")
• tonBalanceNano: Balance in nanotons (smallest unit)
• jettons: List of token objects with:
  • name: Token name
  • symbol: Token symbol
  • balance: Token balance (formatted)
  • decimals: Decimal places
  • jettonAddress: Token contract address
  • imageUrl: Token logo URL (if available)
• success: Boolean indicating success

Example App

The plugin includes a complete example application demonstrating:

• Mnemonic generation
• V4 wallet creation from mnemonics
• Asset fetching and display
• Token list visualization

Run the example:

cd example
flutter run

Platform-Specific Details

Android

Uses the ton-kotlin library:

• Supports BIP39 mnemonic validation and conversion
• Implements V4R2 wallet address generation
• Queries TON API for balance and token data
• Falls back to TonCenter if TON API is unavailable
• Package: com.mt.ton.wallet

iOS

Uses the TonSwift library (v1.0.3):

• Swift-native implementation for iOS 13.0+
• Handles mnemonic validation and wallet generation
• Queries TON API for asset information
• Falls back to TonCenter if TON API is unavailable
• Integrates with native crypto libraries (CryptoKit, CommonCrypto)

Requirements

• Flutter >= 3.3.0
• Dart SDK >= 3.10.1
• Android: minSdkVersion 21
• iOS: 13.0+

Network Requirements

Asset fetching requires internet access to:

• Primary: TON API (https://tonapi.io/)
• Fallback: TonCenter (https://toncenter.com/)

Error Handling

The plugin throws PlatformException on errors. Example:

try {
  final assets = await tonWallet.fetchAssets(address: address);
} on PlatformException catch (e) {
  print('Error: ${e.message}');
}

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Contributors

• asaddigital2809 — https://github.com/asaddigital2809
• Wahabahmad694 — https://github.com/Wahabahmad694

Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.