ndeet / ln-lnd-rest
Requires
- php: >=5.5
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- guzzlehttp/guzzle: ^6.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ~2.12
- phpunit/phpunit: ^4.8
- squizlabs/php_codesniffer: ~2.6
This package is auto-updated.
Last update: 2024-11-15 13:56:21 UTC
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