Skip to content

Latest commit

 

History

History
237 lines (185 loc) · 6.45 KB

README.md

File metadata and controls

237 lines (185 loc) · 6.45 KB
Raw

Lnurl-withdraw

Client library for lnurl-withdraw

Installation

Install the package with:

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

Usage

LNURL

import { requestPayment } from 'lnurl-withdraw'

const { sent, params, invoice, hasValidAmount, hasValidDescription } =
  await requestPayment({
    lnUrl:
      'lnurl1dp68gurn8ghj7amfw35xgunpwuh8xarpva5kueewvaskcmme9e5k7tewwajkcmpdddhx7amw9akxuatjd3mj7ar9wd6xjmn8jx0750',
    invoice: 'lntbs21210n1p3...lqpf9vcjt',
    validateInvoice: true,
  })

Methods

requestPayment

Request a payment to a lnurl service

{
  lnUrl: <Bech32 encoded url (lnurl) String>
  invoice: <Invoice to be paid String>
  [validateInvoice]: <True if invoice amount and description should be validated Bool> // Default to false
  [onionAllowed]: <Onion url allowed Bool> // Default to false
  [fetchGet]: <Function to make a GET request Function> // Default to axios get
}

@throws <Error>

@returns
{
  sent: <True if returned status is OK Bool>
  invoice: <Invoice param String>
  hasValidAmount: <True if the invoice amount is a valid amount according to returned min and max values Bool>
  hasValidDescription: <True if the invoice description is equal to service returned description Bool>
  params: {
    callback: <Url used to request the invoice payment String>
    k1: <Random or non-random string to identify the user's LN WALLET String>
    invoiceDescription: <Default invoice description String>
    min: <Min amount in satoshis Number>
    max: <Max amount in satoshis Number>
    fixed: <Indicates if amount must be a fixed amount Bool>
    domain: <Callback domain String>
    rawData: <Raw data returned by service Object>
  }
}

Example:

const { sent, params, invoice, hasValidAmount, hasValidDescription } =
  await requestPayment({
    lnUrl:
      'lnurl1dp68gurn8ghj7amfw35xgunpwuh8xarpva5kueewvaskcmme9e5k7tewwajkcmpdddhx7amw9akxuatjd3mj7ar9wd6xjmn8jx0750',
    invoice: 'lntbs21210n1p3...lqpf9vcjt',
    validateInvoice: true,
  })

requestWithdrawServiceParams

Request withdraw service params (1st step)

{
  lnUrl: <Bech32 encoded url (lnurl) 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 payment String>
  k1: <Random or non-random string to identify the user's LN WALLET String>
  invoiceDescription: <Default invoice description String>
  min: <Min amount in satoshis Number>
  max: <Max amount in satoshis Number>
  fixed: <Indicates if amount must be a fixed amount Bool>
  domain: <Callback domain String>
  rawData: <Raw data returned by service Object>
}

Example:

const params = await requestWithdrawServiceParams({
  lnUrl:
    'lnurl1dp68gurn8ghj7amfw35xgunpwuh8xarpva5kueewvaskcmme9e5k7tewwajkcmpdddhx7amw9akxuatjd3mj7ar9wd6xjmn8jx0750',
})

requestPaymentWithServiceParams

Request a payment to a lnurl with the given invoice and service params (2nd step)

{
  params: {
    callback: <Url used to request the invoice payment String>
    k1: <Random or non-random string to identify the user's LN WALLET String>
    invoiceDescription: <Default invoice description String>
    min: <Min amount in satoshis Number>
    max: <Max amount in satoshis Number>
    fixed: <Indicates if amount must be a fixed amount Bool>
    domain: <Callback domain String>
    rawData: <Raw data returned by service Object>
  }
  invoice: <Invoice to be paid String>
  [validateInvoice]: <True if invoice amount and description should be validated Bool> // Default to false
  [onionAllowed]: <Onion url allowed Bool> // Default to false
  [fetchGet]: <Function to make a GET request Function> // Default to axios get
}

@throws <Error>

@returns
{
  sent: <True if returned status is OK Bool>
  invoice: <Invoice param String>
  hasValidAmount: <True if the invoice amount is a valid amount according to returned min and max values Bool>
  hasValidDescription: <True if the invoice description is equal to service returned description Bool>
  params: {
    callback: <Url used to request the invoice payment String>
    k1: <Random or non-random string to identify the user's LN WALLET String>
    invoiceDescription: <Default invoice description String>
    min: <Min amount in satoshis Number>
    max: <Max amount in satoshis Number>
    fixed: <Indicates if amount must be a fixed amount Bool>
    domain: <Callback domain String>
    rawData: <Raw data returned by service Object>
  }
}

Example:

const params = await requestPaymentWithServiceParams({
  params,
  invoice: 'lntbs21210n1p3...lqpf9vcjt',
  validateInvoice: true,
})

Utils

  • decodeUrl - Decode a bech32 encoded url (lnurl) and return a url
  • isLnurl - Verify if a string is a valid lnurl value
  • parseLnUrl - Parse an url and return a bech32 encoded url (lnurl)
  • isOnionUrl - Verify if a string is an onion url

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-withdraw
# or
npm link lnurl-withdraw

If you want to remove the symlink, run:

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

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

Please check more details in npm link or yarn link

References

This library was developed based on: