Skip to content

minor: fixed hierarchy and added a table of content #7

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.

Sign up for GitHub

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

Closed
pm47 wants to merge 7 commits into from
Closed

minor: fixed hierarchy and added a table of content #7

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
8cfb189
Update 02-peer-protocol.md
pm47 Nov 16, 2016
7259b8d
Update 02-peer-protocol.md
pm47 Nov 16, 2016
21656c9
added ToC
pm47 Nov 16, 2016
a7d8989
fixed paragraph hierarchy
pm47 Nov 16, 2016
1e9f5cd
reverted close_signature->closing_signed
pm47 Nov 16, 2016
0c35d91
fixed toc
pm47 Nov 17, 2016
ee986d1
Merge branch 'master' of https://github.com/lightningnetwork/lightnin…
pm47 Nov 17, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 54 additions & 38 deletions 02-peer-protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,25 @@ The messages described in this document are grouped logically into 4 groups by t
- Routing (types `256`-`511`): node and channel announcements, as well as any active route exploration.

# Table of Contents

FIXME

* [Channel](#channel)
Copy link
Copy Markdown
Collaborator

@Roasbeef Roasbeef Nov 17, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice addition with the table of contents! 👍

Copy link
Copy Markdown
Collaborator

@rustyrussell rustyrussell Nov 18, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, there's shutdown, which is where we don't add anything new, and closing, which is where we're negotiation the final close tx. I used to call shutdown "clearing" but that has a specific finance meaning which was deeply sucky.

Ah, I see you reverted that AFAICT? I'll squash and merge.

Copy link
Copy Markdown
Collaborator Author

@pm47 pm47 Nov 18, 2016

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see you reverted that AFAICT? I'll squash and merge.

Yeah, I didn't want to mix two separate topics in the same PR. I am just OCDing on funding_signed vs close_signature 😵

* [Channel Establishment](#channel-establishment)
* [The `open_channel` message](#the-open_channel-message)
* [The `accept_channel` message](#the-accept_channel-message)
* [The `funding_created` message](#the-funding_created-message)
* [The `funding_signed` message](#the-funding_signed-message)
* [The `funding_locked` message](#the-funding_locked-message)
* [Updating Fees: `update_fee`](#updating-fees-update_fee)
* [Channel Close](#channel-close)
* [Closing initiation: `shutdown`](#closing-initiation-shutdown)
* [Closing negotiation: `close_signature`](#closing-negotiation-close_signature)
* [Normal Operation](#normal-operation)
* [Risks With HTLC Timeouts](#risks-with-htlc-timeouts)
* [Adding an HTLC](#adding-an-htlc)
* [Removing an HTLC: `update_fulfill_htlc` and `update_fail_htlc`](#removing-an-htlc-update_fulfill_htlc-and-update_fail_htlc)
* [Committing Updates So Far: `commitsig`](#committing-updates-so-far-commitsig)
* [Completing the transition to the updated state: `revocation`](#completing-the-transition-to-the-updated-state-revocation)
* [Authors](#authors)

# Channel

## Channel Establishment
Expand Down Expand Up @@ -46,7 +62,7 @@ offered by the other node are not suitable, the channel establishment
fails.


## The `open_channel` message
### The `open_channel` message


This message contains information about a node, and indicates its
Expand Down Expand Up @@ -85,7 +101,7 @@ The `funding-pubkey` is the public key in the 2-of-2 multisig script of the fund
FIXME: Describe Dangerous feature bit for larger channel amounts.


### Requirements
#### Requirements


A sending node MUST set the most significant bit in
Expand Down Expand Up @@ -128,7 +144,7 @@ are not be 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.


### Rationale
#### Rationale


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.
Expand All @@ -137,15 +153,15 @@ The *channel reserve* is specified by the peer's `channel-reserve-satoshis`; 1%
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.


### Future
#### Future


It would be easy to have a local feature bit which indicated that a
receiving was prepared to fund a channel, which would reverse this
protocol.


## The `accept_channel` message
### The `accept_channel` message


This message contains information about a node, and indicates its
Expand All @@ -168,7 +184,7 @@ acceptance of the new channel.
* [33:Refund base point]


### Requirements
#### Requirements


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.
Expand All @@ -177,7 +193,7 @@ The receiver MAY reject the `minimum-depth` if it considers it unreasonably larg
Other fields have the same requirements as their counterparts in `open_channel`.


## The `funding_created` message
### The `funding_created` message

This message describes the outpoint which the funder has created for
the initial commitment transactions. After receiving the peer's
Expand All @@ -192,11 +208,11 @@ signature, it will broadcast the funding transaction.

FIXME: describe

### Requirements
#### Requirements

The recipient MUST fail the channel if the signature is invalid.

## The `funding_signed` message
### 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
Expand All @@ -207,11 +223,11 @@ redeem their funds if they need to.
* [8:temporary-channel-id]
* [64:signature]

### Requirements
#### Requirements

FIXME: Describe

## The `funding_locked` message
### 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.

Expand All @@ -231,16 +247,16 @@ index which pays to the channel.
This `channel-id` is used in all messages referring to the channel
from this point onwards.

### Requirements
#### Requirements

FIXME: Describe

### Future
#### Future

We could add an SPV proof, and route block hashes in separate
messages.

## Updating Fees: `update_fee`
### Updating Fees: `update_fee`

An `update_fee` message is sent by the node which is paying the
bitcoin fee. Like any update, it is first committed to the receiver's
Expand All @@ -261,9 +277,9 @@ given in [BOLT #3].
1. type: 37 (`MSG_UPDATE_FEE`)
2. data:
* [8:channel-id]
* [4:fee-per-kilobyte]
* [4:feerate-per-kilobyte]

### Requirements
#### Requirements

The node which is responsible for paying the bitcoin fee SHOULD send
`update_fee` when to ensure the current fee rate is sufficient for
Expand All @@ -284,7 +300,7 @@ the new fee rate on the receiving node's current commitment
transaction, but it MAY delay this check until the `update_fee` is
committed.

### Rationale
#### Rationale

Bitcoin fees are required for unilateral closes to be effective,
particularly since there is no general method for the node which
Expand Down Expand Up @@ -326,7 +342,7 @@ negotiation begins.
+-------+ +-------+


## Closing initiation: `shutdown`
### Closing initiation: `shutdown`

Either node (or both) can send a `shutdown` message to initiate closing,
and indicating the scriptpubkey it wants to be paid to.
Expand All @@ -338,7 +354,7 @@ and indicating the scriptpubkey it wants to be paid to.
* [4:len]
* [len:scriptpubkey]

### Requirements
#### Requirements

A node MUST NOT send a `shutdown` if there are updates pending
on the receiving node's commitment transaction which are not yet added to the sender’s commitment.
Expand All @@ -360,7 +376,7 @@ 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`.

### Rationale
#### Rationale

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;
Expand All @@ -375,7 +391,7 @@ 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.

## Closing negotiation: `close_signature`
### Closing negotiation: `close_signature`

Once shutdown is complete and the channel is empty of HTLCs, the final
current commitment transactions will have no HTLCs, and closing fee
Expand All @@ -391,7 +407,7 @@ the channel.
* [8:fee-satoshis]
* [64:signature]

### Requirements
#### Requirements

Nodes SHOULD send a `close_signature` message after `shutdown` has
been received and no HTLCs remain in either commitment transaction.
Expand Down Expand Up @@ -420,7 +436,7 @@ Once a node has sent or received a `close_signature` with matching
`fee-satoshis` it SHOULD close the connection and SHOULD sign and
broadcast the final closing transaction.

### Rationale
#### Rationale

Note that there is limited risk if the closing transaction is
delayed, and it will be broadcast very soon, so there is usually no
Expand Down Expand Up @@ -469,7 +485,7 @@ what matters is whether both sides have irrevocably committed to a
particular HTLC or not (the final state, above).


## Risks With HTLC Timeouts
### Risks With HTLC Timeouts


HTLCs tend to be chained across the network. For example, a node A
Expand Down Expand Up @@ -502,7 +518,7 @@ deadline, and MUST fail the channel if an HTLC which it offered is in
either node's current commitment transaction past this deadline.


## Adding an HTLC
### Adding an HTLC


Either node can send `update_add_htlc` to offer a HTLC to the other,
Expand All @@ -526,7 +542,7 @@ is destined, is described in [BOLT #4].
* [1254:onion-routing-packet]


### Requirements
#### Requirements

A sending node MUST NOT offer `amount-msat` it cannot pay for in the
remote commitment transaction at the current `fee-rate` (see "Updating
Expand Down Expand Up @@ -556,7 +572,7 @@ commitment of that HTLC. A receiving node MAY fail the channel if
other `id` violations occur.


### Rationale
#### Rationale


Invalid amounts are a clear protocol violation and indicate a
Expand All @@ -574,7 +590,7 @@ reconnection purposes; allowing them at other times simplifies the
recipient code, though strict checking may help debugging.


## Removing an HTLC: `update_fulfill_htlc` and `update_fail_htlc`
### Removing an HTLC: `update_fulfill_htlc` and `update_fail_htlc`

For simplicity, a node can only remove HTLCs added by the other node.
There are three reasons for removing an HTLC: it has timed out, it has
Expand All @@ -597,7 +613,7 @@ For a timed out or route-failed HTLC:
* [8:id]
* [154:reason]

### Requirements
#### Requirements

A node SHOULD remove an HTLC as soon as it can; in particular, a node
SHOULD fail an HTLC which has timed out.
Expand All @@ -615,14 +631,14 @@ A receiving node which closes an incoming HTLC in response to an
field to the outgoing `update-fail-htlc`.


### Rationale
#### Rationale


A node which doesn't time out HTLCs it risks channel failure (see
"Risks With HTLC Timeouts").


## Committing Updates So Far: `commitsig`
### Committing Updates So Far: `commitsig`


When a node has changes for the remote commitment, it can apply them,
Expand All @@ -637,7 +653,7 @@ sign the resulting transaction as defined in [BOLT #3] and send a
* [4:num-htlcs]
* [num-htlcs*64:htlc-signature]

## Requirements
#### Requirements


A node MUST NOT send a `commitsig` message which does not include any
Expand All @@ -655,7 +671,7 @@ its local commitment transaction once all pending updates are applied. A receiv
A receiving node MUST respond with a `revocation` message.


## Rationale
#### Rationale


There's little point offering spam updates; it implies a bug.
Expand All @@ -664,7 +680,7 @@ There's little point offering spam updates; it implies a bug.
The `num-htlcs` field is redundant, but makes the packet length check fully self-contained.


## Completing the transition to the updated state: `revocation`
### Completing the transition to the updated state: `revocation`


Once the recipient of `commitsig` checks the signature, it knows that
Expand Down Expand Up @@ -694,7 +710,7 @@ The description of key derivation is in [BOLT #3](03-transactions.md#key-derivat
* [4:num-htlc-timeouts]
* [num-htlc-timeouts*64:htlc-timeout-signature]

### Requirements
#### Requirements


A sending node MUST set `per-commitment-secret` to the secret used to generate keys for the
Expand Down