search

getAlby / nostr-wallet-connect-next

Nostr Wallet Connect (NIP-47) application to allow apps to connect to your node
https://nwc.getalby.com
Apache License 2.0
8 stars 3 forks source link

readme

Nostr Wallet Connect (Next)

This is a self-sovereign, self-custodial, single-user rewrite of NWC currently in an experimental phase development. ❗This version is not backwards compatible with NWC - it requires a fresh database and connections to be re-added

This application allows you to control your Lightning node or wallet from any other application that supports NWC. Connect apps like Damus or Amethyst to your node. There are many more available on https://nwc.dev/.

Specification: NIP-47

The application can run in two modes:

Ideally the app runs 24/7 (on a node, VPS or always-online desktop/laptop machine) so it can be connected to a lightning address and receive online payments.

Supported Backends

Installation

Requirements

The application has no runtime dependencies. (simple Go executable).

As data storage SQLite is used.

$ cp .env.example .env
# edit the config for your needs
vim .env

Development

Required Software

Server (HTTP mode)

  1. Create a Lightning Polar setup with two LND nodes and uncomment the Polar LND section in your .env file.

  2. Compile the frontend or run touch frontend/dist/tmp to ensure there are embeddable files available.

  3. go run cmd/http/main.go

React Frontend (HTTP mode)

Go to /frontend

  1. yarn install
  2. yarn dev

Wails (Backend + Frontend)

Make sure to have wails installed and all platform-specific dependencies installed (see wails doctor)

$ wails dev -tags "wails"

If you get a blank screen, try running in your normal terminal (outside of vscode, and make sure HTTP frontend is not running)

Wails Production build

$ wails build -tags "wails"

Build and run locally (HTTP mode)

$ mkdir tmp
$ go build -o main cmd/http/main.go
$ cp main tmp
$ cp .env tmp
$ cd tmp
$ ./main

Run dockerfile locally (HTTP mode)

$ docker build . -t nwc-local --progress=plain
$ docker run -v $(pwd)/.data/docker:/data -e WORK_DIR='/data' -p 8080:8080 nwc-local

Testing

$ go test -race ./...

Test matching regular expression

$ go test -race ./... -run TestHandleGetInfoEvent

Profiling

The application supports both the Go pprof library and the DataDog profiler.

Go pprof

To enable Go pprof, set the GO_PROFILER_ADDR environment variable to the address you want the profiler to be available on (e.g. localhost:6060).

Now, you should be able to access the pprof web interface at http://localhost:6060/debug/pprof.

You can use the go tool pprof command to collect and inspect the profiling data. For example, to profile the application for 30 seconds and then open the pprof web UI, run:

go tool pprof -http=localhost:8081 -seconds=30 http://localhost:6060/debug/pprof/profile

For more information on the Go pprof library, see the official documentation.

DataDog profiler

To enable the DataDog profiler, set the DD_PROFILER_ENABLED environment variable to true.

Make sure to specify the required DataDog configuration environment variables as well.

For more information refer to:

Versioning

$ go run -ldflags="-X 'github.com/getAlby/nostr-wallet-connect/version.Tag=v0.6.0'" cmd/http/main.go

Windows

Breez SDK requires gcc to build the Breez bindings. Run choco install mingw and copy the breez SDK bindings file into the root of this directory (from your go installation directory) as per the Breez SDK instructions. ALSO copy the bindings file into the output directory alongside the .exe in order to run it.

Optional configuration parameters

LND Backend parameters

Currently only LND can be configured via env. Other node types must be configured via the UI.

To configure via env, the following parameters must be provided:

LDK Backend parameters

Testnet

Mutinynet

Alby OAuth

Create an OAuth client at the Alby Developer Portal and set your ALBY_OAUTH_CLIENT_ID and ALBY_OAUTH_CLIENT_SECRET in your .env. If not running locally, you'll also need to change your BASE_URL.

If running the React app locally, OAuth redirects will not work locally if running the react app you will need to manually change the port to 5173. Login in Wails mode is not yet supported

Getting Started with Mutinynet

