lightning-message-demo

This software demonstrates how data can be sent along with Lightning payments, from payer to payee. The data is sent as a custom payload for the final node in the onion-encrypted routing data; intermediate nodes will not be able to read it. Based on the data, the payee may perform other actions, e.g. as part of an atomic swap, before finishing the transaction. Based on the data, the payee may also decide to refuse the transaction.

Requirements

This software requires Python 3 and C-Lightning.

Usage

The MESSAGE_TLV_TYPE setting in plugin.py must be set to a value that does not conflict any other standard or custom onion TLV types in use on the receiving node. On an otherwise vanilla C-Lightning installation, only the standard types defined in the Lightning protocol ( BOLT #4 ) must be avoided. It must be set to the same value on the sending and the receiving node. You may think of it as a "port number" on the receiving node.

The sending and receiving node must both have C-Lightning running with plugin.py as plugin, for instance by adding --plugin /path/to/plugin.py to the commandline.

The settings in config.py must be set appropriately.

Then, on the receiving side, receiveMessage.py must be started. It starts by giving a payment hash that can be used for sending a payment with a message to this node. For instance:

$ ./receiveMessage.py 
Payment hash: 48703d023bb9ad70c3d2dc2609940b5530e92c807c1f4835d644394717cad536

Next, on the sending side, sendMessage.py must be started. It asks for the payment hash, the payment amount and the message. Once these questions are answered, the payment with the message is performed, receiveMessage.py returns the amount and the message, and sendMessage.py returns some payment status data.

Issues

Only a single payment routing attempt is made. You may be able to work around this by re-trying sendMessage.py if it fails.

Serialization of onion payloads for intermediate nodes has not been tested extensively; in case of bugs, the software may fail for some intermediate nodes.

RPC

plugin.py adds the following RPC functions to C-Lightning's RPC. These are used by the sendMessage.py and receiveMessage.py scripts.

sendmessage

Arguments

• destination, str: The hex-encoded node ID of the receiving node.
• payment_hash, str: The hex-encoded payment hash.
• msatoshi, int: The payment amount.
• message, str: The message to be sent with the payment.

Returns

• send: The output of the sendonion RPC call.
• wait: The output of the waitsendpay RPC call.

Description

Sends a Lightning payment with a message for the receiving node, and waits until this payment completes.

receivemessage_new

Arguments

Returns

str: The hex-encoded payment hash.

Description

Generates a new payment hash for receiving a payment with a message in it. Note that these are non-persistent: after a plugin restart, old payment hashes can no longer be used.

receivemessage_poll

Arguments

• payment_hash, str: The hex-encoded payment hash, generated by an earlier receivemessage_new call.

Returns

If the payment has been received:

• amount, str: The payment amount.
• message, str: The message sent with the payment.

else, None.

Description

If the payment has been received, returns information about the payment. Else, returns None.