Introduction

Welcome - this is how Nostr Wallet Connect works

NWC describes a way for client apps to access a remote bitcoin lightning wallet through a standardized protocol. Wallets and apps want to implement this to allow users to seamlessly connect their own wallet accounts for native payments in apps.

NWC overview

Example pay_invoice flow

1. The user scans the QR code generated by the wallet service with their client application, they follow a nostr+walletconnect: deeplink or configure the connection details manually. The step to setup a connection only happens once.

2. The client app receives an invoice which can happen from various sources such NWC itstelf or LNURL.

3. The client app sends an event to the wallet service via a relay. The content is a pay_invoice request. The private key is the secret from the connection string above.

5. The wallet service verifies that the author's key is authorized to perform the payment, decrypts the payload and sends the payment.

6. The wallet service responds to the event by sending a specific event and content as a response either containing an error message or a preimage.

Using a dedicated relay

The app and the wallet can interact with one another across the relay bridge once the session is initialized. Relays provide a reliable and efficient way to communicate with lightning nodes without the use of TOR or exposing nodes on clearnet.

If the user wishes to perform an action (e.g. pay_invoice) the transactions are prepared by the app frontend, serialized and encrypted, and then written to the relay. The wallet reads the message from the relay, decrypts it, unpacks the transaction, presents it to the wallet user for signing or auto-executes the action. In that way the relay only facilitates the communication but the request itself is encrypted and cannot be read by the relay.