@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
• Query information for assets from Ston.fi DEX
• Swap tokens using Ston.fi DEX

Screenshot

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 pnpm
bash ./packages/plugin-ton/scripts/debug.sh

Installation

npm install @elizaos/plugin-ton

Configuration

The plugin requires the following environment variables:

# Ton
TON_PRIVATE_KEY= # Ton Mnemonic Seed Phrase Join With " "(single space) String
TON_RPC_URL=     # ton rpc - Defaults to https://toncenter.com/api/v2/jsonRPC
TON_RPC_API_KEY= # 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

# STON.fi - Values are not required, they allow using newer versions of STON.fi DEX
# Identifies mainnet / testnet from TON_RPC_URL
STON_API_BASE_URL= # By default, uses null value (i.e. standard STON value)
STON_ROUTER_VERSION= # By default, uses v1 for mainnet and v2_1 for testnet
STON_ROUTER_ADDRESS= # By default, uses standard values
STON_PROXY_VERSION= # By default, uses v1 for mainnet and v2_1 for testnet
STON_PROXY_ADDRESS= # By default, uses standard values

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);

Get Collection Data Action

The GetCollectionData action shows information about NFT collection

import { GetCollectionData } from "@elizaos/plugin-ton";

// Initialize transfer action
const getCollectionDataAction = new GetCollectionDataAction(walletProvider);
const collectionData = await getCollectionDataAction.getData(collectionAddress);

Mint NFT Action

The MintNFT action is responsible for minting a new collection or NFT inside collection

import { MintNFT } from "@elizaos/plugin-ton";

const mintNFTAction = new MintNFTAction(walletProvider);
const nftAddress = await mintNFTAction.mint(mintParams);

Transfer NFT Action

The transferNFTAction action is responsible for transfering the ownership of an NFT within a collection

import { TransferNFT } from "@elizaos/plugin-ton";

const transferAction = new TransferNFTAction(walletProvider);
const transferDetails = {
  "nftAddress": "0QDIUnzAEsgHLL7YSrvm_u7OYSKw93AQbtdidRdcbm7tQep5",
  "newOwner": "EQCGScrZe1xbyWqWDvdI6mzP-GAcAWFv6ZXuaJOuSqemxku4"
};
await transferAction.transfer(transferDetails);

Development

Building

npm run build

Testing

npm run test

Dependencies

• @ston-fi/api: API for STON.fi DEX
• @ston-fi/sdk: SDK for STON.fi DEX
• @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:

• STON.fi: STON.fi DEX
• TON Blockchain: The Open Network blockchain platform
• @ton/ton: Core TON blockchain functionality
• @ton/crypto: Cryptographic operations
• bignumber.js: Precise number handling
• node-cache: Caching functionality

Special thanks to:

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

For more information about TON blockchain capabilities:

• TON Documentation
• TON Developer Portal
• TON Whitepaper
• TON API Reference

License

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