Lnurl-pay

Client library for lnurl-pay and lightning address

Installation

Install the package with:

npm i lnurl-pay
# or
yarn add lnurl-pay

Usage

LNURL

import { requestInvoice, utils } from 'lnurl-pay'

const {
  invoice,
  params,
  rawData,
  successAction,
  hasValidAmount,
  hasValidDescriptionHash,
  validatePreimage,
} = await requestInvoice({
  lnUrlOrAddress:
    'lnurl1dp68gurn8ghj7urp0yh8xarpva5kueewvaskcmme9e5k7tewwajkcmpdddhx7amw9akxuatjd3cz7atnv4erqgfuvv5',
  tokens: 333, // in TS you can use utils.checkedToSats or utils.toSats
})

Lightning Address

import { requestInvoice, utils } from 'lnurl-pay'

const {
  invoice,
  params,
  rawData,
  successAction,
  hasValidAmount,
  hasValidDescriptionHash,
  validatePreimage,
} = await requestInvoice({
  lnUrlOrAddress: 'user@domain.com',
  tokens: 333, // in TS you can use utils.checkedToSats or utils.toSats
})

Lnurlp / LUD-17

import { requestInvoice, utils } from 'lnurl-pay'

const {
  invoice,
  params,
  rawData,
  successAction,
  hasValidAmount,
  hasValidDescriptionHash,
  validatePreimage,
} = await requestInvoice({
  lnUrlOrAddress: 'lnurlp://domain.com/path',
  tokens: 333, // in TS you can use utils.checkedToSats or utils.toSats
})

Methods

• requestInvoice - Request an invoice for lnurl o lightning address
• requestPayServiceParams - Request pay service params (1st step)
• requestInvoiceWithServiceParams - Request an invoice for lnurl o lightning address with the given service params (2nd step)

requestInvoice

Request an invoice for lnurl o lightning address

{
  lnUrlOrAddress: <Bech32 encoded url (lnurl) or lightning address String>
  tokens: <Amount in satoshis Number>
  [comment]: <Comment String>
  [onionAllowed]: <Onion url allowed Bool> // Default to false
  [validateInvoice]: <If true validates the invoice amount and description hash Bool> // Default to false
  [fetchGet]: <Function to make a GET request Function> // Default to axios get
}

@throws <Error>

@returns
{
  invoice: <Invoice returned by pay service String>
  successAction: <Success action defined by lnurl-rfc Object>
  params: {
    callback: <Url used to request the invoice String>
    fixed: <Indicates if amount must be a fixed amount Bool>
    min: <Min amount in satoshis Number>
    max: <Max amount in satoshis Number>
    domain: <Callback domain String>
    metadata: <Decoded metadata Array>
    metadataHash: <Metadata hash String>
    identifier: <Metadata identifier String>
    description: <Metadata description String>
    image: <Metadata base64 image String>
    commentAllowed: <Number of characters accepted for the comment query parameter Number> // Default to 0 - not allowed
  }
  rawData: <Raw data response Object>
  hasValidAmount: <True if the returned invoice amount is equal to tokens param Bool>
  hasValidDescriptionHash: <True if the returned invoice description hash is equal to metadata hash Bool>
  validatePreimage: <validates if preimage param is valid for invoice Function> // (preimage: string) => boolean
}

Example:

const { invoice, params, successAction } = await requestInvoice({
  lnUrlOrAddress:
    'lnurl1dp68gurn8ghj7urp0yh8xarpva5kueewvaskcmme9e5k7tewwajkcmpdddhx7amw9akxuatjd3cz7atnv4erqgfuvv5',
  tokens: 333,
})

requestPayServiceParams

Request pay service params for lnurl o lightning address (1st step)

{
  lnUrlOrAddress: <Bech32 encoded url (lnurl) or lightning address String>
  [onionAllowed]: <Onion url allowed Bool> // Default to false
  [fetchGet]: <Function to make a GET request Function> // Default to axios get
}

@throws <Error>

