|
| 1 | +package bud |
| 2 | + |
| 3 | +import ( |
| 4 | + "bytes" |
| 5 | + "context" |
| 6 | + "errors" |
| 7 | + "fmt" |
| 8 | + "slices" |
| 9 | + "sync" |
| 10 | + |
| 11 | + "github.com/sei-protocol/seilog" |
| 12 | + |
| 13 | + "github.com/sei-protocol/sei-chain/giga/apphash" |
| 14 | + "github.com/sei-protocol/sei-chain/sei-db/state_db/giga/types/mutation" |
| 15 | + "github.com/sei-protocol/sei-chain/sei-db/state_db/sc/flatkv/vtype" |
| 16 | +) |
| 17 | + |
| 18 | +var logger = seilog.NewLogger("giga", "apphash", "bud") |
| 19 | + |
| 20 | +// budTombstoneHorizon is the tombstone horizon, as the BUD spec defines it, of every block: the not-modified-since |
| 21 | +// height of a budlet whose key had no entry in the state before its block. |
| 22 | +// |
| 23 | +// FlatKV MUST start storing tombstones before Autobahn. The true tombstone horizon is the first block at which FlatKV |
| 24 | +// stores tombstones, but it is simpler to set it to the giga upgrade height. It must become that global chain |
| 25 | +// parameter before the mainnet app hash uses the BUD hash. |
| 26 | +const budTombstoneHorizon uint64 = 0 |
| 27 | + |
| 28 | +var _ BUDHasher = (*StandardBUDHasher)(nil) |
| 29 | + |
| 30 | +// StandardBUDHasher is a BUDHasher that sorts each block on one goroutine and hashes it on a second, so the two |
| 31 | +// stages run concurrently on consecutive blocks. |
| 32 | +type StandardBUDHasher struct { |
| 33 | + // Called with each block's BUD hash. An error stops the hasher. |
| 34 | + report func(ctx context.Context, blockHeight uint64, budHash [32]byte) error |
| 35 | + |
| 36 | + // The blocks waiting to be sorted, in submission order, followed by the request Close() sends. |
| 37 | + sortRequests chan budHashRequest |
| 38 | + |
| 39 | + // The sorted blocks waiting to be hashed, in submission order, followed by the request Close() sends. |
| 40 | + hashRequests chan budHashRequest |
| 41 | + |
| 42 | + // Cancelled by Close(), or by the first block that fails. Its cause is the error every later call returns. |
| 43 | + ctx context.Context |
| 44 | + |
| 45 | + // Cancels ctx with a cause. |
| 46 | + cancel context.CancelCauseFunc |
| 47 | + |
| 48 | + // Tracks the sorting and hashing goroutines, which Close() waits for. |
| 49 | + wg sync.WaitGroup |
| 50 | + |
| 51 | + // The error from the block that stopped the hashing goroutine, or nil if none did. Set by the hashing goroutine |
| 52 | + // as it exits, and read by Close() once it has exited. |
| 53 | + failure error |
| 54 | +} |
| 55 | + |
| 56 | +// A request for the sorting and hashing goroutines: a block to hash, or the request Close() sends. |
| 57 | +type budHashRequest struct { |
| 58 | + // The height of the block the mutations belong to. |
| 59 | + blockHeight uint64 |
| 60 | + |
| 61 | + // The block's mutations: as submitted on the way to the sorting goroutine, and sorted by key on the way to the |
| 62 | + // hashing goroutine. |
| 63 | + mutations []mutation.Mutation |
| 64 | + |
| 65 | + // Set only on the request Close() sends, and closed once every block submitted before it has been reported. |
| 66 | + drained chan struct{} |
| 67 | +} |
| 68 | + |
| 69 | +// NewStandardBUDHasher starts a hasher that passes each block's BUD hash to report. Errors if config is invalid. |
| 70 | +func NewStandardBUDHasher( |
| 71 | + // Cancelling it stops the hasher. |
| 72 | + ctx context.Context, |
| 73 | + // Configures the hasher. |
| 74 | + config BUDHasherConfig, |
| 75 | + // Called with each block's BUD hash, in submission order. An error stops the hasher. Its signature matches |
| 76 | + // AppHashBuilder.ReportBUDHash(). |
| 77 | + report func(ctx context.Context, blockHeight uint64, budHash [32]byte) error, |
| 78 | +) (*StandardBUDHasher, error) { |
| 79 | + if err := config.Validate(); err != nil { |
| 80 | + return nil, fmt.Errorf("invalid BUD hasher config: %w", err) |
| 81 | + } |
| 82 | + ctx, cancel := context.WithCancelCause(ctx) |
| 83 | + h := &StandardBUDHasher{ |
| 84 | + report: report, |
| 85 | + sortRequests: make(chan budHashRequest, config.BufferSize), |
| 86 | + hashRequests: make(chan budHashRequest, config.BufferSize), |
| 87 | + ctx: ctx, |
| 88 | + cancel: cancel, |
| 89 | + } |
| 90 | + h.wg.Go(h.sortBlocks) |
| 91 | + h.wg.Go(h.hashBlocks) |
| 92 | + return h, nil |
| 93 | +} |
| 94 | + |
| 95 | +func (h *StandardBUDHasher) Submit(ctx context.Context, blockHeight uint64, mutations []mutation.Mutation) error { |
| 96 | + request := budHashRequest{blockHeight: blockHeight, mutations: mutations} |
| 97 | + if err := h.enqueue(ctx, request); err != nil { |
| 98 | + return fmt.Errorf("failed to submit the mutations of block %d: %w", blockHeight, err) |
| 99 | + } |
| 100 | + return nil |
| 101 | +} |
| 102 | + |
| 103 | +func (h *StandardBUDHasher) Close() error { |
| 104 | + drained := make(chan struct{}) |
| 105 | + // A hasher already stopped refuses the request, and has nothing left to report. |
| 106 | + if h.enqueue(context.Background(), budHashRequest{drained: drained}) == nil { |
| 107 | + select { |
| 108 | + case <-drained: |
| 109 | + case <-h.ctx.Done(): |
| 110 | + } |
| 111 | + } |
| 112 | + h.cancel(errors.New("BUD hasher is closed")) |
| 113 | + h.wg.Wait() |
| 114 | + if h.failure != nil { |
| 115 | + return fmt.Errorf("failed to close BUD hasher: %w", h.failure) |
| 116 | + } |
| 117 | + return nil |
| 118 | +} |
| 119 | + |
| 120 | +// Hands request to the sorting goroutine. |
| 121 | +func (h *StandardBUDHasher) enqueue(ctx context.Context, request budHashRequest) error { |
| 122 | + // A stopped hasher must refuse the request rather than race it into the buffer, where nothing would run it. |
| 123 | + if h.ctx.Err() != nil { |
| 124 | + return h.stoppedError() |
| 125 | + } |
| 126 | + select { |
| 127 | + case h.sortRequests <- request: |
| 128 | + return nil |
| 129 | + case <-h.ctx.Done(): |
| 130 | + return h.stoppedError() |
| 131 | + case <-ctx.Done(): |
| 132 | + return fmt.Errorf("BUD hasher call abandoned: %w", ctx.Err()) |
| 133 | + } |
| 134 | +} |
| 135 | + |
| 136 | +// Returns the error every call returns once the hasher is stopped. |
| 137 | +func (h *StandardBUDHasher) stoppedError() error { |
| 138 | + return fmt.Errorf("BUD hasher stopped: %w", context.Cause(h.ctx)) |
| 139 | +} |
| 140 | + |
| 141 | +// The sorting goroutine. Sorts each block and hands it to the hashing goroutine, until it has handed over the |
| 142 | +// request Close() sends, or the context is cancelled. |
| 143 | +func (h *StandardBUDHasher) sortBlocks() { |
| 144 | + for { |
| 145 | + var request budHashRequest |
| 146 | + select { |
| 147 | + case <-h.ctx.Done(): |
| 148 | + return |
| 149 | + case request = <-h.sortRequests: |
| 150 | + } |
| 151 | + if request.drained == nil { |
| 152 | + request.mutations = sortedByKey(request.mutations) |
| 153 | + } |
| 154 | + select { |
| 155 | + case <-h.ctx.Done(): |
| 156 | + return |
| 157 | + case h.hashRequests <- request: |
| 158 | + } |
| 159 | + if request.drained != nil { |
| 160 | + return |
| 161 | + } |
| 162 | + } |
| 163 | +} |
| 164 | + |
| 165 | +// The hashing goroutine. Hashes and reports sorted blocks until the request Close() sends, a cancelled context, or a |
| 166 | +// block that fails. |
| 167 | +func (h *StandardBUDHasher) hashBlocks() { |
| 168 | + for { |
| 169 | + select { |
| 170 | + case <-h.ctx.Done(): |
| 171 | + return |
| 172 | + case request := <-h.hashRequests: |
| 173 | + if request.drained != nil { |
| 174 | + close(request.drained) |
| 175 | + return |
| 176 | + } |
| 177 | + if err := h.hashAndReport(request); err != nil { |
| 178 | + logger.Error("BUD hasher stopped", "err", err) |
| 179 | + h.failure = err |
| 180 | + h.cancel(err) |
| 181 | + return |
| 182 | + } |
| 183 | + } |
| 184 | + } |
| 185 | +} |
| 186 | + |
| 187 | +// Computes the BUD hash of one sorted block and reports it. |
| 188 | +func (h *StandardBUDHasher) hashAndReport(request budHashRequest) error { |
| 189 | + budHash, err := budHashFromMutations(request.mutations) |
| 190 | + if err != nil { |
| 191 | + return fmt.Errorf("failed to hash block %d: %w", request.blockHeight, err) |
| 192 | + } |
| 193 | + if err := h.report(h.ctx, request.blockHeight, [32]byte(budHash)); err != nil { |
| 194 | + return fmt.Errorf("failed to report the BUD hash of block %d: %w", request.blockHeight, err) |
| 195 | + } |
| 196 | + return nil |
| 197 | +} |
| 198 | + |
| 199 | +// sortedByKey returns a copy of mutations sorted by key, leaving mutations in its original order. |
| 200 | +func sortedByKey(mutations []mutation.Mutation) []mutation.Mutation { |
| 201 | + sorted := slices.Clone(mutations) |
| 202 | + slices.SortFunc(sorted, func(a mutation.Mutation, b mutation.Mutation) int { |
| 203 | + return bytes.Compare(a.Key, b.Key) |
| 204 | + }) |
| 205 | + return sorted |
| 206 | +} |
| 207 | + |
| 208 | +// budHashFromMutations returns the BUD hash of one block's mutations. Each mutation must meet the requirements of |
| 209 | +// budletFromMutation(). |
| 210 | +func budHashFromMutations( |
| 211 | + // The block's mutations, strictly sorted by key. |
| 212 | + mutations []mutation.Mutation, |
| 213 | +) (apphash.BUDHash, error) { |
| 214 | + budlets := make([]*Budlet, len(mutations)) |
| 215 | + for i := range mutations { |
| 216 | + budlet, err := budletFromMutation(&mutations[i]) |
| 217 | + if err != nil { |
| 218 | + return apphash.BUDHash{}, fmt.Errorf("failed to convert mutation %d: %w", i, err) |
| 219 | + } |
| 220 | + budlets[i] = budlet |
| 221 | + } |
| 222 | + treeHash, err := ComputeBUDTreeHash(budlets) |
| 223 | + if err != nil { |
| 224 | + return apphash.BUDHash{}, fmt.Errorf("failed to compute BUD tree hash: %w", err) |
| 225 | + } |
| 226 | + return ComputeBUDHash(uint64(len(budlets)), treeHash), nil |
| 227 | +} |
| 228 | + |
| 229 | +// budletFromMutation returns the budlet for one key a block modified. |
| 230 | +// |
| 231 | +// The mutation's key must not be empty, and each of its values must be nil or a serialized FlatKV VType. A nil value |
| 232 | +// converts to the absent payload, the empty byte string, which budPayload() never returns. |
| 233 | +func budletFromMutation( |
| 234 | + // The mutation to convert. The budlet retains its key. |
| 235 | + m *mutation.Mutation, |
| 236 | +) (*Budlet, error) { |
| 237 | + var value []byte |
| 238 | + if m.NewValue != nil { |
| 239 | + var err error |
| 240 | + value, _, err = budPayload(m.NewValue) |
| 241 | + if err != nil { |
| 242 | + return nil, fmt.Errorf("invalid new value of key %x: %w", m.Key, err) |
| 243 | + } |
| 244 | + } |
| 245 | + |
| 246 | + var previousValue []byte |
| 247 | + notModifiedSince := budTombstoneHorizon |
| 248 | + if m.PreviousValue != nil { |
| 249 | + var err error |
| 250 | + previousValue, notModifiedSince, err = budPayload(m.PreviousValue) |
| 251 | + if err != nil { |
| 252 | + return nil, fmt.Errorf("invalid previous value of key %x: %w", m.Key, err) |
| 253 | + } |
| 254 | + } |
| 255 | + |
| 256 | + budlet, err := NewBudlet(m.Key, value, previousValue, notModifiedSince) |
| 257 | + if err != nil { |
| 258 | + return nil, fmt.Errorf("invalid mutation of key %x: %w", m.Key, err) |
| 259 | + } |
| 260 | + return budlet, nil |
| 261 | +} |
| 262 | + |
| 263 | +// budPayload returns the BUD payload of a serialized FlatKV VType, its serialization version followed by its data, |
| 264 | +// and the height of the block that wrote it. |
| 265 | +func budPayload( |
| 266 | + // The serialized VType. |
| 267 | + value []byte, |
| 268 | +) ([]byte, uint64, error) { |
| 269 | + version, blockHeight, data, err := vtype.SplitValue(value) |
| 270 | + if err != nil { |
| 271 | + return nil, 0, fmt.Errorf("failed to split value: %w", err) |
| 272 | + } |
| 273 | + payload := make([]byte, 0, 1+len(data)) |
| 274 | + payload = append(payload, version) |
| 275 | + payload = append(payload, data...) |
| 276 | + return payload, blockHeight, nil |
| 277 | +} |
0 commit comments