mirror of https://github.com/ElementsProject/lightning.git synced 2024-11-19 09:54:16 +01:00

History

Christian Decker 8cad3ffeac pyln: Work around the socket path length on Linux OSs Some Linux OSs impose a length limit on the path a Unix socket may have. This is not an issue in `lightningd` since we `chdir()` into that directory before opening the socket, however in pyln this became a problem for some tests, since we use absolute paths in the testing framework. It's also a rather strange quirk to expose to users. This patch introduces a `UnixSocket` abstraction that attempts to work around these limitations by aliasing the directory containing the socket into `/proc/self/fd` and then connecting using that alias. It was inspired by Open vSwitch code here https://github.com/openvswitch/ovs/blob/master/python/ovs/socket_util.py Signed-off-by: Christian Decker <@cdecker>		2020-01-02 16:05:52 +01:00
..
pyln/client	pyln: Work around the socket path length on Linux OSs	2020-01-02 16:05:52 +01:00
tests	pyln: Migrate implementation from pylightning to pyln-client	2019-11-12 21:23:55 +01:00
README.md	pyln: Split pylightning into multiple pyln modules	2019-09-30 13:27:37 +02:00
requirements.txt	pyln: Migrate implementation from pylightning to pyln-client	2019-11-12 21:23:55 +01:00
setup.py	pyln: Split pylightning into multiple pyln modules	2019-09-30 13:27:37 +02:00

README.md

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 c-lightning source code and installing into your python3 environment:

git clone https://github.com/ElementsProject/lightning.git
cd lightning/contrib/pyln-client
python3 setup.py develop

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 c-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`.

    """
    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")


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


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