@returns
{
  callback: <Url used to request the invoice String>
  fixed: <Indicates if amount must be a fixed amount Bool>
  min: <Min amount in satoshis Number>
  max: <Max amount in satoshis Number>
  domain: <Callback domain String>
  metadata: <Decoded metadata Array>
  metadataHash: <Metadata hash String>
  identifier: <Metadata identifier String>
  description: <Metadata description String>
  image: <Metadata base64 image String>
  commentAllowed: <Number of characters accepted for the comment query parameter Number> // Default to 0 - not allowed
}

Example:

const params = await requestPayServiceParams({
  lnUrlOrAddress:
    'lnurl1dp68gurn8ghj7urp0yh8xarpva5kueewvaskcmme9e5k7tewwajkcmpdddhx7amw9akxuatjd3cz7atnv4erqgfuvv5',
})

requestInvoiceWithServiceParams

Request an invoice for lnurl o lightning address with the given service params (2nd step)

{
  params: {
    callback: <Url used to request the invoice String>
    fixed: <Indicates if amount must be a fixed amount Bool>
    min: <Min amount in satoshis Number>
    max: <Max amount in satoshis Number>
    domain: <Callback domain String>
    metadata: <Decoded metadata Array>
    metadataHash: <Metadata hash String>
    identifier: <Metadata identifier String>
    description: <Metadata description String>
    image: <Metadata base64 image String>
    commentAllowed: <Number of characters accepted for the comment query parameter Number> // Default to 0 - not allowed
  }
  tokens: <Amount in satoshis Number>
  [comment]: <Comment String>
  [onionAllowed]: <Onion url allowed Bool> // Default to false
  [validateInvoice]: <If true validates the invoice amount and description hash Bool> // Default to false
  [fetchGet]: <Function to make a GET request Function> // Default to axios get
}

@throws <Error>

@returns
{
  invoice: <Invoice returned by pay service String>
  successAction: <Success action defined by lnurl-rfc Object>
  params: {
    callback: <Url used to request the invoice String>
    fixed: <Indicates if amount must be a fixed amount Bool>
    min: <Min amount in satoshis Number>
    max: <Max amount in satoshis Number>
    domain: <Callback domain String>
    metadata: <Decoded metadata Array>
    metadataHash: <Metadata hash String>
    identifier: <Metadata identifier String>
    description: <Metadata description String>
    image: <Metadata base64 image String>
    commentAllowed: <Number of characters accepted for the comment query parameter Number> // Default to 0 - not allowed
  }
  hasValidAmount: <True if the returned invoice amount is equal to tokens param>
  hasValidDescriptionHash: <True if the returned invoice description hash is equal to metadata hash>
  validatePreimage: <validates if preimage param is valid for invoice Function> // (preimage: string) => boolean
}

Example:

const params = await requestInvoiceWithServiceParams({
  params,
  tokens: 333,
})

Utils

• decodeUrlOrAddress - Decode a bech32 encoded url (lnurl) or lightning address and return a url
• isLnurl - Verify if a string is a valid lnurl value
• isLnurlp - Verify if a string is a valid lnurlp url
• parseLnUrl - Parse an url and return a bech32 encoded url (lnurl)
• parseLnurlp - Parse a lnurlp url and return an url with the proper protocol
• isLightningAddress - Verify if a string is a lightning adress
• parseLightningAddress - Parse an address and return username and domain
• isOnionUrl - Verify if a string is an onion url
• getHashFromInvoice - Decodes an invoice(string) and get the hash
• isValidPreimage - Returns true if the given preimage is valid for invoice
• decipherAES - Decipher ciphertext with a preimage

Test

Test with Jest framework:

yarn test

Build

Build production (distribution) files in dist folder:

yarn build

It generates CommonJS (in dist/cjs folder), ES Modules (in dist/esm folder), bundled and minified UMD (in dist/umd folder), as well as TypeScript declaration files (in dist/types folder).

Local development

Run:

yarn link
# or
npm link

and in your test project run:

yarn link lnurl-pay
# or
npm link lnurl-pay

If you want to remove the symlink, run:

# in your test project
yarn unlink lnurl-pay
# or
npm unlink lnurl-pay

# in lnurl-pay folder
yarn unlink
# or
npm unlink

Please check more details in npm link or yarn link

References

This library was developed based on:

• lnurl-rfc
• js-lnurl
• Lightning Address
• BlueWallet
• Example TypeScript Package