README

A Lightning Network Daemon (LND) package for LND's REST endpoints. PHP classes are generated by the Swagger Codegen project using LND's rpc.swagger.json

• Based on LND version: 0.13.3-beta
• This package version: 0.13.3

Requirements

PHP 7.1 and later

Installation & Usage

Composer

To install the bindings via Composer, use the following command:

composer require ndeet/ln-lnd-rest

Tests

To run the unit tests:

composer install
./vendor/bin/phpunit

Getting Started

Note:

• The examples in the generated classes docs are not working out of the box. You will need to pass the port, use SSL and also use macaroons of your properly secured LND installation.
• Generated classes with lnd-0.13.3-beta are not tested yet by me due to lack of time currently. Fingers crossed everything works.

<?php
require_once(__DIR__ . '/vendor/autoload.php');

// Get tls and macaroon paths.
$tlsPath = '';
$macaroonPath = '';
$local_user = posix_getpwuid(posix_getuid());

switch (PHP_OS) {
  case "Darwin":
    $tlsPath = $local_user['dir'] . '/Library/Application Support/Lnd/tls.cert';
    $macaroonPath = $local_user['dir'] . '/Library/Application Support/Lnd/macaroon.admin';
    break;

  case "Linux":
    $tlsPath = $local_user['dir'] . '/.lnd/tls.cert';
    $macaroonPath = $local_user['dir'] . '/.lnd/macaroon.admin';
}

if (! $sslCert = file_get_contents($tlsPath)) {
  $certError = <<<EOT
    tls.cert not found in "example" directory. Make sure to copy it from your
    LND config directory.
    MacOS: ~/Library/Application Support/Lnd/tls.cert
    Linux: ~/.lnd/tls.cert
EOT;

  throw new Exception($certError);
}

// We need to use Configuration class for the url and can't pass it directly in GuzzleClient.
$apiConfig = new \Lnd\Rest\Configuration();
$apiConfig->setHost('https://localhost:8001');

// First we need to unlock the encrypted wallet. This needs only run once.
$walletInstance = new Lnd\Rest\Api\WalletUnlockerApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
  new GuzzleHttp\Client([
    'debug' => TRUE,
    'verify' => $tlsPath,
    'headers' => [
      'Grpc-Metadata-macaroon' => $macaroon
    ]
  ]),
  $apiConfig
);

$unlockRequest = new \Lnd\Rest\Model\LnrpcUnlockWalletRequest([
  'walletPassword' => base64_encode('YOUR_WALLET_PASS')
]);

try {
  $unlocked = $walletInstance->unlockWallet($unlockRequest);
  // gives 408 timeout but unlock successful, afterwards 404 not found
} catch (Exception $e) {
  echo 'Exception when calling WalletUnlockerApi->unlockWallet(): ', $e->getMessage(), PHP_EOL;
}

// We can now use the getInfo endpoint:
$apiInstance = new Lnd\Rest\Api\LightningApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
  new GuzzleHttp\Client([
    'debug' => TRUE,
    'verify' => $tlsPath,
    'headers' => [
      'Grpc-Metadata-macaroon' => bin2hex(file_get_contents($macaroonPath))
    ]
  ]),
  $apiConfig
);

try {
  $result = $apiInstance->getInfo();
  var_dump($result);
} catch (Exception $e) {
  echo 'Exception when calling LightningApi->getInfo: ', $e->getMessage(), PHP_EOL;
}

// Let's generate an lightning invoice.
$invoice = new \Lnd\Rest\Model\LnrpcInvoice([
  'memo' => 'testinvoice memo',
  'value' => 1001,
  'expiry' => 3600
]);

try {
  $invoiceResult = $apiInstance->addInvoice($invoice);
  var_dump($invoiceResult);
} catch (Exception $e) {
  echo 'Exception when calling LightningApi->addInvoice: ', $e->getMessage(), PHP_EOL;
}

?>

How to generate the code yourself

You can use swagger-codegen to create this whole package out of the rpc.swagger.json of LND. To do this you need swagger-codegen and (for this package as example) this lnrest-config.json:

{
  "variableNamingConvention": "camelCase",
  "invokerPackage": "Lnd\\Rest",
  "packagePath": "LndRest",
  "srcBasePath": "src",
  "composerVendorName": "ndeet",
  "gitUserId": "ndeet",
  "composerProjectName": "ln-lnd-rest",
  "gitRepoId": "php-ln-lnd-rest",
  "artifactVersion": "0.13.3",
  "license": "MIT"
}

You can generate the code by having the official lightningnetwork/lnd repo checked out to the tag you need and then use that rpc.swagger.json for the code genration like this.

swagger-codegen generate -c lnrest-config.json -l php -o php-ln-lnd-rest -i /path/to/lightningnetwork/lnd/lnrpc/rpc.swagger.json

Notice regarding to subscribeInvoices endpoint

The REST endpoints are generated from the same gRPC rpc.proto file and it seems the streaming does not work on REST services according to LND's lead developer @roasbeef. But they plan to provide Websockets in a future release. So you may need to do some custom long polling using lookupInvoice endpoint.

This are some autogenerated docs pointing to classes docs:

Documentation for API endpoints

Lightning API Endpoints
Wallet Unlocker API

Documentation for authorization

All endpoints do not require authorization. Make sure that those endpoints provided by this package are not publicly accessible. If you set a wallet password you need to unlock your wallet first, see documentation and example above.

Author

Andreas Tasch