webln
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.0 • Public • Published

    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.3.0/dist/webln.min.js"
      integrity="sha384-g4CABMESGmsa44I6J+t/4fY3DYGpbl8EjqX4L8g6rmD0RLjVinenmzEDqSH3f1QV"
      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>;
    
      /* Sends a keysend payment to a node without needing an invoice */
      keysend(args: KeysendArgs): 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.

    Keywords

    none

    Install

    npm i webln

    DownloadsWeekly Downloads

    757

    Version

    0.3.0

    License

    MIT

    Unpacked Size

    24.9 kB

    Total Files

    12

    Last publish

    Collaborators

    • wbobeirne