Skip to content

Commit d65f39c

Browse files
authored
Define receiptHash commitment scheme for Giga App Hash (#4535)
## Summary - Fills the `receiptHash` placeholder in `giga/apphash/apphash_spec.md` with a full commitment scheme, scoped to Autobahn/evmonly. - Receipt and log data are each committed via their own binary Merkle tree (RFC 6962's MTH, distinct domain tags per tree), so an individual receipt or log can be proven independently without the rest of the block's receipt data. - Only fields that are genuine execution outcomes (not derivable from the transaction plus already-committed prior state) are committed — see the non-normative Rationale section for the full field-by-field reasoning and how this departs from Ethereum's receipt/receipts-trie design. ## Test plan - [ ] Review the Merkle Tree Hash construction and domain-tag choice - [ ] Review the field-inclusion reasoning (status/gasUsed/logsRoot only) - [ ] Spot-check the test vectors — independently recomputed and diffed against the file content before this PR; a from-scratch reimplementation would be good additional confirmation - [ ] Confirm this is compatible with the planned Giga Receipt Store work (crash-recovery decoupling: the hash is a pure function of execution output, never read back from the receipt store)
1 parent 8d901ea commit d65f39c

1 file changed

Lines changed: 313 additions & 0 deletions

File tree

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
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

Comments
 (0)