README

Laravel Tron Package

Laravel Tron is a comprehensive Laravel package for working with the Tron blockchain and TRC-20 tokens. It allows you to generate HD wallets using mnemonic phrases (BIP39/BIP44), validate addresses, check balances and resources, preview and send TRX/TRC-20 tokens. Automate cryptocurrency receiving and withdrawals in your Laravel application with ease.

Features
Requirements
Installation
Configuration
Quick Start
Usage
Advanced Usage
Testing
Artisan Commands
Security
Troubleshooting
Changelog
Support
Credits
License

Features

✨ Key Features:

🔐 Built-in BIP39/BIP44 Support - No external dependencies for mnemonic generation
💼 HD Wallet Generation - Create hierarchical deterministic wallets
🎯 Multiple Address Support - Generate unlimited addresses from a single seed
💰 TRX & TRC-20 Support - Full support for native TRX and TRC-20 tokens
🔄 Automatic Synchronization - Background sync of transactions and balances
📊 Resource Management - Track bandwidth and energy usage
🎨 Customizable Models - Extend default models to fit your needs
🔔 Webhook Handler - Custom event handling for deposits
🧪 Fully Tested - Comprehensive test suite with 17 tests
🛡️ Secure - Encrypted storage for sensitive data

Requirements

PHP: 8.1 or newer
Laravel: 10.0 or newer (tested with Laravel 10, 11, and 12)
PHP Extensions:
- ext-gmp - GNU Multiple Precision arithmetic
- ext-ctype - Character type checking
External Services:
- TronGrid API key (Get one here)

Installation

Install the package via Composer:

composer require it-healer/laravel-tron

Run the installer command:

php artisan tron:install

This will publish the configuration file and migrations.

Run the migrations:

php artisan migrate

Laravel 11+ (Automatic Discovery)

The package will be automatically discovered. No additional steps needed!

Laravel 10 (Manual Registration)

For Laravel 10, register the Service Provider and Facade in config/app.php:

'providers' => ServiceProvider::defaultProviders()->merge([
    // ...
    \ItHealer\LaravelTron\TronServiceProvider::class,
])->toArray(),

'aliases' => Facade::defaultAliases()->merge([
    // ...
    'Tron' => \ItHealer\LaravelTron\Facades\Tron::class,
])->toArray(),

Scheduler Setup

For Laravel 10:

Edit app/Console/Kernel.php and add to the schedule() method:

protected function schedule(Schedule $schedule): void
{
    $schedule->command('tron:sync')
        ->everyMinute()
        ->runInBackground();
}

For Laravel 11+:

Add to routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('tron:sync')
    ->everyMinute()
    ->runInBackground();

Configuration

After installation, you'll find the configuration file at config/tron.php:

return [
    /*
     * Touch Synchronization System (TSS)
     * Optimize sync by only updating recently touched addresses
     */
    'touch' => [
        'enabled' => false,
        'waiting_seconds' => 3600, // 1 hour
    ],

    /*
     * Webhook handler for deposit events
     */
    'webhook_handler' => \ItHealer\LaravelTron\Handlers\EmptyWebhookHandler::class,

    /*
     * Custom model classes
     */
    'models' => [
        'api' => \ItHealer\LaravelTron\Api\Api::class,
        'node' => \ItHealer\LaravelTron\Models\TronNode::class,
        'wallet' => \ItHealer\LaravelTron\Models\TronWallet::class,
        'address' => \ItHealer\LaravelTron\Models\TronAddress::class,
        'trc20' => \ItHealer\LaravelTron\Models\TronTRC20::class,
        'transaction' => \ItHealer\LaravelTron\Models\TronTransaction::class,
        'deposit' => \ItHealer\LaravelTron\Models\TronDeposit::class,
    ]
];

Custom Webhook Handler

Create a custom webhook handler to process deposit events:

namespace App\Handlers;

use ItHealer\LaravelTron\Handlers\WebhookHandler;
use ItHealer\LaravelTron\Models\TronDeposit;

class CustomWebhookHandler extends WebhookHandler
{
    public function handle(TronDeposit $deposit): void
    {
        // Your custom logic here
        // Send notification, update user balance, etc.
    }
}

Then update config/tron.php:

'webhook_handler' => \App\Handlers\CustomWebhookHandler::class,

Quick Start

1. Register with TronGrid

First, create an account on TronGrid and generate an API key.

