Wrapper for Lightning Network Daemon (lnd). It provides separate accounts with minimum trust for end users.

Overview

LndHub.go

Wrapper for Lightning Network Daemon (lnd). It provides separate accounts with minimum trust for end users.

LndHub compatible API implemented in Go using relational database backends

  • Using a relational database (PostgreSQL and SQLite)
  • Focussing only on Lightning (no onchain functionality)
  • No runtime dependencies (simple Go executable)

Status: WIP

Known Issues

  • Currently no fee handling (users are currently not charged for lightning transaction fees)

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

  • DATABASE_URI: The URI for the database. If you want to use SQLite use for example: file:data.db
  • JWT_SECRET: We use JWT for access tokens. Configure your secret here
  • JWT_EXPIRY: How long the access tokens should be valid (in seconds)
  • LND_ADDRESS: LND gRPC address (with port) (e.g. localhost:10009)
  • LND_MACAROON_HEX: LND macaroon (hex)
  • LND_CERT_HEX: LND certificate (hex)
  • LOG_FILE_PATH: (optional) By default all logs are written to STDOUT. If you want to log to a file provide the log file path here
  • SENTRY_DSN: (optional) Sentry DSN for exception tracking
  • PORT: (default: 3000) Port the app should listen on

Developing

go run main.go

Building

To build an lndhub executable, run the following commands:

make

Database

LndHub.go supports PostgreSQL and SQLite as database backend. But SQLite does not support the same data consistency checks as PostgreSQL.

Ideas

  • Using low level database constraints to prevent data inconsistencies
  • Follow double-entry bookkeeping ideas (Every transaction is a debit of one account and a credit to another one)
  • Support multiple database backends (PostgreSQL for production, SQLite for development and personal/friend setups)

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                           └────────────────────────┘                     
                                                                                                
