What is WebLN? Summer of Bitcoin 2022

What is WebLN?

WebLN is a library and set of specifications for lightning apps and client providers to facilitate communication between apps and users’ lightning nodes in a secure way. It provides a programmatic, permissioned interface for letting applications ask users to send payments, generates invoices to receive payments, and much more. This documentation covers both how to use WebLN in your Lightning-driven applications and how to implement a provider.

WebLN Working

Installation

First Way: Install with Package Manager (Preferred)

Install the webln library using your package manager of choice:

  • npm: npm install --save webln
  • yarn: yarn add webln
import { requestProvider } from 'webln';

Second Way: Include Script (Alternative)

Alternatively, you can include a script on your page that will load the library. Be sure to keep the integrity check to prevent malicious Javascript from loading.

<script
src="https://unpkg.com/webln@0.2.0/dist/webln.min.js"
integrity="sha384-mTReBqbhPO7ljQeIoFaD1NYS2KiYMwFJhUNpdwLj+VIuhhjvHQlZ1XpwzAvd93nQ"
crossorigin="anonymous"
></script>

requestProvider

To begin interacting with a user’s Lightning node, you’ll first need to request a WebLNProvider from them. WebLNProvider is a class that various clients implement and attach to your web session. Calling requestProvider will retrieve the provider for you, and prompt the client for permission to use it. Once you get the provider, you're free to call all of the other API methods.

WebLN Provider

WebLN getInfo function

Ask the user for some information about their node. The request may be rejected by the user depending on the provider implementation.

function getInfo(): Promise<GetInfoResponse>;
interface GetInfoResponse = {
node: {
alias: string;
pubkey: string;
color?: string;
};
}

webln.makeInvoice

This is used to create an Invoice for the user by the app. This will return a BOLT-11 invoice. There are many ways to request an invoice they are

  • By specifying an explicit amount, the user's provider should enforce that the user generate an invoice with a specific amount
  • When an explicit amount is not set, the user can return an invoice that has no amount specified, allowing the payment maker to send any amount
  • By specifying a minimumAmount and / or maximumAmount, the user's provider should enforce that the user generate an invoice with an amount field constrained by that amount

Parameters

function makeInvoice(args: RequestInvoiceArgs): Promise<RequestInvoiceResponse>;

interface RequestInvoiceArgs {
amount?: string | number;
defaultAmount?: string | number;
minimumAmount?: string | number;
maximumAmount?: string | number;
defaultMemo?: string;
}

Response

interface RequestInvoiceResponse {
paymentRequest: string;
}

What if there is an error?

To handle this test case both apps and providers can make use of WebLN’s pre-defined errors. They can be found in webln/lib/errors and should be used when throwing and handling errors to best inform the user of what's going on:

WebLN Error
WebLN Error Provider

Resources

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Sanjay Singh Rajpoot

Sanjay Singh Rajpoot

Summer of Bitcoin ’22 • LFX Mentee’22 @mojaglobal • GSoC’21 @ProcessingOrg • Ex-Intern @Disecto • 👨‍💻▪️ Full Stack Developer (MERN) • Tech Blogger