[c-lightning] Feature: run scripts on incoming transactions

Corné Plooy corne at bitonic.nl
Thu Jun 21 02:00:49 AEST 2018


I'm working on an experimental feature for C-Lightning where a custom
(Sphinx) message in an incoming transaction can trigger the execution of
a script. The script can receive information about the transaction
(hash, time-out, amount, message data etc.), do anything it wants, and
reply to lightningd whether this incoming transaction should be accepted
or canceled. The incoming transaction does not have to correspond to an
invoice created in this Lightning node: it can also be that a
higher-level application needs to forward the payment to some other
party, in an application-specific way, to gain access to the preimage.

The (unfinished) code is available at:


By its very nature, the code involves some API changes. So far, the
design is roughly as follows:

* The 'sendpay' command allows optional extra attributes 'realm' and
'data' in individual route steps. These override the normal realm value
(0) and data (channel ID, amount, time-out) that would otherwise be put
into the routing data given to a node.

* If an incoming transaction contains a realm number that would
otherwise not be supported (currently, realm 0 is the only one defined
by the RFC and supported by C-Lightning), lightningd tries to execute a
script "handle_realm_<realmnumber>" in the Lightning directory. It
receives information about the transaction on STDIN (format: TBD), and
sends a single number back on STDOUT indicating whether the transaction
should be accepted or rejected.

* Currently, if such a script hangs, lightningd hangs. I'm not
completely happy with this, but what would be the alternatives? Not have
the script send any data back? Asynchronous communication with the
script? You potentially have a "process leak" problem: an attacker may
crash a machine by triggering huge numbers of parallel script
executions. For now, this problem does not exist, and "don't make buggy
scripts" is an obvious solution to stop lightningd from hanging.

* Extra RPC commands will be added to allow applications to give a
transaction preimage to lightningd (inherently safe) and to indicate
that a certain payment will be canceled (unsafe - the application needs
to ensure that any outgoing goods/services/assets are stopped, before
canceling the incoming funds).

The reason for this e-mail:

* I want you to be aware of this project

* I'd like to have some "early" feed-back on the API design

As a consequence of me being open to feedback, the API is subject to
change; don't depend on it yet!! In fact, currently, it's all designed
in a very ad-hoc manner; I'll have a critical look at it myself, as soon
as I have a prototype with a tested full feature set.



More information about the c-lightning mailing list