2. Create a Tron Node

use ItHealer\LaravelTron\Facades\Tron;

$apiKey = "your-trongrid-api-key";
$node = Tron::createTronGridNode($apiKey, 'MainNet Node');

3. Generate a Wallet

// Generate a new mnemonic phrase (15 words by default)
$mnemonic = Tron::mnemonicGenerate(15);
echo 'Mnemonic: ' . implode(' ', $mnemonic);

// Create wallet from mnemonic
$wallet = Tron::createWallet('My Wallet', $mnemonic);

4. Create an Address

// Primary address is created automatically when wallet is created
// Get the primary address
$address = $wallet->addresses()->first();

// Or create additional addresses
$secondaryAddress = Tron::createAddress($wallet, 'Secondary Address');

echo 'Address: ' . $address->address;

5. Send TRX

$recipientAddress = 'TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW';
$amount = 10; // 10 TRX

$transfer = Tron::transfer($address, $recipientAddress, $amount);

echo 'Transaction ID: ' . $transfer->txid;

Usage

Working with Nodes

Create a Node

use ItHealer\LaravelTron\Facades\Tron;

// Using TronGrid
$node = Tron::createTronGridNode($apiKey, 'Node Name');

// Custom node
$node = Tron::createNode('Node Name', 'https://api.trongrid.io');

Get Node Information

$node = Tron::getNode(); // Get default node
$apiUrl = $node->api_url;
$requestsCount = $node->requests;

Working with Wallets

Generate Wallet

// Generate with default 15 words
$mnemonic = Tron::mnemonicGenerate();

// Generate with custom word count (12, 15, 18, 21, or 24)
$mnemonic = Tron::mnemonicGenerate(24);

// Create wallet
$wallet = Tron::createWallet('Wallet Name', $mnemonic);

Import Existing Wallet

$mnemonic = "your existing twenty four word mnemonic phrase here...";
$wallet = Tron::importWallet('Imported Wallet', $mnemonic);

Wallet with Passphrase

$mnemonic = Tron::mnemonicGenerate();
$passphrase = "super-secret-passphrase";
$wallet = Tron::createWallet('Wallet Name', $mnemonic, $passphrase);

Validate Mnemonic

$isValid = Tron::mnemonicValidate($mnemonic);
if ($isValid) {
    echo "Mnemonic is valid!";
}

Working with Addresses

Create Address

// Create with auto-incremented index
$address = Tron::createAddress($wallet, 'Address Label');

// Create with specific index
$address = Tron::newAddress($wallet, 'Custom Address', $index = 5);

Import Watch-Only Address

$address = Tron::importAddress($wallet, 'TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW');

Validate Address

$isValid = Tron::validateAddress('TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW');

Get Address Balance

$balance = $address->balance; // Balance in TRX
$balanceSun = $address->balance_sun; // Balance in SUN (1 TRX = 1,000,000 SUN)

Get Address Resources

$resources = $address->getResources();
echo "Bandwidth: " . $resources->bandwidth;
echo "Energy: " . $resources->energy;

Working with TRX

Preview Transfer

$preview = Tron::transferPreview($address, $recipientAddress, $amount);

echo "Fee: " . $preview->fee . " TRX";
echo "Total: " . $preview->total . " TRX";

Send TRX

$transfer = Tron::transfer($address, $recipientAddress, $amount);

if ($transfer->success) {
    echo "Transaction sent! TXID: " . $transfer->txid;
} else {
    echo "Transfer failed: " . $transfer->error;
}

Working with TRC-20 Tokens

Register TRC-20 Token

use ItHealer\LaravelTron\Models\TronTRC20;

// USDT TRC-20 contract address
$contractAddress = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t';

$token = TronTRC20::create([
    'contract_address' => $contractAddress,
    'name' => 'Tether USD',
    'symbol' => 'USDT',
    'decimals' => 6,
]);

Get TRC-20 Balance

$balance = $address->getTRC20Balance($token);
echo "USDT Balance: " . $balance;

Preview TRC-20 Transfer

$preview = Tron::transferTRC20Preview($address, $recipientAddress, $amount, $token);

echo "Fee: " . $preview->fee . " TRX";
echo "Energy Required: " . $preview->energy_required;

Send TRC-20 Tokens

$transfer = Tron::transferTRC20($address, $recipientAddress, $amount, $token);

