In this chapter, we'll dive into the wire protocol of the Lightning network,
and also cover all the various extensibility levers that have been built into
@ -10,7 +10,7 @@ to being able to write a custom wire protocol parser, a reader of this chapter
will gain a deep understanding with respect of the various upgrade mechanisms
that have been built into the protocol.
## Wire Framing
== Wire Framing
First, we being by describing the high level structure of the wire _framing_
within the protocol. When we say framing, we mean the way that the bytes are
@ -30,7 +30,7 @@ framing, we assume the encryption layer has already been stripped away (when
decoding), or that we haven't yet encrypted the set of bytes before we send
them on the wire (encoding).
### High-Level Wire Framing
=== High-Level Wire Framing
With that said, we're ready to being describe the high-level schema used to
encode messages on the wire:
@ -58,7 +58,7 @@ nodes are able to provide information in the wire messages that older nodes
feature combined with a very flexible wire message extensibility format also
allows the protocol to achieve _forwards_ compatibility as well.
### Type Encoding
=== Type Encoding
With this high level background provided, we'll now start at the most primitive
layer: parsing primitive types. In addition to encoding integers, the Lightning
@ -73,30 +73,31 @@ encoding/decode any of the higher level types.
In the following table, we'll map the higher-level name of a given type to the
high-level routine used to encode/decode the type.
// TODO(roasbeef): finish
| High Level Type | Framing | Comment |
| --------------- | ------- | ------- |
| `node_alias` | A 32-byte fixed-length byte slice. | When decoding, reject if contents are not a valid UTF-8 string. |
| `channel_id` | A 32-byte fixed-length byte slice that maps an outpoint to a 32 byte value. | Given an outpoint, one can convert it to a `channel_id` by taking the txid of the outpoint and XOR'ing it with the index (interpreted as the lower 2 bytes). |
| `short_chan_id` | An unsigned 64-bit integer (`uint64`) | Composed of the block height (24 bits), transaction index (24 bits), and output index (16 bits) packed into 8 bytes. |
| `milli_satoshi` | An unsigned 64-bit integer (`uint64`) | Represents 1000th of a satoshi. |
| `satoshi` | An unsigned 64-bit integer (`uint64`) | The based unit of bitcoin. |
| `satoshi` | An unsigned 64-bit integer (`uint64`) | The based unit of bitcoin. |
| `pubkey` | An secp256k1 public key encoded in _compressed_ format, occupying 33 bytes. | Occupies a fixed 33-byte length on the wire. |
| `sig` | An ECDSA signature of the secp256k1 Elliptic Curve. | Encoded as a _fixed_ 64-byte byte slice, packed as `R || S`. |
| `uint8` | An 8-bit integer. | |
| `uint16` | A 16-bit integer. ||
| `uint64` | A 64-bit integer. ||
| `[]byte` | A variable length byte slice. | Prefixed with a 16-bit integer denoting the length of the bytes. |
| `color_rgb` | RGB color encoding. | Encoded as a series if 8-bit integers. |
| `net_addr` | The encoding of a network address. | Encoded with a 1 byte prefix that denotes the type of address, followed by the address body. |
| `node_alias` | A 32-byte fixed-length byte slice. | When decoding, reject if contents are not a valid UTF-8 string.
| `channel_id` | A 32-byte fixed-length byte slice that maps an outpoint to a 32 byte value. | Given an outpoint, one can convert it to a `channel_id` by taking the txid of the outpoint and XOR'ing it with the index (interpreted as the lower 2 bytes).
| `short_chan_id` | An unsigned 64-bit integer (`uint64`) | Composed of the block height (24 bits), transaction index (24 bits), and output index (16 bits) packed into 8 bytes.
| `milli_satoshi` | An unsigned 64-bit integer (`uint64`) | Represents 1000th of a satoshi.
| `satoshi` | An unsigned 64-bit integer (`uint64`) | The based unit of bitcoin.
| `satoshi` | An unsigned 64-bit integer (`uint64`) | The based unit of bitcoin.
| `pubkey` | An secp256k1 public key encoded in _compressed_ format, occupying 33 bytes. | Occupies a fixed 33-byte length on the wire.
| `sig` | An ECDSA signature of the secp256k1 Elliptic Curve. | Encoded as a _fixed_ 64-byte byte slice, packed as `R \|\| S`
| `uint8` | An 8-bit integer. |
| `uint16` | A 16-bit integer. |
| `uint64` | A 64-bit integer. |
| `[]byte` | A variable length byte slice. | Prefixed with a 16-bit integer denoting the length of the bytes.
| `color_rgb` | RGB color encoding. | Encoded as a series if 8-bit integers.
| `net_addr` | The encoding of a network address. | Encoded with a 1 byte prefix that denotes the type of address, followed by the address body.
Olaoluwa Osuntokun
3 years ago