Skip to content

Commit 46393e7

Browse files
cody-littleyCody Littley
andauthored
Giga AppHash spec (#4402)
A design proposal and initial implementation of the giga app hash. As an aside, it's funny that the correct label for this PR is `non-app-hash-breaking`. --------- Co-authored-by: Cody Littley <cody.littley@seinetwork.io>
1 parent 68ba070 commit 46393e7

6 files changed

Lines changed: 853 additions & 0 deletions

File tree

‎giga/apphash/app_hash_codec.go‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
package apphash
2+
3+
import (
4+
"encoding/binary"
5+
"fmt"
6+
)
7+
8+
// Design note: protobuf format intentionally not used, as protobuf serialization is notoriously non-deterministic.
9+
10+
// Byte offsets of each field in the canonical format, which is the fields in declaration order with no padding.
11+
const (
12+
versionOffset = 0
13+
chainIDOffset = versionOffset + 1
14+
blockHeightOffset = chainIDOffset + 8
15+
blockHashOffset = blockHeightOffset + 8
16+
stateHashOffset = blockHashOffset + 32
17+
budOffset = stateHashOffset + 32
18+
receiptHashOffset = budOffset + 32
19+
previousAppHashOffset = receiptHashOffset + 32
20+
21+
// serializedSize is the length of the canonical format.
22+
serializedSize = previousAppHashOffset + 32
23+
)
24+
25+
// Serialize the app hash into the canonical byte format.
26+
// Produces deterministic output.
27+
func (ahd *AppHashData) Serialize() []byte {
28+
data := make([]byte, 0, serializedSize)
29+
data = append(data, ahd.version)
30+
data = binary.BigEndian.AppendUint64(data, ahd.chainID)
31+
data = binary.BigEndian.AppendUint64(data, ahd.blockHeight)
32+
data = append(data, ahd.blockHash[:]...)
33+
data = append(data, ahd.stateHash[:]...)
34+
data = append(data, ahd.bud[:]...)
35+
data = append(data, ahd.receiptHash[:]...)
36+
data = append(data, ahd.previousAppHash[:]...)
37+
return data
38+
}
39+
40+
// Deserialize the app hash from the canonical byte format. It returns an error unless data starts with a
41+
// supported schema version and is exactly the length that version defines.
42+
func Deserialize(data []byte) (*AppHashData, error) {
43+
if len(data) < 1 {
44+
return nil, fmt.Errorf("app hash data is empty")
45+
}
46+
if version := data[versionOffset]; version != appHashVersion {
47+
return nil, fmt.Errorf("unsupported app hash version %d, want %d", version, appHashVersion)
48+
}
49+
if len(data) != serializedSize {
50+
return nil, fmt.Errorf("app hash data is %d bytes, want %d", len(data), serializedSize)
51+
}
52+
return NewAppHashData(
53+
binary.BigEndian.Uint64(data[chainIDOffset:blockHeightOffset]),
54+
binary.BigEndian.Uint64(data[blockHeightOffset:blockHashOffset]),
55+
[32]byte(data[blockHashOffset:stateHashOffset]),
56+
[32]byte(data[stateHashOffset:budOffset]),
57+
[32]byte(data[budOffset:receiptHashOffset]),
58+
[32]byte(data[receiptHashOffset:previousAppHashOffset]),
59+
[32]byte(data[previousAppHashOffset:serializedSize]),
60+
), nil
61+
}

‎giga/apphash/app_hash_data.go‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
package apphash
2+
3+
import "crypto/sha256"
4+
5+
// appHashVersion is the version of the app hash schema produced by this package.
6+
const appHashVersion uint8 = 1
7+
8+
// appHashDomain is the domain separation tag that prefixes the canonical byte format in the app hash preimage.
9+
const appHashDomain = "sei-apphash"
10+
11+
// Contains the data used to produce an app hash.
12+
type AppHashData struct {
13+
14+
// The version of the app hash schema.
15+
version uint8
16+
17+
// The EVM chain ID of the chain the block belongs to.
18+
chainID uint64
19+
20+
// The block height corresponding to this
21+
// app hash.
22+
blockHeight uint64
23+
24+
// The hash of the block.
25+
blockHash [32]byte
26+
27+
// The hash of the state lattice hash.
28+
stateHash [32]byte
29+
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
34+
35+
// The hash of the transaction receipts
36+
// produced by executing this block.
37+
receiptHash [32]byte
38+
39+
// The app hash of block (blockHeight-1).
40+
// All 0s if this is the first block.
41+
previousAppHash [32]byte
42+
43+
// The app hash: SHA-256 of appHashDomain followed by the canonical byte format.
44+
// It is not itself serialized.
45+
appHash [32]byte
46+
}
47+
48+
// Construct a new AppHashData object at the current schema version.
49+
func NewAppHashData(
50+
// The EVM chain ID of the chain the block belongs to.
51+
chainID uint64,
52+
// The block height corresponding to this app hash.
53+
blockHeight uint64,
54+
// The hash of the block.
55+
blockHash [32]byte,
56+
// The hash of the state lattice hash.
57+
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,
62+
// The hash of the transaction receipts produced by executing this block.
63+
receiptHash [32]byte,
64+
// The app hash of block (blockHeight-1), or all 0s if this is the first block.
65+
previousAppHash [32]byte,
66+
) *AppHashData {
67+
ahd := &AppHashData{
68+
version: appHashVersion,
69+
chainID: chainID,
70+
blockHeight: blockHeight,
71+
blockHash: blockHash,
72+
stateHash: stateHash,
73+
bud: bud,
74+
receiptHash: receiptHash,
75+
previousAppHash: previousAppHash,
76+
}
77+
ahd.appHash = sha256.Sum256(append([]byte(appHashDomain), ahd.Serialize()...))
78+
return ahd
79+
}
80+
81+
// Version returns the version of the app hash schema.
82+
func (ahd *AppHashData) Version() uint8 {
83+
return ahd.version
84+
}
85+
86+
// ChainID returns the EVM chain ID of the chain the block belongs to.
87+
func (ahd *AppHashData) ChainID() uint64 {
88+
return ahd.chainID
89+
}
90+
91+
// BlockHeight returns the block height corresponding to this app hash.
92+
func (ahd *AppHashData) BlockHeight() uint64 {
93+
return ahd.blockHeight
94+
}
95+
96+
// BlockHash returns the hash of the block.
97+
func (ahd *AppHashData) BlockHash() [32]byte {
98+
return ahd.blockHash
99+
}
100+
101+
// StateHash returns the hash of the state lattice hash.
102+
func (ahd *AppHashData) StateHash() [32]byte {
103+
return ahd.stateHash
104+
}
105+
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
110+
}
111+
112+
// ReceiptHash returns the hash of the transaction receipts produced by executing this block.
113+
func (ahd *AppHashData) ReceiptHash() [32]byte {
114+
return ahd.receiptHash
115+
}
116+
117+
// PreviousAppHash returns the app hash of block (blockHeight-1), or all 0s if this is the first block.
118+
func (ahd *AppHashData) PreviousAppHash() [32]byte {
119+
return ahd.previousAppHash
120+
}
121+
122+
// AppHash returns the app hash: the SHA-256 of appHashDomain followed by the canonical byte format.
123+
func (ahd *AppHashData) AppHash() [32]byte {
124+
return ahd.appHash
125+
}

0 commit comments

Comments
 (0)