Skip to main content

Client library and plugin library for Core Lightning

Project description

pyln-client: A python client library for lightningd

This package implements the Unix socket based JSON-RPC protocol that lightningd exposes to the rest of the world. It can be used to call arbitrary functions on the RPC interface, and serves as a basis for plugins written in python.

Installation

pyln-client is available on pip:

pip install pyln-client

Alternatively you can also install the development version to get access to currently unreleased features by checking out the Core Lightning source code and installing into your python3 environment:

git clone https://github.com/ElementsProject/lightning.git
cd lightning/contrib/pyln-client
poetry install

This will add links to the library into your environment so changing the checked out source code will also result in the environment picking up these changes. Notice however that unreleased versions may change API without warning, so test thoroughly with the released version.

Examples

Using the JSON-RPC client

"""
Generate invoice on one daemon and pay it on the other
"""
from pyln.client import LightningRpc
import random

# Create two instances of the LightningRpc object using two different Core Lightning daemons on your computer
l1 = LightningRpc("/tmp/lightning1/lightning-rpc")
l5 = LightningRpc("/tmp/lightning5/lightning-rpc")

info5 = l5.getinfo()
print(info5)

# Create invoice for test payment
invoice = l5.invoice(100, "lbl{}".format(random.random()), "testpayment")
print(invoice)

# Get route to l1
route = l1.getroute(info5['id'], 100, 1)
print(route)

# Pay invoice
print(l1.sendpay(route['route'], invoice['payment_hash']))

Writing a plugin

Plugins are programs that lightningd can be configured to execute alongside the main daemon. They allow advanced interactions with and customizations to the daemon.

#!/usr/bin/env python3
from pyln.client import Plugin

plugin = Plugin()

@plugin.method("hello")
def hello(plugin, name="world"):
    """This is the documentation string for the hello-function.

    It gets reported as the description when registering the function
    as a method with `lightningd`.

    If this returns (a dict), that's the JSON "result" returned.  If
    it raises an exception, that causes a JSON "error" return (raising
    pyln.client.RpcException allows finer control over the return).
    """
    greeting = plugin.get_option('greeting')
    s = '{} {}'.format(greeting, name)
    plugin.log(s)
    return s


@plugin.init()
def init(options, configuration, plugin):
    plugin.log("Plugin helloworld.py initialized")
    # This can also return {'disabled': <reason>} to self-disable,
	# but normally it returns None.


@plugin.subscribe("connect")
def on_connect(plugin, connect, **kwargs):
    plugin.log("Received connect event for peer {}".format(connect))


plugin.add_option('greeting', 'Hello', 'The greeting I should use.')
plugin.run()

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

pyln_client-25.5.tar.gz (36.0 kB view details)

Uploaded Source

Built Distribution

pyln_client-25.5-py3-none-any.whl (37.4 kB view details)

Uploaded Python 3

File details

Details for the file pyln_client-25.5.tar.gz.

File metadata

  • Download URL: pyln_client-25.5.tar.gz
  • Upload date:
  • Size: 36.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.10.18 Linux/6.8.0-1029-azure

File hashes

Hashes for pyln_client-25.5.tar.gz
Algorithm Hash digest
SHA256 18656e667c7218f8b40c70f893b936aef4518e87e3ce99081bd52f89e6e5af85
MD5 f82a09f13b96ff7ef004b2f58f0b59d8
BLAKE2b-256 f6f570dae7e6985ba44f53e1c634e204ecc4e9ccde8de6cd90e009672203023f

See more details on using hashes here.

File details

Details for the file pyln_client-25.5-py3-none-any.whl.

File metadata

  • Download URL: pyln_client-25.5-py3-none-any.whl
  • Upload date:
  • Size: 37.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.10.18 Linux/6.8.0-1029-azure

File hashes

Hashes for pyln_client-25.5-py3-none-any.whl
Algorithm Hash digest
SHA256 269f9ab346ff679b532af2d24c2a524201884efc5b4781dd40685c8ccaec9507
MD5 c08d3068f9db0e4a2433f49c3a222b18
BLAKE2b-256 c845c504ed8ea59577d8093d377e2f657482f08e87b93aaa039e64421297ff55

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