Issues
  • Investigate 3rd party Authorization flows

    Investigate 3rd party Authorization flows

    It should be possible to give an application or service access to your LNDhub account without giving up the full "admin" lndhub connection string. This kind of Authorization could have "create invoice" access, "read transactions" access or "make payment" access with monthly budgets. The Authorization should be time-scoped and a user should be able to have an overview of linked applications and be able to revoke access.

    opened by kiwiidb 9
  • Feature/event-stream

    Feature/event-stream

    Overview

    I decided to go for Websockets because they were the most robust option that has many client libraries in JS and other languages. I found that for SSE or HTTP response streaming, it was more difficult to find good client-side code examples.

    Based on :

    • https://eli.thegreenplace.net/2020/pubsub-using-channels-in-go/
    • https://echo.labstack.com/cookbook/websocket/

    The pubsub system can also be used by other endpoints or plugins in the future.

    Testing manually

    1. Install wscat: npm i -g wscat
    2. Fetch a token like normal using the /auth endpoint.
    3. Open the websocket wscat -c ws://localhost:3000/invoices/stream\?token=$token

    Integration tests were also added that test multiple scenario, eg. multiple streams for the same user and multiple users having a stream open.

    opened by kiwiidb 9
  • Fee handling

    Fee handling

    Add fixed fee according to issue description and extended tests.

    Tests are failing currently when using lnd1 and lnd2 with rpc error: code = Unknown desc = server is still in the process of starting.

    To add and execute tests I had to configure local polar network and execute using that one, maybe good candidate for future is to have more dynamic configuration for tests, so switch can be easier.

    opened by skosito 9
  • Add webhooks for invoice updates

    Add webhooks for invoice updates

    Webhooks are hard and complex to get right. E.g. we would need to have a system to reply failed webhooks etc.

    There are external services that handle all this complexity for apps: e.g. https://www.svix.com

    We could optionally add support for svix to send webhooks.

    question 
    opened by bumi 7
  • Make it possible to disable account creation

    Make it possible to disable account creation

    This covers the usecase when LndHub is used to serve closed communities which do not want to accept new members anymore (friends, families, etc).

    The PR introduces a new envconfig option CREATE_ACCOUNTS which is true by default but can be set to false if needed.

    opened by prusnak 5
  • Error migrating database on first run with sqlite

    Error migrating database on first run with sqlite

    I am trying to run this locally with sqlite, but i am getting a migration error.

    [email protected]:~/Desktop/lndhub$ ./lndhub-0.7.0-linux-x86_64 
    {"level":"fatal","time":"2022-05-27T19:34:45+02:00","message":"Error migrating database: SQL logic error: unknown database public (1)"}
    

    lndhub-0.7.0-linux-x86_64 is the executable from the latest release but i've tried also to run the main branch and had the same issue.

    This is the .env file

    DATABASE_URI=file:data.db
    LOG_FILE_PATH=
    SENTRY_DSN=
    JWT_SECRET=*************
    JWT_ACCESS_EXPIRY=172800
    JWT_REFRESH_EXPIRY=604800
    LND_ADDRESS=127.0.0.1:10001
    LND_MACAROON_HEX=*************
    LND_CERT_HEX=*************
    FIXED_FEE=10
    

    The data.db file doesn't exist when i run the command, is there maybe something i need to do before to create it?

    opened by riccardobl 5
  • 404 errors (instead of 400 bad auth errors)

    404 errors (instead of 400 bad auth errors)

    Currently all unknown requests lead to a 400 bad auth error. We should make sure that the authentication is only checked for the known routes and have a proper 404 error for unknown routes.

    opened by bumi 5
  • Implement fee-reserve

    Implement fee-reserve

    My shot at fixing/implementing https://github.com/getAlby/lndhub.go/issues/183

    It's rather naive and I am not sure if having the check at one place only is enough.

    Someone with more Go expertise than me should carefully review.

    And yeah, this PR does not contain any tests ... :-/

    opened by prusnak 4
  • Rate limiting & caching middleware.

    Rate limiting & caching middleware.

    For the homepage, we need to have some caching middleware.

    For some critical endpoints, we should have rate-limiting middleware (in-memory, no redis dependency).

    Cfr. Bluewallet: https://github.com/BlueWallet/LndHub/blob/master/controllers/api.js#L138 (search for postLimiter for all the calls that use it).

    enhancement 
    opened by kiwiidb 4
  • deploy canary on new release

    deploy canary on new release

    Like this a new tag (release or tag pushed) will be auto-deployed in production on a seperate, canary deployment lndhub-canary.mainnet.getalby.com. This will allow us to do a test in production without pushing the release out to all users.

    opened by kiwiidb 3
  • always lowercase payreq

    always lowercase payreq

    When testing out Alby and Bluewallet on regtest, I noticed that Bluewallet puts in the invoice uppercase when calling payinvoice. This caused internal Alby payments to fail, as Alby could not find the invoice in the db.

    opened by kiwiidb 3
  • Lnurlp + Auth middleware

    Lnurlp + Auth middleware

    I am pulling a bunch of changes that we need to get the lnurl working. Mostly we need lnurlp and expand the /create route functionality so it accepts further credentials.

    • LNURLP: need a new route so clients can call it and get the proper response. In the response callback param we set /invoice so the LN WALLET will call that route to get the invoice. Hence I needed to modify that route so it does not need credentials (just a valid login/nickname)
    • NICKNAME: Since we will support lightning addresses in the future, I added a unique identifier of a user that, unlike login, could be updated. The way the nickname is updated is calling /create with a valid (and already created) login & password, producing a postgres index collision that updates the nickname. Additionally you can search a user by both login and nickname.
    • CREATEV2: I needed a new way of creating an account that fits our needs, a way that only verifiable peers can do. If the login provided in the /create route is a libp2p CID (we can check that) then the password must be a signature and user must provide the public key of that signature. That's why I introduced a pubkey in the Authorization header so the client signs a message (typically "log in into service bla bla") with its private key and puts the signature as a password in the /create route. It also includes the public key in the authorization header (for those schemas that pubkey cannot be derived from the signature). So the new signature authorization middleware verifies that the signature is valid when the login is a CID. If not, then the extra validation is skipped and everything is as before. The last step in this new validation is validating that the pubkey yields to the login provided.
    • NITS AND IMPROVEMENTS: I have also found various nits and also grow the config variables so it is more flexible to operate the program

    Maybe there are a lot of changes, but I just wanted to pull everything so we can decide if there is anything relevant at all🙂. In that case I can try to isolate those changes

    opened by juligasa 3
  • Add .editorconfig + fix whitespace issues

    Add .editorconfig + fix whitespace issues

    More about EditorConfig: https://editorconfig.org

    Most changes are white-space related, can be reviewed via https://github.com/getAlby/lndhub.go/pull/216/files?&w=1

    opened by prusnak 0
  • Secret API key to enable account creation

    Secret API key to enable account creation

    Idea suggested by @bumi in https://github.com/getAlby/lndhub.go/pull/198#issuecomment-1160353051

    Creating new issue so the idea is not forgotten after https://github.com/getAlby/lndhub.go/pull/198 is merged

    opened by prusnak 0
  • Check PaymentError field in lnd's SendPaymentSync response for errors

    Check PaymentError field in lnd's SendPaymentSync response for errors

    Only for integration tests:

    Apparently it's possible for SendPaymentSync to return a nil error while the payment failed. In this case, PaymentError field of the response was timeout. So we should also check this field and handle the failed payment if there is an error here.

    bug 
    opened by kiwiidb 0
  • Add to Citadel, Umbrel, RaspiBlitz app store

    Add to Citadel, Umbrel, RaspiBlitz app store

    Those nodes OS have appstore. It would be nice to be able to install lndhub there from within the app store. Citadel and Umbrel use Docker, so that should be fairly easy I think. And we can use sqlite by default, so no additional dependency is needed.

    opened by bumi 5
