@lily-technologies/lnrpc

A Typescript gRPC client for LND with support for all LND sub-servers. Originally forked from RadarTech/lnrpc.

$3

- Auto-generates lnd/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 to prevent precision loss

$3

``sh
npm install @lily-technologies/lnrpc

OR

yarn add @lily-technologies/lnrpc
`

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.
- If the following error is thrown in the consuming application, run npm rebuild:
`
Error: Failed to load gRPC binary module because it was not installed for the current system
`

$3

This package exports a create function for the main gRPC server as well as each sub-server:

`typescript
import {
createAutopilotRpc,
createChainRpc,
createInvoicesRpc,
createLnRpc,
createRouterRpc,
createSignRpc,
createWalletRpc,
createWatchtowerRpc,
createWtClientRpc,
} from '@lily-technologies/lnrpc';
`

You can also import the create function for the main gRPC server using the default import:

`typescript
import createLnRpc from '@lily-technologies/lnrpc';
`

If you want to interact with all servers, wrap the functions in a class or object for easy initialization:

`typescript
import createLnRpc, {
AutopilotRpc,
ChainRpc,
createAutopilotRpc,
createChainRpc,
createInvoicesRpc,
createRouterRpc,
createSignRpc,
createWalletRpc,
createWatchtowerRpc,
createWtClientRpc,
InvoicesRpc,
LnRpc,
RouterRpc,
RpcClientConfig,
SignRpc,
WalletRpc,
WatchtowerRpc,
WtClientRpc,
} from '@lily-technologies/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 {
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);
}
}
`

$3

Connecting to an lnd instance at localhost:10001.

`typescript
import createLnRpc from '@lily-technologies/lnrpc';

(async () => {
const lnRpcClient = await createLnRpc(config);

// All requests are promisified and typed
const { confirmedBalance } = await lnRpcClient.walletBalance();

// ...and you're off!
console.log(confirmedBalance);

// subscribe to LND server events
const subscriber = await lnRpcClient.subscribeInvoices();
subscriber.on('data', invoice => {
console.log(invoice); // do something with invoice event
});
})();
`

$3

`typescript
import createLnRpc from '@lily-technologies/lnrpc';

(async () => {
const lnRpcClient = await createLnRpc({
/*
* 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:
*/
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
*/
cert: process.env.MY_SSL_CERT,

/*
* 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
*/
macaroon: process.env.MY_MACAROON_HEX,
});

try {
const getInfoResponse = await lnRpcClient.getInfo();
console.log(getInfoResponse);
} catch (error) {
console.error(error);
}
})();
`

$3

All main server (lnrpc) methods documentation can be found here.

$3

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.

$3

#### Clone Repository & Install Dependencies
`sh
git clone git@github.com:Lily-Technologies/lnrpc.git && cd $_

npm install


OR


yarn
`

#### 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 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.
Any added streaming methods must be included in the subscriptionMethods array that's into the createServiceClient` function.
This prevents streaming methods from being promisified.

$3

This project is licensed under the MIT License.