Follow the steps to integrate Mutinynet with your NWC Next setup:

  1. Configure your environment with the Mutinynet LDK parameters

  2. Proceed as described in the Development section to run the frontend and backend

  3. During onboarding, after setting your password and authorizing via Alby OAuth, you'll be directed to /onboarding/lightning/migrate-alby. Click "Skip For Now" to access your wallet interface

  4. Navigate to channels/onchain/deposit-bitcoin, copy your On-Chain Address, then visit the Mutinynet Faucet to deposit sats. Ensure the transaction confirms on mempool.space

  5. Your On-chain balance will update under /channels

Opening a channel from Mutinynet

  1. To create a channel, use the Mutinynet Faucet by entering your desired Channel Capacity and Amount to Push

  2. Locate your Node ID. In the Wallet click on the status on the top right "online". This shows the node ID or look in the NWC Next logs. Then input this in the Connection String field on the faucet page to request a Lightning Channel

{"level":"info","msg":"Connected to LDK node","nodeId":"<your node ID>","time":"<timestamp>"}
  1. After the transaction confirms, the new channel will appear in the Channels section

Opening a Channel in NWC Next

  1. From the Channels interface (/channels), select "Open a Channel" and opt for "Custom Channel."

  2. Enter the pubkey of the Faucet Lightning Node (omit host and port details) available on the Mutinynet Faucet page.

  3. Specify a channel capacity greater than 25,000 sats, confirm the action, and return to the Channels page to view your newly established channel.

Application deeplink options

/apps/new deeplink options

Clients can use a deeplink to allow the user to add a new connection. Depending on the client this URL has different query options:

NWC created secret

The default option is that the NWC app creates a secret and the user uses the nostr wallet connect URL string to enable the client application.

Query parameter options

Example:

/apps/new?name=myapp

Client created secret

If the client creates the secret the client only needs to share the public key of that secret for authorization. The user authorized that pubkey and no sensitivate data needs to be shared.

Query parameter options for /new

Example:

/apps/new?name=myapp&pubkey=47c5a21...&return_to=https://example.com

Web-flow: client created secret

Web clients can open a new prompt popup to load the authorization page. Once the user has authorized the app connection a nwc:success message is sent to the opening page (using postMessage) to indicate that the connection is authorized. See the initNWC() function in the alby-js-sdk

Example:

import { webln } from "alby-js-sdk";
const nwc = new webln.NWC();
// initNWC opens a prompt with /apps/new?c=myapp&pubkey=xxxx
// the promise resolves once the user has authorized the connection (when the `nwc:success` message is received) and the popup is closed automatically
// the promise rejects if the user cancels by closing the prompt popup
await nwc.initNWC({ name: "myapp" });

Help

If you need help contact support@getalby.com or reach out on Nostr: npub1getal6ykt05fsz5nqu4uld09nfj3y3qxmv8crys4aeut53unfvlqr80nfm You can also visit the chat of our Community on Telegram.

⚡️Donations

Want to support the work on Alby?

Support the Alby team ⚡️hello@getalby.com You can also contribute to our bounty program: ⚡️bounties@getalby.com

NIP-47 Supported Methods

✅ NIP-47 info event

❌ expiration tag in requests

LND

✅ get_info

✅ get_balance

✅ pay_invoice

✅ pay_keysend

✅ make_invoice

✅ lookup_invoice

✅ list_transactions

✅ multi_pay_invoice

✅ multi_pay_keysend

Breez

(Supported methods coming soon)

Node Distributions

Run NWC on your own node!

NOTE: the below links are for the original version of NWC

Deploy it yourself

Digital Ocean

Deploy to DO

Render

Deploy to Render

Fly

Update Fly App

View logs

Main application logs

LDK logs:

Custom Ubuntu VM

Docker

From Alby's Container Registry

Tested on Linux only

docker run -v ~/.local/share/alby-nwc:/data -e WORK_DIR='/data' -p 8080:8080 ghcr.io/getalby/nostr-wallet-connect-next:latest

From Source

Tested on Linux only

docker run -v ~/.local/share/alby-nwc:/data -e WORK_DIR='/data' -p 8080:8080 $(docker build -q .)