Lnd Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require lightningsale/lnd-client
   

   Ensure your project uses PHP 7.2+ (LND compatibility may require newer versions).

2. Basic Connection

   use LightningSale\LndClient\LndClient;
   
   $client = new LndClient(
       'your-lnd-grpc-url:10009', // Default gRPC port
       'macaroon-file-path',       // Path to macaroon file
       'admin-macaroon'            // Macaroon hex string or file content
   );
   

3. First Use Case: Check Node Info

   $nodeInfo = $client->getNodeInfo();
   dump($nodeInfo->getIdentityPubkey());
   

Key Files to Review

• src/LndClient.php – Core client class with all RPC methods.
• src/Protobuf/ – Generated protobuf classes (auto-generated from LND’s .proto files).
• tests/ – Example usage and edge cases.

Implementation Patterns

Common Workflows

1. Payment Handling

• Initiate Payment

  $invoice = $client->addInvoice([
      'value' => 1000, // Satoshis
      'memo' => 'Test payment',
  ]);
  $paymentResult = $client->sendPayment($invoice->getPaymentRequest());
  

• Listen for Payments (via WebSocket or polling)

  $client->subscribeToInvoices();
  $invoices = $client->listInvoices();
  

2. Channel Management

• Open a Channel

  $client->openChannel([
      'public_key' => 'node_pubkey',
      'local_funding_amount' => 1000000, // Satoshis
  ]);
  

• List Active Channels

  $channels = $client->listChannels();
  foreach ($channels as $channel) {
      dump($channel->getRemotePubkey());
  }
  

3. Wallet Operations

• Generate Address

  $address = $client->newAddress();
  

• Check Balance

  $balance = $client->walletBalance();
  dump($balance->getTotalBalance());
  

4. Error Handling

• Wrap calls in try-catch for Grpc\RpcException or LightningSale\LndClient\Exception\LndException.
• Example:

  try {
      $client->sendPayment($invoice);
  } catch (\Grpc\RpcException $e) {
      log::error("Payment failed: " . $e->getMessage());
  }
  

Integration Tips

Macaroon Management

• Store macaroons securely (e.g., environment variables or encrypted storage).
• Rotate macaroons periodically for security (use revokeMacaroon if needed).

gRPC Configuration

• Ensure your LND node’s gRPC interface is accessible (check lnd.conf for tlsextradomain and listen=0.0.0.0).
• For production, use TLS:

  $client = new LndClient(
      'lnd-grpc.example.com:10009',
      'macaroon_path',
      'admin_macaroon',
      ['credentials' => Grpc\ChannelCredentials::createSsl()]
  );
  

Async Operations

• Use sendPaymentSync() for blocking calls or sendPayment() with callbacks for async.
• For high-frequency operations, batch requests (e.g., listInvoices with pagination).

Logging

• Enable debug logging for gRPC:

  putenv('GRPC_VERBOSITY=DEBUG');
  

Gotchas and Tips

Pitfalls

1. Deprecated Protobufs

   • The package was last updated in 2018 and may not support newer LND versions (v0.14+).
   • Workaround: Manually update protobuf definitions or fork the repo to regenerate classes with protoc.

2. Macaroon Permissions

   • Ensure your macaroon has the correct permissions (e.g., invoice, sendpayments).
   • Debug: Use listMacaroons in LND’s CLI to verify permissions.

3. gRPC Timeouts

   • Default timeouts may be too short for slow networks. Adjust with:

     $client->setTimeout(30); // 30 seconds
     

4. Protobuf Type Mismatches

   • LND uses int64 for satoshis, but PHP may convert to float. Cast explicitly:

     $amount = (int) $client->walletBalance()->getTotalBalance();
     

5. WebSocket Limitations

   • The package lacks built-in WebSocket support for real-time updates. Use raw gRPC streaming or a separate WebSocket client.

Debugging Tips

• Check LND Logs

  tail -f ~/.lnd/logs/bitcoin/debug.log
  

• gRPC Debugging Enable verbose gRPC logging:

  putenv('GRPC_TRACE=all');
  

• Validate Protobuf Responses Use var_dump() or json_encode() to inspect raw responses:

  $rawResponse = $client->getRawResponse('GetInfo');
  

Extension Points

1. Custom Protobuf Extensions

   • Extend the auto-generated classes in Protobuf/ to add helper methods:

     namespace App\Extensions;
     use LightningSale\LndClient\Protobuf\Invoice;
     
     class InvoiceExtension extends Invoice {
         public function isPaid(): bool {
             return $this->getState() === Invoice::SETTLED;
         }
     }
     

2. Middleware for Requests

   • Wrap the client to add logging, retries, or metrics:

     class LoggingClient {
         public function __call($method, $args) {
             \Log::debug("Calling $method", $args);
             return $client->$method(...$args);
         }
     }
     

3. Event Dispatching

   • Trigger Laravel events for payments/invoices:

     event(new PaymentReceived($invoice));
     

4. Fallback for Deprecated Methods

   • Override deprecated methods to use newer LND RPCs:

     public function deprecatedMethod() {
         return $this->getClient()->newRpcMethod();
     }
     

Configuration Quirks

• Macaroon File Paths

  • Use absolute paths or ensure the path is resolvable from the PHP process’s working directory.

• LND Version Mismatch

  • If LND updates its gRPC API, the package may fail. Check compatibility by comparing .proto files.

• Network Isolation

  • Test in a local LND setup (e.g., lnd --nolisten for dev) before deploying to production.