Skip to content

Commit 4150c4b

Browse files
authored
Define blockHash in the Giga app hash spec (#4453)
## Summary - Replace the `blockHash` placeholder with the hash Autobahn already assigns to the lane `BlockHeader`: SHA-256 over its canonical encoding, which is the block hash execution exposes to the EVM. - Spell out the header fields, including that `block_number` is the lane counter rather than `blockHeight`, and that `parent_hash` is 32 zero bytes for the first block of a lane. - No change to the app hash bytes. The field was already this hash, so the schema version stays at 1. ## Test plan - [ ] Doc only. Confirm the section matches `BlockHeader.Hash` and the hash `executeBlock` passes as `RequestFinalizeBlock.Hash`. Made with [Cursor](https://cursor.com)
1 parent 96e0483 commit 4150c4b

1 file changed

Lines changed: 92 additions & 13 deletions

File tree

‎giga/apphash/apphash_spec.md‎

Lines changed: 92 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -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

6466
The 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

Comments
 (0)