Add initial guides & documentation#186
Conversation
|
👋 Thanks for assigning @tnull as a reviewer! |
benthecarman
force-pushed
the
docs
branch
4 times, most recently
from
ba54d2f to
fbba9ba
Compare
| ## Transport | ||
|
|
||
| - **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default) | ||
| - **Default address:** `127.0.0.1:3536` |
There was a problem hiding this comment.
In general, but especially if we want to document concrete values, do we have a plan for how to keep the API docs here in-sync and up-to-date with the actual implementation? Could we somehow check that in CI? Or would it make sense to have this live in or generated by rustdoc, so that we can link to the actual values in the code?
There was a problem hiding this comment.
We could put these as docs in the rust files so we could use the consts but feels out of place. Otherwise, not really sure how we'd enforce because its pretty unstructured and hard to detect, maybe having claude verify?
I agree this can be a problem but most of these things should be pretty unchanging (don't see why we'd change the default port). Maybe just remove the Endpoint Reference section as that will have the most changes and just keep sections like Hodl Invoice Lifecycle and Pagination that just explain higher level flows rather than individual endpoints.
|
|
||
| Requires the LSP's public key and address. Some LSPs also require an authentication token. | ||
|
|
||
| ### `[liquidity.lsps2_service]` |
There was a problem hiding this comment.
Might be worth mentioning this also requires compilation with the experimental feature enabled.
There was a problem hiding this comment.
I was planning/hoping to remove that flag so we can ship a single binary, dockerfile, etc but yeah will add that for now since we haven't done it yet.
There was a problem hiding this comment.
Yeah, IMO we should only drop that flag once we refactored the interface to something that is more usable in actual production, not just as a PoC.
| |----------------------------------------|--------------|----------------------------------------------------------------------------| | ||
| | `<storage_dir>/keys_seed` | **Critical** | Node identity and master secret. Required to recover on-chain funds. | | ||
| | `<network_dir>/ldk_node_data.sqlite` | **Critical** | Channel state and on-chain wallet data. Required to recover channel funds. | | ||
| | `<network_dir>/ldk_server_data.sqlite` | Nice-to-have | Payment and forwarding history | |
There was a problem hiding this comment.
Ugh, should we even document this to begin with?
There was a problem hiding this comment.
This should all be in the ldk-node db eventually so we should be able to remove it. In the meantime I'd rather document it so people know what the 2 dbs are. I wouldn't want someone to mess with ldk_node_data thinking they don't need it because they're running ldk-server, not ldk-node
| To make your node reachable as a Tor hidden service, you need to configure Tor itself. LDK | ||
| Server does not manage this automatically. | ||
|
|
||
| ### 1. Configure the Hidden Service |
There was a problem hiding this comment.
Hmmm, did you test this, does the hidden service setup really work right now?
There was a problem hiding this comment.
I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735
| ``` | ||
|
|
||
| This requires a running Tor daemon with a SOCKS port. Only connections to `.onion` peers use | ||
| the proxy. Connections to IPv4/IPv6 peers, Electrum servers, and Esplora endpoints are **not** |
There was a problem hiding this comment.
It seems the Tor bypass of Electrum servers etc. derserves a big Warning sign. I'm honestly even hesitant to advertise Tor support in such a general way until we're sure we're not leaking any connections.
There was a problem hiding this comment.
I'd like to include a doc for it because I know people will ask for it. I agree on the warning sign, will add. However, ideally people aren't using electrum with ldk-server and are using a proper bitcoind node so there wouldn't be leaks anyways.
Anyitechs
left a comment
Anyitechs
left a comment
There was a problem hiding this comment.
Looking good, thank you!
|
|
||
| | RPC | Description | | ||
| |---------------------------|------------------------------------------------------| | ||
| | `ExportPathfindingScores` | Export the router's pathfinding score cache | |
There was a problem hiding this comment.
Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?
There was a problem hiding this comment.
We mention it briefly in the configuration.md. I didn't want to highlight individual config options too much because that can quickly become out of date and we just give descriptions about the overall sections
Add docs/ directory with guides for getting started, configuration, the gRPC API, Tor setup, and production operations. Add per-crate READMEs for ldk-server-client, ldk-server-grpc, and ldk-server-cli. Include READMEs in lib.rs via doc = include_str! so rustdoc validates the code examples. Update the root README to link to the new docs and fix outdated REST/port references. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
tnull
left a comment
tnull
left a comment
There was a problem hiding this comment.
Feel free to land, can still iterate furhter.
|
|
||
| The `grpc-message` trailer contains a human-readable error description. | ||
|
|
||
| ## Endpoint Reference |
There was a problem hiding this comment.
Given you're comment over on #188, how is this different/less annoying to maintain over time?
There was a problem hiding this comment.
Yeah might be better to remove both
|
Actually just landing this, can continue the discussion still. |
4 participants
Add docs/ directory with guides for getting started, configuration, the gRPC API, Tor setup, and production operations. Add per-crate READMEs for ldk-server-client, ldk-server-grpc, and ldk-server-cli.
Include READMEs in lib.rs via doc = include_str! so rustdoc validates the code examples. Update the root README to link to the new docs and fix outdated REST/port references.
Some of the things documented are still subject to change (auth) but if we're able to land this first, we can then just update the docs with the changes as well.