Add initial guides & documentation by benthecarman · Pull Request #186 · lightningdevkit/ldk-server

benthecarman · 2026-04-14T21:47:33Z

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.

ldk-reviews-bot · 2026-04-14T21:47:36Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

Thanks!

tnull · 2026-04-15T08:08:31Z

+## Transport
+
+- **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default)
+- **Default address:** `127.0.0.1:3536`


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?

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.

tnull · 2026-04-15T08:24:49Z

+
+Requires the LSP's public key and address. Some LSPs also require an authentication token.
+
+### `[liquidity.lsps2_service]`


Might be worth mentioning this also requires compilation with the experimental feature enabled.

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.

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.

tnull · 2026-04-15T08:31:56Z

+|----------------------------------------|--------------|----------------------------------------------------------------------------|
+| `<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 |


Ugh, should we even document this to begin with?

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

tnull · 2026-04-15T08:39:13Z

+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


Hmmm, did you test this, does the hidden service setup really work right now?

I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735

tnull · 2026-04-15T08:40:37Z

+```
+
+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**


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.

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

Looking good, thank you!

Anyitechs · 2026-04-15T11:05:49Z

+
+| RPC | Description |
+|---------------------------|------------------------------------------------------|
+| `ExportPathfindingScores` | Export the router's pathfinding score cache |


Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?

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

Feel free to land, can still iterate furhter.

tnull · 2026-04-16T10:59:29Z

+
+The `grpc-message` trailer contains a human-readable error description.
+
+## Endpoint Reference


Given you're comment over on #188, how is this different/less annoying to maintain over time?

Yeah might be better to remove both

tnull · 2026-04-16T11:23:48Z

Actually just landing this, can continue the discussion still.

Add initial guides & documentation

benthecarman · 2026-04-14T21:47:33Z

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.

ldk-reviews-bot · 2026-04-14T21:47:36Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

Thanks!

tnull · 2026-04-15T08:08:31Z

+## Transport
+
+- **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default)
+- **Default address:** `127.0.0.1:3536`


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?

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.

tnull · 2026-04-15T08:24:49Z

+
+Requires the LSP's public key and address. Some LSPs also require an authentication token.
+
+### `[liquidity.lsps2_service]`


Might be worth mentioning this also requires compilation with the experimental feature enabled.

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.

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.

tnull · 2026-04-15T08:31:56Z

+|----------------------------------------|--------------|----------------------------------------------------------------------------|
+| `<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 |


Ugh, should we even document this to begin with?

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

tnull · 2026-04-15T08:39:13Z

+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


Hmmm, did you test this, does the hidden service setup really work right now?

I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735

tnull · 2026-04-15T08:40:37Z

+```
+
+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**


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.

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

Looking good, thank you!

Anyitechs · 2026-04-15T11:05:49Z

+
+| RPC | Description |
+|---------------------------|------------------------------------------------------|
+| `ExportPathfindingScores` | Export the router's pathfinding score cache |


Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?

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

Feel free to land, can still iterate furhter.

tnull · 2026-04-16T10:59:29Z

+
+The `grpc-message` trailer contains a human-readable error description.
+
+## Endpoint Reference


Given you're comment over on #188, how is this different/less annoying to maintain over time?

Yeah might be better to remove both

tnull · 2026-04-16T11:23:48Z

Actually just landing this, can continue the discussion still.

Add initial guides & documentation

benthecarman · 2026-04-14T21:47:33Z

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.

ldk-reviews-bot · 2026-04-14T21:47:36Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

Thanks!

tnull · 2026-04-15T08:08:31Z

+## Transport
+
+- **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default)
+- **Default address:** `127.0.0.1:3536`


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?

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.

tnull · 2026-04-15T08:24:49Z

+
+Requires the LSP's public key and address. Some LSPs also require an authentication token.
+
+### `[liquidity.lsps2_service]`


Might be worth mentioning this also requires compilation with the experimental feature enabled.

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.

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.

tnull · 2026-04-15T08:31:56Z

+|----------------------------------------|--------------|----------------------------------------------------------------------------|
+| `<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 |


Ugh, should we even document this to begin with?

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

tnull · 2026-04-15T08:39:13Z

+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


Hmmm, did you test this, does the hidden service setup really work right now?

I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735

tnull · 2026-04-15T08:40:37Z

+```
+
+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**


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.

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

Looking good, thank you!

Anyitechs · 2026-04-15T11:05:49Z

+
+| RPC | Description |
+|---------------------------|------------------------------------------------------|
+| `ExportPathfindingScores` | Export the router's pathfinding score cache |


Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?

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

