New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BOLT 02: opt-in dual-funding #184

Open
wants to merge 1 commit into
base: master
from
Jump to file or symbol
Failed to load files and symbols.
+69 −27
Diff settings

Always

Just for now

Copy path View file
@@ -292,3 +292,4 @@ SRV
TTL
URI
cli
malleated
Copy path View file
@@ -31,22 +31,17 @@ operation, and closing.
Channel establishment begins immediately after authentication, and
consists of the funding node sending an `open_channel` message,
followed by the responding node sending `accept_channel`. With the
channel parameters locked in, the funder is able to create the funding
transaction and both versions of the commitment transaction as described in
[BOLT
03](https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#bolt-3-bitcoin-transaction-and-script-formats).
The funder then sends the outpoint of the funding output along with a
signature for the responder's version of the commitment transaction
with the `funding_created` message. Once the responder learns the
funding outpoint, she is able to generate the initiator's commitment
for the commitment transaction, and send it over using the
`funding_signed` message.
Once the channel funder receives the `funding_signed` message, they
must broadcast the funding transaction to the Bitcoin network. After
the `funding_signed` message is sent/received, both sides should wait
consists of the funding node sending an `open_channel` message, which
includes a partial funding transaction.
The responding node replies with `accept_channel` which may include additional
inputs for the funding transaction ("dual funding"), and a signature for the
funder's first commitment transaction as described in [BOLT 03](https://github.com/lightningnetwork/lightning-rfc/blob/master/03-transactions.md#bolt-3-bitcoin-transaction-and-script-formats).
The funding node then sends a `funding_created` message that includes a signature for the responder's first
commitment transaction, and the responder replies with a `funding_signed` message that includes
signatures for all the funding inputs that they added in their `accept_channel` message.
Both nodes now have a signed commitment transaction, and the funding node has a fully signed funding transaction that
they can broadcast.
After the `funding_signed` message is sent/received, both sides should wait
for the funding transaction to enter the blockchain and reach their
specified depth (number of confirmations). After both sides have sent
the `funding_locked` message, the channel is established and can begin
@@ -100,6 +95,8 @@ desire to set up a new channel.
* [`33`:`delayed_payment_basepoint`]
* [`33`:`first_per_commitment_point`]
* [`1`:`channel_flags`]
* [`2`: `len`]
* [`len`: `partial_funding_tx`]
The `chain_hash` value denotes the exact blockchain the opened channel will
@@ -122,6 +119,8 @@ as detailed within
The `funding_pubkey` is the public key in the 2-of-2 multisig script of the funding transaction output. The `revocation_basepoint` is combined with the revocation preimage for this commitment transaction to generate a unique revocation key for this commitment transaction. The `payment_basepoint` and `delayed_payment_basepoint` are similarly used to generate a series of keys for any payments to this node: `delayed_payment_basepoint` is used to for payments encumbered by a delay. Varying these keys ensures that the transaction ID of each commitment transaction is unpredictable by an external observer, even if one commitment transaction is seen: this property is very useful for preserving privacy when outsourcing penalty transactions to third parties.
`funding_tx` is an unsigned, partial funding transaction that can be used by the receiver to add funds to the channel ("dual funding").
FIXME: Describe Dangerous feature bit for larger channel amounts.
@@ -172,6 +171,13 @@ are not valid DER-encoded compressed secp256k1 pubkeys.
The receiver MUST NOT consider funds received using `push_msat` to be received until the funding transaction has reached sufficient depth.
The sender must set `len` to the length of the serialized, unsigned, partial funding transaction, which MUST be followed by the transaction itself.
`partial_funding_tx` is an unsigned, partial funding transaction that includes:
* inputs that the sender wants to use to fund the channel. These inputs MUST be either P2WPKH or P2WSH and must include the witness script in their signature script field.
* an optional change output
Please note that this partial transaction does not include the multisig funding output, since the sender does not know the receiver's public key yet.

This comment has been minimized.

@cdecker

cdecker Jun 9, 2017

Collaborator

So this is the TX header with 1 or more inputs, and only change outputs?

This comment has been minimized.

@sstone

sstone Jun 11, 2017

Collaborator

yes

#### Rationale
@@ -213,6 +219,9 @@ acceptance of the new channel.
* [`33`:`payment_basepoint`]
* [`33`:`delayed_payment_basepoint`]
* [`33`:`first_per_commitment_point`]
* [`2`:`len`]
* [`len`:`funding_tx`]
* [`64`:`signature`]
#### Requirements
@@ -225,53 +234,82 @@ The `temporary_channel_id` MUST be the same as the `temporary_channel_id` in the
The receiver MAY reject the `minimum_depth` if it considers it unreasonably large.
Other fields have the same requirements as their counterparts in `open_channel`.
The sender can choose to also fund the channel, so that they can start with a positive balance and can use the channel to pay right away.
The sender MUST set `len` to the length of an unsigned funding transaction, followed by the serialized funding transaction.
`funding_tx` is an unsigned funding transaction which includes:
* optional additional inputs that the sender wants to use to fund the channel. These inputs MUST be either P2WPKH or P2WSH and must include the witness script in their signature script field.
* an optional change output
* a funding transaction output as defined in [BOLT #3](03-transactions.md#funding-transaction-output)
The sender MUST then set `signature` to the valid signature using its funding_pubkey for the initial commitment transaction as defined in BOLT #3
The amount that the sender will start with, i.e. that will be included in his first commit transaction, is the difference between the additional inputs
and the change output.
If the sender does not wish to fund the channel, they MAY set `len` to 0 and not include the funding transaction since the

This comment has been minimized.

@cdecker

cdecker Jun 9, 2017

Collaborator

Wouldn't it be cleaner to have B always return a TX, i.e., an unchanged TX from A if B does not want to add funds? Additionally the initiating node now has a valid signature for some funds of the counterparty. It may delay and doublespend the signer's funds at a later point in time. This sounds quite scary to me.

This comment has been minimized.

@sstone

sstone Jun 11, 2017

Collaborator

yes it would be a bit more consistent to always return a tx.

if the channel is funded by both nodes, then any one them could choose to double-spend their funding inputs before the funding tx is published. The funding tx would never confirm, and the channel would never reach the "open" state. It's annoying but easy to detect with tools that LN nodes must already have implemented, nobody looses money and there's nothing to do so I don't find it scary but maybe I've missed something ?

This comment has been minimized.

@cdecker

cdecker Jun 11, 2017

Collaborator

Well, it forces us to actively doublespend if we fail to create the channel: let's say A proposes a channel to be opened to B. A funds the channel, sends it over to B, which adds its own funds and sends back a signed funding TX. Now A just sits there and does nothing. B must now double spend the funds after it notices that the channel will not be created, otherwise A could dig up the funding TX when B wants to spend its funds for something completely unrelated, i.e., interfering with a later payment, and locking the funds into the unilateral closure procedure, potentially hurting B. The only way for B to safeguard against this is to doublespend right away.

It's not dangerous as in "we can lose funds", but A can interfere and be annoying at a later point in time. It's not currently an issue because the funding party is the one starting the confirmation, and is the only one which has all the signatures ready.

This comment has been minimized.

@sstone

sstone Jun 11, 2017

Collaborator

yes having the spend the funding outputs when channel opening times out is annoying. I think that it can be mitigated by adding time-outs to the funding output scripts, I'll post an update asap

This comment has been minimized.

@joemphilips

joemphilips Sep 1, 2017

Is it possible to add time-outs without introducing new BIP? It seems impossible to me.

receiver will have both public keys and will be able to build it.
#### Rationale
Once `accept_channel` has been received, both nodes have an unsigned funding transaction that cannot be malleated (all
inputs are segwit inputs) and can be used to create commitment transactions.
They can easily compute the `funding txid` and find the `funding output index` (they just need to find a match for the funding
transaction output defined in [BOLT #3](03-transactions.md#funding-transaction-output) which they can both compute since
they know both public keys).
### The `funding_created` message
This message describes the outpoint which the funder has created for
This message describes the funding transaction that the funder has created for
the initial commitment transactions. After receiving the peer's
signature, it will broadcast the funding transaction.
1. type: 34 (`funding_created`)
2. data:
* [`32`:`temporary_channel_id`]
* [`32`:`funding_txid`]
* [`2`:`funding_output_index`]
* [`64`:`signature`]
#### Requirements
The sender MUST set `temporary_channel_id` the same as the `temporary_channel_id` in the `open_channel` message. The sender MUST set `funding_txid` to the transaction ID of a non-malleable transaction, which it MUST NOT broadcast, and MUST set `funding_output_index` to the output number of that transaction which corresponds the funding transaction output as defined in [BOLT #3](03-transactions.md#funding-transaction-output), and MUST set `signature` to the valid signature using its `funding_pubkey` for the initial commitment transaction as defined in [BOLT #3](03-transactions.md#commitment-transaction). The sender SHOULD use only BIP141 (Segregated Witness) inputs when creating the funding transaction.
The sender MUST set `temporary_channel_id` the same as the `temporary_channel_id` in the `open_channel` message.
The sender MUST set `signature` to the valid signature using its `funding_pubkey` for the initial commitment transaction as defined in [BOLT #3](03-transactions.md#commitment-transaction).
The recipient MUST fail the channel if `signature` is incorrect.
#### Rationale
The `funding_output_index` can only be 2 bytes, since that's how we'll pack it into the `channel_id` used throughout the gossip protocol. The limit of 65535 outputs should not be overly burdensome.
A transaction with all Segregated Witness inputs is not malleable, hence the recommendation for the funding transaction.
Once this message has been received, both nodes will have a signed commitment transaction, and an unsigned funding transaction.
### The `funding_signed` message
This message gives the funder the signature they need for the first
commitment transaction, so they can broadcast it knowing they can
redeem their funds if they need to.
This message introduces the `channel_id` to identify the channel, which is derived from the funding transaction by combining the `funding_txid` and the `funding_output_index` using big-endian exclusive-OR (ie. `funding_output_index` alters the last two bytes).
This message introduces the `channel_id` to identify the channel, which is derived from the funding transaction by combining
the `funding txid` and the `funding output index` using big-endian exclusive-OR (ie. `funding output index` alters
the last two bytes).
1. type: 35 (`funding_signed`)
2. data:
* [`32`:`channel_id`]
* [`64`:`signature`]
* [`2`:`len`]
* [`len`:`funding_tx`]
#### Requirements
The sender MUST set `channel_id` by exclusive-OR of the `funding_txid` and the `funding_output_index` from the `funding_created` message, and MUST set `signature` to the valid signature using its `funding_pubkey` for the initial commitment transaction as defined in [BOLT #3](03-transactions.md#commitment-transaction).
The sender MUST set `channel_id` by exclusive-OR of `funding_txid` and `funding_output_index`.
The sender MUST set `len` to the length of the partially signed funding transaction, followed by the serialized funding transaction.
The sender MUST include valid witnesses for all inputs added by their `accept_channel` message
The recipient MUST fail the channel if `signature` is incorrect.
The recipient MUST fail the channel if any of these witnesses are missing or incorrect.
The recipient SHOULD broadcast the funding transaction on receipt of a valid `funding_signed` and MUST NOT broadcast the funding transaction earlier.
#### Rationale
Once they have received and checked `funding_signed`, the receiving node will have a fully signed funding transaction, which
they can now broadcast since they already have a signed commit transaction.
### The `funding_locked` message
This message indicates that the funding transaction has reached the `minimum_depth` asked for in `accept_channel`. Once both nodes have sent this, the channel enters normal operating mode.
Copy path View file
@@ -29,6 +29,9 @@ def guess_alignment(message, name, sizestr):
if message == 'node_announcement' and name == 'alias':
return 1
if message == 'accept_channel' and name == 'len':
return 1
if 'signature' in name:
return 1
ProTip! Use n and p to navigate between commits in a pull request.