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!
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
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/[email protected]/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
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
}
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.
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 [email protected] 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.
Please join the issue queue to discuss the future of the WebLN spec.