Feel free to land, can still iterate furhter.

tnull · 2026-04-16T10:59:29Z

+
+The `grpc-message` trailer contains a human-readable error description.
+
+## Endpoint Reference


Given you're comment over on #188, how is this different/less annoying to maintain over time?

Yeah might be better to remove both

tnull · 2026-04-16T11:23:48Z

Actually just landing this, can continue the discussion still.

Add initial guides & documentation

benthecarman · 2026-04-14T21:47:33Z

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.

ldk-reviews-bot · 2026-04-14T21:47:36Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

Thanks!

tnull · 2026-04-15T08:08:31Z

+## Transport
+
+- **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default)
+- **Default address:** `127.0.0.1:3536`


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?

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.

tnull · 2026-04-15T08:24:49Z

+
+Requires the LSP's public key and address. Some LSPs also require an authentication token.
+
+### `[liquidity.lsps2_service]`


Might be worth mentioning this also requires compilation with the experimental feature enabled.

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.

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.

tnull · 2026-04-15T08:31:56Z

+|----------------------------------------|--------------|----------------------------------------------------------------------------|
+| `<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 |


Ugh, should we even document this to begin with?

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

tnull · 2026-04-15T08:39:13Z

+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


Hmmm, did you test this, does the hidden service setup really work right now?

I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735

tnull · 2026-04-15T08:40:37Z

+```
+
+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**


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.

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

Looking good, thank you!

Anyitechs · 2026-04-15T11:05:49Z

+
+| RPC | Description |
+|---------------------------|------------------------------------------------------|
+| `ExportPathfindingScores` | Export the router's pathfinding score cache |


Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?

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

Feel free to land, can still iterate furhter.

tnull · 2026-04-16T10:59:29Z

+
+The `grpc-message` trailer contains a human-readable error description.
+
+## Endpoint Reference


Given you're comment over on #188, how is this different/less annoying to maintain over time?

Yeah might be better to remove both

tnull · 2026-04-16T11:23:48Z

Actually just landing this, can continue the discussion still.

Add initial guides & documentation

benthecarman · 2026-04-14T21:47:33Z

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.

ldk-reviews-bot · 2026-04-14T21:47:36Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

Thanks!

tnull · 2026-04-15T08:08:31Z

+## Transport
+
+- **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default)
+- **Default address:** `127.0.0.1:3536`


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?

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.

tnull · 2026-04-15T08:24:49Z

+
+Requires the LSP's public key and address. Some LSPs also require an authentication token.
+
+### `[liquidity.lsps2_service]`


Might be worth mentioning this also requires compilation with the experimental feature enabled.

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.

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.

tnull · 2026-04-15T08:31:56Z

+|----------------------------------------|--------------|----------------------------------------------------------------------------|
+| `<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 |


Ugh, should we even document this to begin with?

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

tnull · 2026-04-15T08:39:13Z

+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


Hmmm, did you test this, does the hidden service setup really work right now?

I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735

tnull · 2026-04-15T08:40:37Z

+```
+
+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**


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.

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

Looking good, thank you!

Anyitechs · 2026-04-15T11:05:49Z

+
+| RPC | Description |
+|---------------------------|------------------------------------------------------|
+| `ExportPathfindingScores` | Export the router's pathfinding score cache |


Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?

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

Feel free to land, can still iterate furhter.

tnull · 2026-04-16T10:59:29Z

+
+The `grpc-message` trailer contains a human-readable error description.
+
+## Endpoint Reference


Given you're comment over on #188, how is this different/less annoying to maintain over time?

Yeah might be better to remove both

tnull · 2026-04-16T11:23:48Z

Actually just landing this, can continue the discussion still.

Add initial guides & documentation

benthecarman · 2026-04-14T21:47:33Z

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.

ldk-reviews-bot · 2026-04-14T21:47:36Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

Thanks!

tnull · 2026-04-15T08:08:31Z

+## Transport
+
+- **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default)
+- **Default address:** `127.0.0.1:3536`


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?

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.

tnull · 2026-04-15T08:24:49Z

+
+Requires the LSP's public key and address. Some LSPs also require an authentication token.
+
+### `[liquidity.lsps2_service]`


Might be worth mentioning this also requires compilation with the experimental feature enabled.

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.

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.

tnull · 2026-04-15T08:31:56Z

+|----------------------------------------|--------------|----------------------------------------------------------------------------|
+| `<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 |


Ugh, should we even document this to begin with?

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

tnull · 2026-04-15T08:39:13Z

+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


Hmmm, did you test this, does the hidden service setup really work right now?

I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735

tnull · 2026-04-15T08:40:37Z

+```
+
+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**


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.

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

