{"id":31379352,"url":"https://github.com/imaginator/lightning-kld","last_synced_at":"2025-09-28T07:48:24.419Z","repository":{"id":210482383,"uuid":"724632213","full_name":"imaginator/lightning-kld","owner":"imaginator","description":"hacking on the kld lightning server","archived":false,"fork":false,"pushed_at":"2024-05-13T02:43:09.000Z","size":3458,"stargazers_count":0,"open_issues_count":16,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-26T15:49:05.562Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/imaginator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-28T13:32:36.000Z","updated_at":"2025-09-01T06:50:53.000Z","dependencies_parsed_at":"2024-05-02T04:00:43.687Z","dependency_job_id":null,"html_url":"https://github.com/imaginator/lightning-kld","commit_stats":null,"previous_names":["imaginator/lightning-kld"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/imaginator/lightning-kld","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imaginator%2Flightning-kld","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imaginator%2Flightning-kld/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imaginator%2Flightning-kld/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imaginator%2Flightning-kld/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/imaginator","download_url":"https://codeload.github.com/imaginator/lightning-kld/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/imaginator%2Flightning-kld/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277340300,"owners_count":25801863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-28T02:00:08.834Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-28T07:48:23.104Z","updated_at":"2025-09-28T07:48:24.411Z","avatar_url":"https://github.com/imaginator.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lighting Service Provider (LSP) node cluster\n\n**Nota bene**: kuutamo is bleeding edge decentralized financial infrastructure. Use with caution and only with funds you are prepared to lose.\nIf you want to put it into production and would like to discuss SRE overlay support, please get in touch with us at [opencore-support@kuutamo.co](mailto:opencore-support@kuutamo.co)\n\n## Prerequisites\n\n- 1 or 3 server(s)/node(s): Any Linux OS\n- 1 client/local machine: Any Linux OS, MacOS\n\n## Key components\n\n### Client side:\n- `kld-mgr`       - A CLI tool that will SSH to your server(s) to perform the initial deployment\n- `kld-cli`       - A CLI tool that uses the kld API to support LSP operations\n\n### Server side:\n- `kld`             - kuutamo lightning daemon - our LSP router node software, built on [LDK](https://github.com/lightningdevkit)\n- `cockroachdb`     - a cloud-native, distributed SQL database\n- `telegraf`        - an agent for collecting and sending metrics to any URL that supports the [Prometheus's Remote Write API](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write)\n- `promtail`        - an agent which ships the contents of local logs to a private Grafana Loki instance or Grafana Cloud\n- `bitcoind`        - a bitcoin client\n- `electrs`         - a bitcoin database indexer\n- `kuutamo-upgrade` - an updater service that will monitor the deployment repository and apply any required upgrades\n\n## Nix quickstart\n\nkld-mgr:\n```bash\nnix run github:kuutamolabs/lightning-knd#kld-mgr -- help\n```\n\nkld-cli:\n```bash\nnix run github:kuutamolabs/lightning-knd#kld-cli -- help\n```\n\n## Installing Nix\n\n1. Install the Nix package manager, if you don't already have it. https://zero-to-nix.com/start/install\n\n2. Trust pre-built binaries (optional):\n```shell\n$ printf 'trusted-substituters = https://cache.garnix.io https://cache.nixos.org/\\ntrusted-public-keys = cache.garnix.io:CTFPyKSLcx5RMJKfLo5EEPUObbA78b0YQ2DTCJXqr9g= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=' | sudo tee -a /etc/nix/nix.conf \u0026\u0026 sudo systemctl restart nix-daemon\n```\n\n3. Test\n```shell\n$ nix run --refresh github:kuutamolabs/lightning-knd#kld-mgr -- help\n```\n\n## Install and in life operations\n\nBy default, nodes are locked down once installed and cannot be connected to over SSH. Nodes are upgraded using a GitOps model enabling complete system change auditability.\n\nThe customized `kuutamo-updater` service checks for updates in your private deployment repository. If found, the cluster will upgrade.\nThe maintainers of the deployment repository control when upgrades are accepted. They will review/audit, approve and merge the updated `flake.lock` PR.\n\nAn example install and upgrade workflow is shown below using GitHub. Other Git platforms such as Bitbucket and GitLab can be used inplace.\n`kld-mgr` requires root SSH access to server(s) to perform the initial install.   \nOther cluster bootstrap methods can be used, such as via USB disk or PXE.\n\n\u003e Note: For Test/Dev deployments you can retain Root and SSH capabilities by setting the `DEBUG` environment variable to `true` when performing `install`.\n\nAlthough monitoring is not mandatory for deploying a node, it is highly recommended.  \nConfigure the `self_monitoring_url`, `self_monitoring_username`, and `self_monitoring_password` fields of the host in the `kld.toml`.  \nTo view Logs remotely set the `promtail_client` in the form `https://\u003cuser_id\u003e:\u003ctoken\u003e@\u003cclient hostname\u003e/loki/api/vi/push`\n\n![install and upgrade GitOps setup](./install-upgrade-gitops.jpg)\n\n- Step 1: Generate example `kld.toml`\n```shell\n$ nix run github:kuutamolabs/lightning-knd#kld-mgr generate-example \u003e kld.toml\n```\n- Step 2: Generate classic token with full repo permission, please refer to the [Github doc](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)\n\n- Step 5.1: Generate deployment config\n```shell\n$ nix run github:kuutamolabs/lightning-knd#kld-mgr generate-config ./deployment\n```\n- Step 5.2: Setup Git \u0026 GitHub deployment repository \n```shell \n$ cd ./deployment\n$ git init\n$ git add .\n$ git commit -m \"init deploy\"\n$ git remote add origin git@github.com:my-org/deployment\n$ git push\n$ cd ..\n```\n\n- Step 6: Add the flake-lock-update Github Action\n ```shell\n$ mkdir -p ./deployment/.github/workflows\n$ curl https://raw.githubusercontent.com/DeterminateSystems/update-flake-lock/main/.github/workflows/update.yml --output ./deployment/.github/workflows/upgrade.yml\n```\nPlease refer to [update-flake-lock](https://github.com/DeterminateSystems/update-flake-lock) to configure this Action to your requirements.\n\n- Step 7: Install\n```shell\n$ nix run github:kuutamolabs/lightning-knd#kld-mgr install\n```\n- Connect to node via API. kld API is served on port `2244`\n```shell\n$ nix run github:kuutamolabs/lightning-knd/mgr#kld-cli -- -t \"x.x.x.x:2244\" -c \"secrets/lightning/ca.pem\" -m \"secrets/admin.macaroon get-info\"\n```\n\n\n## kld-cli\n\n```shell\n$ nix run github:kuutamolabs/lightning-knd#kld-cli -- help\n```\n```\nUsage: kld-cli --target \u003cTARGET\u003e --cert-path \u003cCERT_PATH\u003e --macaroon-path \u003cMACAROON_PATH\u003e \u003cCOMMAND\u003e\n\nCommands:\n  get-info                    Fetch information about this lightning node\n  sign                        Creates a signature of the message using nodes secret key (message limit 65536 chars)\n  get-balance                 Fetch confirmed and unconfirmed on-chain balance\n  new-address                 Generates new on-chain address for receiving funds\n  withdraw                    Send on-chain funds out of the wallet\n  list-funds                  Show available funds from the internal wallet\n  list-peers                  Fetch a list of this nodes peers\n  connect-peer                Connect with a network peer\n  disconnect-peer             Disconnect from a network peer\n  list-channels               Fetch a list of this nodes open channels\n  open-channel                Open a channel with another node\n  set-channel-fee             Set channel fees\n  close-channel               Close a channel\n  network-nodes               Get node information from the network graph\n  network-channels            Get channel information from the network graph\n  fee-rates                   Return feerate estimates, either satoshi-per-kw or satoshi-per-kb\n  keysend                     Pay a node without an invoice\n  generate-invoice            Generate a bolt11 invoice for receiving a payment\n  list-invoices               List all invoices\n  pay-invoice                 Pay an invoice\n  list-payments               List all payments\n  estimate-channel-liquidity  Estimate channel liquidity to a target node\n  local-remote-balance        Fetch the aggregate local and remote channel balances (msat) of the node\n  get-fees                    Get node routing fees\n  list-forwards               Fetch a list of the forwarded htlcs\n  help                        Print this message or the help of the given subcommand(s)\n\nOptions:\n  -t, --target \u003cTARGET\u003e                IP address or hostname of the target machine\n  -c, --cert-path \u003cCERT_PATH\u003e          Path to the TLS cert of the target API\n  -m, --macaroon-path \u003cMACAROON_PATH\u003e  Path to the macaroon for authenticating with the API\n  -h, --help                           Print help\n  -V, --version                        Print version\n\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimaginator%2Flightning-kld","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimaginator%2Flightning-kld","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimaginator%2Flightning-kld/lists"}