https://github.com/joule-labs/webln

Spec and client library for WebLN apps and providers
https://github.com/joule-labs/webln

lightning lightning-network webln

Last synced: about 1 month ago
JSON representation

Spec and client library for WebLN apps and providers

• Host: GitHub
• URL: https://github.com/joule-labs/webln
• Owner: joule-labs
• Created: 2018-10-26T14:41:07.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2023-07-11T16:31:18.000Z (over 1 year ago)
• Last Synced: 2024-08-06T01:18:52.253Z (4 months ago)
• Topics: lightning, lightning-network, webln
• Language: TypeScript
• Size: 91.8 KB
• Stars: 244
• Watchers: 21
• Forks: 28
• Open Issues: 22
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• awesome-lightning-network - webln - An app library & set of standards for communication between apps and Lightning clients in the browser (similar to Web3) (Developer Resources / Libraries)

README

        
# 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:

```bash

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:

```html

```

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:

```ts

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:

```ts

export interface WebLNProvider {

  /* Determines if the WebLNProvider will allow the page to use it */

  enable(): Promise;

  /* Returns some basic information about the node */

  getInfo(): Promise;

  /* Prompts the user with a BOLT-11 payment request */

  sendPayment(paymentRequest: string): Promise;

  /* Sends a keysend payment to a node without needing an invoice */

  keysend(args: KeysendArgs): Promise;

  /* Prompts the user to provide the page with an invoice */

  makeInvoice(

    amount: string | number | RequestInvoiceArgs

  ): Promise;

  /* Prompts the user to sign a message with their private key */

  signMessage(message: string): Promise;

  /* Shows the user a view that verifies a signed message */

  verifyMessage(signature: string, message: string): Promise;

}

```

See the [typescript definitions](https://github.com/wbobeirne/webln/blob/master/src/provider.ts)

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:

```ts

// 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 [email protected] for manual verification');

    } else {

      alert(err.message);

    }

  }

```

And the provider should throw the correct error when possible:

```ts

// 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](https://github.com/wbobeirne/webln/blob/master/src/errors.ts)

for more information.

## Contributing

Please [join the issue queue](https://github.com/wbobeirne/webln/issues) to

discuss the future of the WebLN spec.