Wire protocol: framing and extensibility

Underneath every channel, invoice and onion, Lightning nodes exchange plain messages: a few bytes with a fixed layout, sent over an encrypted link (next lesson).

A message, byte by byte

Every message starts with a 2-byte type, big-endian, then the fields for that type. The first message on every connection is init, type 16:

0010          type = 16 (init)
0000          gflen = 0       (length of the old "global features")
0003          flen  = 3       (length of the features field)
0a69a2        features        (a bit field)
0120 0606…    TLV stream      (optional extra records)

Feature bits: "it's OK to be odd"

Each feature has a pair of bits. The even bit means "I require this; disconnect if you don't support it". The odd bit means "I support this, but it's optional". Unknown odd bits are ignored and unknown even bits end the connection. New features can roll out gradually without splitting the network.

TLV: type, length, value

After the fixed fields, a message can carry a TLV stream: records of type | length | value. The same rule applies: unknown odd types are skipped, unknown even types are an error. This is how the protocol grows; older nodes simply skip records they don't understand.

Parse it

⚡Parse an init message

Python

NodeAlice · LNDBob · c-lightningChan · c-lightningDina · LNDNo node

# A Lightning 'init' message, as bytes on the wire (after decryption): # type (u16) | gflen (u16) | globalfeatures | flen (u16) | features | TLV stream msg = bytes.fromhex("0010" "0000" "0003" "0a69a2" "0120" + "06" * 32) def parse_init(data: bytes) -> dict: """Return {"type": int, "global_features": bytes, "features": bytes, "tlv": bytes}.""" msg_type = int.from_bytes(data[0:2], "big") # TODO: read gflen, then globalfeatures, then flen and features; the rest is the TLV stream return {"type": msg_type, "global_features": b"", "features": b"", "tlv": b""} parsed = parse_init(msg) print("type:", parsed["type"]) print("features:", parsed["features"].hex()) print("tlv bytes:", len(parsed["tlv"]))

▶ RunCheckReset lessonRestore starter code

These exercises need a laptop with the lab running. You can read the lesson on your phone.

The check feeds your parse_init several init messages with random features and TLV bytes. If yours handles them all, you have read the same bytes a real node reads.