Looking good, thank you!

Anyitechs · 2026-04-15T11:05:49Z

+
+| RPC | Description |
+|---------------------------|------------------------------------------------------|
+| `ExportPathfindingScores` | Export the router's pathfinding score cache |


Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?

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

Feel free to land, can still iterate furhter.

tnull · 2026-04-16T10:59:29Z

+
+The `grpc-message` trailer contains a human-readable error description.
+
+## Endpoint Reference


Given you're comment over on #188, how is this different/less annoying to maintain over time?

Yeah might be better to remove both

tnull · 2026-04-16T11:23:48Z

Actually just landing this, can continue the discussion still.

Add initial guides & documentation

benthecarman · 2026-04-14T21:47:33Z

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.

ldk-reviews-bot · 2026-04-14T21:47:36Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

Thanks!

tnull · 2026-04-15T08:08:31Z

+## Transport
+
+- **Protocol:** gRPC over HTTP/2 with TLS (self-signed by default)
+- **Default address:** `127.0.0.1:3536`


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?

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.

tnull · 2026-04-15T08:24:49Z

+
+Requires the LSP's public key and address. Some LSPs also require an authentication token.
+
+### `[liquidity.lsps2_service]`


Might be worth mentioning this also requires compilation with the experimental feature enabled.

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.

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.

tnull · 2026-04-15T08:31:56Z

+|----------------------------------------|--------------|----------------------------------------------------------------------------|
+| `<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 |


Ugh, should we even document this to begin with?

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

tnull · 2026-04-15T08:39:13Z

+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


Hmmm, did you test this, does the hidden service setup really work right now?

I tested mine, can connect to me if you want :) 0329febe813633207345f016d06d1e2b07f7b977ae7b34cda67d026769d7beb0b2@abz6grablzwec2afhng5vxtrbeioc2bczlbeeqnf57anl2lcjean3aad.onion:9735

tnull · 2026-04-15T08:40:37Z

+```
+
+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**


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.

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

Looking good, thank you!

Anyitechs · 2026-04-15T11:05:49Z

+
+| RPC | Description |
+|---------------------------|------------------------------------------------------|
+| `ExportPathfindingScores` | Export the router's pathfinding score cache |


Do we also want to add that we support "importing" scorer files via set_pathfinding_scores_source?

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

Feel free to land, can still iterate furhter.

tnull · 2026-04-16T10:59:29Z

+
+The `grpc-message` trailer contains a human-readable error description.
+
+## Endpoint Reference


Given you're comment over on #188, how is this different/less annoying to maintain over time?

Yeah might be better to remove both

tnull · 2026-04-16T11:23:48Z

Actually just landing this, can continue the discussion still.

Add initial guides & documentation

benthecarman requested a review from tnull April 14, 2026 21:47

benthecarman force-pushed the docs branch 4 times, most recently from ba54d2f to fbba9baCompare April 14, 2026 21:54

tnull reviewed Apr 15, 2026
View reviewed changes

Anyitechs reviewed Apr 15, 2026
View reviewed changes

benthecarman force-pushed the docs branch from fbba9ba to 18ea879Compare April 15, 2026 17:09

benthecarman force-pushed the docs branch from 18ea879 to dc555d0Compare April 15, 2026 17:09

benthecarman requested a review from tnull April 15, 2026 20:55

benthecarman mentioned this pull request Apr 15, 2026
Beta Release #121
Open
25 tasks

tnull approved these changes Apr 16, 2026
View reviewed changes

tnull merged commit 04c2bf6 into lightningdevkit:mainApr 16, 2026
10 checks passed

benthecarman added this to Weekly Goals Apr 16, 2026

github-project-automationBot moved this to Done in Weekly Goals Apr 16, 2026

benthecarman self-assigned this Apr 16, 2026

benthecarman deleted the docs branch April 16, 2026 17:54

rsafier pushed a commit to rsafier/ldk-server that referenced this pull request Apr 20, 2026
Merge pull requestlightningdevkit#186from benthecarman/docs
fbbfaf6
Add initial guides & documentation

benthecarman mentioned this pull request May 5, 2026
Fix example config doc link in README #199
Merged

benthecarman requested a review from tnull April 14, 2026 21:47

benthecarman force-pushed the docs branch 4 times, most recently from ba54d2f to fbba9baCompare April 14, 2026 21:54

tnull reviewed Apr 15, 2026
View reviewed changes

Anyitechs reviewed Apr 15, 2026
View reviewed changes

