SUI Wallet Telegram Bot Documentation

🤖 Project Overview

A TypeScript-based Telegram bot that provides comprehensive SUI blockchain wallet management functionality. Users can create, import, and manage SUI wallets directly through Telegram, including balance checking, private key management, and SUI token transfers with slippage protection.

Repository: https://github.com/ecorey/tg_bot

🔒 Security Notice

Security Audit Status

✅ Repository Verified: This repository has been audited for security. No private keys or sensitive information are exposed in the codebase.

• All API keys and tokens are stored in environment variables
• Configuration files with sensitive data are included in .gitignore
• Example configuration files use placeholder values only
• TypeScript implementation with comprehensive testing

Key Features

🔐 Wallet Management: Create, import, and delete SUI wallets
🔑 Private Key Handling: Secure retrieval of wallet credentials
💰 Balance Checking: Real-time SUI balance queries
📤 Token Transfers: Send SUI to any valid address
📊 Slippage Protection: Configurable slippage tolerance for transfers
🧪 Comprehensive Testing: 14 test cases covering all functionality
🛡️ Error Handling: Robust validation and error management
⚡ TypeScript: Full type safety and modern development practices

Build & Run

Build the Project

npm run build

Note: The README shows "npn run build" but this appears to be a typo - should be "npm run build"

Run the Bot

npm run main

Testing

Run Test Suite

npx vitest run

Test Coverage

The project includes comprehensive testing with 14 test cases:

✅ Wallet Management Tests

✓ should create a wallet successfully
✓ should not create a wallet if one already exists
✓ should not import a wallet if one already exists
✓ should get wallet balance
✓ should return public key after wallet is created
✓ should return private key after wallet is created

❌ Error Handling Tests

✓ should throw error when trying to get balance with no wallet
✓ should throw error when trying to get private key with no wallet
✓ should throw error when trying to get public key with no wallet

💸 Transfer & Slippage Tests

✓ should send SUI to a correct address
✓ should fail to send SUI to an incorrect address
✓ should send SUI within slippage tolerance
✓ should fail to send SUI due to exceeding slippage tolerance
✓ should fail to send SUI due to slippage tolerance (too low)

Bot Commands

Primary Commands

Command	Description
/start	Initialize the bot and display welcome message with available options

Interactive Bot Buttons

The bot provides interactive buttons for all wallet operations. Users can perform actions by clicking buttons rather than typing commands.

Button	Parameters	Description
createWallet	None	Generate a new SUI wallet with public/private key pair
importWallet	<suiprivkey....>	Import existing wallet using SUI private key
deleteWallet	<suiprivkey....>	Remove wallet from bot (requires private key confirmation)
getPrivateKey	None	Retrieve private key of current wallet
getPublicKey	None	Retrieve public key of current wallet
checkBalance	None	Display current SUI balance in wallet
sendSui	<ADDRESS> <AMOUNT>	Send SUI tokens to specified address
sendSuiSlippage	<ADDRESS> <AMOUNT> <SLIPPAGE>	Send SUI with slippage protection (default: 1%)
exit	None	Close bot interaction and clear session

Usage Examples

Example Button Interactions

Import Wallet:

importWallet suiprivkey1qxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Send SUI:

sendSui 0x1234567890abcdef1234567890abcdef12345678 1.5

Send with Slippage:

sendSuiSlippage 0x1234567890abcdef1234567890abcdef12345678 1.5 0.5

Installation & Setup

Prerequisites

• Node.js: Version 16 or later
• npm: Node package manager
• Telegram Bot Token: From @BotFather
• SUI Network Access: For blockchain interactions

1. Clone Repository

git clone https://github.com/ecorey/tg_bot.git
cd tg_bot

2. Install Dependencies

npm install

3. Configure Environment

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env

Configuration

Environment Variables

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

# SUI Network Configuration  
SUI_NETWORK=mainnet
SUI_RPC_URL=https://sui-mainnet.nodereal.io/v1/your_api_key

# Security Settings
ENABLE_LOGGING=true
MAX_TRANSFER_AMOUNT=100
DEFAULT_SLIPPAGE=1.0

Bot Setup with @BotFather

1. Start a chat with @BotFather on Telegram
2. Send /newbot command
3. Choose a name and username for your bot
4. Copy the provided token to your .env file
5. Set bot commands using /setcommands

Project Structure

tg_bot/
├── src/                    # Source code
│   ├── bot/               # Bot logic and handlers
│   ├── wallet/            # SUI wallet management
│   ├── utils/             # Utility functions
│   └── types/             # TypeScript type definitions
├── tests/                 # Test suite (14 test cases)
├── assets/                # Static assets and resources  
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── .gitignore             # Git ignore rules
└── README.md              # Project documentation

Security Best Practices

🛡️ Essential Security Measures

• Environment Variables: Store all sensitive data in .env files
• .gitignore: Prevent committing sensitive configuration files
• Input Validation: Validate all user inputs and addresses
• Error Handling: Comprehensive error management without exposing sensitive data
• Key Management: Secure handling of private keys in memory
• Transaction Limits: Implement reasonable transfer limits
• Slippage Protection: Default slippage tolerance to prevent MEV attacks

🔄 Emergency Response

1. Immediate Actions: Stop the bot service immediately
2. Rotate Credentials: Generate new bot token from @BotFather
3. Review Logs: Check for any suspicious activity
4. Update Environment: Refresh all environment variables
5. Restart Service: Deploy with new credentials

🔍 Ongoing Security Practices

• Regular Audits: Review code and dependencies monthly
• Dependency Updates: Keep all packages updated
• Monitoring: Log all transactions and errors
• Testing: Run security tests before deployment
• Access Control: Limit bot permissions and user access

Troubleshooting

Common Issues

Bot not responding:
• Check TELEGRAM_BOT_TOKEN in environment variables
• Verify network connectivity to Telegram servers
• Ensure bot is not already running on another instance

Wallet creation fails:
• Verify SUI network RPC endpoint is accessible
• Check if wallet already exists for the user
• Ensure sufficient permissions for file operations

Transfer failures:
• Validate recipient address format
• Check wallet balance before transfer
• Verify slippage tolerance settings
• Ensure network connectivity to SUI blockchain

Test failures:
• Run: npm run test to see detailed errors
• Ensure test environment has proper configuration
• Check for any missing dependencies

Development Tips

• Use npm run build to check TypeScript compilation
• Run tests frequently with npx vitest run
• Monitor console logs for error messages and debugging info
• Test with small amounts before larger transfers
• Keep backup of wallet private keys in secure location
• Use testnet for development and testing phases