|
| 1 | +# Giga Receipt Hash |
| 2 | + |
| 3 | +**Status:** draft. **Depends on:** [Giga App Hash](apphash_spec.md), schema version 1. |
| 4 | + |
| 5 | +This document defines `receiptHash`, the field of `appHashData` marked **PLACEHOLDER** in the |
| 6 | +[App Hash specification](apphash_spec.md#the-app-hash): *"A commitment to the transaction receipts |
| 7 | +produced by executing the block. Needs design. Its definition is owned by the EVM team and is not |
| 8 | +specified here."* This document is that definition. |
| 9 | + |
| 10 | +It defines a commitment scheme only — what `receiptHash` is a hash of, and how an individual |
| 11 | +receipt or log can be proven against it. It does not define how receipts are stored, pruned, or |
| 12 | +served over RPC; that remains the unmodified concern of the existing receipt store |
| 13 | +(`sei-db/ledger_db/receipt/`). A field appears in this commitment only if it is an execution outcome |
| 14 | +that cannot be derived from a transaction plus already-committed prior state without executing it; |
| 15 | +see [Rationale](#rationale-non-normative) for the complete reasoning. |
| 16 | + |
| 17 | +This document has no schema version of its own. The algorithm it defines is tied 1:1 to the App |
| 18 | +Hash schema version in effect for the block (`appHashData.version`); a future change to anything |
| 19 | +here can only ship by riding a bump to that version. |
| 20 | + |
| 21 | +## Notation |
| 22 | + |
| 23 | +In addition to the notation defined in the [App Hash specification](apphash_spec.md#notation): |
| 24 | + |
| 25 | +- `u8(x)` is `x` as a single unsigned byte. |
| 26 | +- A *tag* is a single domain-separation byte prefixed onto data before it is hashed. |
| 27 | + |
| 28 | +## Merkle tree construction (MTH) |
| 29 | + |
| 30 | +Both trees this document defines — the per-receipt logs tree and the per-block receipts tree — use |
| 31 | +the same construction, parameterized by a pair of domain tags `(tagLeaf, tagNode)`, over an ordered |
| 32 | +list of byte-string entries `D = [d_0, …, d_{n-1}]`: |
| 33 | + |
| 34 | +``` |
| 35 | +MTH(tagLeaf, tagNode, {}) = SHA-256() for n = 0 |
| 36 | +MTH(tagLeaf, tagNode, {d_0}) = SHA-256(tagLeaf ‖ d_0) for n = 1 |
| 37 | +MTH(tagLeaf, tagNode, D[0:n]) = SHA-256(tagNode ‖ MTH(tagLeaf, tagNode, D[0:k]) |
| 38 | + ‖ MTH(tagLeaf, tagNode, D[k:n])) for n > 1 |
| 39 | +``` |
| 40 | + |
| 41 | +where, for `n > 1`, `k` is the largest power of two strictly less than `n`. This is RFC 6962's |
| 42 | +Merkle Tree Hash (§2.1), applied with caller-chosen domain tags in place of RFC 6962's fixed |
| 43 | +`0x00`/`0x01`, so that no leaf or internal-node hash from one tree instance can ever be mistaken for |
| 44 | +one from the other. The empty-tree case (`n = 0`) uses no tag — `SHA-256()`, the hash of the empty |
| 45 | +string — per RFC 6962's own definition, unmodified. |
| 46 | + |
| 47 | +This document uses two tag pairs: |
| 48 | + |
| 49 | +| Tree | `tagLeaf` | `tagNode` | |
| 50 | +|---|---|---| |
| 51 | +| Logs tree (per receipt) | `0x00` | `0x01` | |
| 52 | +| Receipts tree (per block) | `0x02` | `0x03` | |
| 53 | + |
| 54 | +> This unique-per-tree domain separation may be more than is needed. A logs tree's root never |
| 55 | +> enters the receipts tree as a tree element in its own right — it is embedded as 32 opaque bytes |
| 56 | +> inside `receiptPreimage`, which then gets its own leaf hash under the receipts tree's own tags — |
| 57 | +> so there may be no path for a hash from one tree to be mistaken for one from the other even if |
| 58 | +> both reused the same `0x00`/`0x01` pair. Reusing a single shared pair would also let this |
| 59 | +> commitment be built directly on `sei-tendermint/crypto/merkle.HashFromByteSlices`, Sei's own |
| 60 | +> existing RFC 6962 implementation (leaf `0x00`, node `0x01`, SHA-256, the same largest-power-of-two |
| 61 | +> split used here), instead of a bespoke construction. |
| 62 | +
|
| 63 | +## `receiptHash` |
| 64 | + |
| 65 | +``` |
| 66 | +receiptHash(N) = MTH(0x02, 0x03, [ receiptPreimage(r) for r in receipts(N), in transaction order ]) |
| 67 | +``` |
| 68 | + |
| 69 | +`receipts(N)` is block `N`'s list of transaction receipts. Each entry fed to the tree is: |
| 70 | + |
| 71 | +``` |
| 72 | +receiptPreimage(r) = u8(r.status) ‖ varint(r.gasUsed) ‖ varint(r.logCount) ‖ logsRoot(r) |
| 73 | +``` |
| 74 | + |
| 75 | +| Field | Encoding | |
| 76 | +|---|---| |
| 77 | +| `status` | `u8`; `0` = failed, `1` = success | |
| 78 | +| `gasUsed` | `varint`; gas used by this transaction alone, not cumulative across the block | |
| 79 | +| `logCount` | `varint`; `len(r.logs)` — see [Rationale](#logcount) for why this is committed here | |
| 80 | +| `logsRoot` | raw bytes, see below | |
| 81 | + |
| 82 | +`gasUsed` and `logCount` are LEB128, not fixed-width, matching the same choice `blockHash` already |
| 83 | +makes for `totalGasWanted`/`totalGasEstimated`/`block_number` in the App Hash specification: these |
| 84 | +figures are almost always far smaller than 2⁶⁴, so a realistic value fits in a few bytes instead of |
| 85 | +a fixed-width field. `varint` is self-delimiting — every byte but the last has its continuation bit |
| 86 | +set, and that last byte (continuation bit clear) is *included* in the value it terminates, not a |
| 87 | +separator before the next field. So `gasUsed`'s varint runs through and including its first |
| 88 | +clear-continuation-bit byte; `logCount`'s varint starts at the byte immediately after that and is |
| 89 | +parsed the same way; `logsRoot` starts immediately after `logCount`'s varint ends. `receiptPreimage` |
| 90 | +is therefore not a fixed size: it is 35 to 53 bytes — 1 (`status`) plus 1 to 10 (`varint(gasUsed)`) |
| 91 | +plus 1 to 10 (`varint(logCount)`), per the App Hash specification's own bound on `varint`, plus 32 |
| 92 | +(`logsRoot`). It is not itself a leaf hash — `MTH` applies the receipts tree's leaf tag (`0x02`) when |
| 93 | +hashing it. |
| 94 | + |
| 95 | +### `logsRoot` |
| 96 | + |
| 97 | +``` |
| 98 | +logsRoot(r) = MTH(0x00, 0x01, [ logLeaf(l) for l in r.logs, in emission order ]) |
| 99 | +``` |
| 100 | + |
| 101 | +A receipt that emits no logs has `logsRoot(r) = SHA-256()` — the `n = 0` case above. Verifying a |
| 102 | +single log against `logsRoot` in isolation (without the rest of the logs) requires an authenticated |
| 103 | +`len(r.logs)`; that value is committed as `logCount` in `receiptPreimage`, not derived here (see |
| 104 | +[Rationale](#logcount)). |
| 105 | + |
| 106 | +### `logLeaf` |
| 107 | + |
| 108 | +``` |
| 109 | +logLeaf(l) = l.address ‖ u8(l.topicCount) ‖ topics(l) ‖ l.data |
| 110 | +
|
| 111 | +topicCount = len(l.topics), always 0-4 by EVM LOG0-LOG4 semantics |
| 112 | +topics(l) = pad(l, 0) ‖ pad(l, 1) ‖ pad(l, 2) ‖ pad(l, 3) |
| 113 | +pad(l, i) = l.topics[i] if i < l.topicCount |
| 114 | + = 32 zero bytes otherwise |
| 115 | +``` |
| 116 | + |
| 117 | +| Offset | Size | Field | Encoding | |
| 118 | +|---:|---:|---|---| |
| 119 | +| 0 | 20 | `address` | raw bytes; the account that emitted the log | |
| 120 | +| 20 | 1 | `topicCount` | `u8`; `0`–`4` | |
| 121 | +| 21 | 128 | `topics` | 4 × 32 bytes; zero-padded past `topicCount` | |
| 122 | +| 149 | variable | `data` | raw bytes; runs to the end of the leaf's input | |
| 123 | + |
| 124 | +`logLeaf` is not itself a leaf hash — `MTH` applies the logs tree's leaf tag (`0x00`) when hashing |
| 125 | +it. `data` carries no explicit length field: it is the sole variable-length component and it is |
| 126 | +positioned last, so its extent is unambiguous from the preimage alone (see |
| 127 | +[Rationale](#e-no-length-field-for-data)). `topicCount` is the sole authority on how many of the |
| 128 | +four `topics` slots are real; zero-padding beyond it is never content-guessed. |
| 129 | + |
| 130 | +## Test vectors |
| 131 | + |
| 132 | +**Log 0** — `address` is 20 bytes of `0x11`, `topicCount` is 1, `topics[0]` is 32 bytes of `0x22` |
| 133 | +(`topics[1..3]` zero), `data` is `beef`. |
| 134 | + |
| 135 | +``` |
| 136 | +logLeaf(0) = 1111111111111111111111111111111111111111 |
| 137 | + 01 |
| 138 | + 2222222222222222222222222222222222222222222222222222222222222222 |
| 139 | + 0000000000000000000000000000000000000000000000000000000000000000 |
| 140 | + 0000000000000000000000000000000000000000000000000000000000000000 |
| 141 | + 0000000000000000000000000000000000000000000000000000000000000000 |
| 142 | + beef |
| 143 | +``` |
| 144 | + |
| 145 | +**Log 1** — `address` is 20 bytes of `0x33`, `topicCount` is 0, `data` is empty. |
| 146 | + |
| 147 | +``` |
| 148 | +logLeaf(1) = 3333333333333333333333333333333333333333 |
| 149 | + 00 |
| 150 | + 0000000000000000000000000000000000000000000000000000000000000000 |
| 151 | + 0000000000000000000000000000000000000000000000000000000000000000 |
| 152 | + 0000000000000000000000000000000000000000000000000000000000000000 |
| 153 | + 0000000000000000000000000000000000000000000000000000000000000000 |
| 154 | + |
| 155 | +``` |
| 156 | + |
| 157 | +``` |
| 158 | +logsRoot({logLeaf(0), logLeaf(1)}) = c6ab01a590f123c121f3dad8fcc5e8a59ef73156492f384931e0158cd6d12e4e |
| 159 | +logsRoot({}) = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |
| 160 | +``` |
| 161 | + |
| 162 | +**Receipt 0** — `status` 1, `gasUsed` 21000 (`varint` = `88a401`), `logCount` 2 |
| 163 | +(`varint` = `02`), `logsRoot` as computed above from the two logs. |
| 164 | + |
| 165 | +``` |
| 166 | +receiptPreimage(0) = 01 88a401 02 c6ab01a590f123c121f3dad8fcc5e8a59ef73156492f384931e0158cd6d12e4e |
| 167 | +``` |
| 168 | + |
| 169 | +**Receipt 1** — `status` 0 (failed), `gasUsed` 250000 (`varint` = `90a10f`), |
| 170 | +`logCount` 0 (`varint` = `00`), no logs. |
| 171 | + |
| 172 | +``` |
| 173 | +receiptPreimage(1) = 00 90a10f 00 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 |
| 174 | +``` |
| 175 | + |
| 176 | +``` |
| 177 | +receiptHash({receiptPreimage(0)}) = 86dee5ab9eced226d9f56ab788b3457a1bada8f7010bb0cc5e02fe082c8bc417 |
| 178 | +receiptHash({receiptPreimage(0), receiptPreimage(1)}) = b901abdef77024535a360f0abd3fafd95abcd81f52efd23aa6319d48c9916816 |
| 179 | +``` |
| 180 | + |
| 181 | +(The single-receipt case above intentionally equals `MTH`'s `n = 1` leaf hash of `receiptPreimage(0)` |
| 182 | +directly — a consistency check anyone re-implementing this can verify independently. Both |
| 183 | +`receiptPreimage(0)` and `receiptPreimage(1)` happen to be 37 bytes here — `gasUsed` needs 3 LEB128 |
| 184 | +bytes either way (21000 and 250000), and `logCount` needs exactly 1 byte either way (2 and 0 are both |
| 185 | +single-byte values), so the lengths coincide even though the field values differ. That's an artifact |
| 186 | +of these particular example values, not a general property: `receiptPreimage` ranges from 35 to 53 |
| 187 | +bytes depending on `gasUsed` and `logCount`, and `MTH` handles that variation the same as it handles |
| 188 | +any other variable-length tree entry.) |
| 189 | + |
| 190 | +## Rationale (non-normative) |
| 191 | + |
| 192 | +The remainder of this document is not part of the specification — it records why the scheme above |
| 193 | +was chosen, for anyone evaluating or revising it later. |
| 194 | + |
| 195 | +### Why these fields, and not others |
| 196 | + |
| 197 | +A field belongs in the commitment if and only if it is an execution outcome that cannot be derived |
| 198 | +from the transaction plus already-committed prior state without actually running the EVM. Everything |
| 199 | +below fails that test and is deliberately excluded as implied: |
| 200 | + |
| 201 | +| Field | Why it's implied | |
| 202 | +|---|---| |
| 203 | +| `tx_type`, `to` | literal fields of the transaction itself, already covered by the block's committed transaction list (`blockHash`) | |
| 204 | +| `from` | ECDSA-recoverable from the transaction's own signature | |
| 205 | +| `effective_gas_price` | a pure function of the transaction's fee fields and the block's base fee | |
| 206 | +| `contract_address` (CREATE) | deterministic from `from` and the sender's nonce (or `from`+salt+initcode-hash for CREATE2) — pure arithmetic over the transaction plus `stateHash`'s pre-state | |
| 207 | +| `tx_hash` | implied by the receipt's position matching the transaction list's position | |
| 208 | +| `logs_bloom` | a pure, deterministic function of the logs already committed via `logsRoot` | |
| 209 | +| `error_code` | a diagnostic refinement of `status`; nothing is identified as needing to cryptographically prove *which* failure occurred, only that one did | |
| 210 | + |
| 211 | +`status`, `gasUsed`, and the logs themselves are the only fields that fail this test in the |
| 212 | +*include* direction — none are derivable without executing, which is the entire reason this |
| 213 | +commitment needs to exist at all. |
| 214 | + |
| 215 | +No version byte appears in either preimage for the same reason given in the opening section: the |
| 216 | +algorithm is governed by `appHashData.version`, so an independent per-receipt version tag would be |
| 217 | +redundant. The stored receipt format keeps its own, separate versioning (`receiptDataV1` in |
| 218 | +`sei-db/ledger_db/receipt/codec.go`) — a storage concern, decoupled from this document. |
| 219 | + |
| 220 | +### `logCount` |
| 221 | + |
| 222 | +Yes for the logs tree, committed as `logCount` in `receiptPreimage` — reversing an earlier draft of |
| 223 | +this document, which argued it wasn't needed. That argument conflated two separate justifications |
| 224 | +for authenticating a Merkle tree's size, and only addressed one of them. |
| 225 | + |
| 226 | +The one it addressed: RFC 6962 (Certificate Transparency) binds `(tree_size, root_hash)` via its |
| 227 | +Signed Tree Head's *signature*, not by hashing size into the root. CT needs that pairing to catch a |
| 228 | +log server showing different parties divergent histories over time (a "split view") — and this |
| 229 | +document doesn't have that problem, since a given receipt's `logsRoot` is fixed and immutable the |
| 230 | +instant it's produced. |
| 231 | + |
| 232 | +The one it missed: an RFC 6962 Merkle audit path (§2.1.1) does not, by itself, authenticate the tree |
| 233 | +size or leaf index it's checked against — those are told to the verifier as ordinary, unauthenticated |
| 234 | +inputs. A party who already holds every log in a receipt (which a prover constructing a proof |
| 235 | +generally does) can reuse real internal-node hashes from the true tree as "sibling" values and |
| 236 | +present them against a *smaller, false* claimed size and a *different* claimed index. The |
| 237 | +verification arithmetic can still land on the true `logsRoot`, with no hash collision required, |
| 238 | +because nothing in that arithmetic checks that the claimed size is the *only* size consistent with |
| 239 | +the root. That lets a prover misstate which position a log sits at, or how many logs a receipt |
| 240 | +emitted — exactly the kind of claim this commitment exists to make unforgeable. |
| 241 | + |
| 242 | +This is fixable either by committing the count directly, or by pointing to an already-authenticated |
| 243 | +source of it elsewhere. The receipts tree has the latter: a block's transaction count is already |
| 244 | +committed via `blockHash`'s own transaction list (`encodePayload`'s `txs`, in |
| 245 | +[`apphash_spec.md`](apphash_spec.md)), so no separate field is needed there. The logs tree has no |
| 246 | +equivalent source — nothing else commits how many logs a given transaction emitted — so `logCount` |
| 247 | +has to be committed directly, in `receiptPreimage`. |
| 248 | + |
| 249 | +### Deviations from Ethereum, and why |
| 250 | + |
| 251 | +Ethereum's receipt (`core/types.Receipt`) and its receipts-trie commitment are the natural reference |
| 252 | +point. This design departs from it in five places. |
| 253 | + |
| 254 | +#### (a) `gasUsed`, not a cumulative counter |
| 255 | + |
| 256 | +Ethereum's receipt commits the running gas total across the whole block, so every receipt's |
| 257 | +commitment depends on knowing the final gas totals of every transaction before it — a hard |
| 258 | +sequential dependency; transaction *i*'s receipt cannot be hashed until `0..i-1` are fully ordered |
| 259 | +and totaled. Per-transaction `gasUsed` has no such dependency: a receipt can be hashed the moment |
| 260 | +its own transaction finishes executing, regardless of what happens before or after it in the block. |
| 261 | +That serves parallel, multi-proposer block building directly — receipts can be produced and hashed |
| 262 | +concurrently across execution lanes, or by multiple proposers assembling parts of a block at once, |
| 263 | +with no serialization point waiting on final ordering. A verifier wanting the Ethereum-style running |
| 264 | +total can still reconstruct it by summing `gasUsed` across receipts in transaction order; nothing is |
| 265 | +lost, it is simply no longer a *blocking* dependency for commitment. `gasUsed` is varint-encoded |
| 266 | +rather than fixed-width for the same reason it is varint-encoded in `blockHash`: it keeps every |
| 267 | +receipt leaf closer to its true information content, which matters more here than it would on a |
| 268 | +low-throughput chain. |
| 269 | + |
| 270 | +#### (b) Drop `logs_bloom` |
| 271 | + |
| 272 | +Nobody depends on a committed bloom value for correctness — it is a probabilistic filtering |
| 273 | +convenience, not an execution outcome, and it is entirely reconstructible from the logs themselves. |
| 274 | +An indexer that wants one can derive it in a single pass over data already committed via `logsRoot`; |
| 275 | +there is no reason to pay for committing a field that is a pure, cheap function of data already |
| 276 | +present. |
| 277 | + |
| 278 | +#### (c) Logs as their own Merkle tree, not a flat hash or a bloom |
| 279 | + |
| 280 | +The one place this design adds structure rather than removing it: a flat hash over all of a |
| 281 | +receipt's logs can only prove "this is the exact right whole set," never one log in isolation. |
| 282 | +Receipt (and log) data is meant to move between storage and DA planes that will not all hold the |
| 283 | +full set, so individual log provability is the actual goal — hence a tree, not a hash. |
| 284 | + |
| 285 | +#### (d) Fixed `topicCount` and always-four topic slots |
| 286 | + |
| 287 | +EVM logs carry 0–4 topics by opcode semantics (`LOG0`–`LOG4`); Ethereum encodes them as a |
| 288 | +variable-length list. Reserving all four slots unconditionally means topic *k* sits at the same |
| 289 | +fixed byte offset in every log record, regardless of how many topics that particular log actually |
| 290 | +used. That matters for downstream filtering: code scanning for a given event signature |
| 291 | +(conventionally `topics[0]`) seeks directly to a known fixed offset across every record, instead of |
| 292 | +first decoding a variable-length list to find where it starts. |
| 293 | + |
| 294 | +#### (e) No length field for `data` |
| 295 | + |
| 296 | +Ethereum's receipt-trie encoding (RLP) carries explicit lengths throughout, because RLP is a |
| 297 | +general-purpose, randomly-decodable serialization. A hash preimage does not need that: `data` is the |
| 298 | +sole variable-length component of `logLeaf` and it is positioned last, so there is no boundary |
| 299 | +ambiguity to resolve by position alone. Hashing also always produces a fixed-size digest regardless |
| 300 | +of input length, so the digest itself already reflects the data's extent — a verifier checking a |
| 301 | +revealed log's data re-hashes whatever bytes are actually revealed and compares to the leaf hash; |
| 302 | +there is no separate expected-length check to perform. |
| 303 | + |
| 304 | +## References |
| 305 | + |
| 306 | +- `giga/apphash/apphash_spec.md` — the parent App Hash specification this document fills in |
| 307 | +- `sei-db/ledger_db/receipt/receipt_store.go`, `litt_receipt_store.go`, `codec.go` — the existing, |
| 308 | + unmodified receipt store |
| 309 | +- `proto/evm/receipt.proto`, `x/evm/types/receipt.pb.go` — the current stored receipt encoding, |
| 310 | + unaffected by this document |
| 311 | +- RFC 6962 (Certificate Transparency) §2.1 — Merkle Tree Hash construction; §2.1.1 — Merkle Audit |
| 312 | + Path (does not itself authenticate tree size or leaf index); §3.2 — Signed Tree Head size/root |
| 313 | + binding |
0 commit comments