Add initial guides & documentation

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>

Author: benthecarman

CONTRIBUTING.md

@@ -13,7 +13,7 @@ cargo build --release          # Production build (LTO enabled)
 ## Running
 
 ```bash
-cargo run --bin ldk-server ./ldk-server/ldk-server-config.toml
+cargo run --bin ldk-server ./contrib/ldk-server-config.toml
 ```
 
 ## Testing
@@ -54,7 +54,7 @@ cargo fmt --all
 
 ## Configuration
 
-- Config template with all options: `ldk-server/ldk-server-config.toml`
+- Config template with all options: `contrib/ldk-server-config.toml`
 - When updating config options, also update the tests in `ldk-server/src/util/config.rs`
 
 ## Before Submitting

README.md

@@ -15,7 +15,7 @@ a Lightning node while exposing a robust, language-agnostic API via [Protocol Bu
     - Deploy a Lightning Network node with minimal configuration, no coding required.
 
 - **API-First Design**:
-    - Exposes a well-defined API using Protobuf, allowing seamless integration with HTTP-clients or applications.
+    - Exposes a well-defined gRPC API using Protobuf, allowing seamless integration with any language.
 
 - **Powered by LDK**:
     - Built on top of LDK-Node, leveraging the modular, reliable, and high-performance architecture of LDK.
@@ -26,67 +26,38 @@ a Lightning node while exposing a robust, language-agnostic API via [Protocol Bu
 
 ### Project Status
 
-🚧 **Work in Progress**:
-- **APIs Under Development**: Expect breaking changes as the project evolves.
-- **Potential Bugs and Inconsistencies**: While progress is being made toward stability, unexpected behavior may occur.
-- **Improved Logging and Error Handling Coming Soon**: Current error handling is rudimentary (specially for CLI), and usability improvements are actively being worked on.
-- **Pending Testing**: Not tested, hence don't use it for production!
+**Work in Progress**:
+- APIs are under development. Expect breaking changes as the project evolves.
+- Not tested for production use.
+- We welcome your feedback and contributions to help shape the future of LDK Server!
 
-We welcome your feedback and contributions to help shape the future of LDK Server!
+### Quick Start
 
-
-### Configuration
-Refer `./ldk-server/ldk-server-config.toml` to see available configuration options.
-
-You can configure the node via a TOML file, environment variables, or CLI arguments. All options are optional — values provided via CLI override environment variables, which override the values in the TOML file.
-
-### Building
-```
+```bash
 git clone https://github.com/lightningdevkit/ldk-server.git
-cargo build
-```
-
-### Running
-- Using a config file:
-```
-cargo run --bin ldk-server ./ldk-server/ldk-server-config.toml
+cd ldk-server
+cargo build --release
+cp contrib/ldk-server-config.toml my-config.toml  # edit with your settings
+./target/release/ldk-server my-config.toml
 ```
 
-- Using environment variables (all optional):
-```
-export LDK_SERVER_NODE_NETWORK=regtest
-export LDK_SERVER_NODE_LISTENING_ADDRESS=localhost:3001
-export LDK_SERVER_NODE_REST_SERVICE_ADDRESS=127.0.0.1:3002
-export LDK_SERVER_NODE_ALIAS=LDK-Server
-export LDK_SERVER_BITCOIND_RPC_ADDRESS=127.0.0.1:18443
-export LDK_SERVER_BITCOIND_RPC_USER=your-rpc-user
-export LDK_SERVER_BITCOIND_RPC_PASSWORD=your-rpc-password
-export LDK_SERVER_STORAGE_DIR_PATH=/path/to/storage
-cargo run --bin ldk-server
-```
-
-Interact with the node using CLI:
-```
-ldk-server-cli -b localhost:3002 --api-key your-secret-api-key --tls-cert /path/to/tls_cert.pem onchain-receive # To generate onchain-receive address.
-ldk-server-cli -b localhost:3002 --api-key your-secret-api-key --tls-cert /path/to/tls_cert.pem help # To print help/available commands.
-```
-
-### Shell Completions
+See [Getting Started](docs/getting-started.md) for a full walkthrough.
 
-The CLI supports generating shell completions for Bash, Zsh, Fish, Elvish, and PowerShell.
+### Documentation
 
-Add completions to your shell config:
-```bash
-# Bash (add to ~/.bashrc)
-eval "$(ldk-server-cli completions bash)"
+| Document | Description |
+|----------|-------------|
+| [Getting Started](docs/getting-started.md) | Install, configure, and run your first node |
+| [Configuration](docs/configuration.md) | All config options, environment variables, and Bitcoin backend tradeoffs |
+| [API Guide](docs/api-guide.md) | gRPC transport, authentication, and endpoint reference |
+| [Tor](docs/tor.md) | Connecting to and receiving connections over Tor |
+| [Operations](docs/operations.md) | Production deployment, backups, and monitoring |
 
-# Zsh (add to ~/.zshrc)
-eval "$(ldk-server-cli completions zsh)"
+### API
 
-# Fish (add to ~/.config/fish/config.fish)
-ldk-server-cli completions fish | source
-```
+The canonical API definitions are in [`ldk-server-grpc/src/proto/`](ldk-server-grpc/src/proto/). A ready-made
+Rust client library is provided in [`ldk-server-client/`](ldk-server-client/).
 
-## Contributing
+### Contributing
 
 Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on building, testing, code style, and development workflow.

ldk-server/ldk-server-config.toml contrib/ldk-server-config.tomlldk-server/ldk-server-config.toml renamed to contrib/ldk-server-config.toml

@@ -1,9 +1,9 @@
 # Lightning node settings
 [node]
 network = "regtest"                           # Bitcoin network to use
-listening_addresses = ["localhost:3001"]      # Lightning node listening addresses
-announcement_addresses = ["54.3.7.81:3001"]   # Lightning node announcement addresses
-#grpc_service_address = "127.0.0.1:3536"       # LDK Server gRPC address (optional, defaults to 127.0.0.1:3536)
+listening_addresses = ["localhost:9735"]      # Lightning node listening addresses
+#announcement_addresses = ["54.3.7.81:9735"]  # Lightning node announcement addresses
+#grpc_service_address = "127.0.0.1:3536"      # LDK Server gRPC address (optional, defaults to 127.0.0.1:3536)
 alias = "ldk_server"                          # Lightning node alias
 #pathfinding_scores_source_url = ""           # External Pathfinding Scores Source
 #rgs_server_url = "https://rapidsync.lightningdevkit.org/snapshot/v2/"  # Optional: RGS URL for rapid gossip sync
@@ -14,12 +14,12 @@ dir_path = "/tmp/ldk-server/"                 # Path for LDK and BDK data persis
 
 [log]
 level = "Debug"                               # Log level (Error, Warn, Info, Debug, Trace)
-file = "/tmp/ldk-server/ldk-server.log"       # Log file path
+#file = "/tmp/ldk-server/ldk-server.log"      # Log file path
 
 [tls]
 #cert_path = "/path/to/tls.crt"               # Path to TLS certificate, by default uses dir_path/tls.crt
 #key_path = "/path/to/tls.key"                # Path to TLS private key, by default uses dir_path/tls.key
-hosts = ["example.com"]                       # Allowed hosts for TLS, will always include "localhost" and "127.0.0.1"
+#hosts = ["example.com"]                      # Allowed hosts for TLS, will always include "localhost" and "127.0.0.1"
 
 # Must set one of bitcoind, electrum, or esplora
 
@@ -100,4 +100,4 @@ poll_metrics_interval = 60       # The polling interval for metrics in seconds.
 # Tor Config
 [tor]
 # Only connections to OnionV3 peers will be made via this proxy; other connections (IPv4 peers, Electrum server) will not be routed over Tor.
-#proxy_address = ""      # Tor daemon SOCKS proxy address.
+#proxy_address = "127.0.0.1:9050"      # Tor daemon SOCKS proxy address.

contrib/ldk-server.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=LDK Server Lightning Node
+After=network-online.target bitcoind.service
+Wants=network-online.target
+
+[Service]
+Type=notify
+ExecStart=/usr/local/bin/ldk-server /etc/ldk-server/config.toml
+Restart=always
+RestartSec=10
+
+# Security hardening
+User=ldk-server
+ProtectSystem=strict
+NoNewPrivileges=true
+PrivateTmp=true
+PrivateDevices=true
+MemoryDenyWriteExecute=true
+ReadWritePaths=/var/lib/ldk-server
+
+[Install]
+WantedBy=multi-user.target