Skip to main content

@elizaos/plugin-ton

A plugin for handling TON (Telegram Open Network) blockchain operations, providing wallet management and transfer capabilities.

Overview​

This plugin provides functionality to:

  • Manage TON wallets and key derivation
  • Execute secure token transfers
  • Query wallet balances and portfolio information
  • Format and cache transaction data
  • Interface with TON blockchain via RPC endpoints
  • Connect TON wallets using TonConnect protocol
  • Execute secure token transfers
  • Query wallet connection status
  • Support multiple wallet applications (like Tonkeeper)
  • Support QR Code scanning connection

Quick Start​

# you should read the debug.sh first!

# if not provide the apikey, the response may very slow
export OPENAI_API_KEY=""

# if not provide the testnet apikey, the transfer action may not stable
# from https://t.me/toncenter to get your testnet apikey
export TON_RPC_API_KEY=""

# nvm use 23 && npm install -g bun
bash ./packages/plugin-ton/scripts/debug.sh

Installation​

npm install @elizaos/plugin-ton

Configuration​

The plugin requires the following environment variables:

TON_PRIVATE_KEY=your_mnemonic_phrase  # Required - wallet mnemonic words
TON_RPC_URL=your_rpc_endpoint  # Optional - defaults to mainnet RPC
TON_RPC_API_KEY=
TON_MANIFEST_URL=your_manifest_url  # Required - TonConnect manifest URL
TON_BRIDGE_URL=your_bridge_url  # Optional - defaults to https://bridge.tonapi.io/bridge

Usage​

Import and register the plugin in your Eliza configuration:

import { tonPlugin } from '@elizaos/plugin-ton';

export default {
  plugins: [tonPlugin],
  // ... other configuration
};

Features​

WalletProvider​

The WalletProvider manages wallet operations and portfolio tracking:

import { WalletProvider } from '@elizaos/plugin-ton';

// Initialize the provider
const provider = await initWalletProvider(runtime);

// Get wallet balance
const balance = await provider.getWalletBalance();

// Get formatted portfolio
const portfolio = await provider.getFormattedPortfolio(runtime);

TonConnectProvider​

The TonConnectProvider manages wallet connection operations:

import { TonConnectProvider } from '@elizaos/plugin-ton-connect';

// Initialize provider
const provider = await initTonConnectProvider(runtime);

// Connect wallet
const universalLink = await provider.connect();

// Check connection status
const isConnected = provider.isConnected();

// Disconnect
await provider.disconnect();

TransferAction​

The TransferAction handles token transfers:

import { TransferAction } from '@elizaos/plugin-ton';

// Initialize transfer action
const action = new TransferAction(walletProvider);

// Execute transfer
const hash = await action.transfer({
  recipient: 'EQCGScrZe1xbyWqWDvdI6mzP-GAcAWFv6ZXuaJOuSqemxku4',
  amount: '1.5',
});

BatchTransferAction​

The BatchTransferAction handles transfers of NFTs, Jettons and TON in a single transaction:

import { BatchTransferTokens } from '@elizaos/plugin-ton';

// Initialize transfer action
const action = new BatchTransferTokens(walletProvider);
const batchTransfers = {
  transfers: [
    {
      type: 'ton',
      recipientAddress: '0QBLy_5Fr6f8NSpMt8SmPGiItnUE0JxgTJZ6m6E8aXoLtJHB',
      amount: '0.1',
    },
    {
      type: 'token',
      recipientAddress: '0QBLy_5Fr6f8NSpMt8SmPGiItnUE0JxgTJZ6m6E8aXoLtJHB',
      tokenInd: '0QDIUnzAEsgHLL7YSrvm_u7OYSKw93AQbtdidRdcbm7tQep5',
      amount: '1',
    },
  ],
};
const reports = await batchTransferAction.createBatchTransfer(batchTransfers);

Create Ton Wallet Action​

The CreateTonWallet action handles on-demand wallet creation with encrypted key storage from user-supplied encryption key:

