btc-lsp: Lightning service provider

[ bitcoin, bsd3, finance, library, lightning, network, payments, program ] [ Propose Tags ]


[Index] [Quick Jump]


Manual Flags


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Versions [RSS]
Change log
Dependencies aeson (>=1.4 && <1.6), async, base (>=4.7 && <5), base16-bytestring, base64-bytestring (>=1.2.1), binary, btc-lsp, bytestring, case-insensitive, casing, chronos, classy-prelude-yesod (>=1.5 && <1.6), containers, cryptonite, envparse, errors, esqueleto (>=3.5.3), extra, fast-logger (>=2.2 && <3.1), file-embed, format-numbers, generic-pretty-instances, GenericPretty, hjsmin (>=0.1 && <0.3), hspec, http-client-tls (>=0.3 && <0.4), http2, http2-client, http2-client-grpc, http2-grpc-proto-lens, http2-grpc-types, iso8601-time, katip, lnd-client, memory, microlens, monad-logger (>=0.3 && <0.4), network-bitcoin, persistent (>=, persistent-migration, persistent-postgresql (>=, pretty, proto-lens, proto-lens-runtime, qrcode-core, qrcode-juicypixels, QuickCheck, resource-pool, scientific, secp256k1-haskell, SHA, shakespeare (>=2.0 && <2.1), stm, template-haskell, text, time, transformers, unbounded-delays, universum, unliftio, uuid, vector, wai, wai-extra (>=3.1 && <3.2), warp (>=3.0 && <3.4), warp-grpc, warp-tls, witch, yaml (>=0.11 && <0.12), yesod (>=1.6 && <1.7), yesod-auth (>=1.6 && <1.7), yesod-core (>=1.6 && <1.7), yesod-form (>=1.6 && <1.7), yesod-static (>=1.6 && <1.7) [details]
License BSD-3-Clause
Copyright 2022 Yolo <>
Author 21it <>, Mikhail Prushinskiy <>, Artem Markov <>
Maintainer 21it <>, Mikhail Prushinskiy <>, Artem Markov <>
Category Lightning, Bitcoin, Finance, Network, Payments
Home page
Bug tracker
Source repo head: git clone
Uploaded by coingaming at 2022-07-22T12:58:30Z
Executables btc-lsp-prof, btc-lsp-integration, btc-lsp-exe
Downloads 83 total (6 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs uploaded by user
Build status unknown [no reports yet]

Readme for btc-lsp-

[back to package description]


Bitcoin Lightning Service Provider. Development environment is packed into nix-shell.


Every btc-lsp gRPC request/response does have ctx (context) field in payload which contains credentials:

  • First is nonce. The nonce is used for security reasons and is used to guard against replay attacks. The server will reject any request that comes with an incorrect nonce. The only requirement for the nonce is that it needs to be strictly increasing. Nonce generation is often achieved by using the current UNIX timestamp.
  • Second is ln_pub_key. This is lightning node network identity public key in DER format. This key is used to verify request/response signature from headers/trailers.

Also, every request/response does have a signature which is:

  • Signed with LN identity key (key locator family is 6 and index is 0).
  • Signed over binary request payload in exact gRPC/http2 wire format (1 byte of compression flag + 4 bytes of payload length in big endian format + payload bytes).
  • Single hashed (double_hash parameter is False).
  • Not compact (compact_sig parameter is False).
  • Using DER binary format.
  • Base64-encoded according official http2 spec.
  • Located in sig-bin gRPC header/trailer.


Spawn shell:

# If you have Nix installed (a bit faster)

# If you have Docker installed (works on Mac)

Work with Haskell sources in shell:

vi .

Run tests with hot code reloading:


Run app with hot code reloading:



Releases are automated by CI. To create new release, bump the version inside VERSION file. Then push all changes into github and merge into master branch. Then run:


The script will push new tag which will trigger new github release and package.


Some tools are required to be installed directly on host machine. They can be installed using nix-env:


If nix is not available, install tools in any other way you like:


Regtest setup

  1. Setup minikube cluster and deploy k8s resources:
  1. Forward services to host network:

Service/config upgrade

  1. Set k8s context to upgrade
kubectl config use-context <ctx-name>
  1. Upgrade services/configs
./nix/ <net> <mode> <services>


./nix/ --regtest --prebuilt lsp bitcoind

Deploy testnet (DigitalOcean)

  1. Install doctl

If you have used nix-env doctl will already be installed, otherwise install it manually.

  1. Configure doctl

Follow the guide below to configure doctl.

  1. Setup Managed Kubernetes, Managed Postgres, DNS records, TLS certificates and deploy k8s resources:

Destroy testnet (DigitalOcean)


Deploy testnet (AWS)

  1. Install aws cli, eksctl and helm:

If you have used nix-env everything will be already installed, otherwise install manually.

  1. Create IAM user with AdministratorAccess in AWS Console

  2. Configure aws cli access_key_id, secret_access_key, region

aws configure
  1. Setup EKS, RDS, Route53, Request certs from ACM and deploy k8s resources:

Destroy testnet (AWS)



  1. Get list of running pods:
kubectl get po
  1. Get info about pod:
kubectl describe pod <pod-name>
  1. Get detailed info about current cluster state (regtest only):
minikube dashboard --profile=btc-lsp
  1. Lnd after restart is locked. Usually Lsp unlocks it automatically, but if for some reason it's locked (for example Lsp is not running) then you can unlock it with:
  1. Delete all failed Pods:
kubectl delete pod --all-namespaces --field-selector 'status.phase=Failed'
  1. Connect to existing cluster on DigitalOcean:

Get cluster ID

doctl k cluster get lsp-testnet

Add context to kube config

doctl kubernetes cluster kubeconfig save <cluster-id>
  1. Connect to existing eks cluster on AWS:
aws eks update-kubeconfig --name lsp-testnet
  1. Manage k8s contexts:

Display list of contexts

kubectl config get-contexts

Display the current context

kubectl config current-context

Set current context to btc-lsp

kubectl config use-context btc-lsp
  1. List k8s nodes:
kubectl get nodes -o wide
  1. Get current storage class:
kubectl get storageclass


Secure lnd seed generation procedure for the mainnet:

  1. Go to a private place without cameras and witnesses.

  2. Create USB stick with minimal nixos image (cli only).

  3. Boot from USB stick to nixos installer and connect to the internet.

  4. Load nix-shell using the command:

nix-shell --pure -p '(import (fetchTarball { url = ""; sha256 = "1ml6jrz605jx7pmzd38d1490n8cbjv8yaclpqy57j7lqp1raaa7w"; } + "/nix/project.nix")).nixBitcoin.lndinit'

  2. Generate the seed using the command:

lndinit gen-seed
  1. Copy the seed to non-digital durable media, for example steel plate.

  2. Turn off the computer and erase the USB stick.

  3. Keep the seed media safe.