README

Multi-cryptocurrency RPC integration for Laravel with dedicated facades for each coin. Production-ready with circuit breakers, health monitoring, and automatic failover.

Features

🚀 Clean Facade API: Use Bitcoin::, Bch::, Ltc::, Bc2:: instead of complex factories
🔄 Multi-Node Failover: Automatic switching between primary and backup nodes
🛡️ Circuit Breaker: Protects against cascading failures
📊 Health Monitoring: Real-time node health checks and metrics
⚡ Performance Tracking: Response time monitoring and optimization
🔧 Laravel Integration: Full auto-discovery, artisan commands, and logging
🪙 Multi-Coin Support: Bitcoin, Bitcoin Cash, Litecoin, Bitcoinii, and more
📦 Production Ready: Battle-tested with 95% test coverage

Quick Start

Install the package

composer require skaisser/laravel-multicoin-rpc

Simple Setup (Single Coin)

Add to your .env file:

# Bitcoin only
BITCOIN_RPC_HOST=localhost
BITCOIN_RPC_PORT=8332
BITCOIN_RPC_USER=your-rpc-user
BITCOIN_RPC_PASSWORD=your-rpc-password

Use in your code:

use Bitcoin;

// Get blockchain info
$info = Bitcoin::getBlockchainInfo();

// Get current block count
$height = Bitcoin::getBlockCount();

// Get specific block
$block = Bitcoin::getBlock($blockHash);

// Validate address
$valid = Bitcoin::validateAddress('bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh');

Setup with Failover (Recommended for Production)

Add primary and backup nodes to .env:

# Primary node
BITCOIN_RPC_HOST=localhost
BITCOIN_RPC_PORT=8332
BITCOIN_RPC_USER=your-rpc-user
BITCOIN_RPC_PASSWORD=your-rpc-password

# Backup node (automatic failover)
BITCOIN_RPC_BACKUP_HOST=backup.server.com
BITCOIN_RPC_BACKUP_PORT=8332
BITCOIN_RPC_BACKUP_USER=backup-user
BITCOIN_RPC_BACKUP_PASSWORD=backup-password

The package automatically switches to the backup node if the primary fails.

Multiple Cryptocurrencies

use Bitcoin;
use Bch;
use Ltc;
use Bc2;

// Each coin has its own facade
$btcInfo = Bitcoin::getBlockchainInfo();
$bchInfo = Bch::getBlockchainInfo();
$ltcInfo = Ltc::getBlockchainInfo();
$bc2Info = Bc2::getBlockchainInfo();

Advanced Configuration

For detailed configuration options, see Installation Guide.

Available Methods

All coins support these common RPC methods:

// Blockchain
getBlockchainInfo()
getBlockCount()
getBlock(string $hash, int $verbosity = 1)
getBlockHash(int $height)

// Transactions
getRawTransaction(string $txid, bool $verbose = false)
sendRawTransaction(string $hexString)
validateAddress(string $address)

// Network
getNetworkInfo()
getPeerInfo()
getConnectionCount()

// Mining
getMiningInfo()
getDifficulty()

Artisan Commands

# Check node health
php artisan multicoin:health

# List configured coins
php artisan multicoin:list

# Add new coin support
php artisan multicoin:add dash --name="Dash" --port=9998

Production Features

Health Monitoring

php artisan multicoin:health --coin=btc

# Output:
# Bitcoin (BTC) Health Check
# ==========================
# Primary Node: ✅ Healthy (245ms)
# Backup Node: ✅ Healthy (312ms)
# Block Height: 830,000
# Circuit Breaker: Closed

Event Listening

use Skaisser\MultiCoinRpc\Events\NodeFailover;
use Illuminate\Support\Facades\Event;

Event::listen(NodeFailover::class, function ($event) {
    Log::warning("Node failover: {$event->coin} switched from {$event->failedNode} to {$event->activeNode}");
});

Testing

composer test
composer test-coverage

Mock RPC calls in your tests:

use Bitcoin;

it('can get block count', function () {
    Bitcoin::fake(['getBlockCount' => 830000]);

    expect(Bitcoin::getBlockCount())->toBe(830000);
});

Documentation

Installation Guide - Detailed setup instructions
Contributing - How to contribute
Changelog - Version history

Requirements

PHP 8.2+
Laravel 11.x or 12.x
Bitcoin Core or compatible node with RPC enabled

Security

If you discover any security issues, please email skaisser@gmail.com instead of using the issue tracker.

Credits

License

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

Made with ❤️ by Shirleyson Kaisser

skaisser / laravel-multicoin-rpc

Maintainers

Details