import { CreateTonWallet } from '@elizaos/plugin-ton';

// Initialize transfer action
const action = new CreateTonWallet(runtime);

// Execute transfer
const { walletAddress, mnemonic } = await action.createNewWallet({
  rpcUrl: 'https://toncenter.com/api/v2/jsonRPC',
  encryptionPassword: 'GAcAWFv6ZXuaJOuSqemxku4',
});

Auction Interaction Action​

The AuctionInteractionTon action handles Auction interactions

import { AuctionInteractionActionTon } from '@elizaos/plugin-ton';

// Initialize transfer action
const action = new AuctionInteractionActionTon(walletProvider);

result = await auctionAction.getAuctionData(auctionAddress);

Development​

Building​

npm run build

Testing​

npm run test

Dependencies​

  • @ton/ton: Core TON blockchain functionality
  • @ton/crypto: Cryptographic operations
  • bignumber.js: Precise number handling
  • node-cache: Caching functionality
  • Other standard dependencies listed in package.json

API Reference​

Providers​

  • walletProvider: Manages TON wallet operations
  • nativeWalletProvider: Handles native TON token operations

Types​

interface TransferContent {
  recipient: string;
  amount: string | number;
}

interface WalletPortfolio {
  totalUsd: string;
  totalNativeToken: string;
}

interface Prices {
  nativeToken: { usd: string };
}

Configuration Constants​

const PROVIDER_CONFIG = {
  MAINNET_RPC: 'https://toncenter.com/api/v2/jsonRPC',
  STONFI_TON_USD_POOL: 'EQCGScrZe1xbyWqWDvdI6mzP-GAcAWFv6ZXuaJOuSqemxku4',
  CHAIN_NAME_IN_DEXSCREENER: 'ton',
  MAX_RETRIES: 3,
  RETRY_DELAY: 2000,
  TON_DECIMAL: BigInt(1000000000),
};

Common Issues/Troubleshooting​

Issue: Balance Fetching Failure​

  • Cause: Incorrect RPC endpoint or network connectivity issues
  • Solution: Verify TON_RPC_URL and network connection

Issue: Transfer Fails​

  • Cause: Insufficient balance or invalid recipient address
  • Solution: Ensure sufficient funds and valid recipient address format

Security Best Practices​

  • Store private keys securely using environment variables
  • Validate all input addresses and amounts
  • Use proper error handling for blockchain operations
  • Keep dependencies updated for security patches

Future Enhancements​

  1. Wallet Management

    • Multi-wallet support
    • Hardware wallet integration
    • Advanced key management
    • Batch transaction processing
    • Custom wallet contracts
    • Recovery mechanisms

  2. Smart Contract Integration

    • Contract deployment tools
    • FunC contract templates
    • Testing framework
    • Upgrade management
    • Gas optimization
    • Security analysis

  3. Token Operations

    • Jetton creation tools
    • NFT support enhancement
    • Token metadata handling
    • Collection management
    • Batch transfers
    • Token standards

  4. DeFi Features

    • DEX integration
    • Liquidity management
    • Yield farming tools
    • Price feed integration
    • Swap optimization
    • Portfolio tracking

  5. Developer Tools

    • Enhanced debugging
    • CLI improvements
    • Documentation generator
    • Integration templates
    • Performance monitoring
    • Testing utilities

  6. Network Features

    • Workchain support
    • Sharding optimization
    • RPC management
    • Network monitoring
    • Archive node integration
    • Custom endpoints

We welcome community feedback and contributions to help prioritize these enhancements.

Contributing​

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Credits​

This plugin integrates with and builds upon several key technologies:

Special thanks to:

  • The TON Foundation for developing and maintaining the TON blockchain
  • The TON Developer community
  • The TON SDK maintainers
  • The Eliza community for their contributions and feedback

For more information about TON blockchain capabilities:

License​

This plugin is part of the Eliza project. See the main project repository for license information.