@@ -12,6 +12,8 @@ currently placeholders that need further design; each one is marked **PLACEHOLDE
1212- ` ‖ ` is byte concatenation.
1313- ` u64be(x) ` is ` x ` as an 8-byte unsigned big-endian integer.
1414- ` u32le(x) ` is ` x ` as a 4-byte unsigned little-endian integer.
15+ - ` varint(x) ` is the unsigned LEB128 encoding of ` x ` : little-endian base-128 digits, each in a byte whose high bit
16+ is set on every byte but the last. It is 1 to 10 bytes long, and ` varint(0) ` is the single byte ` 0x00 ` .
1517- ` SHA-256 ` is FIPS 180-4 SHA-256, and ` BLAKE3-256 ` is unkeyed BLAKE3 with a 32-byte output.
1618- A * hash* is exactly 32 bytes.
1719
@@ -34,7 +36,7 @@ separators, or length prefixes, for a fixed total of 177 bytes.
3436| 0 | 1 | ` version ` | ` u8 ` | Defined |
3537| 1 | 8 | ` chainID ` | ` u64be ` | Defined |
3638| 9 | 8 | ` blockHeight ` | ` u64be ` | Defined |
37- | 17 | 32 | ` blockHash ` | raw bytes | ** PLACEHOLDER ** |
39+ | 17 | 32 | ` blockHash ` | raw bytes | Defined |
3840| 49 | 32 | ` stateHash ` | raw bytes | Defined |
3941| 81 | 32 | ` bud ` | raw bytes | ** PLACEHOLDER** |
4042| 113 | 32 | ` receiptHash ` | raw bytes | ** PLACEHOLDER** |
@@ -63,20 +65,98 @@ The EVM chain ID of the chain the block belongs to.
6365
6466The Autobahn global block number of the block.
6567
66- ### ` blockHash ` : PLACEHOLDER
68+ ### ` blockHash `
6769
68- The hash that identifies the block. For now, this is the hash Autobahn assigns to the block's lane
69- ` BlockHeader ` , which is SHA-256 over that header's canonical encoding and is the block hash execution already
70- uses. The header contains:
70+ The hash Autobahn assigns to the block's lane header, and the block hash execution exposes to the EVM.
7171
72- - ` lane_id ` : the lane that produced the block.
73- - ` block_number ` : the block's number within its lane, which is not ` blockHeight ` .
74- - ` parent_hash ` : the hash of the previous header in the same lane.
75- - ` payload_hash ` : SHA-256 over the canonical encoding of the block's payload, which holds the block's
76- transactions in block order, the time the block was created, and its total gas wanted and total gas estimated.
72+ ```
73+ blockHash(N) = SHA-256(encodeHeader(header(N)))
74+ ```
75+
76+ The header contains these fields, in the order they are encoded:
77+
78+ | Field | Encoding | Meaning |
79+ | ----------------| ---------------| --------------------------------------------------------------------------------------------------------|
80+ | ` block_number ` | ` varint(u64) ` | The block's number within its lane, from 0. It is not ` blockHeight ` , which is the global block number. |
81+ | ` parent_hash ` | 32 bytes | Hash of the previous header in the same lane, or 32 zero bytes when ` block_number ` is 0. |
82+ | ` payload_hash ` | 32 bytes | SHA-256 over the encoding of the block's payload, defined below. |
83+ | ` validator ` | 32 bytes | Ed25519 public key of the validator whose lane produced the block. |
84+ | ` joined ` | ` varint(u64) ` | Epoch in which that validator most recently joined the committee. |
85+
86+ ` validator ` and ` joined ` together are ` laneID ` , the lane that produced the block. They are encoded last.
87+
88+ The payload holds:
89+
90+ - ` createdAt ` : the time the producer created the block, split into ` seconds ` , the Unix seconds, and ` nanos ` ,
91+ the sub-second part in nanoseconds (` 0 … 999,999,999 ` ).
92+ - ` txs ` : the block's transactions in block order, each as its raw bytes.
93+ - ` totalGasWanted ` : the total gas the transactions want.
94+ - ` totalGasEstimated ` : the total gas the producer estimated they would use.
95+
96+ ** Encoding.** Each field starts with a tag byte ` (field_number << 3) | wire_type ` , and fields are written in
97+ field-number order. Wire type ` 0 ` is a ` varint ` . Wire type ` 2 ` is length-delimited: the tag is followed by
98+ ` varint(length) ` and then that many bytes.
99+
100+ | Tag | Computed as | Fields |
101+ | --------| ----------------| -----------------------------------------------------------------|
102+ | ` 0x08 ` | ` (1 << 3) \| 0 ` | ` seconds ` |
103+ | ` 0x0a ` | ` (1 << 3) \| 2 ` | ` createdAt ` , ` validator ` , and the key inside ` validator ` |
104+ | ` 0x10 ` | ` (2 << 3) \| 0 ` | ` block_number ` , ` joined ` , ` nanos ` |
105+ | ` 0x1a ` | ` (3 << 3) \| 2 ` | ` parent_hash ` |
106+ | ` 0x22 ` | ` (4 << 3) \| 2 ` | ` payload_hash ` |
107+ | ` 0x2a ` | ` (5 << 3) \| 2 ` | ` laneID ` |
108+ | ` 0x32 ` | ` (6 << 3) \| 2 ` | each transaction |
109+ | ` 0x38 ` | ` (7 << 3) \| 0 ` | ` totalGasWanted ` |
110+ | ` 0x40 ` | ` (8 << 3) \| 0 ` | ` totalGasEstimated ` |
111+
112+ ` 0x20 ` is the length 32, not a tag. The ` 0x22 ` after the first ` 0x0a ` in ` laneID ` is the length 34, the size of
113+ the key message, not the ` payload_hash ` tag.
114+
115+ ```
116+ encodeHeader(h) = 0x10 ‖ varint(h.block_number)
117+ ‖ 0x1a ‖ 0x20 ‖ h.parent_hash
118+ ‖ 0x22 ‖ 0x20 ‖ h.payload_hash
119+ ‖ 0x2a ‖ varint(len(laneID(h))) ‖ laneID(h)
77120
78- ** Needs design.** Which header this commits to, which fields that header covers, and its exact byte encoding
79- must be specified precisely and intentionally. This definition is owned by the consensus team.
121+ laneID(h) = 0x0a ‖ 0x22 ‖ 0x0a ‖ 0x20 ‖ h.validator
122+ ‖ 0x10 ‖ varint(h.joined)
123+ ```
124+
125+ ` len(laneID(h)) ` is ` 37 + len(varint(h.joined)) ` .
126+
127+ ```
128+ payload_hash = SHA-256(encodePayload(p))
129+
130+ encodePayload(p) = 0x0a ‖ varint(len(createdAt(p))) ‖ createdAt(p)
131+ ‖ 0x32 ‖ varint(len(tx)) ‖ tx for each tx in p.txs, in order
132+ ‖ 0x38 ‖ varint(p.totalGasWanted)
133+ ‖ 0x40 ‖ varint(p.totalGasEstimated)
134+
135+ createdAt(p) = 0x08 ‖ varint(p.seconds) ‖ 0x10 ‖ varint(p.nanos)
136+ ```
137+
138+ Every field other than ` txs ` is encoded, including when its value is zero; a payload with no transactions
139+ contributes no ` txs ` bytes. ` seconds ` is encoded as ` varint ` of its 64-bit two's-complement value and ` nanos `
140+ as ` varint ` of its 32-bit two's-complement value, so a negative ` seconds ` encodes to 10 bytes.
141+
142+ ** Test vector.** ` validator ` is 32 bytes of ` 0x11 ` , ` joined ` is 7, ` block_number ` is 300, ` parent_hash ` is 32
143+ bytes of ` 0x22 ` , and the payload was created at ` 2024-01-01T00:00:00Z ` (` seconds ` 1704067200, ` nanos ` 0) with
144+ transactions ` 01 ` and ` 0203 ` , ` totalGasWanted ` 21000, and ` totalGasEstimated ` 300.
145+
146+ ```
147+ encodePayload = 0a08 088081c8ac06 1000
148+ 320101
149+ 32020203
150+ 3888a401
151+ 40ac02
152+ payload_hash = c5d7b958f7f6968694dc5b56438ec14a76dca8872c4d18fcfad4ee250805583a
153+
154+ encodeHeader = 10ac02
155+ 1a20 2222222222222222222222222222222222222222222222222222222222222222
156+ 2220 c5d7b958f7f6968694dc5b56438ec14a76dca8872c4d18fcfad4ee250805583a
157+ 2a26 0a220a20 1111111111111111111111111111111111111111111111111111111111111111 1007
158+ blockHash = e94492a4ef3a399de10a1a2e06da1a224ecc91860e10be9b875fd9fee38bc31d
159+ ```
80160
81161### ` stateHash `
82162
@@ -147,7 +227,6 @@ block 0, since the chain already exists without this app hash.
147227
148228| Item | Needed | Owner |
149229| ------------------------------| ------------------------------------------------------------------| ----------------|
150- | ` blockHash ` | A precise, intentional definition of the header and its encoding | Consensus team |
151230| ` bud ` | A Merkle tree schema over the block's changes, to support proofs | Storage team |
152231| ` receiptHash ` | A full definition | EVM team |
153232| ` previousAppHash ` activation | The height of the first block computed under this scheme | TBD |
0 commit comments