benthecarman force-pushed the docs branch from fbba9ba to 18ea879Compare April 15, 2026 17:09

benthecarman force-pushed the docs branch from 18ea879 to dc555d0Compare April 15, 2026 17:09

benthecarman requested a review from tnull April 15, 2026 20:55

benthecarman mentioned this pull request Apr 15, 2026
Beta Release #121
Open
25 tasks

tnull approved these changes Apr 16, 2026
View reviewed changes

tnull merged commit 04c2bf6 into lightningdevkit:mainApr 16, 2026
10 checks passed

benthecarman added this to Weekly Goals Apr 16, 2026

github-project-automationBot moved this to Done in Weekly Goals Apr 16, 2026

benthecarman self-assigned this Apr 16, 2026

benthecarman deleted the docs branch April 16, 2026 17:54

rsafier pushed a commit to rsafier/ldk-server that referenced this pull request Apr 20, 2026
Merge pull requestlightningdevkit#186from benthecarman/docs
fbbfaf6
Add initial guides & documentation

benthecarman mentioned this pull request May 5, 2026
Fix example config doc link in README #199
Merged

benthecarman requested a review from tnull April 14, 2026 21:47

benthecarman force-pushed the docs branch 4 times, most recently from ba54d2f to fbba9baCompare April 14, 2026 21:54

tnull reviewed Apr 15, 2026
View reviewed changes

Anyitechs reviewed Apr 15, 2026
View reviewed changes

benthecarman force-pushed the docs branch from fbba9ba to 18ea879Compare April 15, 2026 17:09

benthecarman force-pushed the docs branch from 18ea879 to dc555d0Compare April 15, 2026 17:09

benthecarman requested a review from tnull April 15, 2026 20:55

benthecarman mentioned this pull request Apr 15, 2026
Beta Release #121
Open
25 tasks

tnull approved these changes Apr 16, 2026
View reviewed changes

tnull merged commit 04c2bf6 into lightningdevkit:mainApr 16, 2026
10 checks passed

benthecarman added this to Weekly Goals Apr 16, 2026

github-project-automationBot moved this to Done in Weekly Goals Apr 16, 2026

benthecarman self-assigned this Apr 16, 2026

benthecarman deleted the docs branch April 16, 2026 17:54

rsafier pushed a commit to rsafier/ldk-server that referenced this pull request Apr 20, 2026
Merge pull requestlightningdevkit#186from benthecarman/docs
fbbfaf6
Add initial guides & documentation

benthecarman mentioned this pull request May 5, 2026
Fix example config doc link in README #199
Merged

benthecarman requested a review from tnull April 14, 2026 21:47

benthecarman force-pushed the docs branch 4 times, most recently from ba54d2f to fbba9baCompare April 14, 2026 21:54

tnull reviewed Apr 15, 2026
View reviewed changes

Anyitechs reviewed Apr 15, 2026
View reviewed changes

benthecarman force-pushed the docs branch from fbba9ba to 18ea879Compare April 15, 2026 17:09

benthecarman force-pushed the docs branch from 18ea879 to dc555d0Compare April 15, 2026 17:09

benthecarman requested a review from tnull April 15, 2026 20:55

benthecarman mentioned this pull request Apr 15, 2026
Beta Release #121
Open
25 tasks

tnull approved these changes Apr 16, 2026
View reviewed changes

tnull merged commit 04c2bf6 into lightningdevkit:mainApr 16, 2026
10 checks passed

benthecarman added this to Weekly Goals Apr 16, 2026

github-project-automationBot moved this to Done in Weekly Goals Apr 16, 2026

benthecarman self-assigned this Apr 16, 2026

benthecarman deleted the docs branch April 16, 2026 17:54

rsafier pushed a commit to rsafier/ldk-server that referenced this pull request Apr 20, 2026
Merge pull requestlightningdevkit#186from benthecarman/docs
fbbfaf6
Add initial guides & documentation

benthecarman mentioned this pull request May 5, 2026
Fix example config doc link in README #199
Merged

benthecarman requested a review from tnull April 14, 2026 21:47

benthecarman force-pushed the docs branch 4 times, most recently from ba54d2f to fbba9baCompare April 14, 2026 21:54

tnull reviewed Apr 15, 2026
View reviewed changes

Anyitechs reviewed Apr 15, 2026
View reviewed changes

benthecarman force-pushed the docs branch from fbba9ba to 18ea879Compare April 15, 2026 17:09

benthecarman force-pushed the docs branch from 18ea879 to dc555d0Compare April 15, 2026 17:09

