Introduction to NWC

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 - a free and open protocol

NWC is a free and open protocol. This is a crucial property, because it creates several benefits:

1. NWC can be used by anyone.

2. Implementing payments based on NWC avoids vendor lock-in.

3. NWC offers a higher degree of flexibility, with more integration options between existing and new apps.

Apps that adopt NWC enhance their accessibility and innovation. Most importantly you ensure interoperability with the ecosystem and capitalize on network effects of your ecosystem.

NWC builds on bitcoin's lightning network

Bitcoin is a decentralized digital currency that enables peer-to-peer transactions without the need for banks or intermediaries. The lightning network comes in as a second-layer protocol that enables instant, low-fee payments by routing transactions off-chain while maintaining bitcoin’s security guarantees. Together, bitcoin and the lightning network provide a powerful foundation for a global, open financial system that’s fast, borderless, and permissionless. It's a match made in heaven and therefore the payment protocol of choice for NWC.

Please note, NWC only describes how payment intents are exchanged between apps and wallets. NWC can support any payment network. In fact, there are proposals for bitcoin on-chain transactions or multi-currency payments.

Why is it called Nostr Wallet Connect?

As stated in the beginning NWC describes a way for apps to connect with wallets, hence the name of the protocol. Nostr is part of NWC as the underlying enabling technology. Nostr itself is a simple, open protocol that enables censorship-resistant, decentralized communication flows—built on public-key cryptography and message relays. It does not rely on central servers or gatekeepers. NWC uses Nostr's relay technology and public-key cryptography to securely exchange information between apps and wallets.

As a end-user of an NWC-enabled wallet, you don't need to know anything about the underlying relay technology or own your own Nostr key. Same as your email provider today that abstracts away SMTP, your wallet and the connected app handles the information exchange.

How a Payment Works (Big Picture)

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.

How a Payment Works (Step-by-Step)

NWC overview

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.

4. The relay forwards the pay_invoice request to the wallet service.

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.