Releases(0.9.0)
  • 0.9.0(Jul 8, 2022)

    What's Changed

    • Don't defer close when the creation failed by @prusnak in https://github.com/getAlby/lndhub.go/pull/192
    • switch to Go 1.17 by @prusnak in https://github.com/getAlby/lndhub.go/pull/196
    • Implement fee-reserve by @prusnak in https://github.com/getAlby/lndhub.go/pull/193
    • Chore/mock lnd by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/197
    • remove all sqlite dependencies and mentions by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/199
    • Chore/v2 api by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/202
    • Make it possible to disable account creation by @prusnak in https://github.com/getAlby/lndhub.go/pull/198
    • Fix makefile by @prusnak in https://github.com/getAlby/lndhub.go/pull/206
    • Introduce MaxReceiveAmount, MaxSendAmount, MaxAccountBalance by @prusnak in https://github.com/getAlby/lndhub.go/pull/200
    • replace username by login by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/207
    • also return user id when generating token by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/208

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.8.0...0.9.0

    Source code(tar.gz)
    Source code(zip)
    lndhub-0.9.0-linux-arm_v7(46.58 MB)
    lndhub-0.9.0-linux-x86_64(50.27 MB)
  • 0.8.0(Jun 10, 2022)

    What's Changed

    • Set cache-control headers for static routes (getinfo and home) by @bumi in https://github.com/getAlby/lndhub.go/pull/170
    • Feature/accept keysend by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/172
    • add user login to webhook payload by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/175
    • Fix: start invoice subscription from last NOT expired invoice by @bumi in https://github.com/getAlby/lndhub.go/pull/177
    • small fixes in readme/env_example by @prusnak in https://github.com/getAlby/lndhub.go/pull/185
    • Extend sentry with some mode debugging information by @bumi in https://github.com/getAlby/lndhub.go/pull/171
    • Fix/keysend-payments by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/187
    • Fix/amt-validations by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/189

    New Contributors

    • @prusnak made their first contribution in https://github.com/getAlby/lndhub.go/pull/185

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.7.0...0.8.0

    Source code(tar.gz)
    Source code(zip)
    lndhub-0.8.0-linux-arm_v7(49.90 MB)
    lndhub-0.8.0-linux-x86_64(54.88 MB)
  • 0.7.0(May 3, 2022)

    What's Changed

    • Log user ids on more errors by @bumi in https://github.com/getAlby/lndhub.go/pull/164
    • Replace math rand with crypto rand by @skosito in https://github.com/getAlby/lndhub.go/pull/152
    • Feature: pay 0 amount invoice by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/168
    • Feature/webhooks by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/162

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.6.2...0.7.0

    Source code(tar.gz)
    Source code(zip)
    lndhub-0.7.0-linux-arm_v7(49.90 MB)
    lndhub-0.7.0-linux-x86_64(54.87 MB)
  • 0.6.2(May 2, 2022)

    What's Changed

    • Add logo and update favicon by @stefanwuest in https://github.com/getAlby/lndhub.go/pull/157
    • fix: add fees for outgoing invoices by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/160
    • Feature/api docs by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/161
    • Fix: 0 amount incoming invoice by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/167

    New Contributors

    • @stefanwuest made their first contribution in https://github.com/getAlby/lndhub.go/pull/157

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.6.1...0.6.2

    Source code(tar.gz)
    Source code(zip)
    lndhub-0.6.2-linux-arm_v7(49.89 MB)
    lndhub-0.6.2-linux-x86_64(54.85 MB)
  • 0.6.1(Apr 22, 2022)

  • 0.6.0(Apr 21, 2022)

  • 0.5.0(Apr 10, 2022)

    What's Changed

    • Dynamic fee limits by @skosito in https://github.com/getAlby/lndhub.go/pull/136
    • add favicon.ico rewrite by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/145
    • Add and use expected requests and responses for integration tests by @skosito in https://github.com/getAlby/lndhub.go/pull/147
    • Feature/metrics by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/142
    • Do not send bad auth errors to sentry by @skosito in https://github.com/getAlby/lndhub.go/pull/146
    • always lowercase payreq by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/149
    • always build docker images on every branch by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/148

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.4.1...0.5.0

    Source code(tar.gz)
    Source code(zip)
    lndhub-0.5.0-linux-arm_v7(30.98 MB)
    lndhub-0.5.0-linux-x86_64(35.72 MB)
  • 0.4.0(Mar 22, 2022)

    What's Changed

    • Rate limiter and cache middleware by @skosito in https://github.com/getAlby/lndhub.go/pull/131
    • Feature/keysend-custom-records by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/133
    • Unauthorized invoice endpoint by @skosito in https://github.com/getAlby/lndhub.go/pull/134
    • add build workflow by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/120

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.3.1...0.4.0

    Source code(tar.gz)
    Source code(zip)
    lndhub-0.4.0-linux-arm_v7(30.07 MB)
    lndhub-0.4.0-linux-x86_64(34.72 MB)
  • 0.3.1(Mar 9, 2022)

  • 0.3.0(Mar 8, 2022)

    What's Changed

    • Use sql for init migration: the initial db migration is now fully being done using sql syntax. By @skosito in https://github.com/getAlby/lndhub.go/pull/115
    • Refresh token support by @skosito in https://github.com/getAlby/lndhub.go/pull/116
    • Fix overload of Sentry notifications: No more notifications on a bad auth error. @skosito in https://github.com/getAlby/lndhub.go/pull/124
    • 🆕 Keysend support! @skosito in https://github.com/getAlby/lndhub.go/pull/127
    • 🆕Fee handling. Users are now charged for transaction fees. Be aware that this could cause a user's balance to go below 0. By @skosito in https://github.com/getAlby/lndhub.go/pull/117

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.2.0...0.3.0

    Source code(tar.gz)
    Source code(zip)
  • 0.2.0(Feb 18, 2022)

    What's Changed

    • Ability to override the node's name by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/86
    • Feature/integration-testing by @kiwiidb and @skosito in https://github.com/getAlby/lndhub.go/pull/87
    • Wrap the LND client so we can more easily switch to alternative node implementations later by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/90
    • Alby branded index page 🐝 by @kiwiidb in https://github.com/getAlby/lndhub.go/pull/94
    • Custom usernames and password when creating new users by @skosito in https://github.com/getAlby/lndhub.go/pull/100
    • Handling of in-transit payments by @skosito in https://github.com/getAlby/lndhub.go/pull/107

    New Contributors

    • @skosito made their first contribution in https://github.com/getAlby/lndhub.go/pull/95

    Full Changelog: https://github.com/getAlby/lndhub.go/compare/0.1.1...0.2.0

    Source code(tar.gz)
    Source code(zip)
