-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #61 from RadarTech/cf-cc-1123-subserver-support
Typescript Refactor & Sub-Server Support
- Loading branch information
Showing
101 changed files
with
9,470 additions
and
1,783 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,3 +3,5 @@ yarn-error.log | |
| .esm-cache | ||
| /rpc.proto | ||
| *.macaroon | ||
| dist | ||
| .DS_Store | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| { | ||
| "typescript.tsdk": "node_modules/typescript/lib" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,18 +1,19 @@ | ||
| ## LNRPC | ||
| ## @radar/lnrpc | ||
|
|
||
| [](https://circleci.com/gh/RadarTech/lnrpc) | ||
| [](https://snyk.io/test/github/RadarTech/lnrpc?targetFile=package.json) | ||
| [](https://www.npmjs.com/package/@radar/lnrpc) | ||
| [](https://img.shields.io/github/license/radartech/lnrpc.svg?style=flat) | ||
|
|
||
| Maintained fork of [lnrpc](https://github.com/Matt-Jensen/lnrpc) adding support for generating typescript type definitions. | ||
| A Typescript gRPC client for LND with support for all LND sub-servers. Originally forked from [Matt-Jensen/lnrpc](https://github.com/Matt-Jensen/lnrpc). | ||
|
|
||
| ### Features | ||
| - Auto-generates [lnd/lnrpc](https://github.com/lightningnetwork/lnd/tree/master/lnrpc) client and typescript definitons based on target release tag | ||
| - Auto-generates [lnd/lnrpc](https://github.com/lightningnetwork/lnd/tree/master/lnrpc) clients and Typescript type definitions using a target release tag | ||
| - Supports all LND sub-servers | ||
| - Wraps requests in promises | ||
| - Easily setup SSL and Macaroons | ||
| - Instantiates all gRPC services | ||
| - uint64/int64 types cast to string | ||
| - uint64/int64 types cast to string to prevent precision loss | ||
|
|
||
| ### Installation | ||
| ```sh | ||
|
|
@@ -21,40 +22,96 @@ npm install @radar/lnrpc | |
| yarn add @radar/lnrpc | ||
| ``` | ||
|
|
||
| Install [lnd](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md) before using this project and ensure you have an lnd instance running with `--no-macaroons`, unless you provide macaroon authentication to your lnrpc instance when created. | ||
| **Notes:** | ||
| - Ensure you have an lnd instance running with `--no-macaroons`, unless you provide macaroon authentication to your lnrpc instance when created. | ||
| - If you want to interact with the LND sub-servers, ensure that LND was compiled with the necessary sub-server build tags. | ||
|
|
||
| ### Change LND gRPC release version | ||
| To change the gRPC definitions used for all auto-generated types and RPC methods edit the `config.lnd_release_tag` value in `package.json` to the desired [LND release tag](https://github.com/lightningnetwork/lnd/releases) and run the following: | ||
|
|
||
| ```sh | ||
| npm run update-proto | ||
| # OR | ||
| yarn update-proto | ||
| ### Usage | ||
|
|
||
| # AND | ||
| This package exports a create function for the main gRPC server as well as each sub-server: | ||
|
|
||
| npm run generate | ||
| # OR | ||
| yarn generate | ||
| ```typescript | ||
| import { | ||
| createAutopilotRpc, | ||
| createChainRpc, | ||
| createInvoicesRpc, | ||
| createLnRpc, | ||
| createRouterRpc, | ||
| createSignRpc, | ||
| createWalletRpc, | ||
| createWatchtowerRpc, | ||
| createWtClientRpc, | ||
| } from '@radar/lnrpc'; | ||
| ``` | ||
| Newly generated type definitions will be available in `./generated`. | ||
| You can now delete the old proto file inside the lnd directory. | ||
| Use the generated type definitions to update the types in `lnrpc.d.ts`. | ||
|
|
||
| You can also import the create function for the main gRPC server using the default import: | ||
|
|
||
| ### Usage | ||
| ```typescript | ||
| import createLnRpc from '@radar/lnrpc'; | ||
| ``` | ||
|
|
||
| Connecting to an lnd instance at `localhost:10001`. | ||
| If you want to interact with all servers, wrap the functions in a class or object for easy initialization: | ||
|
|
||
| ```typescript | ||
| import createLnRpc, { | ||
| Invoice, | ||
| InvoiceSubscription, | ||
| WalletBalanceResponse | ||
| AutopilotRpc, | ||
| ChainRpc, | ||
| createAutopilotRpc, | ||
| createChainRpc, | ||
| createInvoicesRpc, | ||
| createRouterRpc, | ||
| createSignRpc, | ||
| createWalletRpc, | ||
| createWatchtowerRpc, | ||
| createWtClientRpc, | ||
| InvoicesRpc, | ||
| LnRpc, | ||
| RouterRpc, | ||
| RpcClientConfig, | ||
| SignRpc, | ||
| WalletRpc, | ||
| WatchtowerRpc, | ||
| WtClientRpc, | ||
| } from '@radar/lnrpc'; | ||
|
|
||
| export class Lightning { | ||
| public static lnrpc: LnRpc; | ||
| public static autopilotrpc: AutopilotRpc; | ||
| public static chainrpc: ChainRpc; | ||
| public static invoicesrpc: InvoicesRpc; | ||
| public static routerrpc: RouterRpc; | ||
| public static signrpc: SignRpc; | ||
| public static walletrpc: WalletRpc; | ||
| public static watchtowerrpc: WatchtowerRpc; | ||
| public static wtclientrpc: WtClientRpc; | ||
|
|
||
| /** | ||
| * Initialize gRPC clients for the main server and all sub-servers | ||
| * @param config The RPC client connection configuration | ||
| */ | ||
| public static async init(config: RpcClientConfig): Promise<void> { | ||
| this.lnrpc = await createLnRpc(config); | ||
| this.autopilotrpc = await createAutopilotRpc(config); | ||
| this.chainrpc = await createChainRpc(config); | ||
| this.invoicesrpc = await createInvoicesRpc(config); | ||
| this.routerrpc = await createRouterRpc(config); | ||
| this.signrpc = await createSignRpc(config); | ||
| this.walletrpc = await createWalletRpc(config); | ||
| this.watchtowerrpc = await createWatchtowerRpc(config); | ||
| this.wtclientrpc = await createWtClientRpc(config); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Usage Example - Main Server | ||
|
|
||
| Connecting to an lnd instance at `localhost:10001`. | ||
|
|
||
| ```typescript | ||
| import createLnRpc from '@radar/lnrpc'; | ||
|
|
||
| (async () => { | ||
| const lnRpcClient = await createLnRpc(); | ||
| const lnRpcClient = await createLnRpc(config); | ||
|
|
||
| // All requests are promisified and typed | ||
| const { confirmedBalance } = await lnRpcClient.walletBalance(); | ||
|
|
@@ -70,47 +127,45 @@ import createLnRpc, { | |
| })(); | ||
| ``` | ||
|
|
||
| ### Options | ||
| ### Options Example - Main Server | ||
|
|
||
| ```typescript | ||
| import createLnRpc, { | ||
| GetInfoResponse | ||
| } from '@radar/lnrpc'; | ||
| import createLnRpc from '@radar/lnrpc'; | ||
|
|
||
| (async () => { | ||
| const lnRpcClient = await createLnRpc({ | ||
| /* | ||
| By default lnrpc connects to `localhost:10001`, | ||
| however we can point to any host. | ||
| * By default lnrpc connects to `localhost:10001`, | ||
| * however we can point to any host. | ||
| */ | ||
| server: '173.239.209.2:3001', | ||
|
|
||
| /* | ||
| By default lnrpc looks for your tls certificate at: | ||
| `~/.lnd/tls.cert`, unless it detects you're using macOS and | ||
| defaults to `~/Library/Application\ Support/Lnd/tls.cert` | ||
| however you can configure your own SSL certificate path like: | ||
| * By default lnrpc looks for your tls certificate at: | ||
| * `~/.lnd/tls.cert`, unless it detects you're using macOS and | ||
| * defaults to `~/Library/Application\ Support/Lnd/tls.cert` | ||
| * however you can configure your own SSL certificate path like: | ||
| */ | ||
| tls: './path/to/tls.cert', | ||
|
|
||
| /* | ||
| You can also provide a TLS certificate directly as a string | ||
| (Just make sure you don't commit this to git). | ||
| Overwrites: `tls` | ||
| * You can also provide a TLS certificate directly as a string | ||
| * (Just make sure you don't commit this to git). | ||
| * Overwrites: `tls` | ||
| */ | ||
| cert: process.env.MY_SSL_CERT, | ||
|
|
||
| /* | ||
| Optional path to configure macaroon authentication | ||
| from LND generated macaroon file. | ||
| * Optional path to configure macaroon authentication | ||
| * from LND generated macaroon file. | ||
| */ | ||
| macaroonPath: './path/to/data/admin.macaroon', | ||
|
|
||
| /* | ||
| Optional way to configure macaroon authentication by | ||
| passing a hex encoded string of your macaroon file. | ||
| Encoding: `xxd -ps -u -c 1000 ./path/to/data/admin.macaroon` | ||
| Details: https://github.com/lightningnetwork/lnd/blob/dc3db4b/docs/macaroons.md#using-macaroons-with-grpc-clients | ||
| * Optional way to configure macaroon authentication by | ||
| * passing a hex encoded string of your macaroon file. | ||
| * Encoding: `xxd -ps -u -c 1000 ./path/to/data/admin.macaroon` | ||
| * Details: https://github.com/lightningnetwork/lnd/blob/dc3db4b/docs/macaroons.md#using-macaroons-with-grpc-clients | ||
| */ | ||
| macaroon: process.env.MY_MACAROON_HEX, | ||
| }); | ||
|
|
@@ -126,47 +181,43 @@ import createLnRpc, { | |
|
|
||
| ### API Reference | ||
|
|
||
| [All lnrpc methods documentation can be found here](http://api.lightning.community). | ||
|
|
||
| ### Usage With Typescript | ||
|
|
||
| You must enable the `esModuleInterop` Typescript compiler option if you would like to use a default import. | ||
|
|
||
| This can be accomplished by setting `"esModuleInterop": true` in your `tsconfig.json`. | ||
|
|
||
| Import Example: | ||
| ```typescript | ||
| import createLnRpc from '@radar/lnrpc'; | ||
| ``` | ||
|
|
||
| Otherwise, you can import `createLnRpc` using the `as *` syntax. | ||
|
|
||
| Import Example: | ||
| ```typescript | ||
| import * as createLnRpc from '@radar/lnrpc'; | ||
| ``` | ||
| [All main server (lnrpc) methods documentation can be found here](http://api.lightning.community). | ||
|
|
||
| ### Usage With BTCPayServer | ||
|
|
||
| By default lnrpc assumes SSl certificate pinning. | ||
| In order to use lnrpc with a service (like BTCPayServer) which manages your certification, | ||
| you'll have to opt to disable certificate pinning by passing `{ tls: false }` within your lnrpc configuration. | ||
|
|
||
| ### Contributors | ||
|
|
||
| To develop on the project please run: | ||
| ### Contributing | ||
|
|
||
| #### Clone Repository & Install Dependencies | ||
| ```sh | ||
| git clone [email protected]:RadarTech/lnrpc.git && cd $_ | ||
|
|
||
|
|
||
| npm install | ||
| npm start | ||
| # OR | ||
| yarn | ||
| yarn start | ||
| ``` | ||
|
|
||
| #### Change LND gRPC release version | ||
| To change the gRPC definitions used for all auto-generated types and RPC methods edit the `config.lnd_release_tag` value in `package.json` to the desired [LND release tag](https://github.com/lightningnetwork/lnd/releases) and run the following: | ||
|
|
||
| ```sh | ||
| npm run update-protos | ||
| # OR | ||
| yarn update-protos | ||
|
|
||
| # AND | ||
|
|
||
| npm run generate | ||
| # OR | ||
| yarn generate | ||
| ``` | ||
| Newly generated type definitions will be available in `./generated`. | ||
| You can now delete the old proto file inside the lnd directory. | ||
| Use the generated type definitions to update the types in `src/types/rpc`. | ||
|
|
||
| ### License | ||
|
|
||
| This project is licensed under the MIT License. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.