LNURL implementation for Python.
Project description
LNURL implementation for Python
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
e768a5b475fdb315b339b175c851635824bcef5cc1c5a3b79205575c2888d8a0
|
|
MD5 |
0761662bf62e75a0a9b2637b91585601
|
|
BLAKE2b-256 |
dab55fd14e06bf7a24eb59d5236b935c49f6b10423f4a86487314a0621e95bbd
|
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
Algorithm | Hash digest | |
---|---|---|
SHA256 |
3a68586b8a4c608b80b0f2d99d512d1632b0a637e084e349df17d5ae5ab8615e
|
|
MD5 |
dc408fecc97aa1702dd132bbe00ec010
|
|
BLAKE2b-256 |
19ba4920c1bf362f498251965c6f6d59ceab03f42adbdc6dd05ca602e6967a57
|