Skip to content
Spec and client library for WebLN apps and providers
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.gitignore Add rollup to make UMD releases. Jan 19, 2019
README.md Point to new docs Mar 26, 2019
package.json Version 0.2.1 May 20, 2019
rollup.config.js
tsconfig.json
yarn.lock Add rollup to make UMD releases. Jan 19, 2019

README.md

WebLN

This library provides the spec and client libraries for WebLN, a way of interacting with a user's Lightning node via the browser.

Heads up: This spec is in early stages, and is subject to change. Join in the discussion in the issue queue, and please be mindful when building apps with it!

Documentation and Demos

Check out the documentation site at https://webln.dev/

If you'd like to contribute to the documentation, you can find it over at https://github.com/wbobeirne/webln-docs

TL;DR Docs

Installation

For use in node-built projects, install via npm or yarn:

npm install webln
# OR #
yarn add webln

If you don't have a build system, you can add the following script tag to your project which will add all functionality under the global WebLN namespace:

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

Make sure you leave the integrity hash in to prevent possibly malicious JS

Client Library

Apps that want to enable WebLN interactions can use the requestProvider function to grab a WebLN provider:

import { requestProvider } from 'webln';

let webln;
try {
  webln = await requestProvider();
} catch (err) {
  // Handle users without WebLN
}

// Elsewhere in the code...
if (webln) {
  // Call webln functions
}

WebLN Provider

Providers are classes that implement the interface provided in webln/lib/provider. The spec is as follows:

export interface WebLNProvider {
  /* Determines if the WebLNProvider will allow the page to use it */
  enable(): Promise<void>;

  /* Returns some basic information about the node */
  getInfo(): Promise<GetInfoResponse>;

  /* Prompts the user with a BOLT-11 payment request */
  sendPayment(paymentRequest: string): Promise<SendPaymentResponse>;

  /* Prompts the user to provide the page with an invoice */
  makeInvoice(amount: string | number | RequestInvoiceArgs): Promise<RequestInvoiceResponse>;

  /* Prompts the user to sign a message with their private key */
  signMessage(message: string): Promise<SignMessageResponse>;

  /* Shows the user a view that verifies a signed message */
  verifyMessage(signature: string, message: string): Promise<void>;
}

See the typescript definitions for more detail about request objects and response shapes. The spec is far from complete, and will need more functions to be fully-fledged, but these methods should cover most use-cases.

Errors

Both apps and providers will want to 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:

// For example, an app should check if an uncommon method isn't supported,
// and let the user know what to do.
import { requestProvider } from 'webln';
import { UnsupportedMethodError } from 'webln/lib/errors';

async function signMsg(msg: string) {
  try {
    const webln = await requestProvider();
    const res = await webln.signMessage(msg);
    return res;
  } catch(err) {
    if (err.constructor === UnsupportedMethodError) {
      alert('Your WebLN provider doesn’t support message signing, please email support@app.com for manual verification');
    } else {
      alert(err.message);
    }
  }

And the provider should throw the correct error when possible:

// And a provider should correctly throw this error
import { WebLNProvider } from 'webln';
import { UnsupportedMethodError } from 'webln/lib/errors';

class MyProvider extends WebLNProvider {
  signMessage() {
    throw new UnsupportedMethodError('MyProvider doesn’t support message signatures!');
  }
}

See the full list of error types for more information.

Contributing

Please join the issue queue to discuss the future of the WebLN spec.

You can’t perform that action at this time.