Skip to main content

LNURL implementation for Python.

Project description

LNURL implementation for Python

github-tests-badge github-mypy-badge codecov-badge pypi-badge pypi-versions-badge license-badge

A collection of helpers for building [LNURL][lnurl] support into wallets and services.

LUDS support

Check out the LUDS repository: luds

  • LUD-01 - Base LNURL encoding and decoding
  • LUD-02 - channelRequest base spec
  • LUD-03 - withdrawRequest base spec
  • LUD-04 - Auth base spec
  • LUD-05 - BIP32-based seed generation for auth protocol
  • LUD-06 - payRequest base spec
  • LUD-07 - hostedChannelRequest base spec
  • LUD-08 - Fast withdrawRequest
  • LUD-09 - successAction field for payRequest
  • LUD-10 - aes success action in payRequest
  • LUD-11 - Disposable and storeable payRequests
  • LUD-12 - Comments in payRequest
  • LUD-13 - signMessage-based seed generation for auth protocol
  • LUD-14 - balanceCheck: reusable withdrawRequests
  • LUD-15 - balanceNotify: services hurrying up the withdraw process
  • LUD-16 - Paying to static internet identifiers
  • LUD-17 - Scheme prefixes and raw (non bech32-encoded) URLs
  • LUD-18 - Payer identity in payRequest protocol
  • LUD-19 - Pay link discoverable from withdraw link
  • LUD-20 - Long payment description for pay protocol
  • LUD-21 - verify LNURL-pay payments

Configuration

Developers can force strict RFC3986 validation for the URLs that the library encodes/decodes, using this env var:

LNURL_STRICT_RFC3986 = "0" by default (False)

Basic usage

>>> import lnurl
>>> lnurl.encode('https://service.io/?q=3fc3645b439ce8e7')
Lnurl('LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9', bech32=Bech32('LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9', hrp='lnurl', data=[13, 1, 26, 7, 8, 28, 3, 19, 7, 8, 23, 18, 30, 28, 27, 5, 14, 9, 27, 6, 18, 24, 27, 5, 5, 25, 20, 22, 30, 11, 25, 31, 14, 4, 30, 19, 6, 25, 19, 3, 6, 12, 27, 3, 8, 13, 11, 2, 6, 16, 25, 19, 18, 24, 27, 5, 7, 1, 18, 19, 14]), url=WebUrl('https://service.io/?q=3fc3645b439ce8e7', scheme='https', host='service.io', tld='io', host_type='domain', path='/', query='q=3fc3645b439ce8e7'))
>>> lnurl.decode('LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9')
WebUrl('https://service.io/?q=3fc3645b439ce8e7', scheme='https', host='service.io', tld='io', host_type='domain', path='/', query='q=3fc3645b439ce8e7')

The Lnurl object wraps a bech32 LNURL to provide some extra utilities.

from lnurl import Lnurl

lnurl = Lnurl("LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9")
lnurl.bech32  # "LNURL1DP68GURN8GHJ7UM9WFMXJCM99E5K7TELWY7NXENRXVMRGDTZXSENJCM98PJNWXQ96S9"
lnurl.bech32.hrp  # "lnurl"
lnurl.url  # "https://service.io/?q=3fc3645b439ce8e7"
lnurl.url.host  # "service.io"
lnurl.url.base  # "https://service.io/"
lnurl.url.query  # "q=3fc3645b439ce8e7"
lnurl.url.query_params  # {"q": "3fc3645b439ce8e7"}

Parsing LNURL responses

You can use a LnurlResponse to wrap responses you get from a LNURL. The different types of responses defined in the [LNURL spec][lnurl-spec] have a different model with different properties (see models.py):

import httpx

from lnurl import Lnurl, LnurlResponse

lnurl = Lnurl('LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94MKJARGV3EXZAELWDJHXUMFDAHR6WFHXQERSVPCA649RV')
try:
  async with httpx.AsyncClient() as client:
    r = await client.get(lnurl.url)
    res = LnurlResponse.from_dict(r.json())  # LnurlPayResponse
    res.ok  # bool
    res.max_sendable  # int
    res.max_sats  # int
    res.callback.base  # str
    res.callback.query_params # dict
    res.metadata  # str
    res.metadata.list()  # list
    res.metadata.text  # str
    res.metadata.images  # list
