Home

Awesome

LndHub.go

LndHub.go

Wrapper for Lightning Network Daemon (lnd) ⚡

It provides separate accounts for end users. Live deployment at ln.getalby.com. API documentation

LndHub compatible API implemented in Go using relational database backends

Configuration

All required configuration is done with environment variables and a .env file can be used. Check the .env_example for an example.

cp .env_example .env
vim .env # edit your config

Available configuration

Macaroon

There are two ways how to obtain hex-encoded macaroon needed for LND_MACAROON_HEX.

Either you hex-encode the admin.macaroon:

xxd -p -c 1000 ~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon

Or you bake a new macaroon with the following permissions and use that instead:

lncli bakemacaroon info:read invoices:read invoices:write offchain:read offchain:write

If you want to use a macaroon stored on a filesystem, you either set LND_MACAROON_FILE to a path pointing to admin.macaroon or use the following command to generate the lndhub.macaroon and setting the variable to path of that file.

lncli bakemacaroon --save_to=lndhub.macaroon info:read invoices:read invoices:write offchain:read offchain:write

Developing

To run the server

go run cmd/server/main.go

Building

To build an lndhub executable, run the following commands:

make

Development LND setup

To run your own local lightning network and LND you can use Lightning Polar which helps you to spin up local LND instances.

Alternatively you can also use the Alby simnetwork

Database

LndHub.go requires a PostgreSQL database backend.

Prometheus

Prometheus metrics can be optionally exposed through the ENABLE_PROMETHEUS environment variable. For an example dashboard, see https://grafana.com/grafana/dashboards/10913.

Webhooks

If WEBHOOK_URL is specified, a http POST request will be dispatched at that location when an incoming payment is settled, or an outgoing payment is completed. Example payload:

{
  "id": 721,
  "type": "incoming", //incoming, outgoing
  "user_id": 299,
  "amount": 1000,
  "fee": 0,
  "memo": "fill wallet",
  "description_hash": "",
  "payment_request": "lnbcrt10u1p38p4ehpp5xp07pda02vk40wxd9gyrene8qzheucz7ast435u9jwxejs6f0v5sdqjve5kcmpqwaskcmr9wscqzpgxqyz5vqsp56nyve3v5fw306j74nmewv7t5ey3aer2khjrrwznh4k2vuw44unzq9qyyssqv2wq9hn7a39x8cvz9fvpzul87u4kc4edf0t6jukzvmx8v5swl3jqg8p3sh6czkepczcjkm523q9x8yswsastctnsns3q9d26szu703gpwh7a09",
  "destination_pubkey_hex": "0376442c750766d5d127512609a5618d9aa82db2d06aae226084da92a3e133acda",
  "custom_records": {
    "5482373484": "YWY4MDhlZDUxZjNmY2YxNWMxYWI3MmM3ODVhNWI1MDE="
  }, //only set when keysend=true
  "r_hash": "305fe0b7af532d57b8cd2a083ccf2700af9e605eec1758d385938d9943497b29",
  "preimage": "3735363531303032626332356439376136643461326434336335626434653035",
  "keysend": false,
  "state": "settled",
  "created_at": "2022-05-03T09:18:15.15774+02:00",
  "expires_at": "2022-05-04T09:18:15.157597+02:00",
  "updated_at": "2022-05-03T09:18:19.837567+02:00",
  "settled_at": "2022-05-03T09:18:19+02:00"
}

Keysend

Both incoming and outgoing keysend payments are supported. For outgoing keysend payments, check out the API documentation.

For incoming keysend payments, we are using a custom TLV record with type 696969, which should contain the hex-encoded login of the receiving user's account. TLV records are stored as json blobs with the invoices and are returned by the /getuserinvoices endpoint.

The V2 API has an endpoint to make multiple keysend payments with 1 request, which can be useful for splitting value4value payments.

Ideas

Data model

                                              ┌─────────────┐
                                              │    User     │
                                              └─────────────┘
                                                     │
                           ┌─────────────────┬───────┴─────────┬─────────────────┐
                           ▼                 ▼                 ▼                 ▼
Accounts:          ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
                   │   Incoming   │  │   Current    │  │   Outgoing   │  │     Fees     │
Every user has     └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘
four accounts

                    Every Transaction Entry is associated to one debit account and one
                                             credit account

                                          ┌────────────────────────┐
                                          │Transaction Entry       │
                                          │                        │
                                          │+ user_id               │
            ┌────────────┐                │+ invoice_id            │
            │  Invoice   │────────────────▶+ debit_account_id      │
            └────────────┘                │+ credit_account_id     │
                                          │+ amount                │
           Invoice holds the              │+ ...                   │
           lightning related              │                        │
           data                           └────────────────────────┘