Skip to content

Commit 5d36964

Browse files
cody-littleyCody Littley
andauthored
Implement receipt hashing (#4651)
An implementation of the receipt hashing spec (with a few spec changes that revealed themselves as necessary). --------- Co-authored-by: Cody Littley <cody.littley@seinetwork.io>
1 parent adbbb1a commit 5d36964

37 files changed

Lines changed: 2598 additions & 661 deletions

‎giga/apphash/app_hash_codec.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ func Deserialize(data []byte) (*AppHashData, error) {
6363
[32]byte(data[blockHashOffset:stateHashOffset]),
6464
[32]byte(data[stateHashOffset:budHashOffset]),
6565
BUDHash(data[budHashOffset:receiptHashOffset]),
66-
[32]byte(data[receiptHashOffset:previousAppHashOffset]),
66+
ReceiptHash(data[receiptHashOffset:previousAppHashOffset]),
6767
[32]byte(data[previousAppHashOffset:serializedSize]),
6868
), nil
6969
}

‎giga/apphash/app_hash_data.go‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ type AppHashData struct {
3333

3434
// The hash of the transaction receipts
3535
// produced by executing this block.
36-
receiptHash [32]byte
36+
receiptHash ReceiptHash
3737

3838
// The app hash of block (blockHeight-1).
3939
// All 0s if this is the first block.
@@ -51,6 +51,9 @@ type AppHashData struct {
5151
// BUDHash is the hash committing to the key-value changes produced by executing a block.
5252
type BUDHash [32]byte
5353

54+
// ReceiptHash is the hash committing to the transaction receipts produced by executing a block.
55+
type ReceiptHash [32]byte
56+
5457
// Construct a new AppHashData object at the current schema version.
5558
func NewAppHashData(
5659
// The EVM chain ID of the chain the block belongs to.
@@ -65,7 +68,7 @@ func NewAppHashData(
6568
// executing this block.
6669
budHash BUDHash,
6770
// The hash of the transaction receipts produced by executing this block.
68-
receiptHash [32]byte,
71+
receiptHash ReceiptHash,
6972
// The app hash of block (blockHeight-1), or all 0s if this is the first block.
7073
previousAppHash [32]byte,
7174
) *AppHashData {
@@ -131,7 +134,7 @@ func (ahd *AppHashData) BUDHash() BUDHash {
131134
}
132135

133136
// ReceiptHash returns the hash of the transaction receipts produced by executing this block.
134-
func (ahd *AppHashData) ReceiptHash() [32]byte {
137+
func (ahd *AppHashData) ReceiptHash() ReceiptHash {
135138
return ahd.receiptHash
136139
}
137140

‎giga/apphash/app_hash_golden_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ func verifyGoldenRecord(t *testing.T, index int, version uint8, record goldenRec
127127
require.Equal(t, blockHash, decoded.BlockHash(), "record %d", index)
128128
require.Equal(t, stateHash, decoded.StateHash(), "record %d", index)
129129
require.Equal(t, BUDHash(budHash), decoded.BUDHash(), "record %d", index)
130-
require.Equal(t, receiptHash, decoded.ReceiptHash(), "record %d", index)
130+
require.Equal(t, ReceiptHash(receiptHash), decoded.ReceiptHash(), "record %d", index)
131131
require.Equal(t, previousAppHash, decoded.PreviousAppHash(), "record %d", index)
132132
require.Equal(t, serialization, mustSerialize(t, decoded), "record %d", index)
133133
require.Equal(t, appHash, decoded.AppHash(), "record %d", index)

‎giga/apphash/app_hash_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ func TestConstructorAndGetters(t *testing.T) {
6161
require.Equal(t, filledHash(0xa1), ahd.BlockHash())
6262
require.Equal(t, filledHash(0xb2), ahd.StateHash())
6363
require.Equal(t, BUDHash(filledHash(0xc3)), ahd.BUDHash())
64-
require.Equal(t, filledHash(0xd4), ahd.ReceiptHash())
64+
require.Equal(t, ReceiptHash(filledHash(0xd4)), ahd.ReceiptHash())
6565
require.Equal(t, filledHash(0xe5), ahd.PreviousAppHash())
6666
}
6767

@@ -177,7 +177,7 @@ func TestZeroAppHashData(t *testing.T) {
177177
require.Equal(t, [32]byte{}, ahd.BlockHash())
178178
require.Equal(t, [32]byte{}, ahd.StateHash())
179179
require.Equal(t, BUDHash{}, ahd.BUDHash())
180-
require.Equal(t, [32]byte{}, ahd.ReceiptHash())
180+
require.Equal(t, ReceiptHash{}, ahd.ReceiptHash())
181181
require.Equal(t, [32]byte{}, ahd.PreviousAppHash())
182182
require.Equal(t, [32]byte{}, ahd.AppHash())
183183

‎giga/apphash/apphash_spec.md‎

Lines changed: 19 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
# Giga App Hash
22

3-
**Status:** draft. **Schema version:** 1.
3+
**Schema version:** 1.
44

55
This document defines the app hash that Giga validators compute for each executed block and agree on through
6-
Autobahn. It specifies what goes into the app hash and how those inputs are combined. Several inputs are
7-
currently placeholders that need further design; each one is marked **PLACEHOLDER**, and they are collected in
8-
[Open design work](#open-design-work).
6+
Autobahn. It specifies what goes into the app hash and how those inputs are combined.
97

108
## Notation
119

@@ -31,16 +29,16 @@ the hash input only, not of the serialization.
3129
`appHashData(N)` holds eight fields. Its serialization is the fields in the order below, with no padding,
3230
separators, or length prefixes, for a fixed total of 177 bytes.
3331

34-
| Offset | Size | Field | Encoding | Status |
35-
|-------:|-----:|-------------------|-----------|-------------------------------------------------------------|
36-
| 0 | 1 | `version` | `u8` | Defined |
37-
| 1 | 8 | `chainID` | `u64be` | Defined |
38-
| 9 | 8 | `blockHeight` | `u64be` | Defined |
39-
| 17 | 32 | `blockHash` | raw bytes | Defined |
40-
| 49 | 32 | `stateHash` | raw bytes | Defined |
41-
| 81 | 32 | `budHash` | raw bytes | Defined |
42-
| 113 | 32 | `receiptHash` | raw bytes | **PLACEHOLDER** |
43-
| 145 | 32 | `previousAppHash` | raw bytes | Defined, except for the block at the giga activation height |
32+
| Offset | Size | Field | Encoding |
33+
|-------:|-----:|-------------------|-----------|
34+
| 0 | 1 | `version` | `u8` |
35+
| 1 | 8 | `chainID` | `u64be` |
36+
| 9 | 8 | `blockHeight` | `u64be` |
37+
| 17 | 32 | `blockHash` | raw bytes |
38+
| 49 | 32 | `stateHash` | raw bytes |
39+
| 81 | 32 | `budHash` | raw bytes |
40+
| 113 | 32 | `receiptHash` | raw bytes |
41+
| 145 | 32 | `previousAppHash` | raw bytes |
4442

4543
A decoder reads `version` from the first byte and rejects any version it does not support. It then rejects
4644
any input that is not exactly the length that version defines, which is 177 bytes for version 1.
@@ -49,9 +47,8 @@ any input that is not exactly the length that version defines, which is 177 byte
4947

5048
`version` identifies this specification. Once the design is formally accepted as final, `version` is bumped on
5149
any change to the serialization and on any change to how any field is computed. Until then, a change does not
52-
require a bump: code not yet released to mainnet may not be finalized, and may change without a new version, as
53-
when a placeholder below is replaced by its real definition. A block's app hash is always computed under the
54-
version in effect at that block.
50+
require a bump: code not yet released to mainnet may not be finalized, and may change without a new version. A
51+
block's app hash is always computed under the version in effect at that block.
5552

5653
## Fields
5754

@@ -99,8 +96,8 @@ The payload holds:
9996
field-number order. Wire type `0` is a `varint`. Wire type `2` is length-delimited: the tag is followed by
10097
`varint(length)` and then that many bytes.
10198

102-
| Tag | Computed as | Fields |
103-
|--------|----------------|-----------------------------------------------------------------|
99+
| Tag | Computed as | Fields |
100+
|--------|-----------------|-----------------------------------------------------------------|
104101
| `0x08` | `(1 << 3) \| 0` | `seconds` |
105102
| `0x0a` | `(1 << 3) \| 2` | `createdAt`, `validator`, and the key inside `validator` |
106103
| `0x10` | `(2 << 3) \| 0` | `block_number`, `joined`, `nanos` |
@@ -208,11 +205,10 @@ The BUD hash of the block: a commitment to the key-value changes produced by exe
208205
defined by the [BUD specification](bud/bud_spec.md), which also defines the BUD proofs and BUD
209206
state proofs built against it.
210207

211-
### `receiptHash`: PLACEHOLDER
208+
### `receiptHash`
212209

213-
A commitment to the transaction receipts produced by executing the block.
214-
215-
**Needs design.** Its definition is owned by the EVM team and is not specified here.
210+
The receipt hash of the block: a commitment to the transaction receipts produced by executing it. It is defined
211+
by the [Giga Receipt Hash specification](receipthash/receipt_hash_spec.md).
216212

217213
### `previousAppHash`
218214

@@ -221,16 +217,6 @@ The app hash of block `blockHeight - 1`. This chains every app hash to the full
221217
The giga activation height is the first block whose app hash is computed under this scheme. For that block,
222218
`previousAppHash` is 32 zero bytes. Every other height the scheme depends on is derived from it.
223219

224-
**Needs design.** The giga activation height is a chain-wide value that is not yet defined. It is not expected
225-
to be block 0, since the chain already exists without this app hash.
226-
227-
## Open design work
228-
229-
| Item | Needed | Owner |
230-
|------------------------|----------------------------------------------------------|----------|
231-
| `receiptHash` | A full definition | EVM team |
232-
| Giga activation height | The height of the first block computed under this scheme | TBD |
233-
234220
## Test vector
235221

236222
| Field | Value |

‎giga/apphash/bud/bud.go‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,12 @@ const (
1212
budHashDomain = "sei-bud"
1313

1414
// budVersion is the version of the BUD scheme produced by this package: the budlet serialization, the BUD
15-
// tree and its serialization, and the BUD hash preimage.
15+
// tree, and the BUD hash preimage.
1616
budVersion uint8 = 1
1717
)
1818

19-
// computeBUDHash returns the BUD hash committing to a BUD tree.
20-
func computeBUDHash(
19+
// ComputeBUDHash returns the BUD hash committing to a BUD tree.
20+
func ComputeBUDHash(
2121
// The number of leaves in the BUD tree.
2222
leafCount uint64,
2323
// The root of the BUD tree.

‎giga/apphash/bud/bud_fuzz_test.go‎

Lines changed: 11 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,14 @@ type budFuzzSeeds struct {
1414
// Serialized budlets.
1515
budlets [][]byte
1616

17-
// Serialized BUD trees.
18-
trees [][]byte
19-
2017
// Serialized BUD proofs.
2118
proofs [][]byte
2219

2320
// Serialized BUD state proofs.
2421
stateProofs [][]byte
2522
}
2623

27-
// newBUDFuzzSeeds returns the serialized budlets, BUD trees, BUD proofs, and BUD state proofs of the bud_spec.md
24+
// newBUDFuzzSeeds returns the serialized budlets, BUD proofs, and BUD state proofs of the bud_spec.md
2825
// test vectors.
2926
func newBUDFuzzSeeds(f *testing.F) budFuzzSeeds {
3027
f.Helper()
@@ -34,13 +31,9 @@ func newBUDFuzzSeeds(f *testing.F) budFuzzSeeds {
3431
require.NoError(f, err)
3532
return budlet
3633
}
37-
newTree := func(budlets ...*Budlet) *BUDTree {
38-
tree, err := NewBUDTree(budlets)
34+
buildProof := func(budlets []*Budlet, key string) *BUDProof {
35+
proof, found, err := NewBUDProof(budlets, []byte(key))
3936
require.NoError(f, err)
40-
return tree
41-
}
42-
buildProof := func(tree *BUDTree, key string) *BUDProof {
43-
proof, found := tree.BuildBUDProof([]byte(key))
4437
require.True(f, found)
4538
return proof
4639
}
@@ -53,18 +46,19 @@ func newBUDFuzzSeeds(f *testing.F) budFuzzSeeds {
5346
newBudlet("evm/b", []byte{0x00, 0xbb, 0xcc}, []byte{0x00, 0xbb}, 7),
5447
newBudlet("evm/c", []byte{0x00, 0xcc}, []byte{}, 8),
5548
}
56-
tree := newTree(budlets...)
49+
treeHash, err := ComputeBUDTreeHash(budlets)
50+
require.NoError(f, err)
51+
budHash := ComputeBUDHash(uint64(len(budlets)), treeHash)
5752
appHashData := apphash.NewAppHashData(
58-
0x1112131415161718, 9, filled(0xa9), filled(0xb9), tree.BUDHash(), filled(0xd9), filled(0xe9))
59-
stateProof, err := NewBUDStateProof(appHashData, buildProof(tree, "evm/b"))
53+
0x1112131415161718, 9, filled(0xa9), filled(0xb9), budHash, filled(0xd9), filled(0xe9))
54+
stateProof, err := NewBUDStateProof(appHashData, buildProof(budlets, "evm/b"))
6055
require.NoError(f, err)
6156

6257
var seeds budFuzzSeeds
6358
for _, budlet := range budlets {
6459
seeds.budlets = append(seeds.budlets, budlet.Serialize())
65-
seeds.proofs = append(seeds.proofs, buildProof(tree, string(budlet.Key())).Serialize())
60+
seeds.proofs = append(seeds.proofs, buildProof(budlets, string(budlet.Key())).Serialize())
6661
}
67-
seeds.trees = [][]byte{newTree().Serialize(), tree.Serialize()}
6862
seeds.stateProofs = [][]byte{mustSerializeBUDStateProof(f, stateProof)}
6963
return seeds
7064
}
@@ -84,26 +78,6 @@ func FuzzDeserializeBudlet(f *testing.F) {
8478
})
8579
}
8680

87-
// FuzzDeserializeBUDTree requires DeserializeBUDTree() never to panic, and every BUD tree it accepts to serialize
88-
// back to the same bytes and prove each of its budlets.
89-
func FuzzDeserializeBUDTree(f *testing.F) {
90-
for _, seed := range newBUDFuzzSeeds(f).trees {
91-
f.Add(seed)
92-
}
93-
f.Fuzz(func(t *testing.T, data []byte) {
94-
tree, err := DeserializeBUDTree(data)
95-
if err != nil {
96-
return
97-
}
98-
require.Equal(t, data, tree.Serialize())
99-
for _, budlet := range tree.Budlets() {
100-
proof, found := tree.BuildBUDProof(budlet.Key())
101-
require.True(t, found)
102-
require.Equal(t, tree.BUDHash(), proof.ComputeBUDHash())
103-
}
104-
})
105-
}
106-
10781
// FuzzDeserializeBUDProof requires DeserializeBUDProof() never to panic, and every BUD proof it accepts to
10882
// serialize back to the same bytes and compute a BUD hash.
10983
func FuzzDeserializeBUDProof(f *testing.F) {
@@ -116,7 +90,8 @@ func FuzzDeserializeBUDProof(f *testing.F) {
11690
return
11791
}
11892
require.Equal(t, data, proof.Serialize())
119-
_ = proof.ComputeBUDHash()
93+
_, err = proof.ComputeBUDHash()
94+
require.NoError(t, err)
12095
})
12196
}
12297

‎giga/apphash/bud/bud_golden_test.go‎

Lines changed: 13 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -76,15 +76,12 @@ type budGoldenStateProof struct {
7676
EndValue string `json:"endValue"`
7777
}
7878

79-
// budGoldenRecord is one recorded block: its budlets, its serialized BUD tree, its BUD hash, and the BUD proof of each
80-
// budlet. Byte fields are lowercase hex.
79+
// budGoldenRecord is one recorded block: its budlets, its BUD hash, and the BUD proof of each budlet. Byte fields are
80+
// lowercase hex.
8181
type budGoldenRecord struct {
8282
// The block's budlets, sorted by key.
8383
Budlets []budGoldenBudlet `json:"budlets"`
8484

85-
// The block's serialized BUD tree.
86-
Tree string `json:"tree"`
87-
8885
// The block's BUD hash.
8986
BUDHash string `json:"budHash"`
9087

@@ -149,9 +146,9 @@ func TestCurrentVersionsHaveGoldenFile(t *testing.T) {
149146
require.NoError(t, err, "no golden file for the current versions; record %s with -bud-golden-record", path)
150147
}
151148

152-
// verifyBUDGoldenRecord requires the recorded BUD tree and BUD proofs to deserialize to the recorded budlets and
153-
// compute the recorded BUD hash. A record of the current versions must also be reproduced by NewBUDTree() and
154-
// BuildBUDProof().
149+
// verifyBUDGoldenRecord requires the recorded BUD proofs to deserialize to the recorded budlets and compute the
150+
// recorded BUD hash. A record of the current versions must also be reproduced by ComputeBUDTreeHash(),
151+
// ComputeBUDHash(), and NewBUDProof().
155152
func verifyBUDGoldenRecord(
156153
t *testing.T,
157154
// The position of the record in its golden file.
@@ -168,34 +165,25 @@ func verifyBUDGoldenRecord(
168165
budlets = append(budlets, decodeBUDGoldenBudlet(t, index, i, recorded))
169166
}
170167

171-
serializedTree, err := hex.DecodeString(record.Tree)
172-
require.NoError(t, err, "record %d tree", index)
173-
deserializedTree, err := DeserializeBUDTree(serializedTree)
174-
require.NoError(t, err, "record %d tree", index)
175-
require.Equal(t, budlets, deserializedTree.Budlets(), "record %d deserialized tree", index)
176-
budHash := deserializedTree.BUDHash()
177-
require.Equal(t, record.BUDHash, hex.EncodeToString(budHash[:]), "record %d BUD hash", index)
178-
179168
require.Len(t, record.Proofs, len(budlets), "record %d", index)
180169
for i, budlet := range budlets {
181170
serialized, err := hex.DecodeString(record.Proofs[i])
182171
require.NoError(t, err, "record %d budlet %d", index, i)
183172
deserialized, err := DeserializeBUDProof(serialized)
184173
require.NoError(t, err, "record %d budlet %d", index, i)
185174
require.Equal(t, budlet, deserialized.Budlet(), "record %d budlet %d", index, i)
186-
require.Equal(t, budHash, deserialized.ComputeBUDHash(), "record %d budlet %d", index, i)
175+
budHash, err := deserialized.ComputeBUDHash()
176+
require.NoError(t, err, "record %d budlet %d", index, i)
177+
require.Equal(t, record.BUDHash, hex.EncodeToString(budHash[:]), "record %d budlet %d", index, i)
187178
}
188179

189180
if !current {
190181
return
191182
}
192-
tree, err := NewBUDTree(budlets)
193-
require.NoError(t, err, "record %d", index)
194-
require.Equal(t, record.Tree, hex.EncodeToString(tree.Serialize()), "record %d tree", index)
195-
require.Equal(t, budHash, tree.BUDHash(), "record %d BUD hash", index)
183+
budHash := budHashOf(t, budlets)
184+
require.Equal(t, record.BUDHash, hex.EncodeToString(budHash[:]), "record %d BUD hash", index)
196185
for i, budlet := range budlets {
197-
proof, found := tree.BuildBUDProof(budlet.Key())
198-
require.True(t, found, "record %d budlet %d", index, i)
186+
proof := mustNewBUDProof(t, budlets, budlet.Key())
199187
require.Equal(t, record.Proofs[i], hex.EncodeToString(proof.Serialize()),
200188
"record %d budlet %d", index, i)
201189
}
@@ -364,12 +352,9 @@ func recordBUDGoldenFile(t *testing.T) {
364352
func newBUDGoldenRecord(t *testing.T, budlets []*Budlet) budGoldenRecord {
365353
t.Helper()
366354

367-
tree, err := NewBUDTree(budlets)
368-
require.NoError(t, err)
369-
budHash := tree.BUDHash()
355+
budHash := budHashOf(t, budlets)
370356
record := budGoldenRecord{
371357
Budlets: make([]budGoldenBudlet, 0, len(budlets)),
372-
Tree: hex.EncodeToString(tree.Serialize()),
373358
BUDHash: hex.EncodeToString(budHash[:]),
374359
Proofs: make([]string, 0, len(budlets)),
375360
}
@@ -380,8 +365,7 @@ func newBUDGoldenRecord(t *testing.T, budlets []*Budlet) budGoldenRecord {
380365
PreviousValue: hex.EncodeToString(budlet.PreviousValue()),
381366
NotModifiedSince: strconv.FormatUint(budlet.NotModifiedSince(), 10),
382367
})
383-
proof, found := tree.BuildBUDProof(budlet.Key())
384-
require.True(t, found)
368+
proof := mustNewBUDProof(t, budlets, budlet.Key())
385369
record.Proofs = append(record.Proofs, hex.EncodeToString(proof.Serialize()))
386370
}
387371
return record

0 commit comments

Comments
 (0)