Cryptocurrency Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require analogic/cryptocurrency-bundle
   

   Enable the bundle in config/bundles.php:

   Analogic\CryptocurrencyBundle\AnalogicCryptocurrencyBundle::class => ['all' => true],
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=cryptocurrency-config
   

   Update config/packages/analogic_cryptocurrency.yaml with your:

   • LND (Lightning Network Daemon) RPC credentials
   • Network settings (e.g., mainnet, testnet)

3. First Use Case: Fetching Wallet Balance Inject the CryptocurrencyService into a controller or command:

   use Analogic\CryptocurrencyBundle\Service\CryptocurrencyService;
   
   public function __construct(private CryptocurrencyService $cryptoService) {}
   
   public function showBalance() {
       $balance = $this->cryptoService->getWalletBalance();
       return response()->json($balance);
   }
   

Implementation Patterns

Core Workflows

1. Daemon Communication Use the service to interact with LND via RPC:

   // Open a channel
   $this->cryptoService->openChannel('node_pubkey', 1000000);
   
   // List payments
   $payments = $this->cryptoService->listPayments();
   

2. Event-Driven Extensions Subscribe to LND events (e.g., invoice_paid, channel_open) via Symfony’s event system:

   # config/packages/analogic_cryptocurrency.yaml
   services:
       App\EventListener\CryptoEventListener:
           tags:
               - { name: kernel.event_listener, event: analogic.cryptocurrency.event, method: onEvent }
   

3. Command-Line Integration Create Artisan commands for admin tasks:

   use Analogic\CryptocurrencyBundle\Service\CryptocurrencyService;
   
   class SyncChannelsCommand extends Command {
       protected function execute(InputInterface $input, OutputInterface $output) {
           $this->cryptoService->syncChannels();
           $output->writeln('Channels synced!');
       }
   }
   

Integration Tips

• Laravel Service Providers: Bind the bundle’s services to Laravel’s container in AppServiceProvider:

  $this->app->bind('Analogic\CryptocurrencyBundle\Service\CryptocurrencyService', function ($app) {
      return new CryptocurrencyService($app['analogic_cryptocurrency.client']);
  });
  

• API Controllers: Use the service to build REST endpoints for crypto operations:

  public function createInvoice(Request $request) {
      $invoice = $this->cryptoService->createInvoice($request->amount);
      return response()->json($invoice);
  }
  

• Testing: Mock the CryptocurrencyService in PHPUnit:

  $this->mock(CryptocurrencyService::class)->shouldReceive('getWalletBalance')->andReturn(['sat': 1000000]);
  

Gotchas and Tips

Common Pitfalls

1. Deprecated Dependencies

   • The bundle relies on lightningsale/lnd-client (last updated in 2019). Ensure compatibility with your LND version (v0.13+ recommended).
   • Workaround: Fork the package and update the client library if needed.

2. Socket Timeouts

   • The underlying analogic/socket package may hang if LND is unreachable. Set a timeout in config:

     analogic_cryptocurrency:
         client:
             timeout: 30 # seconds
     

3. Testnet vs. Mainnet

   • Misconfigured networks (e.g., using testnet credentials on mainnet) will fail silently. Validate in logs:

     $this->cryptoService->getInfo(); // Check 'network' field
     

4. Rate Limiting

   • LND may throttle RPC calls. Implement exponential backoff in custom services:

     try {
         $this->cryptoService->listPayments();
     } catch (RateLimitException $e) {
         sleep(2 ** $attempts++);
         retry();
     }
     

Debugging Tips

• Enable RPC Logging: Add to config/packages/analogic_cryptocurrency.yaml:

  client:
      debug: true
  

  Logs will appear in storage/logs/laravel.log.

• Check Socket Connection:

  telnet lnd-host 10009 # Default LND RPC port
  

  If unreachable, verify firewall rules and LND’s lnd.conf (rpcbind setting).

Extension Points

1. Custom RPC Methods Extend the client via a decorator:

   class ExtendedCryptoService extends CryptocurrencyService {
       public function customRpcCall($method, $params) {
           return $this->client->call($method, $params);
       }
   }
   

2. Database Persistence Save LND responses to a model (e.g., Payment):

   $payment = $this->cryptoService->listPayments()[0];
   Payment::create([
       'hash' => $payment['payment_hash'],
       'amount' => $payment['amt'],
   ]);
   

3. Webhook Integration Use Symfony’s HttpClient to forward LND events to an external service:

   $this->httpClient->post('https://your-service.com/webhook', [
       'body' => json_encode($eventData),
   ]);