r = requests.get(lnurl.url)

If you have already httpx installed, you can also use the .handle() function directly. It will return the appropriate response for a LNURL.

>>> import lnurl
>>> lnurl.handle('lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94CXZ7FLWDJHXUMFDAHR6V33XCUNSVE38QV6UF')
LnurlPayResponse(tag='payRequest', callback=WebUrl('https://lnurl.bigsun.xyz/lnurl-pay/callback/2169831', scheme='https', host='lnurl.bigsun.xyz', tld='xyz', host_type='domain', path='/lnurl-pay/callback/2169831'), min_sendable=10000, max_sendable=10000, metadata=LnurlPayMetadata('[["text/plain","NgHaEyaZNDnW iI DsFYdkI"],["image/png;base64","iVBOR...uQmCC"]]'))

You can execute and LNURL with either payRequest, withdrawRequest or login tag using the execute function.

>>> import lnurl
>>> lnurl.execute('lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNZD9NHXATW9EU8J730D3H82UNV94CXZ7FLWDJHXUMFDAHR6V33XCUNSVE38QV6UF', 100000)

Building your own LNURL responses

For LNURL services, the lnurl package can be used to build valid responses.

from lnurl import LnurlWithdrawResponse

res = LnurlWithdrawResponse(
    callback="https://lnurl.bigsun.xyz/lnurl-withdraw/callback/9702808",
    k1="38d304051c1b76dcd8c5ee17ee15ff0ebc02090c0afbc6c98100adfa3f920874",
    min_withdrawable=551000,
    max_withdrawable=551000,
    default_description="sample withdraw",
)
res.json()  # str
res.dict()  # dict

All responses are [pydantic][pydantic] models, so the information you provide will be validated and you have access to .json() and .dict() methods to export the data.

Data is exported using :camel: camelCase keys by default, as per spec. You can also use camelCases when you parse the data, and it will be converted to snake_case to make your Python code nicer.

If you want to export the data using :snake: snake_case (in your Python code, for example), you can change the by_alias parameter: res.dict(by_alias=False) (it is True by default).

CLI

$ poetry run lnurl
Usage: lnurl [OPTIONS] COMMAND [ARGS]...

  Python CLI for LNURL decode and encode lnurls

Options:
  --help  Show this message and exit.

Commands:
  decode           decode a LNURL
  encode           encode a URL
  handle           handle a LNURL
  execute          execute a LNURL

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lnurl-0.6.4.tar.gz (16.8 kB view details)

Uploaded Source

Built Distribution

lnurl-0.6.4-py3-none-any.whl (17.1 kB view details)

Uploaded Python 3

File details

Details for the file lnurl-0.6.4.tar.gz.

File metadata

  • Download URL: lnurl-0.6.4.tar.gz
  • Upload date:
  • Size: 16.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.11.0 Linux/6.11.0-1015-azure

File hashes

Hashes for lnurl-0.6.4.tar.gz
Algorithm Hash digest
SHA256 e768a5b475fdb315b339b175c851635824bcef5cc1c5a3b79205575c2888d8a0
MD5 0761662bf62e75a0a9b2637b91585601
BLAKE2b-256 dab55fd14e06bf7a24eb59d5236b935c49f6b10423f4a86487314a0621e95bbd

See more details on using hashes here.

File details

Details for the file lnurl-0.6.4-py3-none-any.whl.

File metadata

  • Download URL: lnurl-0.6.4-py3-none-any.whl
  • Upload date:
  • Size: 17.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.11.0 Linux/6.11.0-1015-azure

File hashes

Hashes for lnurl-0.6.4-py3-none-any.whl
Algorithm Hash digest
SHA256 3a68586b8a4c608b80b0f2d99d512d1632b0a637e084e349df17d5ae5ab8615e
MD5 dc408fecc97aa1702dd132bbe00ec010
BLAKE2b-256 19ba4920c1bf362f498251965c6f6d59ceab03f42adbdc6dd05ca602e6967a57

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page