Owner
Alby
Versatile browser extension to consume and directly reward content or services online based on Bitcoin/ Lightning
Alby
Zero Trust Network Communication Sentinel provides peer-to-peer, multi-protocol, automatic networking, cross-CDN and other features for network communication.

Thank you for your interest in ZASentinel ZASentinel helps organizations improve information security by providing a better and simpler way to protect

ZTALAB 6 Jul 30, 2022
LNC is a lightning network capital management tool built for routing nodes.

LNC is a lightning network capital management tool built for routing nodes.

LN.capital 5 Dec 21, 2021
fast tool for separate existing domains from list of domains using DNS/HTTP.

NETGREP How To Install • How to use Description netgrep can send http/https request or resolve domain from dns (can customize dns server) to separate

aWolver 2 Jan 27, 2022
Go rate limiter used to ensure a minimum duration between executions.

Ratelimiter Rate limiter used to ensure a minimum duration between executions. Additionally supports the optional limit of max queue size. This can be

Branden 0 Jul 14, 2022
Creates a linux group of users synced to your Google Workspace users and automatically imports their public SSH keys.

Creates a linux group of users synced to your Google Workspace users and automatically imports their public SSH keys.

Dane Tuso 1 Jan 27, 2022
Simple web content/proxy server that embodies enterprise zero trust security

