C-Otto / lnd-manageJ

MIT License
52 stars 12 forks source link

lnd-manageJ

What is the purpose of lnd-manageJ?

In the far future, you can run lnd-manageJ in the background and constantly gather information from your lnd node. This information is condensed and analyzed so that

In short, lnd-manageJ helps you understand and manage the inner workings of your lnd node.

Privacy and external API usage

This service requests transaction details from public APIs (Bitaps and Blockcypher). As such, information about the channels associated with your node are leaked, possibly revealing your IP address and enabling anti-privacy analyses.

Depending on the size of your node, you might run into limits imposed by these API providers. The downloads will be retried automatically as long as the service runs, but the returned information may be incomplete or delayed until the necessary downloads are completed.

Do not run the service if any of this is an issue to you!

What can you do with lnd-manageJ?

Once the service is running, it offers several REST endpoints that can be accessed with, for example, curl. All endpoints are served at the base URL http://localhost:8081/. As an example, to get a list of all open channels, you can run:

curl -s http://localhost:8081/api/status/open-channels

As the JSON output isn't exactly nice to read, you might want to install jq and run:

curl -s http://localhost:8081/api/status/open-channels | jq

The service itself only provides metrics and error logs as its output.

Endpoints

Status: /api/status/ followed by...

Channel specific: /api/channel/{ID}/ (where {ID} is the channel ID) followed by...

Note: the channel ID can be supplied in any of the following formats:

Node specific: /api/node/{PUBKEY}/ (where {PUBKEY} is the node pubkey) followed by...

Warnings:

/api/warnings: show all warnings for all peers and channels

Payments:

See PickhardtPayments.md.

Legacy:

/legacy/open-channels/pretty: a readable list (not JSON!) of all open channels showing channel ID, pubkey, capacity and alias. As the name implies, this endpoint will be removed sooner rather than later.

Configuration

Some settings, especially for node/channel warnings, can be configured. Please have a look at example-lnd-manageJ.conf for further information. The configuration file is read every few seconds, so that you can change settings without restarting lnd-manageJ.

Caching and Performance

Most information is cached to improve performance, which is why you might see outdated information. Some information like node aliases does not need to be up-to-date and, as such, is cached for several minutes. On the other hand, channel balance information is only cached for less than a second.

This project has not been tested in many environments. Depending on your setup, it might be very slow and/or consume many resources. Please share your insights by raising a GitHub issue!

As most information is cached, performance improves the more you use the endpoints. However, sometimes (for example directly after starting the service) many pieces of information need to be gathered from different sources, which may take several seconds. For example, transaction details for all (including closed) channels need to be downloaded once (see below), which will delay any endpoint requesting information about a/all channel(s).

Is there a graphical user interface (GUI)?

Yes! You can start a demo with ./ui-demo.sh and browse to http://localhost:8081 (press CTRL+C to stop the demo). Once lnd-manageJ is running, you can access the full (non-demo) UI at the same address: http://localhost:8081

How can I run lnd-manageJ?

The service is intended to run 24/7 to collect statistics about your node. You may restart both the service and lnd at any time.

Using H2

Install Java 21 and run ./start-h2.sh.

Using PostgreSQL (recommended)

Install PostgreSQL (Debian: apt install postgresql) and create a database named lndmanagej and a user bitcoin. You can tweak these settings in application/src/main/resources/application.properties. Configure the database so that the user bitcoin can access lndmanagej without a password at jdbc:postgresql://localhost:5432/lndmanagej (pg_hba.conf: host lndmanagej bitcoin 127.0.0.1/32 trust).

Install Java 21 and run ./start.sh.

Disclaimer

This project is not related to bitromortac's Python based lndmanage.

Can I help?

Sure! Please test the software, review the code, create feature requests, report bugs, ...

How can I reach you?

I'm in the lnd slack and on Twitter.