Skip to content

Commit 4a03446

Browse files
cody-littleyCody Littley
andauthored
BUD proof wire format schema + impl (#4417)
Defines the serialization schema for BUD proofs and provides an implementation. --------- Co-authored-by: Cody Littley <cody.littley@seinetwork.io>
1 parent d65f39c commit 4a03446

31 files changed

Lines changed: 3381 additions & 60 deletions

‎giga/apphash/app_hash_codec.go‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,8 @@ const (
1414
blockHeightOffset = chainIDOffset + 8
1515
blockHashOffset = blockHeightOffset + 8
1616
stateHashOffset = blockHashOffset + 32
17-
budOffset = stateHashOffset + 32
18-
receiptHashOffset = budOffset + 32
17+
budHashOffset = stateHashOffset + 32
18+
receiptHashOffset = budHashOffset + 32
1919
previousAppHashOffset = receiptHashOffset + 32
2020

2121
// serializedSize is the length of the canonical format.
@@ -31,7 +31,7 @@ func (ahd *AppHashData) Serialize() []byte {
3131
data = binary.BigEndian.AppendUint64(data, ahd.blockHeight)
3232
data = append(data, ahd.blockHash[:]...)
3333
data = append(data, ahd.stateHash[:]...)
34-
data = append(data, ahd.bud[:]...)
34+
data = append(data, ahd.budHash[:]...)
3535
data = append(data, ahd.receiptHash[:]...)
3636
data = append(data, ahd.previousAppHash[:]...)
3737
return data
@@ -53,8 +53,8 @@ func Deserialize(data []byte) (*AppHashData, error) {
5353
binary.BigEndian.Uint64(data[chainIDOffset:blockHeightOffset]),
5454
binary.BigEndian.Uint64(data[blockHeightOffset:blockHashOffset]),
5555
[32]byte(data[blockHashOffset:stateHashOffset]),
56-
[32]byte(data[stateHashOffset:budOffset]),
57-
[32]byte(data[budOffset:receiptHashOffset]),
56+
[32]byte(data[stateHashOffset:budHashOffset]),
57+
BUDHash(data[budHashOffset:receiptHashOffset]),
5858
[32]byte(data[receiptHashOffset:previousAppHashOffset]),
5959
[32]byte(data[previousAppHashOffset:serializedSize]),
6060
), nil

‎giga/apphash/app_hash_data.go‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ type AppHashData struct {
2727
// The hash of the state lattice hash.
2828
stateHash [32]byte
2929

30-
// The "Block Update Digest", aka the hash of
31-
// the key-value pairs that changed as a result
32-
// of executing this block.
33-
bud [32]byte
30+
// The BUD hash: the hash of the key-value
31+
// pairs that changed as a result of
32+
// executing this block.
33+
budHash BUDHash
3434

3535
// The hash of the transaction receipts
3636
// produced by executing this block.
@@ -45,6 +45,9 @@ type AppHashData struct {
4545
appHash [32]byte
4646
}
4747

48+
// BUDHash is the hash committing to the key-value changes produced by executing a block.
49+
type BUDHash [32]byte
50+
4851
// Construct a new AppHashData object at the current schema version.
4952
func NewAppHashData(
5053
// The EVM chain ID of the chain the block belongs to.
@@ -55,10 +58,10 @@ func NewAppHashData(
5558
blockHash [32]byte,
5659
// The hash of the state lattice hash.
5760
stateHash [32]byte,
58-
// The "Block Update Digest", aka the hash of
59-
// the key-value pairs that changed as a result
60-
// of executing this block.
61-
bud [32]byte,
61+
// The BUD hash: the hash of the key-value
62+
// pairs that changed as a result of
63+
// executing this block.
64+
budHash BUDHash,
6265
// The hash of the transaction receipts produced by executing this block.
6366
receiptHash [32]byte,
6467
// The app hash of block (blockHeight-1), or all 0s if this is the first block.
@@ -70,7 +73,7 @@ func NewAppHashData(
7073
blockHeight: blockHeight,
7174
blockHash: blockHash,
7275
stateHash: stateHash,
73-
bud: bud,
76+
budHash: budHash,
7477
receiptHash: receiptHash,
7578
previousAppHash: previousAppHash,
7679
}
@@ -103,10 +106,9 @@ func (ahd *AppHashData) StateHash() [32]byte {
103106
return ahd.stateHash
104107
}
105108

106-
// BUD returns the "Block Update Digest", aka the hash of the key-value pairs that changed as a result of executing
107-
// this block.
108-
func (ahd *AppHashData) BUD() [32]byte {
109-
return ahd.bud
109+
// BUDHash returns the BUD hash: the hash of the key-value pairs that changed as a result of executing this block.
110+
func (ahd *AppHashData) BUDHash() BUDHash {
111+
return ahd.budHash
110112
}
111113

112114
// ReceiptHash returns the hash of the transaction receipts produced by executing this block.

‎giga/apphash/app_hash_fuzz_test.go‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
package apphash
2+
3+
import (
4+
"testing"
5+
6+
"github.com/stretchr/testify/require"
7+
)
8+
9+
// FuzzDeserialize requires Deserialize() never to panic, and all app hash data it accepts to serialize back to the
10+
// same bytes.
11+
func FuzzDeserialize(f *testing.F) {
12+
f.Add(goldenData().Serialize())
13+
f.Fuzz(func(t *testing.T, data []byte) {
14+
ahd, err := Deserialize(data)
15+
if err != nil {
16+
return
17+
}
18+
require.Equal(t, data, ahd.Serialize())
19+
})
20+
}

‎giga/apphash/app_hash_golden_test.go‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,8 @@ type goldenRecord struct {
5353
// The hash of the state lattice hash.
5454
StateHash string `json:"stateHash"`
5555

56-
// The Block Update Digest.
57-
BUD string `json:"bud"`
56+
// The BUD hash.
57+
BUDHash string `json:"budHash"`
5858

5959
// The hash of the transaction receipts.
6060
ReceiptHash string `json:"receiptHash"`
@@ -112,7 +112,7 @@ func verifyGoldenRecord(t *testing.T, index int, version uint8, record goldenRec
112112
require.NoError(t, err, "record %d blockHeight", index)
113113
blockHash := decodeGoldenHash(t, index, "blockHash", record.BlockHash)
114114
stateHash := decodeGoldenHash(t, index, "stateHash", record.StateHash)
115-
bud := decodeGoldenHash(t, index, "bud", record.BUD)
115+
budHash := decodeGoldenHash(t, index, "budHash", record.BUDHash)
116116
receiptHash := decodeGoldenHash(t, index, "receiptHash", record.ReceiptHash)
117117
previousAppHash := decodeGoldenHash(t, index, "previousAppHash", record.PreviousAppHash)
118118
appHash := decodeGoldenHash(t, index, "appHash", record.AppHash)
@@ -126,15 +126,15 @@ func verifyGoldenRecord(t *testing.T, index int, version uint8, record goldenRec
126126
require.Equal(t, blockHeight, decoded.BlockHeight(), "record %d", index)
127127
require.Equal(t, blockHash, decoded.BlockHash(), "record %d", index)
128128
require.Equal(t, stateHash, decoded.StateHash(), "record %d", index)
129-
require.Equal(t, bud, decoded.BUD(), "record %d", index)
129+
require.Equal(t, BUDHash(budHash), decoded.BUDHash(), "record %d", index)
130130
require.Equal(t, receiptHash, decoded.ReceiptHash(), "record %d", index)
131131
require.Equal(t, previousAppHash, decoded.PreviousAppHash(), "record %d", index)
132132
require.Equal(t, serialization, decoded.Serialize(), "record %d", index)
133133
require.Equal(t, appHash, decoded.AppHash(), "record %d", index)
134134

135135
if version == appHashVersion {
136136
constructed := NewAppHashData(
137-
chainID, blockHeight, blockHash, stateHash, bud, receiptHash, previousAppHash)
137+
chainID, blockHeight, blockHash, stateHash, budHash, receiptHash, previousAppHash)
138138
require.Equal(t, serialization, constructed.Serialize(), "record %d", index)
139139
require.Equal(t, appHash, constructed.AppHash(), "record %d", index)
140140
}
@@ -207,10 +207,11 @@ func buildGoldenChain() []*AppHashData {
207207
for i := uint64(0); i < goldenChainLength; i++ {
208208
blockHash := randomHash()
209209
stateHash := randomHash()
210-
bud := randomHash()
210+
budHash := randomHash()
211211
receiptHash := randomHash()
212212

213-
ahd := NewAppHashData(chainID, startHeight+i, blockHash, stateHash, bud, receiptHash, previousAppHash)
213+
ahd := NewAppHashData(
214+
chainID, startHeight+i, blockHash, stateHash, budHash, receiptHash, previousAppHash)
214215
chain = append(chain, ahd)
215216
previousAppHash = ahd.AppHash()
216217
}
@@ -221,7 +222,7 @@ func buildGoldenChain() []*AppHashData {
221222
func newGoldenRecord(ahd *AppHashData) goldenRecord {
222223
blockHash := ahd.BlockHash()
223224
stateHash := ahd.StateHash()
224-
bud := ahd.BUD()
225+
budHash := ahd.BUDHash()
225226
receiptHash := ahd.ReceiptHash()
226227
previousAppHash := ahd.PreviousAppHash()
227228
appHash := ahd.AppHash()
@@ -230,7 +231,7 @@ func newGoldenRecord(ahd *AppHashData) goldenRecord {
230231
BlockHeight: strconv.FormatUint(ahd.BlockHeight(), 10),
231232
BlockHash: hex.EncodeToString(blockHash[:]),
232233
StateHash: hex.EncodeToString(stateHash[:]),
233-
BUD: hex.EncodeToString(bud[:]),
234+
BUDHash: hex.EncodeToString(budHash[:]),
234235
ReceiptHash: hex.EncodeToString(receiptHash[:]),
235236
PreviousAppHash: hex.EncodeToString(previousAppHash[:]),
236237
Serialization: hex.EncodeToString(ahd.Serialize()),

‎giga/apphash/app_hash_test.go‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ func TestConstructorAndGetters(t *testing.T) {
5252
require.Equal(t, uint64(0x0102030405060708), ahd.BlockHeight())
5353
require.Equal(t, filledHash(0xa1), ahd.BlockHash())
5454
require.Equal(t, filledHash(0xb2), ahd.StateHash())
55-
require.Equal(t, filledHash(0xc3), ahd.BUD())
55+
require.Equal(t, BUDHash(filledHash(0xc3)), ahd.BUDHash())
5656
require.Equal(t, filledHash(0xd4), ahd.ReceiptHash())
5757
require.Equal(t, filledHash(0xe5), ahd.PreviousAppHash())
5858
}
@@ -74,6 +74,17 @@ func TestHashGoldenVector(t *testing.T) {
7474
require.Equal(t, goldenHash, hex.EncodeToString(hash[:]))
7575
}
7676

77+
func TestDeserializeGoldenVector(t *testing.T) {
78+
serialized, err := hex.DecodeString(goldenSerialization)
79+
require.NoError(t, err)
80+
81+
decoded, err := Deserialize(serialized)
82+
require.NoError(t, err)
83+
require.Equal(t, goldenData(), decoded)
84+
hash := decoded.AppHash()
85+
require.Equal(t, goldenHash, hex.EncodeToString(hash[:]))
86+
}
87+
7788
func TestRoundTrip(t *testing.T) {
7889
original := goldenData()
7990

@@ -85,7 +96,7 @@ func TestRoundTrip(t *testing.T) {
8596
require.Equal(t, original.BlockHeight(), decoded.BlockHeight())
8697
require.Equal(t, original.BlockHash(), decoded.BlockHash())
8798
require.Equal(t, original.StateHash(), decoded.StateHash())
88-
require.Equal(t, original.BUD(), decoded.BUD())
99+
require.Equal(t, original.BUDHash(), decoded.BUDHash())
89100
require.Equal(t, original.ReceiptHash(), decoded.ReceiptHash())
90101
require.Equal(t, original.PreviousAppHash(), decoded.PreviousAppHash())
91102
require.Equal(t, original.Serialize(), decoded.Serialize())
@@ -105,8 +116,8 @@ func TestEveryFieldAffectsHash(t *testing.T) {
105116
filledHash(0xc3), filledHash(0xd4), filledHash(0xe5)),
106117
"stateHash": NewAppHashData(0x1112131415161718, 0x0102030405060708, filledHash(0xa1), other,
107118
filledHash(0xc3), filledHash(0xd4), filledHash(0xe5)),
108-
"bud": NewAppHashData(0x1112131415161718, 0x0102030405060708, filledHash(0xa1), filledHash(0xb2), other,
109-
filledHash(0xd4), filledHash(0xe5)),
119+
"budHash": NewAppHashData(0x1112131415161718, 0x0102030405060708, filledHash(0xa1), filledHash(0xb2),
120+
other, filledHash(0xd4), filledHash(0xe5)),
110121
"receiptHash": NewAppHashData(0x1112131415161718, 0x0102030405060708, filledHash(0xa1),
111122
filledHash(0xb2), filledHash(0xc3), other, filledHash(0xe5)),
112123
"previousAppHash": NewAppHashData(0x1112131415161718, 0x0102030405060708, filledHash(0xa1),

‎giga/apphash/apphash_spec.md‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ separators, or length prefixes, for a fixed total of 177 bytes.
3838
| 9 | 8 | `blockHeight` | `u64be` | Defined |
3939
| 17 | 32 | `blockHash` | raw bytes | Defined |
4040
| 49 | 32 | `stateHash` | raw bytes | Defined |
41-
| 81 | 32 | `bud` | raw bytes | **PLACEHOLDER** |
41+
| 81 | 32 | `budHash` | raw bytes | Defined |
4242
| 113 | 32 | `receiptHash` | raw bytes | **PLACEHOLDER** |
4343
| 145 | 32 | `previousAppHash` | raw bytes | Defined, except for the block at the giga activation height |
4444

@@ -47,9 +47,11 @@ any input that is not exactly the length that version defines, which is 177 byte
4747

4848
### Versioning
4949

50-
`version` identifies this specification. It is bumped on any change to the serialization and on any change to
51-
how any field is computed, including when a placeholder below is replaced by its real definition. A block's
52-
app hash is always computed under the version in effect at that block.
50+
`version` identifies this specification. Once the design is formally accepted as final, `version` is bumped on
51+
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.
5355

5456
## Fields
5557

@@ -200,13 +202,11 @@ resulting state.
200202
entry the block writes, subtract the leaf of its previous value (if any) and add the leaf of its new value
201203
(unless it was deleted).
202204

203-
### `bud`: PLACEHOLDER
205+
### `budHash`
204206

205-
The Block Update Digest: a commitment to the key-value changes produced by executing the block. For now, this
206-
is SHA-256 over the block's StateWAL entry. Its byte format is intentionally not specified here.
207-
208-
**Needs design.** The `bud` will become a Merkle tree schema over the block's changes, so that proofs can be
209-
built against it. That design is out of scope for this document.
207+
The BUD hash of the block: a commitment to the key-value changes produced by executing it. It is
208+
defined by the [BUD specification](bud/bud_spec.md), which also defines the BUD proofs and BUD
209+
state proofs built against it.
210210

211211
### `receiptHash`: PLACEHOLDER
212212

@@ -226,11 +226,10 @@ to be block 0, since the chain already exists without this app hash.
226226

227227
## Open design work
228228

229-
| Item | Needed | Owner |
230-
|------------------------|------------------------------------------------------------------|--------------|
231-
| `bud` | A Merkle tree schema over the block's changes, to support proofs | Storage team |
232-
| `receiptHash` | A full definition | EVM team |
233-
| Giga activation height | The height of the first block computed under this scheme | TBD |
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 |
234233

235234
## Test vector
236235

@@ -241,7 +240,7 @@ to be block 0, since the chain already exists without this app hash.
241240
| `blockHeight` | `0x0102030405060708` |
242241
| `blockHash` | 32 bytes of `0xa1` |
243242
| `stateHash` | 32 bytes of `0xb2` |
244-
| `bud` | 32 bytes of `0xc3` |
243+
| `budHash` | 32 bytes of `0xc3` |
245244
| `receiptHash` | 32 bytes of `0xd4` |
246245
| `previousAppHash` | 32 bytes of `0xe5` |
247246

@@ -263,3 +262,6 @@ App hash, i.e. SHA-256 of `"sei-apphash"` followed by the serialization:
263262
```
264263
5cc80f7617e8286151501cfccacbf5bc8b60826b7e224832519b84bdfef6c533
265264
```
265+
266+
Verified by [`TestSerializeLayout`](app_hash_test.go) (serialization) and
267+
[`TestHashGoldenVector`](app_hash_test.go) (app hash).

‎giga/apphash/bud/bud.go‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
package bud
2+
3+
import (
4+
"crypto/sha256"
5+
"encoding/binary"
6+
7+
"github.com/sei-protocol/sei-chain/giga/apphash"
8+
)
9+
10+
const (
11+
// budHashDomain is the domain separation tag that leads the BUD hash preimage.
12+
budHashDomain = "sei-bud"
13+
14+
// 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.
16+
budVersion uint8 = 1
17+
)
18+
19+
// computeBUDHash returns the BUD hash committing to a BUD tree.
20+
func computeBUDHash(
21+
// The number of leaves in the BUD tree.
22+
leafCount uint64,
23+
// The root of the BUD tree.
24+
treeRoot [32]byte,
25+
) apphash.BUDHash {
26+
preimage := make([]byte, 0, len(budHashDomain)+1+8+32)
27+
preimage = append(preimage, budHashDomain...)
28+
preimage = append(preimage, budVersion)
29+
preimage = binary.BigEndian.AppendUint64(preimage, leafCount)
30+
preimage = append(preimage, treeRoot[:]...)
31+
return sha256.Sum256(preimage)
32+
}

0 commit comments

Comments
 (0)