mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2024-11-19 01:50:03 +01:00
Code Issues Projects Releases Wiki Activity

Transfer from google doc.

Browse Source 
Minimal markdown and consistency fixes, more to come.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell 2016-11-15 11:53:20 +10:30
parent 1393561ced
commit 76dfd378ff
6 changed files with 2178 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
00-introduction.md Normal file
View File

@ -0,0 +1,164 @@
# BOLT #0: Introduction and Index
Welcome, friend! These Basis of Lightning Technology (BOLT) documents
describe a layer-2 protocol for off-chain bitcoin transfer by mutual
cooperation, relying on on-chain transactions for enforcement if
necessary.
Some requirements are subtle; we have tried to highlight motivations
and reasoning behind the results you see here. I'm sure we've fallen
short: if you find any part confusing, or wrong, please contact us and
help us improve.
This is version 0.
1. [BOLT #1](01-messaging-crypto-and-init.md): Message Format, Encryption, Authentication and Initialization
2. [BOLT #2](02-peer-protocol.md): Peer Protocol for Channel Management
3. [BOLT #3](03-transactions.md): Bitcoin Transaction and Script Formats
4. [BOLT #4](04-onion-routing.md): Onion Routing Protocol
5. [BOLT #5](05-onchain.md): Recommendations for On-chain Transaction Handling
6. [BOLT #6](06-irc-announcements.md): Interim Node and Channel Discovery
## Glossary and Terminology Guide
* *Funding Transaction*:
* The on-chain, irreversible transaction which pays to both peers
on a channel. Thus it can only be spent by mutual consent.
* *Channel*:
* A fast, off-chain method of mutual exchange between two *peers*.
To move funds, they exchange signatures for an updated *commitment
transaction*.
* *Commitment Transaction*:
* A transaction which spends the funding transaction; each peers
holds a signature from the other peer for this transaction, so it
always has a commitment transaction it can spend. After a new
commitment transaction is negotiated, the old one is *revoked*.
* *HTLC*: Hashed Time Locked Contract.
* A conditional payment between two peers: the recipient can spend
the payment by presenting its signature and a *payment preimage*,
otherwise the payer can cancel the contract by spending it after
a given time. These are implemented as outputs from the
*commitment transaction*.
* *Payment hash, payment preimage*:
* The HTLC contains the payment hash, which is the hash of the
payment preimage. Only the final recipient knows the payment
preimage; thus when it reveals the preimage to collect funds is
considered proof that it received the payment.
* *Commitment revocation key*:
* Every *commitment transaction* has a unique *commitment revocation key*
value which allows the other peer to spend all outputs
immediately: revealing this key is how old commitment
transactions are revoked. To do this, each output refers to the
commitment revocation pubkey.
* *Per-commitment secret*:
* Every commitment derives its keys from a *per-commitment secret*,
which is generated such that the series of per-commitment secrets
for all prevoius commitments can be stored compactly.
* *Mutual Close*:
* A cooperative close of a channel, by broadcasting an unconditional
spend of the *funding transaction* with an output to each peer
(unless one output is too small, and thus is not included).
* *Unilateral Close*:
* An uncooperative close of a channel, by broadcasting a
*commitment transaction*. This transaction is larger (ie. less
efficient) than a mutual close transaction, and the peer whose
commitment is broadcast cannot access its own outputs for some
previously-negotiated duration.
* *Revoked Transaction Close*:
* An invalid close of the channel, by broadcasting a revoked
*commitment transaction*. Since the other peer knows the
*commitment revocation secret key*, it can create a *penalty transaction*.
* *Penalty Transaction*:
* A transaction which spends all outputs of a revoked commitment
transaction, using the *commitment revocation secret key*. A peer uses this
if the other peer tries to "cheat" by broadcasting a revoked
*commitment transaction*.
* *Commitment Number*:
* A 48-bit incrementing counter for each *commitment transaction*; they
are independent for each peer in the channel, and start at 0.
* *Channel shortid*:
* An 8 byte globally unique identifier for the *funding transaction*
(and thus for the channel).
## Theme Song
Why this network could be democratic...
Numismatic...
Cryptographic!
Why it could be released Lightning!
(Release Lightning!)
We'll have some timelocked contracts with hashed pubkeys, oh yeah.
(Keep talking, whoa keep talkin')
We'll segregate the witness for trustless starts, oh yeah.
(I'll get the money, I've got to get the money)
With dynamic onion routes, they'll be shakin' in their boots;
You know that's just the truth, we'll be scaling through the roof.
Release Lightning!
(Go, go, go, go; go, go, go, go, go, go)
[Chorus:]
Oh released Lightning, it's better than a debit card..
(Release Lightning, go release Lightning!)
With released Lightning, micropayments just ain't hard...
(Release Lightning, go release Lightning!)
Then kaboom: we'll hit the moon -- release Lightning!
(Go, go, go, go; go, go, go, go, go, go)
We'll have QR codes, and smartphone apps, oh yeah.
(Ooo ooo ooo ooo ooo ooo ooo)
P2P messaging, and passive incomes, oh yeah.
(Ooo ooo ooo ooo ooo ooo ooo)
Outsourced closure watch, gives me feelings in my crotch.
You'll know it's not a brag when the repo gets a tag:
Released Lightning.
[Chorus]
[Instrumental, ~1m10s]
[Chorus]
(Lightning! Lightning! Lightning! Lightning!
Lightning! Lightning! Lightning! Lightning!)
C'mon guys, let's get to work!
-- Anthony Towns <aj@erisian.com.au>
## Authors
[ FIXME: Insert Author List ]

790
01-messaging-crypto-and-init.md Normal file
View File

@ -0,0 +1,790 @@
# BOLT #1: Message Format, Encryption, Authentication and Initialization
All communications between Lightning nodes should be encrypted in order to
provide confidentiality for all transcripts between nodes, and authenticated to
avoid malicious interference. Each node has a known long-term identifier which
is a public key on Bitcoin's `secp256k1` curve. This long-term public key is
used within the protocol to establish an encrypted+authenticated connection
with peers, and also to authenticate any information advertised on the behalf
of a node.
## Communication Protocols
This protocol is written with TCP in mind, but could use any ordered,
reliable transport.
The default TCP port is `9735`. This corresponds to hexadecimal `2607`,
the unicode code point for LIGHTNING.<sup>[2](#reference-2)</sup>
## Message Format and Handling
All messages are of form:
1. `4-byte` big-endian data length.
2. `4-byte` big-endian type.
3. Data bytes as specified by the length.
All data fields are big-endian unless otherwise specified.
### Requirements
A node MUST NOT send a message with data length greater than `8388608`
bytes. A node MUST NOT send an evenly-typed message not listed here
without prior negotiation.
A node MUST disconnect if it receives a message with data length
greater than `8388608` bytes; it MUST NOT fail the channels in that case.
A node MUST ignore a received message of unknown type, if that type is
odd. A node MUST fail the channels if it receives a message of unknown
type, if that type is even.
A node MUST ignore any additional data within a message, beyond the
length it expects for that type.
### Rationale
The standard endian of `SHA2` and the encoding of bitcoin public keys
are big endian, thus it would be unusual to use a different endian for
other fields.
Length is limited to avoid memory exhaustion attacks, yet still allow
(for example) an entire bitcoin block to be comfortable forwarded as a
reasonable upper limit.
The "it's OK to be odd" rule allows for future optional extensions
without negotiation or special coding in clients. The "ignore
additional data" rule similarly allows for future expansion.
## Cryptographic Messaging Overview
Prior to sending any protocol related messages, nodes must first initiate the
cryptographic session state which is used to encrypt and authenticate all
messages sent between nodes. The initialization of this cryptographic session
state is completely distinct from any inner protocol message header or
conventions.
The transcript between two nodes is separated into two distinct segments:
1. First, before any actual data transfer, both nodes participate in an
authenticated key agreement protocol which is based off of the Noise
Protocol Framework<sup>[4](#reference-4)</sup>.
2. If the initial handshake is successful, then nodes enter the transport
message exchange phase. In the transport message exchange phase, all
messages are `AEAD` ciphertexts.
### Authenticated Key Agreement Handshake
The handshake chosen for the authenticated key exchange is `Noise_XK`. As a
"pre-message", we assume that the initiator knows the identity public key of
the responder. This handshake provides a degree of identity hiding for the
responder, its public key is _never_ transmitted during the handshake. Instead,
authentication is achieved implicitly via a series of `ECDH` operations followed
by a `MAC` check.
The authenticated key agreement (`Noise_XK`) is performed in three distinct
steps. During each "act" of the handshake, some (possibly encrypted) keying
material is sent to the other party, an `ECDH` is performed based on exactly
which act is being executed with the result mixed into the current sent of
encryption keys (`ck` and `k`), and finally an `AEAD` payload with a zero
length cipher text is sent. As this payload is of length zero, only a `MAC` is
sent across. The mixing of `ECDH` outputs into a hash digest forms an
incremental TripleDH handshake.
Using the language of the Noise Protocol, `e` and `s` indicate possibly
encrypted keying material, and `es, ee, se` indicates `ECDH` operations. The
handshake is laid out as follows:
Noise_XK(s, rs):
<- s
...
-> e, es
<- e, ee
-> s, se
All of the handshake data sent across the wire including the keying material is
incrementally hashed into a session-wide "handshake digest", `h`. Note that the
handshake state `h`, is never transmitted during the handshake, instead digest
is used as the Authenticated Data within the zero-length AEAD messages.
By authenticating each message sent, we can ensure that a MiTM hasn't modified
or replaced any of the data sent across as part of a handshake, as the MAC
check would fail on the other side if so.
A successful check of the `MAC` by the receiver indicates implicitly that all
authentication has been successful up to that point. If `MAC` check ever fails
during the handshake process, then the connection is to be immediately
terminated.
## Handshake Versioning
Each message sent during the initial handshake starts with a single leading
byte which indicates the version used for the current handshake. A version of 0
indicates that no change is necessary, while a non-zero version indicate the
client has deviated from the protocol originally specified within this
document. Clients MUST reject handshake attempts initiated with an unknown
version.
### Transport Message Exchange
The actual protocol messages sent during the transport message exchange phase
are encapsulated within `AEAD` ciphertexts. Each message is prefixed with
another `AEAD` ciphertext which encodes the total length of the next transport
message. The length prefix itself is protected with a MAC in order to avoid
the creation of an oracle and to also prevent a MiTM from modifying the length
prefix thereby causing a node to erroneously read an incorrect number of bytes.
## Protocol Message Encapsulation
Once both sides have entered the transport message exchange phase (after a
successful completion of the handshake), Lightning Network protocol messages
will be encapsulated within the exchanged `AEAD` ciphertexts. The maximum size
of transport messages is `65535-bytes`. Node MUST NOT send a transport message
which exceeds this size. Note that this is only a cryptographic messaging limit
within the protocol, and not a limit on the message size of Lightning Network
protocol messages. A Lightning Network message which exceeds this size can be
chunked into several messages before being sent.
### Noise Protocol Instantiation
Concrete instantiations of the Noise Protocol are require the definition of
three abstract cryptographic objects: the hash function, the elliptic curve,
and finally the `AEAD` cipher scheme. Within our instantiation `SHA-256` is
chosen as the hash function, `secp256k1` as the elliptic curve, and finally
`ChaChaPoly-1305` as the `AEAD` construction. The composition of `ChaChaPoly`
and `Poly1305` used MUST conform to `RFC 7539`<sup>[3](#reference-3)</sup>. With this laid out, the
official Noise protocol name for our variant is:
`Noise_XK_secp256k1_ChaChaPoly_SHA256`. The ascii string representation of
this value is hashed into a digest used to initialize the starting handshake
state. If the protocol names of two endpoints differs, then the handshake
process fails immediately.
## Authenticated Key Exchange Handshake Specification
The handshake proceeds in three acts, taking 1.5 round trips. Each handshake is
a _fixed_ sized payload without any header or additional meta-data attached.
The exact size of each Act is as follows:
* **Act One**: `50 bytes`
* **Act Two**: `50 bytes`
* **Act Three**: `66 bytes`
### Handshake State
Throughout the handshake process, each side maintains these three variables:
* `ck`: The **chaining key**. This value is the accumulated hash of all
previous ECDH outputs. At the end of the handshake, `ck` is used to derive
the encryption keys for transport messages.
* `h`: The **handshake hash**. This value is the accumulated hash of _all_
handshake data that has been sent and received so far during the handshake
process.
* `temp_k`: An **intermediate key** key used to encrypt/decrypt the
zero-length AEAD payloads at the end of each handshake message.
* `n`: A **counter-based nonce** which is to be used with `temp_k` to encrypt
each message with a new nonce.
* `e`: A party's **ephemeral public key**. For each session a node MUST generate a
new ephemeral key with strong cryptographic randomness.
* `s`: A party's **static public key**.
The following functions will also be referenced:
* `HKDF`: a function is defined in [3](#reference-3), evaluated with a zero-length `info`
field.
* `encryptWithAD(ad, plaintext)`: outputs `encrypt(k, n++, ad, plaintext)`
* where `encrypt` is an evaluation of `ChaChaPoly-Poly1305` with the
passed arguments.
* `decryptWithAD(ad, ciphertext)`: outputs `decrypt(k, n++, ad, ciphertext)`
* where `decrypt` is an evaluation of `ChaChaPoly-Poly1305` with the
passed arguments.
* `e = generateKey()`
* where generateKey generates a fresh secp256k1 keypair
* `a || b` denotes the concatenation of two byte strings `a` and `b`
### Handshake State Initialization
Before the start of the first act, both sides initialize their per-sessions
state as follows:
* `h = SHA-256(protocolName)`
* where `protocolName = "Noise_XK_secp256k1_ChaChaPoly_SHA256"` encoded as
an ascii string.
* `ck = h`
* `temp_k = empty`
* where `empty` is a byte string of length 32 fully zeroed out.
* `n = 0`
* `h = SHA-256(h || prologue)`
* where `prologue` is the ascii string: `lightning`.
As a concluding step, both sides mix the responder's public key into the
handshake digest:
* The initiating node mixes in the responding node's static public key
serialized in Bitcoin's DER compressed format:
* `h = SHA-256(h || rs.serializeCompressed())`
* The responding node mixes in their local static public key serialized in
Bitcoin's DER compressed format:
* `h = SHA-256(h || ls.serializeCompressed())`
### Handshake Exchange
#### Act One
```
-> e, es
```
Act One is sent from initiator to responder. During `Act One`, the initiator
attempts to satisfy an implicit challenge by the responder. To complete this
challenge, the initiator _must_ know the static public key of the responder.
The handshake message is _exactly_ `50 bytes`: `1 byte` for the handshake
version, `33 bytes` for the compressed ephemeral public key of the initiator,
and `16 bytes` for the `poly1305` tag.
**Sender Actions:**
* `e = generateKey()`
* `h = SHA-256(h || e.serializeCompressed())`
* The newly generated ephemeral key is accumulated into our running
handshake digest.
* `s = ECDH(e, rs)`
* The initiator performs a ECDH between its newly generated ephemeral key
with the remote node's static public key.
* `ck, temp_k = HKDF(ck, s)`
* This phase generates a new temporary encryption key (`temp_k`) which is
used to generate the authenticating MAC.
* `c = encryptWithAD(h, zero)`
* where `zero` is a zero-length plaintext
* `h = SHA-256(h || c)`
* Finally, the generated ciphertext is accumulated into the authenticating
handshake digest.
* Send `m = 0 || e || c` to the responder over the network buffer.
**Receiver Actions:**
* Read _exactly_ `50-bytes` from the network buffer.
* Parse out the read message (`m`) into `v = m[0]`, `e = m[1:34]` and `c = m[43:]`
* where `m[0]` is the _first_ byte of `m`, `m[1:33]` are the next `33`
bytes of `m` and `m[34:]` is the last 16 bytes of `m`
* If `v` is an unrecognized handshake version, then the the responder MUST
abort the connection attempt.
* `h = SHA-256(h || e.serializeCompressed())`
* Accumulate the initiator's ephemeral key into the authenticating
handshake digest.
* `s = ECDH(s, e)`
* The responder performs an ECDH between its static public key and the
initiator's ephemeral public key.
* `ck, temp_k = HKDF(ck, s)`
* This phase generates a new temporary encryption key (`temp_k`) which will
be used to shortly check the authenticating MAC.
* `p = decryptWithAD(h, c)`
* If the MAC check in this operation fails, then the initiator does _not_
know our static public key. If so, then the responder MUST terminate the
connection without any further messages.
* `h = SHA-256(h || c)`
* Mix the received ciphertext into the handshake digest. This step serves
to ensure the payload wasn't modified by a MiTM.
#### Act Two
```
<- e, ee
```
`Act Two` is sent from the responder to the initiator. `Act Two` will _only_
take place if `Act One` was successful. `Act One` was successful if the
responder was able to properly decrypt and check the `MAC` of the tag sent at
the end of `Act One`.
The handshake is _exactly_ `50 bytes:` `1 byte` for the handshake version, `33
bytes` for the compressed ephemeral public key of the initiator, and `16 bytes`
for the `poly1305` tag.
**Sender Actions:**
* `e = generateKey()`
* `h = SHA-256(h || e.serializeCompressed())`
* The newly generated ephemeral key is accumulated into our running
handshake digest.
* `s = ECDH(e, re)`
* where `re` is the ephemeral key of the initiator which was received
during `ActOne`.
* `ck, temp_k = HKDF(ck, s)`
* This phase generates a new temporary encryption key (`temp_k`) which is
used to generate the authenticating MAC.
* `c = encryptWithAD(h, zero)`
* where `zero` is a zero-length plaintext
* `h = SHA-256(h || c)`
* Finally, the generated ciphertext is accumulated into the authenticating
handshake digest.
* Send `m = 0 || e || c` to the initiator over the network buffer.
**Receiver Actions:**
* Read _exactly_ `50-bytes` from the network buffer.
* Parse out the read message (`m`) into `v = m[0]`, e = m[1:34]` and `c = m[43:]`
* where `m[0]` is the _first_ byte of `m`, `m[1:33]` are the next `33`
bytes of `m` and `m[34:]` is the last 16 bytes of `m`
* If `v` is an unrecognized handshake version, then the the responder MUST
abort the connection attempt.
* `h = SHA-256(h || e.serializeCompressed())`
* `s = ECDH(re, e)`
* where `re` is the responder's ephemeral public key.
* `ck, temp_k = HKDF(ck, s)`
* This phase generates a new temporary encryption key (`temp_k`) which is
used to generate the authenticating MAC.
* `p = decryptWithAD(h, c)`
* If the MAC check in this operation fails, then the initiator MUST
terminate the connection without any further messages.
* `h = SHA-256(h || c)`
* Mix the received ciphertext into the handshake digest. This step serves
to ensure the payload wasn't modified by a MiTM.
#### Act Three
```
-> s, se
```
`Act Three` is the final phase in the authenticated key agreement described in
this section. This act is sent from the initiator to the responder as a final
concluding step. `Act Three` is only executed `iff` `Act Two` was successful.
During `Act Three`, the initiator transports its static public key to the
responder encrypted with _strong_ forward secrecy using the accumulated `HKDF`
derived secret key at this point of the handshake.
The handshake is _exactly_ `66 bytes`: `1 byte` for the handshake version, `33
bytes` for the ephemeral public key encrypted with the `ChaCha20` stream
cipher, `16 bytes` for the encrypted public key's tag generated via the `AEAD`
construction, and `16 bytes` for a final authenticating tag.
**Sender Actions:**
* `c = encryptWithAD(h, s.serializeCompressed())`
* where `s` is the static public key of the initiator.
* `h = SHA-256(h || c)`
* `s = ECDH(s, re)`
* where `re` is the ephemeral public key of the responder.
* `ck, temp_k = HKDF(ck, s)`
* Mix the finaly intermediate shared secret into the running chaining key.
* `t = encryptWithAD(h, zero)`
* where `zero` is a zero-length plaintext
* `h = SHA-256(h || t)`
* `sk, rk = HKDF(ck, zero)`
* where `zero` is a zero-length plaintext,
`sk` is the key to be used by the initiator to encrypt messages to the
responder,
and `rk` is the key to be used by the initiator to decrypt messages sent by
the responder.
* This step generates the final encryption keys to be used for sending and
receiving messages for the duration of the session.
* Send `m = 0 || c || t` over the network buffer.
**Receiver Actions:**
* Read _exactly_ `66-bytes` from the network buffer.
* Parse out the read message (`m`) into `v = m[0]`, `c = m[1:50]` and `t = m[50:]`
* If `v` is an unrecognized handshake version, then the the responder MUST
abort the connection attempt.
* `rs = decryptWithAD(h, c)
* At this point, the responder has recovered the static public key of the
initiator.
* `h = SHA-256(h || rs.serializeCompressed())`
* `s = ECDH(e, rs)`
* where `e` is the responder's original ephemeral key
* `p = decryptWithAD(h, t)`
* If the MAC check in this operation fails, then the responder MUST
terminate the connection without any further messages.
* `rk, sk = HKDF(ck, zero)`
* where `zero` is a zero-length plaintext,
`rk` is the key to be used by the responder to decrypt the messages sent
by the responder,
and `sk` is the key to be used by the initiator to encrypt messages to
the responder,
* This step generates the final encryption keys to be used for sending and
receiving messages for the duration of the session.
## Transport Message Specification
At the conclusion of `Act Three` both sides have derived the encryption keys
which will be used to encrypt/decrypt messages for the remainder of the
session.
The *maximum* size of _any_ transport message MUST NOT exceed 65535 bytes. A
maximum payload size of 65535 simplifies testing and also makes memory
management and avoid exhaustion attacks easy. Note that the protocol messages
encapsulated in within the encrypted transport messages can be larger that the
maximum transport messages. If a party wishes to send a message larger then
65535 bytes, then they can simply partition the message into chunks less than
the maximum size, sending each of them sequentially. Messages which exceed the
max message size MUST be partitioned into chunks of size `65519 bytes`, in
order to leave room for the `16-byte` `MAC`.
In order to make make traffic analysis more difficult, then length prefix for
all encrypted transport messages is also encrypted. We additionally add a
`16-byte` `Poly-1305` tag to the encrypted length prefix in order to ensure
that the packet length hasn't been modified with in-flight, and also to avoid
creating a decryption oracle.
The structure of transport messages resembles the following:
```
+------------------------------
|2-byte encrypted packet length|
+------------------------------
| 16-byte MAC of the encrypted |
| packet length |
+------------------------------
| |
| |
| ciphertext |
| |
| |
+------------------------------
```
The prefixed packet lengths are encoded as a `16-byte` big-endian integer.
### Encrypting Messages
In order to encrypt a message (`m`), given a sending key (`sk`), and a nonce
(`n`), the following is done:
* let `l = len(m)`,
where `len` obtains the length in bytes of the message.
* Serialize `l` into `2-bytes` encoded as a big-endian integer.
* Encrypt `l` using `ChaChaPoly-1305`, `n`, and `sk` to obtain `lc`
(`18-bytes`)
* The nonce for `sk MUST be incremented after this step.
* Finally encrypt the message itself (`m`) using the same procedure used to
encrypt the length prefix. Let encrypted ciphertext be known as `c`.
* The nonce for `sk` MUST be incremented after this step.
* Send `lc || c` over the network buffer.
### Decrypting Messages
In order to decrypt the _next_ message in the network stream, the following is
done:
* Read _exactly_ `18-bytes` from the network buffer.
* Let the encrypted length prefix be known as `lc`
* Decrypt `lc` using `ChaChaPoly-1305`, `n`, and `rk` to obtain size of the
encrypted packet `l`.
* The nonce for `rk` MUST be incremented after this step.
* Read _exactly_ `l` bytes from the network buffer, let the bytes be known as
`c`.
* Decrypt `c` using `ChaChaPoly-1305`, `n`, and `rk` to obtain decrypted
plaintext packet `p`.
* The nonce for `rk` MUST be incremented after this step.
## Transport Message Key Rotation
Changing keys regularly and forgetting the previous key is useful for
preventing decryption of old messages in the case of later key leakage (ie.
backwards secrecy).
Key rotation is performed for _each_ key (`sk` and `rk`) _individually _. A key
is to be rotated after a party sends of decrypts `1000` messages with it.
This can be properly accounted for by rotating the key once the nonce dedicated
to it exceeds `1000`.
Key rotation for a key `k` is performed according to the following:
* Let `ck` be the chaining key obtained at the end of `Act Three`.
* `ck, k' = HKDF(ck, k)`
* The underscore indicates that only `32-bytes` are extracted from the
`HKDF`.
* Reset the nonce for the key to `n = 0`.
* `k = k'`
## Future Directions
Protocol messages may be padded out to the full maximum message length in order
to max traffic analysis even more difficult.
The initial handshake message may also be padded out to a fixed size in order
to obscure exactly which of the Noise handshakes is being executed.
In order to allow zero-RTT encrypted+authenticated communication, a Noise Pipes
protocol can be adopted which composes two handshakes, potentially falling back
to a full handshake if static public keys have changed.
## Initialization Message
Once authentication is complete, the first message reveals the
features supported or required by this node. Odd features are
optional, even features are compulsory ("it's OK to be odd!"). The
meaning of these bits will be defined in future.
1. type: 16 (MSG_INIT)
2. data: [4:len] [len:globalfeatures] [4:len] [len:localfeatures]
The 4-byte len fields indicate the number of bytes in the immediately
following field.
### Requirements
The sending node SHOULD use the minimum lengths required to represent
the feature fields. The sending node MUST set feature bits
corresponding to features is requires the peer to support, and SHOULD
set feature bits corresponding to features it optionally supports.
The receiving node MUST fail the channels if it receives a
`globalfeatures` or `localfeatures` with an even bit set which it does
not understand.
Each node MUST wait to receive MSG_INIT before sending any other
messages.
### Rationale
The even/odd semantic allows future incompatible changes, or backward
compatible changes. Bits should generally be assigned in pairs, so
that optional features can later become compulsory.
Nodes wait for receipt of the other's features to simplify error
diagnosis where features are incompatible.
## Error Message
For simplicity of diagnosis, it is often useful to tell the peer that
something is incorrect.
1. type: 17 (`MSG_ERROR`)
2. data: [8:channel-id] [4:len] [len:data]
The 4-byte len field indicates the number of bytes in the immediately
following field.
### Requirements
A node SHOULD send `MSG_ERROR` for protocol violations or internal
errors which make channels unusable or further communication unusable.
A node MAY send an empty [data] field. A node sending `MSG_ERROR` MUST
fail the channel referred to by the `channel-id`, or if `channel-id`
is 0xFFFFFFFFFFFFFFFF it MUST fail all channels and MUST close the
connection. A node MUST NOT set `len` to greater than the data length.
A node receiving `MSG_ERROR` MUST fail the channel referred to by
`channel-id`, or if `channel-id` is 0xFFFFFFFFFFFFFFFF it MUST fail
all channels and MUST close the connection. A receiving node MUST truncate `len` to the remainder of the packet if it is larger.
A receiving node SHOULD only print out `data` verbatim if it is a
valid string.
### Rationale
There are unrecoverable errors which require abort of conversations;
if the connection is simply dropped then the peer may retry
connection. It's also useful to describe protocol violations for
diagnosis, as it indicates that one peer has a bug.
It may be wise not to distinguish errors in production settings, lest
it leak information, thus the optional data field.
# Security Considerations #
It is strongly recommended that existing, commonly-used, validated
libraries be used for encryption and decryption, to avoid the many
implementation pitfalls possible.
## Acknowledgements
TODO(roasbeef); fin
# References
1. <a id="reference-1">https://en.bitcoin.it/wiki/Secp256k1</a>
2. <a id="reference-2">http://www.unicode.org/charts/PDF/U2600.pdf</a>
3. <a id="reference-3">https://tools.ietf.org/html/rfc7539</a>
4. <a id="reference-4">http://noiseprotocol.org/noise.html</a>
# Authors
FIXME

719
02-peer-protocol.md Normal file
View File

@ -0,0 +1,719 @@
# BOLT #2: Peer Protocol for Channel Management
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
operation.
+-------+ +-------+
| |--(1)-- open_channel ---->| |
| |<-(2)-- open_channel -----| |
| | | |
| |--(3)-- open_funding ---->| |
| A | | B |
| |<-(4)-- open_commit_sig ----| |
| | | |
| |--(5)-- open_complete ---->| |
| |<-(6)-- open_complete -----| |
+-------+ +-------+
If this fails at any stage, or a node decides that the channel terms
offered by the other node are not suitable, the channel establishment
fails.
## The `open_channel` message
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.
### Requirements
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
network. It MUST set `max-num-htlcs` to less than or equal to 300
[FIXME:LAOLU recalc?]. It SHOULD set `htlc-minimum-msat` to the minimum
amount HTLC it is willing to accept from this peer.
The receiving node MUST fail the channel if `to-self-delay` is
unreasonably large. The receiver MAY fail the channel if
`funding-satoshis` is too small, and MUST fail the channel if
`push-msat` is greater than `funding-amount` * 1000.
The receiving node MAY fail the channel if it considers
`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 300 [FIXME:LAOLU recalc?]
The receiver MUST fail the channel if
considers `feerate-per-kb` too small for timely processing. The
receiver MUST fail the channel if `funding-pubkey` or `commit-point`
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
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.
### 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
This message contains information about a node, and indicates its
acceptance of the new channel.
1. type: 33 (`MSG_ACCEPT_CHANNEL`)
2. data:
* [8:temporary-channel-id]
* [8:dust-limit-satoshis]
* [8:max-htlc-value-in-flight-msat]
* [8:channel-reserve-satoshis]
* [4:minimum-depth]
* [4:htlc-minimum-msat]
* [4:max-num-htlcs]
* [32:first-commitment-key-offset]
* [2:to-self-delay]
* [33:funding-pubkey]
* [33:HAKD base point]
* [33:Refund base point]
### 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.
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 `funding_created` message
This message describes the outpoint which the funder has created for
the initial commitment transactions. After receiving the peer's
signature, it will broadcast the funding transaction.
1. type: 34 (`MSG_FUNDING_CREATED`)
2. data:
* [8:temporary-channel-id]
* [32:txid]
* [2:output_index]
* [64:signature]
FIXME: describe
### Requirements
The recipient MUST fail the channel if the signature is invalid.
## 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.
1. type: 35 (`MSG_FUNDING_SIGNED`)
2. data:
* [8:temporary-channel-id]
* [64:signature]
### Requirements
FIXME: Describe
## 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.
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
from this point onwards.
### Requirements
FIXME: Describe
### Future
We could add an SPV proof, and route block hashes in separate
messages.
## 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
commitment transaction, then (once acknowledged) committed to the
sender's. Unlike an HTLC, `update_fee` is never closed, simply
replaced.
There is a possibility of a race: the recipient can add new HTLCs
before it receives the `update_fee`, and the sender may not be able to
afford the fee on its own commitment transaction once the `update_fee`
is acknowledged by the recipient. In this case, the fee will be less
than the fee rate.
The exact calculation used for deriving the fee from the fee rate is
given in [BOLT #3].
1. type: 37 (`MSG_UPDATE_FEE`)
2. data:
* [8:channel-id]
* [4:fee-per-kilobyte]
### 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
timely processing of the commitment transaction by a significant
margin.
The node which is not responsible for paying the bitcoin fee MUST NOT
send `update_fee`.
A receiving node SHOULD fail the channel if the `update_fee` is too
low for timely processing.
A receiving node MUST fail the channel if the sender is not
responsible for paying the bitcoin fee.
A receiving node SHOULD fail the channel if the sender cannot afford
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
Bitcoin fees are required for unilateral closes to be effective,
particularly since there is no general method for the node which
broadcasts it to use child-pays-for-parent to increase its effective
fee.
Given the variance in fees, and the fact that the transaction may be
spent in the future, it's a good idea for the fee payer to keep a good
margin, say 5x the expected fee requirement, but differing methods of
fee estimation mean we don't specify an exact value.
Since the fees are currently one-sided (the party which requested the
channel creation always pays the fees), it is simplest to only allow
them to set fee levels.
## Channel Close
Nodes can negotiate a mutual close for the connection, which unlike a
unilateral close, allows them to access their funds immediately and
can be negotiated with lower fees.
Closing happens in two stages: the first is by one side indicating
that it wants to clear the channel (and thus will accept no new
HTLCs), and once all HTLCs are resolved, the final channel close
negotiation begins.
+-------+ +-------+
| |--(1)----- shutdown ------->| |
| |<-(2)----- shutdown --------| |
| | | |
| | <complete all pending htlcs> | |
| A | ... | B |
| | | |
| |<-(3)-- close_signature F1----| |
| |--(4)-- close_signature F2--->| |
| | ... | |
| |--(?)-- close_signature Fn--->| |
| |<-(?)-- close_signature Fn----| |
+-------+ +-------+
## 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.
1. type: 38 (`MSG_SHUTDOWN`)
2. data:
* [8:channel-id]
* [4:len]
* [len:scriptpubkey]
### 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.
A node MUST NOT send an `update_add_htlc` after a `shutdown`,
and MUST NOT send more than one `shutdown`. A sending node
SHOULD fail to route any HTLC added after it sent `shutdown`.
A sending node MUST set `scriptpubkey` to one of the following forms:
1. `OP_DUP` `OP_HASH160` `20` 20-bytes `OP_EQUALVERIFY` `OP_CHECKSIG`
(pay to pubkey hash), OR
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`.
### 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;
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.
## 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
negotiation begins. Each node chooses a fee it thinks is fair, and
signs the close transaction with the `script_pubkey` fields from the
`shutdown` messages and that fee, and sends the signature. The
process terminates when both agree on the same fee, or one side fails
the channel.
1. type: 39 (`MSG_CLOSE_SIGNATURE`)
2. data:
* [8:channel-id]
* [8:fee-satoshis]
* [64:signature]
### Requirements
Nodes SHOULD send a `close_signature` message after `shutdown` has
been received and no HTLCs remain in either commitment transaction.
A sending node MUST set `fee-satoshis` lower than or equal to the
fee of the final commitment transaction.
The sender SHOULD set the initial `fee-satoshis` according to its
estimate of cost of inclusion in a block.
The sender MUST set `signature` to the bitcoin signature of the close
transaction with the node responsible for paying the bitcoin fee
paying `fee-satoshis`, without populating any output which is below
the receiver's `dust-limit-satoshis`.
The receiver MUST check `signature` is valid for the close transaction
with the given `fee-satoshis` as detailed above, and MUST fail the
connection if it is not.
If the receiver agrees with the fee, it SHOULD reply with a
`close_signature` with the same `fee-satoshis` value, otherwise it
SHOULD propose a value strictly between the received `fee-satoshis`
and its previously-sent `fee-satoshis`.
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
Note that there is limited risk if the closing transaction is
delayed, and it will be broadcast very soon, so there is usually no
reason to pay a premium for rapid processing.
## Normal Operation
Once both nodes have exchanged `funding_locked`, the channel can be
used to make payments via Hash TimeLocked Contracts.
Changes are sent in batches: one or more `update` messages are sent before a
`commit_sig` message, as in the following diagram:
+-------+ +-------+
| |--(1)---- add_htlc ------>| |
| |--(2)---- add_htlc ------>| |
| |<-(3)---- add_htlc -------| |
| | | |
| |--(4)---- commit ------>| |
| A | | B |
| |<-(5)---- revocation -------| |
| |<-(6)---- commit -------| |
| | | |
| |--(7)---- revocation ------>| |
+-------+ +-------+
Counterintuitively, these updates apply to the *other node's*
commitment transaction; the node only adds those updates to its own
commitment transaction when the remote node acknowledges it has
applied them.
Thus each update traverses through the following states:
1. Pending on the receiver
2. In the receiver's latest commitment transaction,
3. ... and the receiver's previous commitment transaction has been revoked,
and the HTLC is pending on the sender.
4. ... and in the sender's latest commitment transaction
5. ... and the sender's previous commitment transaction has been revoked
As the two nodes updates are independent, the two commitment
transactions may be out of sync indefinitely. This is not concerning:
what matters is whether both sides have irrevocably committed to a
particular HTLC or not (the final state, above).
## Risks With HTLC Timeouts
HTLCs tend to be chained across the network. For example, a node A
might offer node B an HTLC with a timeout of 3 days, and node B might
offer node C the same HTLC with a timeout of 2 days.
This difference in timeouts is important: after 2 days B can try to
remove the offer to C even if C is unresponsive, by broadcasting the
commitment transaction it has with C and spending the HTLC output.
Even though C might race to try to use its payment preimage at that point to
also spend the HTLC, it should be resolved well before the 3 day
deadline so B can either redeem the HTLC off A or close it.
If the timing is too close, there is a risk of "one-sided redemption",
where the payment preimage received from an offered HTLC is too late
to be used for an incoming HTLC, leaving the node with unexpected
liability.
Thus the effective timeout of the HTLC is the `expiry`, plus some
additional delay for the transaction which redeems the HTLC output to
be irreversibly committed to the blockchain.
Thus a node MUST estimate the deadline for successful redemption for
each HTLC it offers. A node MUST NOT offer a HTLC after this
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
Either node can send `update_add_htlc` to offer a HTLC to the other,
which is redeemable in return for a payment preimage. Amounts are in
millisatoshi, though on-chain enforcement is only possible for whole
satoshi amounts greater than the dust limit: in commitment transactions these are rounded down as
specified in [BOLT #3].
The format of the `route` portion, which indicates where the payment
is destined, is described in [BOLT #4].
1. type: 128 (`MSG_UPDATE_ADD_HTLC`)
2. data:
* [8:channel-id]
* [8:id]
* [4:amount-msat]
* [4:expiry]
* [32:payment-hash]
* [1254:onion-routing-packet]
### 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
Fees") while maintaining its channel reserve, and MUST offer
`amount-msat` greater than 0, and MUST NOT offer `amount-msat` below
the receiving node's `htlc-minimum-msat`.
A sending node MUST NOT add an HTLC if it would result in it offering
more than the remote's `max-num-htlcs` HTLCs in the remote commitment
transaction.
A sending node MUST set `id` to 0 for the first HTLC it offers, and
increase the value by 1 for each successive offer.
A receiving node SHOULD fail the channel if it receives an
`amount-sat` equal to zero, below its own `htlc-minimum-msat`, or
which the sending node cannot afford at the current `fee-rate` while
maintaining its channel reserve. A receiving node SHOULD fail the
channel if a sending node adds more than its `max-num-htlcs` HTLCs to
its local commitment transaction.
A receiving node MUST allow multiple HTLCs with the same payment hash.
A receiving node MUST ignore a repeated `id` value after a
reconnection if it has the sender did not previously acknowledge the
commitment of that HTLC. A receiving node MAY fail the channel if
other `id` violations occur.
### Rationale
Invalid amounts are a clear protocol violation and indicate a
breakdown.
If a node did not accept multiple HTLCs with the same payment hash, an
attacker could probe to see if a node had an existing HTLC. This
requirement deal with duplicates leads us to using a separate
identifier; we assume a 64 bit counter never wraps.
Retransmissions of unacknowledged updates are explicitly allowed for
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`
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
failed to route, or the payment preimage is supplied.
The `reason` field is an opaque encrypted blob for the benefit of the
original HTLC initiator as defined in [BOLT #4].
1. type: 130 (`MSG_UPDATE_FULFILL_HTLC`)
2. data:
* [8:channel-id]
* [8:id]
* [32:payment-preimage]
For a timed out or route-failed HTLC:
1. type: 131 (`MSG_UPDATE_FAIL_HTLC`)
2. data:
* [8:channel-id]
* [8:id]
* [FIXME:CDECKER/LAOLU:reason]
### Requirements
A node SHOULD remove an HTLC as soon as it can; in particular, a node
SHOULD fail an HTLC which has timed out.
A receiving node MUST check that `id` corresponds to an HTLC in its
current commitment transaction, and MUST fail the channel if it does
not.
A receiving node MUST check that the `payment-preimage` value in
`update-fulfill_htlc` SHA256 hashes to the corresponding HTLC
`payment-hash`, and MUST fail the channel if it does not.
A receiving node which closes an incoming HTLC in response to an
`update-fail-htlc` message on an offered HTLC MUST copy the `reason`
field to the outgoing `update-fail-htlc`.
### Rationale
A node which doesn't time out HTLCs it risks channel failure (see
"Risks With HTLC Timeouts").
## Committing Updates So Far: `commitsig`
When a node has changes for the remote commitment, it can apply them,
sign the resulting transaction as defined in [BOLT #3] and send a
`commitsig` message.
1. type: 132 (`MSG_COMMIT_SIG`)
2. data:
* [8:channel-id]
* [64:signature]
* [4:num-htlcs]
* [num-htlcs*64:htlc-signature]
## Requirements
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.
## Rationale
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`
Once the recipient of `commitsig` checks the signature, it knows that
it has a valid new commitment transaction, replies with the commitment
preimage for the previous commitment transaction in a `revocation`
message.
This message also implicitly serves as an acknowledgement of receipt
of the `commitsig`, so it's a logical time for the `commitsig` sender
to apply to its own commitment, any pending updates it sent before
that `commitsig`.
This message also supplies the signatures for the sender's HTLC-timeout transactions. See FIXME for how this is used with a penalty transaction.
The description of key derivation is in [BOLT #3: Key Derivation FIXME].
1. type: 133 (`MSG_REVOCATION`)
2. data:
* [8:channel-id]
* [32:per-commitment-secret]
* [32:next-key-offset]
* [33:next-revocation-halfkey]
* [4:num-htlc-timeouts]
* [num-htlc-timeouts*64:htlc-timeout-signature]
### Requirements
A sending node MUST set `per-commitment-secret` to the secret used to generate keys for the
previous commitment transaction, and must set `next-key-offset` and `next-revocation-halfkey` to the values for its next commitment 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 [FIXME].
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. A receiving node MAY fail the channel if the `revocation-key` was not
generated as specified in "Commitment Key Generation"[FIXME] below.
Nodes MUST NOT broadcast old (revoked) commitment transactions; doing
so will allow the other node to seize all the funds. Nodes SHOULD NOT
sign commitment transactions unless it is about to broadcast them (due
to a failed connection), to reduce this risk.
# Authors
FIXME

170
03-transactions.md Normal file
View File

@ -0,0 +1,170 @@
# BOLT #3: Bitcoin Transaction and Script Formats
This details the exact format of on-chain transactions, which both sides need to agree on to ensure signatures are valid. That is, the funding transaction output script, commitment transactions and the HTLC transactions.
## Transaction input and output ordering
Lexicographic ordering as per BIP 69.
## Funding Transaction Output
* The funding output script is a pay-to-witness-script-hash [FIXME: reference BIP] to:
* 0 2 <key1> <key2> 2 OP_CHECKMULTISIG
* Where <key1> is the numerically lesser of the two DER-encoded `funding-pubkey` and <key2> is the greater.
## Commitment Transaction
* version: 2
* locktime: lower 24 bits are the commitment transaction number.
* txin count: 1
* txin[0] outpoint: `txid` and `output_index` from `funding_created` message
* txin[0] sequence: lower 24 bits are upper 24 bits of commitment transaction number.
* txin[0] script bytes: 0
* txin[0] witness: `<signature-for-key1>` `<signature-for-key-2>`
### Commitment Transaction Outputs
The amounts for each output are rounded down to whole satoshis. If this amount is less than the `dust-limit-satoshis` set by the owner of the commitment transaction, the output is not produced (thus the funds add to fees).
To allow an opportunity for penalty transactions in case of a revoked commitment transaction, all outputs which return funds to the owner of the commitment transaction (aka "local node") must be delayed for `to-self-delay` blocks. This delay is done in a second stage HTLC transaction.
The reason for the separate transaction stage for HTLC outputs is so that HTLCs can time out or be fulfilled even though they are within the `to-self-delay` `OP_CHECKSEQUENCEVERIFY` delay. Otherwise the required minimum timeout on HTLCs is lengthened by this delay, causing longer timeouts for HTLCs traversing the network.
#### To-Local Output
This output sends funds back to the owner of this commitment transaction (ie. `<localkey>`), thus must be timelocked using OP_CSV. The output is a version 0 P2WSH, with a witness script:
to-self-delay OP_CHECKSEQUENCEVERIFY OP_DROP <localkey> OP_CHECKSIG
It is spent by a transaction with nSequence field set to `to-self-delay` (which can only be valid after that duration has passed), and witness script `<localsig>`.
#### To-Remote Output
This output sends funds to the other peer, thus is a simple P2PKH to `<remotekey>`.
#### Offered HTLC Outputs
This output sends funds to a HTLC-timeout transaction after the HTLC timeout, or to the remote peer on successful payment preimage. The output is a P2WSH, with a witness script:
emotekey> OP_SWAP
OP_SIZE 32 OP_EQUAL
OP_NOTIF
# To me via HTLC-timeout tx (timelocked).
OP_DROP 2 OP_SWAP <localkey> 2 OP_CHECKMULTISIGVERIFY
OP_ELSE
# To you with preimage.
OP_HASH160 <ripemd-of-payment-hash> OP_EQUALVERIFY
OP_CHECKSIGVERIFY
OP_ENDIF
The remote node can redeem the HTLC with the scriptsig:
<remotesig> <payment-preimage>
Either node can use the HTLC-timeout transaction to time out the HTLC once the HTLC is expired, as show below.
#### Received HTLC Outputs
This output sends funds to the remote peer after the HTLC timeout, or to an HTLC-success transaction with a successful payment preimage. The output is a P2WSH, with a witness script:
<remotekey> OP_SWAP
OP_SIZE 32 OP_EQUAL
OP_IF
# To me via HTLC-success tx.
OP_HASH160 <ripemd-of-payment-hash> OP_EQUALVERIFY
2 OP_SWAP <localkey> 2 OP_CHECKMULTISIGVERIFY
OP_ELSE
# To you after timeout.
OP_DROP <locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP
OP_CHECKSIGVERIFY
OP_ENDIF
To timeout the htlc, the local node spends it with the scriptsig:
<remotesig> 0
To redeem the HTLC, the HTLC-success transaction is used as detailed below.
## HTLC-Timeout and HTLC-Success Transaction
These HTLC transactions are almost identical, except the HTLC-Timeout transaction is timelocked. This is also the transaction which can be spent by a valid penalty transaction.
* version: 2
* txin: the commitment transaction HTLC output.
* locktime: 0 for HTLC-Success, `htlc-timeout` for HTLC-Timeout.
* txin count: 1
* txin[0] outpoint: `txid` of the commitment transaction and `output_index` of the matching HTLC output for the HTLC transaction.
* txin[0] sequence: 0
* txin[0] script bytes: 0
* txin[0] witness stack: `<localsig> <remotesig> 0` (HTLC-Timeout) or `<localsig> <remotesig> <payment-preimage>` (HTLC-success).
* txout count: 1
* txout[0] amount: the HTLC amount minus fees (see below)
* txout[0] script: version 0 P2WSH with witness script:
OP_IF
# Penalty transaction
<revocation pubkey>
OP_ELSE
`to-self-delay`
OP_CSV
OP_DROP
<localkey>
OP_ENDIF
OP_CHECKSIG
To spend this via penalty, the remote node uses a witness stack `<revocationsig> 1` and to collect the output the local node uses an input with nSequence `to-self-delay` and a witness stack `<localsig> 0`
# Key Derivation
Each commitment transaction uses a unique set of keys; <localkey>, <remotekey> and <revocationkey>. Changing the <localkey> and <remotekey> every time ensures that commitment txids cannot be determined by a third party even it knows another commitment transaction, which helps preserve privacy in the case of outsourced penalties. The <revocationkey> is generated such that the remote node is the only one in possession of the secret key once the commitment transaction has been revoked.
For efficiency, keys are generated from a series of per-commitment secrets which are generated from a single seed, allowing the receiver to compactly store them (see [FIXME]).
### localkey and remotekey Derivation
The localkey for a commitment transaction is generated by EC addition of the local `refund base point` and the current local `key-offset` multiplied by G (eg. secp256k1_ec_pubkey_tweak_add() from libsecp256k1). The local node knows the secret key corresponding to `refund base point` so can similarly derive the secret key for `localkey`.
The `key-offset` is generated using HMAC(`per-commit-secret`, “R”) [FIXME: more detail!].
The remotekey is generated the same way, using the remote `refund base point` and the current `key-offset` from the remote node: this is given by `first-key-offset` (for the initial commitment transaction) and `next-key-offset` for successive transactions.
### revocationkey Derivation
The local revocation key is derived from both the remote `HAKD basepoint` and a key derived from the local per-commit secret, called the “revocation-halfkey”.
The secret key for the `revocation-halfkey` is HMAC(`per-commit-secret`, “T”) [FIXME: more detail!]. The public key corresponding to this secret key is `revocation-halfkey`. Elliptic curve point addition of `revocation-halfkey` and `HAKD basepoint` gives the `revocationkey`.
Upon revocation, the per-commit secret is revealed to the remote node: this allows it to derive the secret key for `revocation-halfkey`, and it already knows the secret key corresponding to the `HAKD basepoint` so it can derive the secret key corresponding to `revocationkey`.
### Per-commitment Secret Requirements
A node MUST select an unguessable 256-bit seed for each connection,
and MUST NOT reveal the seed. Up to 2^48-1 per-commitment secrets can be
generated; the first secret used MUST be index 281474976710655, and
then the index decremented.
The psecret P for index N MUST match the output of this algorithm:
generate_from_seed(seed, N):
P = seed
for B in 0 to 47:
if B set in N:
flip(B) in P
P = SHA256(P)
return P
Where "flip(B)" alternates the B'th least significant bit in the value P.
The receiving node MAY store all previous R values, or MAY calculate
it from a compact representation as described in [FIXME].
# References
# Authors
FIXME

2
04-onion-routing.md
View File

@ -1,4 +1,4 @@
# Onion Routing Protocol for Lightning
# BOLT #4: Onion Routing Protocol
## Overview

334
05-onchain.md Normal file
View File

@ -0,0 +1,334 @@
# BOLT #5: Recommendations for On-chain Transaction Handling
## Abstract
Lightning allows for two parties (A and B) to make transactions off-chain, by both holding a cross-signed *commitment transaction*, which describes the current state of the channel (basically the current balance). This *commitment transaction* is updated everytime a new payment is made, and is spendable at all times.
There are three ways a channel can end:
1. The good way (*mutual close*): at some point A and B agree on closing the channel, they generate a *closing transaction* (which is similar to a *commitment transaction* without any pending payments), and publish it on the blockchain (see "BOLT #2: Channel close").
2. The bad way (*unilateral close*): something goes wrong, without necessarily any evil intent on either side (maybe one of the party crashed, for instance). Anyway, one side publishes its latest *commitment transaction*.
3. The ugly way (*revoked transaction close*): one of the parties deliberately tries to cheat by publishing an outdated version of its *commitment transaction* (presumably one that was more in her favor).
Because Lightning is designed to be trustless, there is no risk of loss of funds in any of these 3 cases, provided that the situation is properly handled. The goal of this document is to explain exactly how node A should react to seeing any of these on-chain.
## Table of Contents
TODO
# General Nomenclature
We consider any unspent output to be *unresolved*, and *resolve* them
as detailed in this document. Usually this means spending it with
another *resolving* transaction. Sometimes it simply means noting it
for later wallet spending, in which case the transaction containing
the output is considered to be its own *resolving* transaction.
Outputs which are *resolved* are considered *irrevocably resolved*
once their *resolving* transaction is included in a block at least 100
deep on the most-work blockchain. 100 blocks is far greater than the
longest known bitcoin fork, and the same value used to wait for
confirmations of miner's rewards[FIXME: ref].
## Requirements
Once a node has broadcast a funding transaction or sent a commitment
signature for a commitment transaction which contains an HTLC output,
it MUST monitor the blockchain for transactions which spend any output
which is not *irrevocably resolved* until all outputs are *irrevocably
resolved*.
A node MUST *resolve* all outputs as specified below, and MUST be
prepared to resolve them multiple times in case of blockchain
reorganizations.
A node SHOULD fail the channel if it is not already closed when it
sees the funding transaction spent. A node MAY send a descriptive
error packet in this case.
Invalid transactions SHOULD be ignored.
## Rationale
Once a node has had some money at stake, monitoring is required to
ensure the other side does not close unilaterally.
Invalid transactions (eg. bad signatures) can be generated by anyone,
(and will be ignored by the blockchain anyway), so they should not
trigger any action.
# Commitment Transaction
A and B each hold a *commitment transaction*, which has 4 types of outputs:
1. _A's main output_: Zero or one outputs which pay to A's commitment key.
2. _B's main output_: Zero or one outputs which pay to B's commitment key.
3. _A's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay B in return for a payment preimage.
4. _B's offered HTLCs_: Zero or more pending payments (*HTLCs*) to pay A in return for a payment preimage.
As an incentive for A and B to cooperate, an `OP_CHECKSEQUENCEVERIFY` relative timeout encumbers A's outputs in A's *commitment transaction*, and B's outputs in B's *commitment transaction*. If A publishes its commitment tx, she won't be able to get her funds immediately but B will. As a consequence, A and B's *commitment transactions* are not identical, they are (usually) symmetrical.
See "BOLT #3: Bitcoin Transaction and Script Formats" for more details.
# Mutual Close Handling
A mutual close transaction *resolves* the funding transaction output.
A node doesn't need to do anything else as it has already agreed to the
output, which is sent to its specified scriptpubkey (see BOLT #2 "Closing initiation: `shutdown`").
# Unilateral Close Handling
There are two cases to consider here: in the first case, node A sees
its own *commitment transaction*, in the second, it sees the node B's unrevoked
*commitment transaction*.
Either transaction *resolves* the funding transaction output.
## Requirements
When node A sees its own *commitment transaction*:
1. _A's main output_: A node SHOULD spend this output to a convenient address.
A node MUST wait until the `OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other
node's `to-self-delay` field) before spending the output. If the
output is spent (as recommended), the output is *resolved* by the spending
transaction, otherwise it is considered *resolved* by the *commitment transaction* itself.
2. _B's main output_: No action required, this output is considered *resolved*
by the *commitment transaction* utself.
3. _A's offered HTLCs_: See "On-chain HTLC Output Handling: Our Offers" below.
4. _B's offered HTLCs_: See "On-chain HTLC Output Handling: Their Offers" below.
Similarly, when node A sees a *commitment transaction* from B:
1. _A's main output_: No action is required; this is a simple P2WPKH output.
This output is considered *resolved* by the *commitment tx* itself.
2. _B's main output_: No action required, this output is considered *resolved*
by the *commitment tx*.
3. _A's offered HTLCs_: See "On-chain HTLC Output Handling: Our Offers" below.
4. _B's offered HTLCs_: See "On-chain HTLC Output Handling: Their Offers" below.
A node MUST handle the broadcast if any valid *commitment transaction*
from B in this way.
## Rationale
Spending the to-self output avoids having to remember the complicated
witness script associated with that particular channel for later
spending.
Note that there can be more than one valid, unrevoked *commitment
transaction* after a signature has been received via `commitsig` and
before the corresponding `revocation`. Either commitment can serve as
B's *commitment transaction*, hence the requirement to handle both.
# On-chain HTLC Output Handling: Our Offers
Each HTLC output can only be spent by us after it's timed out,
or them if they have the payment preimage.
The HTLC has *timed out* once the depth of the latest block is equal
or greater than the HTLC `expiry`.
## Requirements
If the HTLC output is spent using the payment preimage, the HTLC
output is considered *irrevocably resolved*, and the node MUST extract
the payment preimage from the transaction input witness.
If the HTLC output has *timed out* and not been *resolved*, the node
MUST *resolve* the output by spending it using the HTLC-timeout
transaction. The HTLC-timeout transaction output MUST be *resolved*
as described in "On-chain HTLC Transaction Handling".
## Rationale
If the commitment transaction is theirs, the only way to spend the
HTLC output using a payment preimage is for them to use the
HTLC-success transaction. If the commitment transaction is ours, they
could create any transaction using the primage.
The payment preimage either serves to prove payment (if this node
originated the payment), or to redeem the corresponding incoming HTLC
from another peer. Note that we don't care about the fate of the
HTLC-spending transaction itself once we've extracted the payment
preimage; the knowledge is not revocable.
Note that in cases where both resolutions are possible (payment
success seen after timeout, for example), either interpretation is
acceptable; it is the responsibility of the other node spend it
before this occurs.
# On-chain HTLC Output Handling: Their Offers
Each HTLC output can only be spent by us if we have the payment
preimage, or them if it has timed out.
## Requirements
If the node receives (or already knows) a payment preimage for an
unresolved HTLC output it was offered, it MUST *resolve* the output by
spending it. If this is done using the HTLC-success transaction, the
HTLC-success transaction output MUST be *resolved* as described in
"On-chain HTLC Transaction Handling".
Otherwise, if the HTLC output has expired, it is considered
*irrevocably resolved*.
## Rationale
If this is our commitment transaction, we can only use a payment
preimage with the HTLC-success transaction (which preserves the
`to-self` delay). Otherwise we can create any transaction we want to
resolve it.
We don't care about expired offers: we should have ensured that the
HTLC can only expire long it is needed.
# On-chain HTLC Transaction Handling
Because to-self payments have to be delayed (to allow time for a
penalty transaction), HTLC outputs can only be spent by the node which
broadcast the *commitment transaction* using the HTLC-timeout or the
HTLC-success transaction, which include that delay.
## Requirements
A node SHOULD resolve its own HTLC transaction output by spending it
to a convenient address. A node MUST wait until the
`OP_CHECKSEQUENCEVERIFY` delay has passed (as specified by the other
node's `open_channel` `to-self-delay` field) before spending the
output.
If the output is spent (as recommended), the output is *resolved* by
the spending transaction, otherwise it is considered *resolved* by the
*commitment transaction* itself.
## Rationale
Spending the to-self output avoids having to remember the complicated
witness script associated with that particular channel for later
spending.
# Revoked Transaction Close Handling
If a node tries to broadcast old state, we can use the revocation key
to claim all the funds.
## Requirements
A node MUST NOT broadcast a *commitment transaction* for which it has
exposed the revocation key.
If a node sees a *commitment transaction* for which it has a
revocation key, that *resolves* the funding transaction output.
A node MUST resolve all unresolved outputs as follows:
1. _A's main output_: No action is required; this is a simple P2WPKH output.
This output is considered *resolved* by the *commitment transaction*.
2. _B's main output_: The node MUST *resolve* this by spending using the
revocation key.
3. _A's offered HTLCs_: The node MUST *resolve* this in one of two ways: either by spending using the payment preimage if known, or spending using B’s HTLC-timeout transaction.
4. _B's offered HTLCs_: The node MUST *resolve* this by spending once the HTLC timeout has passed.
5. _B's HTLC-timeout transaction_: The node MUST *resolve* this by
spending using the revocation key.
6. _B's HTLC-success transaction_: The node MUST *resolve* this by
spending using the revocation key. The node SHOULD extract
the payment preimage from the transaction input witness if not
already known.
The node MAY use a single transaction to *resolve* all the outputs, but MUST handle its transactions being invalidated by HTLC transactions.
## Rationale
A single transaction which resolves all the outputs will be under the
standard size limit thanks to the [FIXME] HTLC-per-party limit (See
BOLT #2: FIXME).
Note that if a single transaction is used, it may be invalidated as B
broadcasts HTLC-timeout and HTLC-success transactions, but the
requirement that we persist until all outputs are irrevocably resolved
should cover this. [FIXME: May have to divide and conquer here, since they may be able to delay us long enough to avoid successful penalty spend? ]
# General Requirements
A node SHOULD report an error to the operator if it sees a transaction
spend the funding transaction output which does not fall into one of
these categories (mutual close, unilateral close, or revoked
transaction close). Such a transaction implies its private key has
leaked, and funds may be lost.
A node MAY simply watch the contents of the most-work chain for
transactions, or MAY watch for (valid) broadcast transactions a.k.a
mempool. Considering mempool transactions should cause lower latency
for HTLC redemption, but on-chain HTLCs should be such an unusual case
that speed cannot be considered critical.