Suggestion: lower-level "paycode" below "invoice" level

[ZmnSCPxj]

Currently, all incoming payments are done via invoice interface.

This includes incoming payments that will be used for e.g. rebalancing.

However, we might want to consider:

1. A user c-lightning node might want to have some rebalancing plugin that ensures it has sufficient incoming liquidity to accept at least the median size of its payments.
2. The same node has a separate merchant software that monitors customer payments via waitanyinvoice.

Currently, the only way for a rebalance to work would be to generate a synthetic invoice and making a self-payment to that.

However, this synthetic invoice might confuse or otherwise interact badly with merchant software running on top of c-lightning using waitanyinvoice.

So I suggest the following low-level interface; then invoice would actually build on top of this low-level interface.

• paycode {12345|any} {timeout} - generate a paycode. The paycode is identified by payment_hash that is returned by this command.
• waitpaycode {hash} - wait for the paycode to be paid, or timeout.
• listpaycodes {hash} - list paycodes and their status and timeouts.
• delpaycode {hash} {status} - delete a paycode if it has the given status. Any attached invoice is also deleted.

Of note, there is no waitanypaycode - the intent is that the low-level interface is to be used for such things as circular donation and rebalancing, which should generate one paycode for an instance of its command execution and pay attention only to that single paycode.

---

Internally, this is implemented using the same struct invoices, but at invoice creation we add a new boolean flag paycode_only (adding this to the invoices table with value false for existing entries).

Then we modify waitanyinvoice and listinvoices to skip invoices with paycode_only equal to true.

(the above can be an alternate interface, but I like the conceptual separation at the JSON-RPC level of the low-level "paycode" versus the high-level "invoice")

[trueptolemy]

I like this idea!

[ZmnSCPxj]

It seems to me that htlc_accepted can actually also work, rather than this idea. A "rebalance" or other plugin that requires circular payments can simply intercept the htlc_accepted hook and return the preimage for a particular incoming payment hash.

However it does require that we support hooks that can be set up in a chain-of-responsibility: consider that multiple plugins may want to get htlc_accepted, not just for circular payments, but for such things as cross-chain support.

[ZmnSCPxj]

An alternate interface would be for paycodes to not be stored in database (i.e. they are transient in memory only).
As the intent is they will be used very transiently for plugins, this improves our resource management: no need to store in permanent storage and add more db_hook spoor, and if the plugin using the paycode dies, we automatically clean up after it.

Then we just need a single command:

1. waitpaycode <payment_preimage> <timeout> - Accept incoming payments with payment_hash matching the given payment_preimage. Fail if <timeout> is reached, succeed if incoming payment occurs.

The plugin needs to acquire a crypto-secure random number for the preimage (lightningd could provide a getrandom).