The peer channel protocol has three phases: establishment, normal
operation, and closing.
The messages described in this document are grouped logically into 4 groups by their most significant set bit:
- Setup & signalling (types `0`-`31`): comprises setup of the cryptographic transport, communication of supported features and error reporting. These are described in BOLT #1.
- Channel (types `32`-`127`): comprises messages used to setup, update and tear down micropayment channels
- HTLC (types `128`-`255`: comprises messages related to adding, revoking and settling HTLCs on a micropayment channel
- Routing (types `256`-`511`): node and channel announcements, as well as any active route exploration.
# Table of Contents
FIXME
# Channel
## Channel Establishment
Channel establishment begins immediately after authentication, and
consists of each node sending an `open_channel` message, followed by
one node sending `open_funding`, the other providing its
`open_commit_sig` then both sides waiting for the funding transaction
to enter the blockchain and reach their specified depth, at which
point they send `open_complete`. After both sides have sent
`open_complete` the channel is established and can begin normal
This message contains information about a node, and indicates its
desire to set up a new channel.
1. type: 32 (`MSG_OPEN_CHANNEL`)
2. data:
* [8:temporary-channel-id]
* [8:funding-satoshis]
* [8:push-msat]
* [8:dust-limit-satoshis]
* [8:max-htlc-value-in-flight-msat]
* [8:channel-reserve-satoshis]
* [4:htlc-minimum-msat]
* [4:max-num-htlcs]
* [4:feerate-per-kb]
* [2:to-self-delay]
* [33:Funding pubkey]
* [33:HAKD base point]
* [33:Refund base point]
The `temporary-channel-id` is used to identify this channel until the funding transaction is established. `funding-satoshis` is the amount the sender is putting into the channel. `dust-limit-satoshis` is the threshold below which no HTLC output should be generated for this node’s commitment transaction; ie. HTLCs below this amount are not enforceable onchain. This reflects the reality that tiny outputs are not considered standard transactions and will not propagate through the bitcoin network.
`max-htlc-value-in-inflight-msat` is a cap on total value of outstanding HTLCs, which allows a node to limit its exposure to HTLCs; similarly `max-num-htlcs` limits the number of outstanding HTLCs the other node can offer. `channel-reserve-satoshis` is the minimum amount that the other node is to keep as a direct payment. `htlc-minimum-msat` indicates the smallest value HTLC this node wil accept. `feerate-per-kb` indicates the initial fee rate which this side will pay for commitment and HTLC transactions (this can be adjusted later with a `update_fee` message). `to-self-delay` is the number of block that the other nodes to-self outputs must be delayed, using `OP_CHECKSEQUENCEVERIFY` delays; this is how long it will have to wait in case of breakdown before redeeming its own funds.
The `funding-pubkey` is the public key in the 2-of-2 multisig script of the funding transaction output. The `hakd-base-point` is combined with the revocation hash for this commitment transaction to generate a unique revocation key for this commitment transaction (HAKD = homomorphic adversarial key derivation). The `refund-base-point` is similarly used to generate a series of keys for non-HTLC outputs, ensuring 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.
FIXME: Describe Dangerous feature bit for larger channel amounts.
A sending node MUST set the most significant bit in
`temporary-channel-id`, and MUST ensure it is unique from any other
channel id with the same peer. The sender MUST set `funding-satoshis`
to less than 2^24 satoshi. The sender MUST set `push-msat` to
equal or less than to 1000 * `funding-satoshis`. The sender SHOULD set `dust-limit-satoshis` large enough to ensure it can propagate the resulting transaction to miners.
The sender SHOULD set `to-self-delay` sufficient to ensure the sender
can irreversibly spend a commitment transaction output in case of
misbehavior by the receiver. The sender SHOULD set `minimum-depth` to
an amount where the sender considers reorganizations to be low risk.
`funding-pubkey` and `commit-point` MUST be valid DER-encoded
compressed secp256k1 pubkeys. The sender SHOULD set `feerate-per-kb`
to at least the rate it estimates would cause the transaction to be
immediately included in a block.
The sender SHOULD set `dust-limit-satoshis` to sufficient value to
allow commitment transactions to propagate through the bitcoin
`htlc-minimum-msat` too large, `max-htlc-value-in-flight` too small, `channel-reserve-satoshis` too large, or `max-num-htlcs` too small. It MUST fail the channel if `max-num-htlcs` is greater than 600.
The *channel reserve* is specified by the peer's `channel-reserve-satoshis`; 1% of the channel total is suggested. Each side of a channel maintains this reserve so it always has something to lose if it were to try to broadcast an old, revoked commitment transaction. Initially this reserve may not be met, as only one side has funds, but the protocol ensures that progress is always toward it being met, and once met it is maintained.
The sender can unconditionally give initial funds to the receiver using a non-zero `push-msat`, and this is one case where the normal reserve mechanism doesn't apply. However, like any other on-chain transaction, this payment is not certain until the funding transaction has been confirmed sufficiently (may be double-spent) and may require a separate method to prove payment via on-chain confirmation.
The `temporary-channel-id` MUST be the same as the `temporary-channel-id` in the `open_channel` message. The sender SHOULD set `minimum-depth` to a number of blocks it considers reasonable to avoid double-spending of the funding transaction.
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`.
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.
1. type: 36 (`MSG_FUNDING_LOCKED`)
2. data:
* [8:temporary-channel-id]
* [8:channel-id]
* [32:next-key-offset]
* [33:next-revocation-halfkey]
The `channel-id` is the unique description of the funding transaction.
It is constructed with the most significant 3 bytes as the block
height, the next 3 bytes indicating the transaction index within the
block, and the least significant two bytes indicating the output
index which pays to the channel.
This `channel-id` is used in all messages referring to the channel
2.`OP_HASH160``20` 20-bytes `OP_EQUAL` (pay to script hash), OR
3.`OP_0``20` 20-bytes (version 0 pay to witness pubkey), OR
4.`OP_0``32` 32-bytes (version 0 pay to witness script hash)
A receiving node SHOULD fail the connection if the `scriptpubkey` is not one
of those forms.
A receiving node MUST reply to a `shutdown` message with a `shutdown` once there are no outstanding updates on the peer, unless it has already sent a `shutdown`.
If channel state is always "clean" (no pending changes) when a
shutdown starts, we avoid the question of how to behave if it wasn't;
the sender an always send an `update_commit` first.
As shutdown implies a desire to terminate, it implies that no new
HTLCs will be added or accepted.
The `scriptpubkey` forms include only standard forms accepted by the
bitcoin network, ensuring that the resulting transaction will
propagate to miners.
The `shutdown` response requirement implies that the node sends `update_commit` to commit any outstanding changes before replying, but it could theoretically reconnect instead, which simply erases all outstanding uncommitted changes.
A node MUST NOT send a `commitsig` message which does not include any
updates. Note that a node MAY send a `commitsig` message which only
alters the fee, and MAY send a `commitsig` message which doesn't
change the commitment transaction other than the new revocation hash
(due to dust, identical HTLC replacement, or insignificant or multiple
fee changes). A node MUST include one `htlc-signature` for every HTLC transaction corresponding to BIP69 lexicographic ordering of the commitment transaction.
A receiving node MUST fail the channel if `signature` is not valid for
its local commitment transaction once all pending updates are applied. A receiving node MUST fail the channel if `num-htlcs` is not exactly the number of HTLC outputs in the local commitment transaction once all pending updates are applied. A receiving node MUST fail the channel if any `htlc-signature` is not valid for the corresponding HTLC transaction.
A receiving node MUST respond with a `revocation` message.
This message also supplies the signatures for the sender's HTLC-timeout transactions. See [BOLT #5](05-onchain.md) for how this is used with a penalty transaction.
A receiving node MUST check that `per-commitment-secret` generates the previous `key-offset` and `revocation-halfkey`, and MUST fail if it does not. A receiving node MAY fail if the `per-commitment-secret` was not generated by the protocol in [BOLT #3](03-transactions.md#per-commitment-secret-requirements).
A receiving node MUST fail the channel if any htlc-timeout-signature is not valid, or if num-htlc-timeout is not equal to the number of outputs in the sending node's commitment transaction corresponding to HTLCs offered be the sending node.