pswa - Protected Static Web App Introduction pswa is a simple web content/proxy server which is suitable for various static web apps. Features Availab

YAEGASHI Takeshi 3 Jan 10, 2022
Aidos Kuneen (v2 network) daemon program that is controlled through the command line and remotely via RPC calls

adk-daemon: aidosd.v2 aidosd (v2) is a deamon which acts as bitcoind for adk. This version has been built specifically for network mesh version 2+ For

Aidos Kuneen 0 Dec 1, 2021
Package socket provides a low-level network connection type which integrates with Go's runtime network poller to provide asynchronous I/O and deadline support. MIT Licensed.

socket Package socket provides a low-level network connection type which integrates with Go's runtime network poller to provide asynchronous I/O and d

Matt Layher 42 Jul 3, 2022
Yet another TCP Port Scanner, but lightning faster.

Fast TCP Port Scanner A highly concurrent TCP port scanner. Run Tests with Code Coverage (Linux) go test -cover Compile (Linux) go build -v -o fglps R

Hysteresis 6 Jul 23, 2022
Serverless Lightning Address server

Addressless Put a Lightning Address "server" on a serverless host like Vercel. The code is heavily borrowed from satdress, minus the federated part. T

Paul Miller 11 Jan 28, 2022
Minimalistic paste daemon written in golang

Minimalistic paste daemon written in golang

Christoph Hoopmann 1 Nov 8, 2021
shoutrrr daemon

shoutrrr daemon Orginal repositories: shoutrrr repository shoutrrr documentation Installation & Configuration Create a services.yaml with the followin

AdriDevelopsThings 1 Dec 12, 2021
Secure Time Sync Daemon

stsd - Secure Time Sync Daemon ============================== Set system date based on HTTP 'date' headers over TLS. Inspired by Whonix's sdwdate, an

null 1 Dec 15, 2021
DNS synchronization daemon for the AIRE project.

dns-sync Database structure: { "name": "example-host.example.com", "content": "127.1.33.7" } ENV parameters: DEBUG: true|false DNS_FILTER: Reg

Neuvo Inc. Global 0 Dec 20, 2021
NDP Proxy + Responder daemon

PNDPD - NDP Responder + Proxy Features Efficiently process incoming packets using bpf (which runs in the kernel) Respond to all NDP solicitations on a

Kioubit 12 Jul 18, 2022
CoreRAD is an extensible and observable IPv6 Neighbor Discovery Protocol router advertisement daemon. Apache 2.0 Licensed.

CoreRAD CoreRAD is an extensible and observable IPv6 Neighbor Discovery Protocol router advertisement daemon. Apache 2.0 Licensed. To get started with

Matt Layher 121 Jul 20, 2022
Go built-in package network address wrapper.

osnet Go built-in package network address wrapper. Installation go get -u github.com/coolstina/osnet functions IsIP: Check whether the IP address is r

coolstina 0 Jan 10, 2022
Magma is an open-source software platform that gives network operators an open, flexible and extendable mobile core network solution.

Connecting the Next Billion People Magma is an open-source software platform that gives network operators an open, flexible and extendable mobile core

Magma 1.3k Jul 31, 2022
Optimize Windows's network/NIC driver settings for NewTek's NDI(Network-Device-Interface).

windows-ndi-optimizer[WIP] Optimize Windows's network/NIC driver settings for NewTek's NDI(Network-Device-Interface). How it works This is batchfile d

Nil Hiiragi 3 Apr 15, 2022