Zeus Server is a Lightning Network Point of Sale application for LND, written in Java.
If you are looking for the Mobile App, please visit ZeusLN/zeus.
This chapter will show you how you can quickly start Zeus Server.
You will need:
- Your own LND node (see next chapter)
docker
anddocker-compose
installed on your machine
The Spring Boot backend uses the
LightningJ Java library to connect to a
Lightning Network Daemon (LND) over
gRPC. You will need to set up an LND node with version
0.6.1-beta
or newer.
There are many tutorials out there but we recommend either this (default) or this (docker)
This application is network agnostic, so it does not matter if you are running
testnet
or mainnet
. But of course we strongly recommend to start with
testnet
first!
After the LND node is running and is fully synced to the chain, follow the steps
below. We assume that LND saves its files to ~/.lnd/
. If you changed that
path, adjust the following example paths accordingly.
- Make sure the gRPC port (default
10009
) of the node is open and reachable - Copy the file
~/.lnd/tls.cert
to the folderbackend/src/main/resources/certs
of your local Zeus source checkout location and also name ittls.cert
- Get the hex value of the
invoice.macaroon
and store it somewhere, we'll need this later.
Use this command for example:
xxd -p -c 999 ~/.lnd/data/chain/bitcoin/testnet/invoice.macaroon
- Get the hex value of the
readonly.macaroon
and store it somewhere, we'll need this later.
Use this command for example:
xxd -p -c 999 ~/.lnd/data/chain/bitcoin/testnet/readonly.macaroon
Now you need to configure the application to use the LND node you just set up.
To do this, edit the file application-dev.yml
in the folder backend/src/main/resources/config
and
change the following values:
application:
bitcoin:
# point this to http://<bitcoind-hostname>:8332/rest/chaininfo.json if you have a full node.
# set it to 'disabled' if you don't have a bitcoind full node running.
restUrl: disabled
mail:
send: true
recipient: [email protected]
lnd:
host: localhost
port: 10009
certPath: classpath:/certs/tls.cert
# insert the hex values of the macaroon obtained in the previous step here!
invoiceMacaroonHex: 0201036c.....
readonlyMacaroonHex: 0201036c.....
The most important thing you need to change is to change the hostname/port and to add the hex values for the macaroons that you saved somewhere in the previous step.
This will start the docker images from Docker Hub and mount the configuration file:
docker-compose up
Now you should see the application when opening http://localhost:9000/
in your browser.
To start developing you need to start every component manually:
- Start DB in background:
docker-compose up -d zeus-db
- Start the backend:
cd backend; ../gradlew bootRun
- Start the frontend:
cd frontend; yarn install; yarn start
Now you should see the application when opening http://localhost:9000/
in your browser.
The following modules have been implemented so far:
A classic web shop with a shopping cart and a checkout procedure.
URL: http://host:port/#/shop
A self-order page that only displays a certain number of products that can be ordered by directly paying an invoice that is shown. Available for portrait or landscape display orientation.
URL: http://host:port#/self-service/INVOICE-PREFIX
URL: http://host:port/#/self-service-landscape/INVOICE-PREFIX
A simple donation form that can be embedded as an iframe for example.
URL: http://host:port/#/donate/DONATION-TEXT
Apart from the default JHipster admin pages for health, metrics, configuration and log configuration, there are also two specific interfaces related to the Lightning Network.
URL: http://host:port/#/admin
The default username is admin
and the password is admin
.
A list of all paid and unpaid invoices, can be filtered by type and date.
An admin interface that shows some node statistics and the current open channels with their balances.
We built this application as a template so you can build your own fancy self-order point of sale screen. You can see a demo video of our version here.
The following chapters will guide you through the steps that are necessary to
customize the generic Zeus Server
to your needs.
Invoice processors are invoked after a Lightning Network invoice has been
updated. Usually, this means it has been paid/settled. You can write your
own invoice processor by implementing ApplicationListener<InvoiceEvent>
in
your service.
There is an example ch.puzzle.ln.zeus.service.processors.MailSendOrderProcessor
service that sends out an e-mail whenever an invoice has been paid:
package ch.puzzle.ln.zeus.service.processors;
import ch.puzzle.ln.zeus.service.InvoiceEvent;
import ch.puzzle.ln.zeus.service.MailService;
import ch.puzzle.ln.zeus.service.dto.InvoiceDTO;
import org.springframework.context.ApplicationListener;
import org.springframework.stereotype.Service;
@Service
public class MailSendOrderProcessor implements ApplicationListener<InvoiceEvent> {
private final MailService mailService;
public MailSendOrderProcessor(MailService mailService) {
this.mailService = mailService;
}
@Override
public void onApplicationEvent(InvoiceEvent event) {
InvoiceDTO invoice = event.getInvoice();
// Make sure we only send an e-mail if the invoice has been settled
// for the first time.
if (invoice.isSettled() && event.isFirstSettleEvent()) {
mailService.sendOrderConfirmation(invoice);
}
}
}
You can customize this however you want.
There is a simple generic example self-order store implemented in the web GUI.
To change the products and their price, make sure to edit the following files:
- TODO: config file
To change the way the self-order store looks, edit the following files:
src/main/webapp/app/shop/self-service.component.html
src/main/webapp/app/shop/self-service.component.scss