Ctrl+K

Set Up Self-Custody Lightning Infrastructure

Overview

Self-custody Lightning wallets require you to set up and maintain infrastructure to run a Lightning node. There are two main components to this setup:

  1. Lightning Signer Node - This is a Lightning Network Daemon (LND) signer node that runs in a remote signing mode. This ensures separate signing operations from the watch-only node, which enables you to keep your private keys in a more restricted environment, enhancing security.
  2. BitGo Express Server - This manages your wallet and signer LND node.

Architecture

The architecture follows the LND remote signing pattern, where signer nodes hold private keys and perform signing operations and watch-only nodes handle the network operations.

Remote Signer
  • Dockerize LND instance that holds the private key to your wallets.
  • Must be deployed in your infrastructure.
  • Handles all transaction signing for both Lightning and on-chain transactions.
BitGo Express
  • Runs in your infrastructure.
  • Interfaces between your applications and the remote signer.
  • Handles request authentication and signing.
Watch-Only Lightning Node
  • Hosted by a Lightning hosting service provider.
  • Manages channel operations and network connectivity.
  • Doesn't hold private keys.
Exchange

Security Considerations

  1. Keep the signer node in a secure network zone.
  2. Use TLS for all communications.
  3. Implement proper network policies.
  4. Regularly update both LND and Express components.
  5. Follow security best practices for certificate management.

Network Requirements

Express Server

  • Egress
    • Port 8080 to signer node

Signer Node

  • Ingress:
    • Port 10009 (gRPC) from watch-only node
    • Port 8080 (REST) from Express server

Prerequisites

  • Get Started
    • Docker or Kubernetes environment
    • Ability to generate TLS certificates (see Run in Production)
  • Network access for required ports

1. Configure Signer Node

The signer node is an LND instance that manages your keys and signs transactions. It runs in a restricted mode that doesn't require direct access to the Bitcoin or Lightning Network P2P connections.

Configuration requirements:

  • TLS certificate and key for secure communication.
  • External static IP address and host names accessible by the watch-only node.
  • Secure, isolated network zone with limited access.
  • No direct internet connectivity required (except for watch-only node communication).

The following is an example configuration for an LND signer node:

  • Bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Core settings
--lnddir=/lnd                  # Base directory for LND data
--nolisten                     # Disable p2p listening as this is a signer node
--nobootstrap                  # Disable bootstrap as we don't need peer connections

# Network interfaces
--restlisten=0.0.0.0:8080      # REST API endpoint for Express server communication
--rpclisten=0.0.0.0:10009      # gRPC endpoint for watch-only node communication

# Bitcoin network settings
--bitcoin.active               # Enable Bitcoin chain
--bitcoin.node=nochainbackend  # Run without full node (watch-only mode)
--bitcoin.testnet              # Use testnet (remove for mainnet)

# TLS configuration
--tlscertpath=/lnd/tls.cert    # TLS certificate location
--tlskeypath=/lnd/tls.key      # TLS private key location

2. Generate TLS Certificate

With self-custody Lightning, there are two sets of TLS certificates that you need to manage:

  • The TLS certificate for the Express server (see Run in Production).
  • The self-signed TLS certificate for the signer node, which is required for Express and BitGo to be able to communicate.

BitGo recommends creating a TLS certificate for the signer node by generating it within the LND node and then exporting it. You can automatically generate a certificate on startup by ensuring the tlscertpath and tlskeypath options aren't set on the LND configuration.

The following code sample enables you to run the LND node locally with this TLS configuration in Docker or Podman:

Note: BitGo highly recommends generating a TLS certificate with configurations for IP and domains by adding extra arguments to the LND configuration. For more details, see the GitHub repository for Lightning Network.

  • Bash
1
2
3
4
5
6
7
8
9
10
11
docker run -p 8080:8080 lightninglabs/lnd:v0.18.4 \
  --nolisten \
  --nobootstrap \
  --bitcoin.active \
  --bitcoin.node=nochainbackend \
  --bitcoin.testnet \
  --lnddir=/lnd \
  --tlsextradomain=example-hostname.com \
  --tlsextradomain=other-example-hostname.com\
  --tlsextraip=1.2.3.4  \
  --tlsextraip=4.5.6.7

3. Extract TLS Credentials

With your newly generated the TLS certificate:

  1. Remote into the signer.

    • Bash
    1
docker exec -it containerId /bin/sh

  2. Copy the tls.key and tls.cert files located at the root of the lnddir that was set when starting the container. Export these in base64 format:

    • Bash
    1
2
3
cd /lnd
base64 -i tls.cert
base64 -i tls.key

  3. Save the tls.key to your secrets.

  4. Upload the base64 TLS certificate to the wallet by updating the wallet with the signerTlsCert parameter.

  5. Add the --tlscertpath and --tlskeypath to the files in the LND configuration so it uses these certificates when it starts up next.

  6. Restart the node so it can begin using the latest TLS information.

4. Map Wallet to Signer Node

BitGo Express must start with the --lightningSignerFileSystemPath flag pointing to a JSON configuration file. This configuration file contains the mapping between wallet IDs and their corresponding signer node details.

  • JSON
1
2
3
4
5
6
{
  "walletId1": {
    "url": "hostname-of-signer-node",
    "tlsCert": "base64-encoded-tls-cert"
  }
}

The configuration file contains:

  • walletId - JSON key.
  • url - REST API endpoint of the signer node.
  • tlsCert - TLS certificate in base64-encoded format of the signer node.

Example Deployments

Docker Compose

  • YAML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
version: '3.8'
services:
  lnd-signer:
    image: lightninglabs/lnd:latest
    volumes:
      - ./lnd-data:/root/.lnd
      - ./tls:/tls
    ports:
      - "10009:10009"
      - "8080:8080"
    command: >
      --bitcoin.active
      --bitcoin.node=nochainbackend
      --tlscertpath=/tls/tls.cert
      --tlskeypath=/tls/tls.key
      --rpclisten=0.0.0.0:10009
      --restlisten=0.0.0.0:8080

express:
  image: bitgo/express:latest
    depends_on:
      - lnd-signer
    ports:
      - "3080:3080"
    command:
    - --lightningSignerFileSystemPath=/config/lightning-config.json
    volumes:
      - ./tls:/tls
      - ./config:/config

Kubernetes

  • YAML (Basic LND Signer)
  • YAML (Basic Express Deployment)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
apiVersion: apps/v1
kind: Deployment
metadata:
  name: lnd-signer
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: lnd
        image: lightninglabs/lnd:latest
        ports:
        - containerPort: 10009
        - containerPort: 8080
        volumeMounts:
        - name: tls
        mountPath: /tls
        - name: lnd-data
        mountPath: /root/.lnd
    volumes:
    - name: tls
      secret:
        secretName: lnd-tls
    - name: lightning-config
        secret:
          secretName: lightning-config
    - name: lnd-data
      persistentVolumeClaim:
        claimName: lnd-data

Next

Set Up Self-Custody Lightning Wallets

See Also