if ($transfer->success) {
    echo "Transaction sent! TXID: " . $transfer->txid;
}

Advanced Usage

Custom Models

Extend the default models to add custom functionality:

namespace App\Models;

use ItHealer\LaravelTron\Models\TronWallet as BaseTronWallet;

class TronWallet extends BaseTronWallet
{
    // Add custom methods or properties
    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

Update config/tron.php:

'models' => [
    'wallet' => \App\Models\TronWallet::class,
    // ...
],

Touch Synchronization System (TSS)

For applications with many addresses, enable TSS to optimize synchronization:

// In config/tron.php
'touch' => [
    'enabled' => true,
    'waiting_seconds' => 3600, // Sync for 1 hour after touch
],

Touch an address when user activity is detected:

$address->touch(); // Updates touch_at timestamp

Multiple Derivation Paths

The package uses BIP44 standard with the path m/44'/195'/0'/0 for Tron:

// Create addresses with different indexes from the same wallet
$address0 = Tron::createAddress($wallet, 'Address 0', 0);
$address1 = Tron::createAddress($wallet, 'Address 1', 1);
$address2 = Tron::createAddress($wallet, 'Address 2', 2);

Testing

The package includes a comprehensive test suite:

# Run all tests
composer test

# Run with detailed output
vendor/bin/phpunit --testdox

# Run specific test
vendor/bin/phpunit --filter MnemonicTest

Test Coverage:

✅ BIP39 mnemonic generation (12, 15, 24 words)
✅ BIP39 mnemonic validation
✅ Seed generation with/without passphrase
✅ BIP44 address derivation
✅ Private/public key generation
✅ Address generation from private keys
✅ Multiple address generation

See tests/README.md for more details.

Artisan Commands

Synchronization Commands

# Sync everything (all nodes, wallets, addresses)
php artisan tron:sync

# Sync specific node
php artisan tron:sync-node {nodeId}

# Sync specific wallet
php artisan tron:sync-wallet {walletId}

# Sync specific address
php artisan tron:sync-address {addressId}

Creation Commands

# Create a new Tron node
php artisan tron:new-node

# Create a new wallet
php artisan tron:new-wallet

# Generate a new address
php artisan tron:new-address

# Import watch-only address
php artisan tron:import-address

# Register TRC-20 token
php artisan tron:new-trc20

Security

Best Practices

🔐 Never store mnemonics in plain text - Always encrypt sensitive data
🔑 Use strong passphrases - Add an additional layer of security to wallets
🌐 Use HTTPS - Always communicate with Tron nodes over HTTPS
🔒 Secure your database - Encrypt database backups and use strong credentials
👥 Limit access - Restrict who can access wallet operations
📝 Log transactions - Keep audit logs of all cryptocurrency operations
🧪 Test on testnet first - Always test on Shasta testnet before mainnet

Encrypted Storage

The package automatically encrypts sensitive data:

Private keys are encrypted using Laravel's encryption
Mnemonics are encrypted before storage
Passwords are hashed using bcrypt

Reporting Vulnerabilities

If you discover a security vulnerability, please email info@it-healer.com. All security vulnerabilities will be promptly addressed.

Troubleshooting

Common Issues

Issue: "Class 'GMP' not found"

# Install GMP extension
# Ubuntu/Debian
sudo apt-get install php-gmp

# macOS (Homebrew)
brew install gmp

Issue: "Invalid mnemonic phrase"

Ensure the mnemonic has the correct number of words (12, 15, 18, 21, or 24)
Check for typos in the mnemonic words
Verify words are from the BIP39 wordlist

Issue: "Insufficient energy"

Freeze TRX to get energy
Or use TRX to pay for energy (higher cost)
Consider using transferPreview() to estimate costs

Issue: "Node API limit exceeded"

TronGrid free tier has rate limits
Upgrade to a paid plan on TronGrid
Or use your own Tron node

Debug Mode

Enable debug logging in .env:

LOG_LEVEL=debug

Check logs in storage/logs/laravel.log for detailed information.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Support

Need help? Reach out to us:

💬 Telegram: @biodynamist
📱 WhatsApp: +905516294716
🌐 Website: it-healer.com
📧 Email: info@it-healer.com
🐛 Issues: GitHub Issues

Credits

IT-HEALER
Built with ❤️ using Laravel
Powered by TronGrid

License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ by IT-HEALER

it-healer / laravel-tron

Maintainers

Details