aljaz/lspd
1
0
Fork 0
mirror of https://github.com/aljazceru/lspd.git synced 2026-02-23 06:54:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #119 from aljazceru/master

Browse Source 
Adding Cloudformation template, bash automation and documentation update
This commit is contained in:
Aljaz Ceru
2023-08-29 19:43:25 +02:00
committed by GitHub
parent 2c396656e4 2ef5baca15
commit 505a02e5d9
7 changed files with 893 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
README.md
View File

@@ -3,44 +3,14 @@ lspd is a simple deamon that provides [LSP](https://medium.com/breez-technology/
This is a simple example of an lspd that works with an [lnd](https://github.com/lightningnetwork/lnd) node or a [cln](https://github.com/ElementsProject/lightning) node.
## Installation
### Build
1. git clone https://github.com/breez/lspd (or fork)
1. Compile lspd using `go build .`
### Before running
1. Create a random token (for instance using the command `openssl rand -base64 48`, or `./lspd genkey`)
1. Define the environment variables as described in sample.env. If `CERTMAGIC_DOMAIN` is defined, certificate for this domain is automatically obtained and renewed from Let's Encrypt. In this case, the port needs to be 443. If `CERTMAGIC_DOMAIN` is not defined, lspd needs to run behind a reverse proxy like treafik or nginx.
### Running lspd on LND
1. Run LND with the following options set:
- `--protocol.zero-conf`: for being able to open zero conf channels
- `--protocol.option-scid-alias`: required for zero conf channels
- `--requireinterceptor`: to make sure all htlcs are intercepted by lspd
- `--bitcoin.chanreservescript="0"` to allow the client to have zero reserve on their side
1. Run lspd
### Running lspd on CLN
In order to run lspd on top of CLN, you need to run the lspd process and run cln with the provided cln plugin.
The cln plugin (go build -o lspd_plugin cln_plugin/cmd) is best started with a bash script to pass environment variables (note this LISTEN_ADDRESS is the listen address for communication between lspd and the plugin, this is not the listen address mentioned in the 'final step')
```bash
#!/bin/bash
export LISTEN_ADDRESS=<listen address>
/path/to/lspd_plugin
```
1. Run cln with the following options set:
- `--plugin=/path/to/shell/script.sh`: to use lspd as plugin
- `--max-concurrent-htlcs=30`: In order to use zero reserve channels on the client side, (local max_accepted_htlcs + remote max_accepted_htlcs + 2) * dust limit must be lower than the channel capacity. Reduce max-concurrent-htlcs or increase channel capacity accordingly.
- `--dev-allowdustreserve=true`: In order to allow zero reserve on the client side, you'll need to enable developer mode on cln (`./configure --enable-developer`)
- `--experimental-anchors`: In order to allow opening anchor channels.
1. Run lspd
### Final step
1. Share with Breez the TOKEN and the LISTEN_ADDRESS you've defined (send to contact@breez.technology)
## Deployment
Installation and configuration instructions for both implementations can be found here:
### Manual install
- [CLN](./docs/CLN.md) - step by step installation instructions for CLN
- [LND](./docs/LND.md) - step by step installation instructions for LND
### Automated deployment
- [AWS](./docs/aws.md) - automated deployment of bitcoind, CLN and lspd to AWS, together with
- [Bash](./docs/bash.md) - install everything on any debian/ubuntu server
## Implement your own lspd
You can create your own lsdp by implementing the grpc methods described [here](https://github.com/breez/lspd/blob/master/rpc/lspd.md).
@@ -98,5 +68,4 @@ up some artefacts. Here's where to look:
- bitcoind process
- docker container for postgres with default name
It may be a good idea to clean your testdir every once in a while if you're
using the `preservelogs` or `preservestate` flags.
It may be a good idea to clean your testdir every once in a while if you're using the `preservelogs` or `preservestate` flags.

385
deploy/deploy.yml Normal file
View File

@@ -0,0 +1,385 @@
AWSTemplateFormatVersion: '2010-09-09'
Parameters:
KeyName:
Description: Name of an existing EC2 KeyPair to enable SSH access
Type: 'AWS::EC2::KeyPair::KeyName'
LSPName:
Description: LSP Name
Type: String
VPCID:
Description: The ID of the VPC in which to create the resources
Type: 'AWS::EC2::VPC::Id'
Mappings:
AMIRegionMap:
ap-northeast-1:
AMIID: ami-0deffe25fb08894f5
ap-northeast-2:
AMIID: ami-097243fad67b35a40
ap-northeast-3:
AMIID: ami-03ad2f651aaddff3a
ap-south-1:
AMIID: ami-0361008010558ea2d
ap-southeast-1:
AMIID: ami-07bf64b7ca62c96ee
ap-southeast-2:
AMIID: ami-0cc8e61f3957442b8
ca-central-1:
AMIID: ami-0cfe1aac5d0b881ff
eu-central-1:
AMIID: ami-0042e6537994c4181
eu-north-1:
AMIID: ami-00347e40213620217
eu-west-1:
AMIID: ami-04620cb5b85309067
eu-west-2:
AMIID: ami-0315c69b482426e70
eu-west-3:
AMIID: ami-0dcc6ef9e7a6e70f2
sa-east-1:
AMIID: ami-027ba68d27297f530
us-east-1:
AMIID: ami-01e8fbda99c153c6b
us-east-2:
AMIID: ami-0ef27e70f95b439e8
us-west-1:
AMIID: ami-09d529cbaf5cc7e6f
us-west-2:
AMIID: ami-0acfc42b227d0b719
Resources:
# EC2 Instance
EC2Instance:
Type: 'AWS::EC2::Instance'
Properties:
InstanceType: m6a.xlarge
ImageId: !FindInMap [AMIRegionMap, !Ref "AWS::Region", AMIID]
KeyName: !Ref KeyName
BlockDeviceMappings: # resize root volume to 1TB
- DeviceName: "/dev/xvda"
Ebs:
VolumeSize: 1024
VolumeType: gp2
DeleteOnTermination: true
UserData:
Fn::Base64:
!Sub |
#!/bin/bash
# Elevate privileges
if [ "$EUID" -ne 0 ]; then
sudo bash "$0" "$@"
exit
fi
# Redirect all outputs to a log file
exec > >(tee -a "/tmp/deployment.log") 2>&1
# fix locale if on debian
if grep -q "Debian" /etc/os-release; then
sed -i '/^# en_US.UTF-8 UTF-8/s/^# //' /etc/locale.gen
locale-gen
echo "export LC_ALL=en_US.UTF-8" >> /etc/bash.bashrc
echo "export LANG=en_US.UTF-8" >> /etc/bash.bashrc
fi
source /etc/bash.bashrc
# create users
sudo adduser --disabled-password --gecos "" lightning
sudo adduser --disabled-password --gecos "" bitcoin
sudo adduser --disabled-password --gecos "" lspd
# Create a file to store the credentials
CREDENTIALS="/home/lspd/credentials.txt"
touch "$CREDENTIALS"
# Generate a random password for PostgreSQL users
LSPD_DB_PASSWORD=$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 20)
LIGHTNING_DB_PASSWORD=$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 20)
# Output the password to a file
echo "### PostgreSQL Credentials ###" >> "$CREDENTIALS"
echo "postgres lspd:" >> "$CREDENTIALS"
echo "username: lspd " >> "$CREDENTIALS"
echo "password: $LSPD_DB_PASSWORD" >> "$CREDENTIALS"
echo "postgres lightning:" >> "$CREDENTIALS"
echo "username: lightning" >> "$CREDENTIALS"
echo "password: $LIGHTNING_DB_PASSWORD" >> "$CREDENTIALS"
# Generic name if no name is provided (running locally)
if [ -z "$LSPName" ]; then
LSPName="lsp-$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 5)"
fi
# Install dependencies and required packages
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get upgrade -y
sudo apt-get install -y git autoconf automake build-essential libtool libgmp-dev libsqlite3-dev python3 python3-pip net-tools zlib1g-dev postgresql postgresql-client-common postgresql-client postgresql postgresql-contrib libpq5 libsodium-dev gettext cargo protobuf-compiler libgmp3-dev python-is-python3 libpq-dev jq
sudo pip3 install mako grpcio grpcio-tools
# Modify the pg_hba.conf file to set md5 password authentication for local connections
PG_VERSION=$(psql -V | awk '{print $3}' | awk -F"." '{print $1}')
sed -i 's/local all all peer/local all all md5/g' /etc/postgresql/$PG_VERSION/main/pg_hba.conf
# Create PostgreSQL users and databases
sudo -i -u postgres psql -c "CREATE ROLE lightning;"
sudo -i -u postgres psql -c "CREATE DATABASE lightning;"
sudo -i -u postgres psql -c "ALTER ROLE lightning WITH NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD '$LIGHTNING_DB_PASSWORD';"
sudo -i -u postgres psql -c "ALTER DATABASE lightning OWNER TO lightning;"
sudo -i -u postgres psql -c "CREATE ROLE lspd;"
sudo -i -u postgres psql -c "ALTER ROLE lspd WITH NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD '$LSPD_DB_PASSWORD';"
sudo -i -u postgres psql -c "CREATE DATABASE lspd WITH TEMPLATE = template0 ENCODING = 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';"
sudo -i -u postgres psql -c "ALTER DATABASE lspd OWNER TO lspd;"
# Restart PostgreSQL to apply changes
service postgresql restart
# Create directories under /opt
sudo mkdir -p /opt/lightning /opt/lspd
# Install go
wget https://go.dev/dl/go1.20.6.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.20.6.linux-amd64.tar.gz
echo "export PATH=$PATH:/usr/local/go/bin" | sudo tee -a /etc/bash.bashrc
source /etc/bash.bashrc
# Install rust
curl https://sh.rustup.rs -sSf | sh -s -- -y
# Install bitcoin
wget https://bitcoincore.org/bin/bitcoin-core-25.0/bitcoin-25.0-x86_64-linux-gnu.tar.gz -O /opt/bitcoin.tar.gz
tar -xzf /opt/bitcoin.tar.gz -C /opt/
cd /opt/bitcoin-*/bin
chmod 710 /etc/bitcoin
sudo install -m 0755 -t /usr/local/bin *
cat <<EOL | sudo tee /etc/systemd/system/bitcoind.service
[Unit]
Description=Bitcoin daemon
After=network.target
[Service]
WorkingDirectory=/var/lib/bitcoind
ExecStart=bitcoind -pid=/run/bitcoind/bitcoind.pid -conf=/etc/bitcoin/bitcoin.conf
PermissionsStartOnly=true
ExecStartPre=/bin/chgrp bitcoin /var/lib/bitcoind
Type=forking
PIDFile=/run/bitcoind/bitcoind.pid
Restart=on-failure
TimeoutStartSec=infinity
TimeoutStopSec=600
User=bitcoin
Group=bitcoin
RuntimeDirectory=bitcoind
RuntimeDirectoryMode=0710
ConfigurationDirectory=bitcoin
StateDirectory=bitcoind
StateDirectoryMode=0710
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
NoNewPrivileges=true
PrivateDevices=true
MemoryDenyWriteExecute=true
[Install]
WantedBy=multi-user.target
EOL
# cat to a bitcoin.conf file
RPCPASSWORD=$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 20)
echo "### Bitcoin Configuration ###" >> "$CREDENTIALS"
echo "rpcuser: cln" >> "$CREDENTIALS"
echo "rpcpassword: $RPCPASSWORD" >> "$CREDENTIALS"
sudo mkdir /etc/bitcoin/
sudo touch /etc/bitcoin/bitcoin.conf
cat <<EOL | sudo tee /etc/bitcoin/bitcoin.conf
txindex=1
daemon=1
datadir=/var/lib/bitcoind
startupnotify='systemd-notify --ready'
shutdownnotify='systemd-notify --stopping'
rpcuser=cln
rpcpassword=$RPCPASSWORD
minrelaytxfee=0.00000000
incrementalrelayfee=0.00000010
zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28333
EOL
chown -R bitcoin:bitcoin /etc/bitcoin
chmod 755 /etc/bitcoin
sudo mkdir /home/lightning/.bitcoin/
sudo mkdir /root/.bitcoin/
sudo ln -s /etc/bitcoin/bitcoin.conf /home/lightning/.bitcoin/bitcoin.conf
sudo ln -s /etc/bitcoin/bitcoin.conf /root/.bitcoin/bitcoin.conf
###################################
######## Install lightning ########
###################################
sudo mkdir /home/lightning/.lightning/
sudo mkdir /etc/lightningd
#cat <<EOL | sudo tee /home/lightning/.lightning/config
cat <<EOL | sudo tee /etc/lightningd/lightningd.conf
bitcoin-rpcuser=cln
bitcoin-rpcpassword=$RPCPASSWORD
bitcoin-rpcconnect=127.0.0.1
bitcoin-rpcport=8332
addr=:9735
bitcoin-retry-timeout=3600
alias="${LSPName}"
wallet=postgres://lightning:$LIGHTNING_DB_PASSWORD@localhost:5432/lightning
plugin=/home/lightning/.lightning/plugins/lspd_plugin
lsp-listen=127.0.0.1:12312
max-concurrent-htlcs=30
dev-allowdustreserve=true
allow-deprecated-apis=true
log-file=/var/log/lightningd/lightningd.log
EOL
chmod 755 /etc/lightningd/
git clone https://github.com/ElementsProject/lightning.git /opt/lightning
cd /opt/lightning
git checkout v23.05
./configure --enable-developer
make
make install
cat <<EOL | sudo tee /etc/systemd/system/lightningd.service
[Unit]
Description=Lightning Network Daemon (lightningd)
Wants=network-online.target
After=network.target
[Service]
ExecStart=/usr/local/bin/lightningd --daemon --conf /etc/lightningd/lightningd.conf --pid-file=/run/lightningd/lightningd.pid
MemoryDenyWriteExecute=true
NoNewPrivileges=true
PrivateDevices=true
Type=forking
PrivateTmp=true
ProtectSystem=full
Restart=on-failure
User=lightning
Group=lightning
RuntimeDirectory=lightningd
ConfigurationDirectory=lightningd
LogsDirectory=lightningd
[Install]
WantedBy=multi-user.target
EOL
# Install lspd
git clone https://github.com/breez/lspd.git /opt/lspd
cd /opt/lspd
source /etc/bash.bashrc
export PATH=$PATH:/usr/local/go/bin
sudo env "PATH=$PATH" go get
sudo env "PATH=$PATH" go get github.com/breez/lspd/cln_plugin
sudo env "PATH=$PATH" go build .
sudo env "PATH=$PATH" go build -o lspd_plugin ./cln_plugin/cmd
sudo cp lspd /usr/local/bin/
sudo mkdir /home/lightning/.lightning/plugins
sudo cp lspd_plugin /home/lightning/.lightning/plugins/
cat <<EOL | sudo tee /etc/systemd/system/lspd.service
[Unit]
Description=Lightning Service Daemon (lspd)
After=network.target
[Service]
User=lspd
EnvironmentFile=/home/lspd/.env
WorkingDirectory=/opt/lspd
ExecStart=/usr/local/bin/lspd
Restart=on-failure
RestartSec=5
EOL
sudo chown -R lightning:lightning /home/lightning/
sudo systemctl daemon-reload
sudo systemctl enable bitcoind.service
sudo systemctl enable lspd.service
sudo systemctl enable lightningd.service
sudo systemctl start bitcoind.service
sudo systemctl start lightningd.service
sleep 60
echo "### Lightning Credentials ###" >> "$CREDENTIALS"
sudo echo "cln hsm_secret backup:" >> "$CREDENTIALS"
sudo xxd /home/lightning/.lightning/bitcoin/hsm_secret >> "$CREDENTIALS"
# Post install
PUBKEY=$(sudo -u lightning lightning-cli getinfo | jq .id | cut -d "\"" -f 2)
LSPD_PRIVATE_KEY=$(lspd genkey | awk -F= '{print $2}' | cut -d "\"" -f 2)
TOKEN=$(lspd genkey | awk -F= '{print $2}' | cut -d "\"" -f 2)
EXTERNAL_IP=$(curl -s http://whatismyip.akamai.com/)
echo "### LSPD Credentials ###" >> "$CREDENTIALS"
echo "token: $TOKEN" >> "$CREDENTIALS"
echo "lspd_private_key: $LSPD_PRIVATE_KEY" >> "$CREDENTIALS"
cat <<EOL | sudo tee /home/lspd/.env
LISTEN_ADDRESS=0.0.0.0:8888
LSPD_PRIVATE_KEY="$LSPD_PRIVATE_KEY"
AWS_REGION="<REPLACE ME>"
AWS_ACCESS_KEY_ID="<REPLACE ME>"
AWS_SECRET_ACCESS_KEY="<REPLACE ME>"
DATABASE_URL="postgres://lspd:$LSPD_DB_PASSWORD@localhost/lspd"
OPENCHANNEL_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
OPENCHANNEL_NOTIFICATION_CC='["REPLACE ME <test@example.com>"]'
OPENCHANNEL_NOTIFICATION_FROM="test@example.com"
CHANNELMISMATCH_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_CC='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_FROM="replaceme@example.com"
MEMPOOL_API_BASE_URL=https://mempool.space/api/v1/
MEMPOOL_PRIORITY=economy
NODES='[ { "name": "${LSPName}", "nodePubkey": "$PUBKEY", "lspdPrivateKey": "$LSPD_PRIVATE_KEY", "token": "$TOKEN", "host": "$EXTERNAL_IP:8888", "publicChannelAmount": "1000183", "channelAmount": "100000", "channelPrivate": false, "targetConf": "6", "minConfs": "6", "minHtlcMsat": "600", "baseFeeMsat": "1000", "feeRate": "0.000001", "timeLockDelta": "144", "channelFeePermyriad": "40", "channelMinimumFeeMsat": "2000000", "additionalChannelCapacity": "100000", "maxInactiveDuration": "3888000", "cln": { "pluginAddress": "127.0.0.1:12312", "socketPath": "/home/lightning/.lightning/bitcoin/lightning-rpc" } } ]'
EOL
sudo systemctl start lspd.service
echo "Installation complete"
sudo chmod 400 /home/lspd/credentials.txt
echo "Make sure to backup the credentials.txt file that can be found at /home/lspd/credentials.txt"
SecurityGroupIds:
- !GetAtt EC2SecurityGroup.GroupId
Tags:
- Key: Name
Value: lspd
# EC2 Elastic IP
EIP:
Type: 'AWS::EC2::EIP'
Properties:
Tags:
- Key: Name
Value: lspd
# EC2 Elastic IP Association
EIPAssociation:
Type: 'AWS::EC2::EIPAssociation'
Properties:
InstanceId: !Ref EC2Instance
EIP: !Ref EIP
# EC2 Security Group
EC2SecurityGroup:
Type: 'AWS::EC2::SecurityGroup'
Properties:
VpcId: !Ref VPCID
GroupDescription: Security Group for EC2 instance
SecurityGroupIngress:
- IpProtocol: tcp
FromPort: 22
ToPort: 22
CidrIp: 84.255.203.183/32
- IpProtocol: tcp
FromPort: 9735
ToPort: 9735
CidrIp: 0.0.0.0/0
- IpProtocol: tcp
FromPort: 8888
ToPort: 8888
CidrIp: 0.0.0.0/0

276
deploy/lspd-install.sh Normal file
View File

@@ -0,0 +1,276 @@
#!/bin/bash
# Elevate privileges
if [ "$EUID" -ne 0 ]; then
sudo bash "$0" "$@"
exit
fi
# Redirect all outputs to a log file
exec > >(tee -a "/tmp/deployment.log") 2>&1
# fix locale if on debian
if grep -q "Debian" /etc/os-release; then
sed -i '/^# en_US.UTF-8 UTF-8/s/^# //' /etc/locale.gen
locale-gen
echo "export LC_ALL=en_US.UTF-8" >> /etc/bash.bashrc
echo "export LANG=en_US.UTF-8" >> /etc/bash.bashrc
fi
source /etc/bash.bashrc
# create users
sudo adduser --disabled-password --gecos "" lightning
sudo adduser --disabled-password --gecos "" bitcoin
sudo adduser --disabled-password --gecos "" lspd
# Create a file to store the credentials
CREDENTIALS="/home/lspd/credentials.txt"
touch "$CREDENTIALS"
# Generate a random password for PostgreSQL users
LSPD_DB_PASSWORD=$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 20)
LIGHTNING_DB_PASSWORD=$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 20)
# Output the password to a file
echo "### PostgreSQL Credentials ###" >> "$CREDENTIALS"
echo "postgres lspd:" >> "$CREDENTIALS"
echo "username: lspd " >> "$CREDENTIALS"
echo "password: $LSPD_DB_PASSWORD" >> "$CREDENTIALS"
echo "postgres lightning:" >> "$CREDENTIALS"
echo "username: lightning" >> "$CREDENTIALS"
echo "password: $LIGHTNING_DB_PASSWORD" >> "$CREDENTIALS"
# Generic name if no name is provided (running locally)
if [ -z "$LSPName" ]; then
LSPName="lsp-$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 5)"
fi
# Install dependencies and required packages
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get upgrade -y
sudo apt-get install -y git autoconf automake build-essential libtool libgmp-dev libsqlite3-dev python3 python3-pip net-tools zlib1g-dev postgresql postgresql-client-common postgresql-client postgresql postgresql-contrib libpq5 libsodium-dev gettext cargo protobuf-compiler libgmp3-dev python-is-python3 libpq-dev jq
sudo pip3 install mako grpcio grpcio-tools
# Modify the pg_hba.conf file to set md5 password authentication for local connections
PG_VERSION=$(psql -V | awk '{print $3}' | awk -F"." '{print $1}')
sed -i 's/local all all peer/local all all md5/g' /etc/postgresql/$PG_VERSION/main/pg_hba.conf
# Create PostgreSQL users and databases
sudo -i -u postgres psql -c "CREATE ROLE lightning;"
sudo -i -u postgres psql -c "CREATE DATABASE lightning;"
sudo -i -u postgres psql -c "ALTER ROLE lightning WITH NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD '$LIGHTNING_DB_PASSWORD';"
sudo -i -u postgres psql -c "ALTER DATABASE lightning OWNER TO lightning;"
sudo -i -u postgres psql -c "CREATE ROLE lspd;"
sudo -i -u postgres psql -c "ALTER ROLE lspd WITH NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD '$LSPD_DB_PASSWORD';"
sudo -i -u postgres psql -c "CREATE DATABASE lspd WITH TEMPLATE = template0 ENCODING = 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';"
sudo -i -u postgres psql -c "ALTER DATABASE lspd OWNER TO lspd;"
# Restart PostgreSQL to apply changes
service postgresql restart
# Create directories under /opt
sudo mkdir -p /opt/lightning /opt/lspd
# Install go
wget https://go.dev/dl/go1.20.6.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.20.6.linux-amd64.tar.gz
echo "export PATH=$PATH:/usr/local/go/bin" | sudo tee -a /etc/bash.bashrc
source /etc/bash.bashrc
# Install rust
curl https://sh.rustup.rs -sSf | sh -s -- -y
# Install bitcoin
wget https://bitcoincore.org/bin/bitcoin-core-25.0/bitcoin-25.0-x86_64-linux-gnu.tar.gz -O /opt/bitcoin.tar.gz
tar -xzf /opt/bitcoin.tar.gz -C /opt/
cd /opt/bitcoin-*/bin
chmod 710 /etc/bitcoin
sudo install -m 0755 -t /usr/local/bin *
cat <<EOL | sudo tee /etc/systemd/system/bitcoind.service
[Unit]
Description=Bitcoin daemon
After=network.target
[Service]
WorkingDirectory=/var/lib/bitcoind
ExecStart=bitcoind -pid=/run/bitcoind/bitcoind.pid -conf=/etc/bitcoin/bitcoin.conf
PermissionsStartOnly=true
ExecStartPre=/bin/chgrp bitcoin /var/lib/bitcoind
Type=forking
PIDFile=/run/bitcoind/bitcoind.pid
Restart=on-failure
TimeoutStartSec=infinity
TimeoutStopSec=600
User=bitcoin
Group=bitcoin
RuntimeDirectory=bitcoind
RuntimeDirectoryMode=0710
ConfigurationDirectory=bitcoin
StateDirectory=bitcoind
StateDirectoryMode=0710
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
NoNewPrivileges=true
PrivateDevices=true
MemoryDenyWriteExecute=true
[Install]
WantedBy=multi-user.target
EOL
# cat to a bitcoin.conf file
RPCPASSWORD=$(</dev/urandom tr -dc 'A-Za-z0-9' | head -c 20)
echo "### Bitcoin Configuration ###" >> "$CREDENTIALS"
echo "rpcuser: cln" >> "$CREDENTIALS"
echo "rpcpassword: $RPCPASSWORD" >> "$CREDENTIALS"
sudo mkdir /etc/bitcoin/
sudo touch /etc/bitcoin/bitcoin.conf
cat <<EOL | sudo tee /etc/bitcoin/bitcoin.conf
txindex=1
daemon=1
datadir=/var/lib/bitcoind
startupnotify='systemd-notify --ready'
shutdownnotify='systemd-notify --stopping'
rpcuser=cln
rpcpassword=$RPCPASSWORD
minrelaytxfee=0.00000000
incrementalrelayfee=0.00000010
zmqpubrawblock=tcp://127.0.0.1:28332
zmqpubrawtx=tcp://127.0.0.1:28333
EOL
chown -R bitcoin:bitcoin /etc/bitcoin
chmod 755 /etc/bitcoin
sudo mkdir /home/lightning/.bitcoin/
sudo mkdir /root/.bitcoin/
sudo ln -s /etc/bitcoin/bitcoin.conf /home/lightning/.bitcoin/bitcoin.conf
sudo ln -s /etc/bitcoin/bitcoin.conf /root/.bitcoin/bitcoin.conf
###################################
######## Install lightning ########
###################################
sudo mkdir /home/lightning/.lightning/
sudo mkdir /etc/lightningd
#cat <<EOL | sudo tee /home/lightning/.lightning/config
cat <<EOL | sudo tee /etc/lightningd/lightningd.conf
bitcoin-rpcuser=cln
bitcoin-rpcpassword=$RPCPASSWORD
bitcoin-rpcconnect=127.0.0.1
bitcoin-rpcport=8332
addr=:9735
bitcoin-retry-timeout=3600
alias="${LSPName}"
wallet=postgres://lightning:$LIGHTNING_DB_PASSWORD@localhost:5432/lightning
plugin=/home/lightning/.lightning/plugins/lspd_plugin
lsp-listen=127.0.0.1:12312
max-concurrent-htlcs=30
dev-allowdustreserve=true
allow-deprecated-apis=true
log-file=/var/log/lightningd/lightningd.log
EOL
chmod 755 /etc/lightningd/
git clone https://github.com/ElementsProject/lightning.git /opt/lightning
cd /opt/lightning
git checkout v23.05
./configure --enable-developer
make
make install
cat <<EOL | sudo tee /etc/systemd/system/lightningd.service
[Unit]
Description=Lightning Network Provider Daemon (lightningd)
Wants=network-online.target
After=network.target
[Service]
ExecStart=/usr/local/bin/lightningd --daemon --conf /etc/lightningd/lightningd.conf --pid-file=/run/lightningd/lightningd.pid
MemoryDenyWriteExecute=true
NoNewPrivileges=true
PrivateDevices=true
Type=forking
PrivateTmp=true
ProtectSystem=full
Restart=on-failure
User=lightning
Group=lightning
RuntimeDirectory=lightningd
ConfigurationDirectory=lightningd
LogsDirectory=lightningd
[Install]
WantedBy=multi-user.target
EOL
# Install lspd
git clone https://github.com/breez/lspd.git /opt/lspd
cd /opt/lspd
source /etc/bash.bashrc
export PATH=$PATH:/usr/local/go/bin
sudo env "PATH=$PATH" go get
sudo env "PATH=$PATH" go get github.com/breez/lspd/cln_plugin
sudo env "PATH=$PATH" go build .
sudo env "PATH=$PATH" go build -o lspd_plugin ./cln_plugin/cmd
sudo cp lspd /usr/local/bin/
sudo mkdir /home/lightning/.lightning/plugins
sudo cp lspd_plugin /home/lightning/.lightning/plugins/
cat <<EOL | sudo tee /etc/systemd/system/lspd.service
[Unit]
Description=Lightning Service Daemon (lspd)
After=network.target
[Service]
User=lspd
EnvironmentFile=/home/lspd/.env
WorkingDirectory=/opt/lspd
ExecStart=/usr/local/bin/lspd
Restart=on-failure
RestartSec=5
EOL
sudo chown -R lightning:lightning /home/lightning/
sudo systemctl daemon-reload
sudo systemctl enable bitcoind.service
sudo systemctl enable lspd.service
sudo systemctl enable lightningd.service
sudo systemctl start bitcoind.service
sudo systemctl start lightningd.service
sleep 60
echo "### Lightning Credentials ###" >> "$CREDENTIALS"
sudo echo "cln hsm_secret backup:" >> "$CREDENTIALS"
sudo xxd /home/lightning/.lightning/bitcoin/hsm_secret >> "$CREDENTIALS"
# Post install
PUBKEY=$(sudo -u lightning lightning-cli getinfo | jq .id | cut -d "\"" -f 2)
LSPD_PRIVATE_KEY=$(lspd genkey | awk -F= '{print $2}' | cut -d "\"" -f 2)
TOKEN=$(lspd genkey | awk -F= '{print $2}' | cut -d "\"" -f 2)
EXTERNAL_IP=$(curl -s http://whatismyip.akamai.com/)
echo "### LSPD Credentials ###" >> "$CREDENTIALS"
echo "token: $TOKEN" >> "$CREDENTIALS"
echo "lspd_private_key: $LSPD_PRIVATE_KEY" >> "$CREDENTIALS"
cat <<EOL | sudo tee /home/lspd/.env
LISTEN_ADDRESS=0.0.0.0:8888
LSPD_PRIVATE_KEY="$LSPD_PRIVATE_KEY"
AWS_REGION="<REPLACE ME>"
AWS_ACCESS_KEY_ID="<REPLACE ME>"
AWS_SECRET_ACCESS_KEY="<REPLACE ME>"
DATABASE_URL="postgres://lspd:$LSPD_DB_PASSWORD@localhost/lspd"
OPENCHANNEL_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
OPENCHANNEL_NOTIFICATION_CC='["REPLACE ME <test@example.com>"]'
OPENCHANNEL_NOTIFICATION_FROM="test@example.com"
CHANNELMISMATCH_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_CC='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_FROM="replaceme@example.com"
MEMPOOL_API_BASE_URL=https://mempool.space/api/v1/
MEMPOOL_PRIORITY=economy
NODES='[ { "name": "${LSPName}", "nodePubkey": "$PUBKEY", "lspdPrivateKey": "$LSPD_PRIVATE_KEY", "token": "$TOKEN", "host": "$EXTERNAL_IP:8888", "publicChannelAmount": "1000183", "channelAmount": "100000", "channelPrivate": false, "targetConf": "6", "minConfs": "6", "minHtlcMsat": "600", "baseFeeMsat": "1000", "feeRate": "0.000001", "timeLockDelta": "144", "channelFeePermyriad": "40", "channelMinimumFeeMsat": "2000000", "additionalChannelCapacity": "100000", "maxInactiveDuration": "3888000", "cln": { "pluginAddress": "127.0.0.1:12312", "socketPath": "/home/lightning/.lightning/bitcoin/lightning-rpc" } } ]'
EOL
sudo systemctl start lspd.service
echo "Installation complete"
sudo chmod 400 /home/lspd/credentials.txt
echo "Make sure to backup the credentials.txt file that can be found at /home/lspd/credentials.txt"

72
docs/CLN.md Normal file
View File

@@ -0,0 +1,72 @@
## Installation instructions for core lightning and lspd
### Requirements
- CLN (compiled with developer mode on)
- lspd
- lspd plugin for cln
- postgresql
### Installation
#### CLN
Follow compilation steps for CLN [here](https://github.com/ElementsProject/lightning/blob/master/doc/getting-started/getting-started/installation.md) to enable developer mode.
#### lspd
Needs to be built from source:
```
git clone https://github.com/breez/lspd
cd lspd
go build . # compile lspd
go build -o lspd_plugin ./cln_plugin/cmd # compile lspd cln plugin
```
#### Postgresql
Lspd supports postgresql backend. To create database and new role to access it on your postgres server use:
##### Postgresql server
```
CREATE ROLE <username>;
ALTER ROLE <username> WITH NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD '<password>';
CREATE DATABASE <dbname> WITH TEMPLATE = template0 ENCODING = 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';
ALTER DATABASE <dbname> OWNER TO <username>;
```
##### RDS on AWS
```
CREATE ROLE <username>;
ALTER ROLE <username> WITH INHERIT NOCREATEROLE NOCREATEDB LOGIN NOBYPASSRLS PASSWORD '<password>';
CREATE DATABASE <dbname> WITH TEMPLATE = template0 ENCODING = 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';
ALTER DATABASE <dbname> OWNER TO <username>;
```
### Configuration
1. Create a random token (for instance using the command `openssl rand -base64 48`, or `./lspd genkey`)
1. Define the environment variables as described in [sample.env](./sample.env). If `CERTMAGIC_DOMAIN` is defined, certificate for this domain is automatically obtained and renewed from Let's Encrypt. In this case, the port needs to be 443. If `CERTMAGIC_DOMAIN` is not defined, lspd needs to run behind a reverse proxy like treafik or nginx.
ENV variables:
- `LISTEN_ADDRESS` defines the host:port for the lspd grpc server
- `CERTMAGIC_DOMAIN` domain on which lspd will be accessible
- `DATABASE_URL` postgresql db url
- `AWS_REGION` AWS region for SES emailing
- `AWS_ACCESS_KEY_ID` API key for SES emailing
- `AWS_SECRET_ACCESS_KEY`API secret for SES emailing
- `MEMPOOL_API_BASE_URL` uses fee estimation for opening new channels (default: https://mempool.space/api/v1/)
- `MEMPOOL_PRIORITY` priority with which open new channels using mempool api
(options: minimum, economy, hour, halfhour, fastest) (default: economy)
- `NODES` which nodes are used by lspd (see below for example, multiple nodes supported and more examples can be found in [sample.env](../sample.env))
Example of NODES variable:
```
NODES='[ { "name": "${LSPName}", "nodePubkey": "$PUBKEY", "lspdPrivateKey": "$LSPD_PRIVATE_KEY", "token": "$TOKEN", "host": "$EXTERNAL_IP:8888", "publicChannelAmount": "1000183", "channelAmount": "100000", "channelPrivate": false, "targetConf": "6", "minConfs": "6", "minHtlcMsat": "600", "baseFeeMsat": "1000", "feeRate": "0.000001", "timeLockDelta": "144", "channelFeePermyriad": "40", "channelMinimumFeeMsat": "2000000", "additionalChannelCapacity": "100000", "maxInactiveDuration": "3888000", "cln": { "pluginAddress": "127.0.0.1:12312", "socketPath": "/home/lightning/.lightning/bitcoin/lightning-rpc" } } ]'
```
### Running lspd on CLN
In order to run lspd on top of CLN, you need to run the lspd process and run cln with the provided cln plugin. You also need lightningd compiled with developer mode on (`./configure --enable-developer`)
1. Run cln with the following options set:
- `--plugin=/path/to/lspd_plugin`: to use lspd as plugin
- `--max-concurrent-htlcs=30`: In order to use zero reserve channels on the client side, (local max_accepted_htlcs + remote max_accepted_htlcs + 2) * dust limit must be lower than the channel capacity. Reduce max-concurrent-htlcs or increase channel capacity accordingly.
- `--dev-allowdustreserve=true`: In order to allow zero reserve on the client side (requires developer mode turned on)
- `--allow-deprecated-apis=true`: lspd currently uses a deprecated api, so needs this flag set.
- `--lsp-listen=127.0.0.1:<port>`: Set on which port the lspd_plugin will listen for lspd communication, must be the same port that is used in pluginAddress parameter in NODES env variable.
1. Run lspd
### Final step
1. Share with Breez the TOKEN and the LISTEN_ADDRESS you've defined (send to contact@breez.technology)

52
docs/LND.md Normal file
View File

@@ -0,0 +1,52 @@
## Installation instructions for lnd and lspd
### Requirements
- lnd
- lspd
- postgresql
### Installation
#### LND
Follow LND installation instructions [here](https://github.com/lightningnetwork/lnd/blob/master/docs/INSTALL.md).
#### lspd
Needs to be build from source:
```
git clone https://github.com/breez/lspd
cd lspd
go build . # compile lspd
```
### Postgresql
Lspd supports postgresql backend. Create new database and user for lspd:
```
CREATE ROLE <username>;
ALTER ROLE <username> WITH NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB LOGIN NOREPLICATION NOBYPASSRLS PASSWORD '<password>';
CREATE DATABASE <dbname> WITH TEMPLATE = template0 ENCODING = 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8';
ALTER DATABASE <dbname> OWNER TO <username>;
``````
### Configure
1. Create a random token (for instance using the command `openssl rand -base64 48`, or `./lspd genkey`)
1. Define the environment variables as described in [sample.env](./sample.env). If `CERTMAGIC_DOMAIN` is defined, certificate for this domain is automatically obtained and renewed from Let's Encrypt. In this case, the port needs to be 443. If `CERTMAGIC_DOMAIN` is not defined, lspd needs to run behind a reverse proxy like treafik or nginx.
ENV variables:
- `LISTEN_ADDRESS` defines the host:port for the lspd grpc server
- `CERTMAGIC_DOMAIN` domain on which lspd will be accessible
- `DATABASE_URL` postgresql db url
- `AWS_REGION`
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `MEMPOOL_API_BASE_URL` uses fee estimation for opening new channels (default: https://mempool.space)
- `MEMPOOL_PRIORITY` priority with which open new channels using mempool api (default: economy)
### Running lspd on LND
1. Run LND with the following options set:
- `--protocol.zero-conf`: for being able to open zero conf channels
- `--protocol.option-scid-alias`: required for zero conf channels
- `--requireinterceptor`: to make sure all htlcs are intercepted by lspd
- `--bitcoin.chanreservescript="0"` to allow the client to have zero reserve on their side
1. Run lspd
### Final step
1. Share with Breez the TOKEN and the LISTEN_ADDRESS you've defined (send to contact@breez.technology)

42
docs/aws.md Normal file
View File

@@ -0,0 +1,42 @@
## Automated deployment of LSPD stack to AWS
Cloudformation template for automated deployment of lspd, bitcoind and cln with postgresql backend.
### Requirements
- AWS account
- AWS SES configured
### Deployment
[Cloudformation template](../deploy/deploy.yml) will automatically deploy several things:
- new ec2 instance (m6a.xlarge) to your selected VPC
- bitcoind
- cln (with postgresql as backend)
- lspd
### After deployment steps
#### Configure email notifications
Edit file ```/home/lspd/.env```.
1) set your SES credentials:
```
AWS_REGION="<REPLACE ME>"
AWS_ACCESS_KEY_ID="<REPLACE ME>"
AWS_SECRET_ACCESS_KEY="<REPLACE ME>"
```
2) configure email
```
OPENCHANNEL_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
OPENCHANNEL_NOTIFICATION_CC='["REPLACE ME <test@example.com>"]'
OPENCHANNEL_NOTIFICATION_FROM="test@example.com"
CHANNELMISMATCH_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_CC='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_FROM="replaceme@example.com"
```
#### Backup credentials
All credentials are generated automatically and are written down in ```/home/lspd/credentials.txt```
**Store them securely and delete the file.**
### Debugging
Log file of deployment is written to ```/tmp/deployment.log``` where you can see the entire output of what happend during deployment.

57
docs/bash.md Normal file
View File

@@ -0,0 +1,57 @@
## Automated install of LSPD stack for linux
### Requirements
- ubuntu or debian based distribution
- AWS SES credentials
- root / user without sudo password
### Installation
To install bitcoind,cln and lspd to your system simply run:
```curl -sL https://raw.githubusercontent.com/breez/lspd/master/deploy/lspd-install.sh | sudo bash -```
It will automatically configure your server and install all needed dependencies for running LSPD stack. You will have to manually change the name of your LSPD and your cln alias.
LSPD:
```
vim /home/lspd/.env
# change the name variable in the last line, it will have randomly generated name like "lsp-53v4"
NODES='[ { "name": "${LSPName}"
```
CLN:
```
vim /home/lightning/.lightning/config
# change alias row, it will have randomly generated name like "lsp-53v4"
alias="${LSPName}"
```
### After deployment steps
#### Configure email notifications
Edit file ```/home/lspd/.env```.
1) set your SES credentials:
```
AWS_REGION="<REPLACE ME>"
AWS_ACCESS_KEY_ID="<REPLACE ME>"
AWS_SECRET_ACCESS_KEY="<REPLACE ME>"
```
2) configure email
```
OPENCHANNEL_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
OPENCHANNEL_NOTIFICATION_CC='["REPLACE ME <test@example.com>"]'
OPENCHANNEL_NOTIFICATION_FROM="test@example.com"
CHANNELMISMATCH_NOTIFICATION_TO='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_CC='["REPLACE ME <email@example.com>"]'
CHANNELMISMATCH_NOTIFICATION_FROM="replaceme@example.com"
```
#### Backup credentials
All credentials are generated automatically and are written down in ```/home/lspd/credentials.txt```
**Store them securely and delete the file.**
### Debugging
Log file of deployment is written to ```/tmp/deployment.log``` where you can see the entire output of what happend during deployment.