dual-funding, the monster

[niftynei]

Dual Funding

This PR updates the channel establishment (aka openingd's responsiblity) to allow for both the originating and the reciprocating peer to contribute UTXOs to the funding transaction. The protocol for this has been laid out in #524 in the lightning-rfc's, but for ease of review, I'll include it here as well, along with some explanation for the decisions.

Note that this PR does not encompass the RBF flows illustrated; those will be covered in a future update.

    +-------+                              +-------+
    |       |--(1)--- open_channel2  ----->|       |
    |       |<-(2)--- accept_channel2 -----|       |
    |       |                              |       |
    |       |--(3a)-  funding_add_input -->|       |
    |       |<-(3b)-  funding_add_input ---|       |
    |       |--(3c)-  funding_add_input -->|       |
    |       |--(3d)-  funding_add_output ->|       |
    |       |<-(3e)-  funding_add_output --|       |
    |       |                              |       |
    |       |--(4a)- funding_add_complete >|       |
    |       |<-(4b)- funding_add_complete -|       |
    |   A   |                              |   B   |
--->|       |--(5)--  commitment_signed -->|       |
|   |       |<-(6)--  commitment_signed ---|       |
|   |       |                              |       |
|   |       |<-(7)--  funding_signed2   ---|       |
|   |       |                              |       |
|   |       |--(a)--- init_rbf ----------->|       |
----|       |<-(b)--- ack_rbf  ------------|       |
    |       |                              |       |
    |       |--(8)--- funding_locked ----->|       |
    |       |<-(9)--  funding_locked ------|       |
    +-------+                              +-------+

There are a few notable changes. First, the funding inputs and outputs are exchanged via rounds, where either peer may submit almost any number of funding_add_input or funding_add_output messages. The round is finished when both peers have sent a funding_add_complete message, with a tally of all the inputs and outputs that they sent.

The peers construct the funding transaction from the set of inputs and outputs that have been sent and received, and update the message's channel_id accordingly, such that commitment_signed now includes both the correct funding transaction id and a valid commitment signature for that transaction.

Finally, the reciprocating peer (also known as the accepter) sends the originating peer (opener) the signatures for their inputs in the funding transaction.

Why Rounds of Inputs/Outputs

Originally, the dual funding protocol called for both peers to exchange signatures for their inputs. However, we've softened this to just the accepter side sending their signatures. The reason for this has to do with why we introduced the rounds of funding_add in the first place. The goal is to enable the accepter and the opener to both solicit and then include funding transaction outputs from other peers simultaneously. Here's a quick example of how the Accepter of a channel open might include a second open in the same transaction.

OPENER_A	ACCEPTER_A/OPENER_B		ACCEPTER_B
   -- open_channel --->
   <- accept_channel --
  -- funding_add_input->        -- open_channel --->
  <- funding_add_input -        <- accept_channel -- 
 -- funding_add_output ->       -- funding_add_input ->
     <- funding_add_output --       -- funding_add_output ->
 -- funding_add_complete->      <- funding_add_input --
 <- funding_add_input --	<- funding_add_output --
 <- funding_add_output --	<- funding_add_complete --
 <- funding_add_complete -      -- funding_add_complete ->
 -- commitment_signed ->	-- commitment_signed ->
 <- commtment_signed --         <- commitment_signed --
			        <- funding_signed2 --
 <- funding_signed2 --

In this scenario, OPENER_A will be the peer that broadcasts the funding transaction, as they're the only peer who knows the signatures to their funding transaction inputs.

Note that the commitment_signed message is broken out from the funding_signed2 message. Originally I had these as the same message, but that would delay the communication of the commitments in the case where the the first accepter (ACCEPTER_A) needs to get the funding signatures from ACCEPTER_B before sending their signatures to OPENER_A.

Note that this construction allows a small ambiguity into the origination of any input that an opener receives for a funding transaction. One downside to this is that the opener, as a result of their receiving all of the inputs and having control over the broadcast of the transaction, pays all of the fees.

This makes opens more brittle, as more peers are required to be online and participate in order to RBF an open transaction. It has no effect on the operation of channels opened in this manner.

How to Dual Fund a Channel

To dual fund a channel, we make use of the openchannel plugin hook. We've expanded the openchannel payload to include a few new fields. First, we now provide a version number of the channel open protocol that this openchannel request is using. Second, we rename funding_satoshis to opener_satoshis, as this amount is the satoshi value that the opener is contributing to the channel, not the total funding amount. Finally we also include an available_funds value, which tells the plugin the total amount of funds that the internal wallet currently has available to fund this channel.

To contribute funds to an openchannel request, the hook must respond with a continue JSON object that also includes a funding_sats member, indicating the total value of satoshi that we should add to this channel.

See tests/plugins/funder.py as a very simple example of this.

Channel Open Tracking

With the first version of channel establishment, the publishing node was the one that owned all of the outputs as well as the funding transaction. Any failure of the channel to open was within your own purview; forgetting a failed channel open as an accepting peer had no consequences.

v2, however, changes these assumptions. We now need to know if a channel open gets voided via the spend of any of its inputs. Until the channel funding transaction or an input to it is seen on chain, we must keep track and not forget any data about the channel open.

To this end, this PR also includes a series of commits which add a new table to the database, called output_tracking. This is where we keep data of every input which pertains to a channel.

If we detect a spend of an input for a channel's funding transaction (and not in that funding transaction), we move a channel to a temporary state called BORKED. It persists in the BORKED state until the offending transaction that contains the input spend reaches a depth of 6. At this point, the channel is forgotten, and a new open may be attempted with this peer. We also track these across re-orgs and restarts. If you restart a node with a rescan value of less than 6 there's a good chance you'll break this and your channel will get stuck in BORKED mode forever.

Errata

Because of how fundchannel_start and fundchannel_complete are used under the hood to make fundchannel work, we do a few hacky things to work around the fact that txprepare/txsend hold the transaction for this channel.

Dual-funded transactions expect a zero-value output from the opener that will be used/filled in with the feerate; in order to accommodate this, txprepare has an option zero_out_change, which will supply a transaction with a change output of value zero. (Likewise, hsmd has been adjusted to make sure that we never actually sign a transaction with any output of value zero, so these are unspendable, as is). Completing a funding open (fundchannel_complete) will return the updated txid for the funding transaction. This updated txid is what must be passed into txsend in order to send the transaction, as the v2 channel open pathways modify the underlying prepared transaction in c-lightning's wallet.

This is admittedly suboptimal; I've got some sketches done of how to transition this to PSBT.

Ongoing Work

• The python tests are currently not passing (32 failed + 12 error on my machine)
• The commits for this PR are missing CHANGELOG entries
• Protocol tests need to be fixed up for the new SIGS() and message updates
• Protocol tests for the opener side need to be completed

Future Work

• RBF
• Using PBST to handle the inputs/outputs for fundchannel_start/fundchannel_complete

[ZmnSCPxj]

@niftynei added 30 commits ... 47 hidden items Load More ... @niftynei added 25 commits. Monstrous indeed.

Note that the funding_signed2 message is broken out from the funding_signed2 message.

Maybe you mean "Note that the commitment_signed message is broken out from the funding_signed2 message"?

Completing a funding open (fundchannel_complete) will return the updated txid for the funding transaction. This updated txid is what must be passed into txsend in order to send the transaction, as the v2 channel open pathways modify the underlying prepared transaction in c-lightning's wallet.

That seems a bit too magical. In principle the funding process should not interact with the wallet, otherwise you tie yourself in the following manner:

• No longer able to use a truly external wallet for funding.
• Opening to multiple peers is done how now?

Maybe some modification to #3415 can be done instead, where we provide some way to "edit" a txprepared transaction? This probably implies more splitting of the funding process and more fundchannel_* sub-commands.

[niftynei]

That is correct, multi-fund open and external wallet funding are not currently supported in this preliminary PR. Note that this restriction only applies to v2 opens; current, v1 opens still work as they have. This functionality will be re-enabled in a subsequent PR, with PSBTs.

…

On Fri, Jan 17, 2020 at 00:26 ZmnSCPxj, ZmnSCPxj jxPCSmnZ < ***@***.***> wrote: @niftynei <https://github.com/niftynei> added 30 commits ... 47 hidden items Load More ... @niftynei <https://github.com/niftynei> added 25 commits. Monstrous indeed. Note that the funding_signed2 message is broken out from the funding_signed2 message. Maybe you mean "Note that the commitment_signed message is broken out from the funding_signed2 message"? Completing a funding open (fundchannel_complete) will return the updated txid for the funding transaction. This updated txid is what must be passed into txsend in order to send the transaction, as the v2 channel open pathways modify the underlying prepared transaction in c-lightning's wallet. That seems a bit too magical. In principle the funding process should not interact with the wallet, otherwise you tie yourself in the following manner: - No longer able to use a truly external wallet for funding. - Opening to multiple peers is done how now? Maybe some modification to #3415 <#3415> can be done instead, where we provide some way to "edit" a txprepared transaction? This probably implies more splitting of the funding process and more fundchannel_* sub-commands. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#3418?email_source=notifications&email_token=AAIMAKL322OU5OWBRQWC3MTQ6FFRVA5CNFSM4KIBNXXKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEJGS4ZI#issuecomment-575483493>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAIMAKN63CT3FPEOCW7OZYTQ6FFRVANCNFSM4KIBNXXA> .

[niftynei]

retiring this, new PR incoming soon ™️