benthecarman requested a review from tnull April 15, 2026 20:55

benthecarman mentioned this pull request Apr 15, 2026
Beta Release #121
Open
25 tasks

tnull approved these changes Apr 16, 2026
View reviewed changes

tnull merged commit 04c2bf6 into lightningdevkit:mainApr 16, 2026
10 checks passed

benthecarman added this to Weekly Goals Apr 16, 2026

github-project-automationBot moved this to Done in Weekly Goals Apr 16, 2026

benthecarman self-assigned this Apr 16, 2026

benthecarman deleted the docs branch April 16, 2026 17:54

rsafier pushed a commit to rsafier/ldk-server that referenced this pull request Apr 20, 2026
Merge pull requestlightningdevkit#186from benthecarman/docs
fbbfaf6
Add initial guides & documentation

benthecarman mentioned this pull request May 5, 2026
Fix example config doc link in README #199
Merged

benthecarman requested a review from tnull April 14, 2026 21:47

benthecarman force-pushed the docs branch 4 times, most recently from ba54d2f to fbba9baCompare April 14, 2026 21:54

tnull reviewed Apr 15, 2026
View reviewed changes

Anyitechs reviewed Apr 15, 2026
View reviewed changes

benthecarman force-pushed the docs branch from fbba9ba to 18ea879Compare April 15, 2026 17:09

benthecarman force-pushed the docs branch from 18ea879 to dc555d0Compare April 15, 2026 17:09

benthecarman requested a review from tnull April 15, 2026 20:55

benthecarman mentioned this pull request Apr 15, 2026
Beta Release #121
Open
25 tasks

tnull approved these changes Apr 16, 2026
View reviewed changes

tnull merged commit 04c2bf6 into lightningdevkit:mainApr 16, 2026
10 checks passed

benthecarman added this to Weekly Goals Apr 16, 2026

github-project-automationBot moved this to Done in Weekly Goals Apr 16, 2026

benthecarman self-assigned this Apr 16, 2026

benthecarman deleted the docs branch April 16, 2026 17:54

rsafier pushed a commit to rsafier/ldk-server that referenced this pull request Apr 20, 2026
Merge pull requestlightningdevkit#186from benthecarman/docs
fbbfaf6
Add initial guides & documentation

benthecarman mentioned this pull request May 5, 2026
Fix example config doc link in README #199
Merged

benthecarman requested a review from tnull April 14, 2026 21:47

benthecarman force-pushed the docs branch 4 times, most recently from ba54d2f to fbba9baCompare April 14, 2026 21:54

tnull reviewed Apr 15, 2026
View reviewed changes

Anyitechs reviewed Apr 15, 2026
View reviewed changes

benthecarman force-pushed the docs branch from fbba9ba to 18ea879Compare April 15, 2026 17:09

benthecarman force-pushed the docs branch from 18ea879 to dc555d0Compare April 15, 2026 17:09

benthecarman requested a review from tnull April 15, 2026 20:55

benthecarman mentioned this pull request Apr 15, 2026
Beta Release #121
Open
25 tasks

tnull approved these changes Apr 16, 2026
View reviewed changes

tnull merged commit 04c2bf6 into lightningdevkit:mainApr 16, 2026
10 checks passed

benthecarman added this to Weekly Goals Apr 16, 2026

github-project-automationBot moved this to Done in Weekly Goals Apr 16, 2026

benthecarman self-assigned this Apr 16, 2026

benthecarman deleted the docs branch April 16, 2026 17:54

rsafier pushed a commit to rsafier/ldk-server that referenced this pull request Apr 20, 2026
Merge pull requestlightningdevkit#186from benthecarman/docs
fbbfaf6
Add initial guides & documentation

benthecarman mentioned this pull request May 5, 2026
Fix example config doc link in README #199
Merged


		Requires the LSP's public key and address. Some LSPs also require an authentication token.

		### `[liquidity.lsps2_service]`


		The `grpc-message` trailer contains a human-readable error description.

		## Endpoint Reference

Uh oh!

Conversation

benthecarman commented Apr 14, 2026

Uh oh!

ldk-reviews-bot commented Apr 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benthecarmanApr 15, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Anyitechs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tnull commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

benthecarman commented Apr 14, 2026

Uh oh!

ldk-reviews-bot commented Apr 14, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benthecarmanApr 15, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

ldk-reviews-bot commented Apr 14, 2026•
edited
Loading

benthecarmanApr 15, 2026•
edited
Loading

ldk-reviews-bot commented Apr 14, 2026•
edited
Loading

benthecarmanApr 15, 2026•
edited
Loading