From b5d5c2f47a10bdc2f6f9f72c03f4fdfcb4165a5f Mon Sep 17 00:00:00 2001 From: Timothy Wu Date: Fri, 10 Jan 2025 14:43:34 -0500 Subject: [PATCH] update all client and primitives docs to include type name in docs --- internal/client/api/backend.go | 78 +++++++++---------- internal/client/api/client.go | 2 +- internal/client/api/leaves.go | 5 +- internal/client/api/utils/utils.go | 12 ++- .../client/consensus/grandpa/authorities.go | 2 +- .../client/consensus/grandpa/justification.go | 13 ++-- internal/client/db/backend.go | 42 +++++----- internal/client/db/columns/columns.go | 17 ++-- internal/client/db/metakeys/metakeys.go | 3 +- internal/client/db/offchain/offchain.go | 4 +- internal/cost-lru/cost_lru.go | 2 +- internal/hash-db/hash_db.go | 5 +- internal/kvdb/kvdb.go | 20 ++--- internal/memory-db/memory_db.go | 10 +-- internal/primitives/blockchain/backend.go | 70 ++++++++--------- .../primitives/blockchain/header_metadata.go | 14 ++-- internal/primitives/core/ed25519/ed25519.go | 2 +- internal/primitives/core/offchain/offchain.go | 18 ++--- internal/primitives/database/kvdb.go | 2 +- internal/primitives/database/mem.go | 4 +- internal/primitives/runtime/digest.go | 13 ++-- internal/primitives/runtime/generic/block.go | 2 +- internal/primitives/state-machine/backend.go | 60 +++++++------- .../state-machine/in_memory_backend.go | 2 +- .../state-machine/overlayed_changes.go | 20 ++--- .../primitives/state-machine/trie_backend.go | 14 ++-- internal/primitives/storage/keys/keys.go | 4 +- internal/primitives/storage/storage.go | 52 ++++++------- internal/primitives/trie/cache/cache.go | 10 +-- .../primitives/trie/cache/shared_cache.go | 21 ++--- internal/primitives/trie/recorder/recorder.go | 16 ++-- internal/primitives/trie/storage_proof.go | 10 +-- internal/primitives/trie/trie.go | 28 +++---- 33 files changed, 273 insertions(+), 304 deletions(-) diff --git a/internal/client/api/backend.go b/internal/client/api/backend.go index 36901e1c18..173722362b 100644 --- a/internal/client/api/backend.go +++ b/internal/client/api/backend.go @@ -13,29 +13,29 @@ import ( "github.com/ChainSafe/gossamer/internal/primitives/storage" ) -// State of a new block. +// NewBlockState is the state of a new block. type NewBlockState uint8 const ( - // Normal block. + // NewBlockStateNormal is a normal block. NewBlockStateNormal NewBlockState = iota - // New best block. + // NewBlockStateBest is a new best block. NewBlockStateBest - // Newly finalized block. + // NewBlockStateFinal is a newly finalized block. NewBlockStateFinal ) +// IsBest returns true if equal to [NewBlockStateBest] func (nbs NewBlockState) IsBest() bool { return nbs == NewBlockStateBest } +// IsFinal returns true if equal to [NewBlockStateFinal] func (nbs NewBlockState) IsFinal() bool { return nbs == NewBlockStateFinal } -// Block insertion operation. -// -// Keeps hold of the inserted block state and data. +// BlockImportOperation keeps hold of the inserted block state and data. type BlockImportOperation[ N runtime.Number, H runtime.Hash, @@ -43,12 +43,11 @@ type BlockImportOperation[ Header runtime.Header[N, H], E runtime.Extrinsic, ] interface { - // Returns pending state. - // + // State returns the pending state. // Returns nil for backends with locally-unavailable state data. State() (statemachine.Backend[H, Hasher], error) - // Set block data to the transaction. + // SetBlockData will set block data to the transaction. SetBlockData( header Header, body []E, @@ -57,35 +56,34 @@ type BlockImportOperation[ state NewBlockState, ) error - // Inject storage data into the database. + // UpdateDBStorage will inject storage data into the database. UpdateDBStorage(update statemachine.BackendTransaction[H, Hasher]) error - // Set genesis state. If commit is false the state is saved in memory, but is not written + // SetGenesisState will set genesis state. If commit is false the state is saved in memory, but is not written // to the database. SetGenesisState(storage storage.Storage, commit bool, stateVersion storage.StateVersion) (H, error) - // Inject storage data into the database replacing any existing data. + // ResetStorage will inject storage data into the database replacing any existing data. ResetStorage(storage storage.Storage, stateVersion storage.StateVersion) (H, error) - // Set storage changes. + // UpdateStorage will set storage changes. UpdateStorage(update statemachine.StorageCollection, childUpdate statemachine.ChildStorageCollection) error - // Write offchain storage changes to the database. + // UpdateOffchainStorage will write offchain storage changes to the database. UpdateOffchainStorage(offchainUpdate statemachine.OffchainChangesCollection) error - // Insert auxiliary keys. - // + // InsertAux will insert auxiliary keys. // Values that are nil respresent the keys should be deleted. InsertAux(ops AuxDataOperations) error - // Mark a block as finalized. + // MarkFinalized marks a block as finalized. MarkFinalized(hash H, justification *runtime.Justification) error - // Mark a block as new head. If the block import changes the head and MarkHead is called with a different - // block hash, MarkHead will override the changed head as a result of the block import. + // MarkHead marks a block as the new head. If the block import changes the head and MarkHead is called with + // a different block hash, MarkHead will override the changed head as a result of the block import. MarkHead(hash H) error - // Add a transaction index operation. + // UpdateTransactionIndex adds a transaction index operation. UpdateTransactionIndex(index []statemachine.IndexOperation) error } @@ -94,7 +92,7 @@ type KeyValue struct { Value []byte } -// Provides access to an auxiliary database. +// AuxStore provides access to an auxiliary database. // // This is a simple global database not aware of forks. Can be used for storing auxiliary // information like total block weight/difficulty for fork resolution purposes as a common use @@ -109,7 +107,7 @@ type AuxStore interface { GetAux(key []byte) ([]byte, error) } -// Client backend. +// Backend is the client backend. // // Manages the data layer. // @@ -138,37 +136,35 @@ type Backend[ Header runtime.Header[N, H], E runtime.Extrinsic, ] interface { - // Insert auxiliary data into key-value store. - AuxStore + AuxStore // Insert auxiliary data into key-value store. - // Begin a new block insertion transaction with given parent block id. - // + // BeginOperation begins a new block insertion transaction with given parent block id. // When constructing the genesis, this is called with all-zero hash. BeginOperation() (BlockImportOperation[N, H, Hasher, Header, E], error) - // Note an operation to contain state transition. + // BeginStateOperation notes an operation to contain state transition. BeginStateOperation(operation BlockImportOperation[N, H, Hasher, Header, E], block H) error - // Commit block insertion. + // CommitOperation will commit block insertion. CommitOperation(transaction BlockImportOperation[N, H, Hasher, Header, E]) error - // Finalize block with given hash. + // FinalizeBlock will finalize block with given hash. // // This should only be called if the parent of the given block has been finalized. FinalizeBlock(hash H, justification *runtime.Justification) error - // Append justification to the block with the given hash. + // AppendJustification appends justification to the block with the given hash. // // This should only be called for blocks that are already finalized. AppendJustification(hash H, justification runtime.Justification) error - // Returns reference to blockchain backend. + // Blockchain returns reference to blockchain backend. Blockchain() blockchain.Backend[H, N, Header, E] - // Returns a pointer to offchain storage. + // OffchainStorage returns a pointer to offchain storage. OffchainStorage() offchain.OffchainStorage - // Pin the block to keep body, justification and state available after pruning. + // PinBlock pins the block to keep body, justification and state available after pruning. // Number of pins are reference counted. Users need to make sure to perform // one call to UnpinBlock per call to PinBlock. PinBlock(hash H) error @@ -176,13 +172,13 @@ type Backend[ // Unpin the block to allow pruning. UnpinBlock(hash H) - // Returns true if state for given block is available. + // HaveStateAt returns true if state for given block is available. HaveStateAt(hash H, number N) bool - // Returns state backend with post-state of given block. + // StateAt returns state backend with post-state of given block. StateAt(hash H) (statemachine.Backend[H, Hasher], error) - // Attempts to revert the chain by n blocks. If revertFinalized is set it will attempt to + // Revert attempts to revert the chain by n blocks. If revertFinalized is set it will attempt to // revert past any finalized block. This is unsafe and can potentially leave the node in an // inconsistent state. All blocks higher than the best block are also reverted and not counting // towards n. @@ -191,10 +187,10 @@ type Backend[ // blocks that has been reverted. Revert(n N, revertFinalized bool) (N, map[H]any, error) - // Discard non-best, unfinalized leaf block. + // RemoveLeafBlock discards non-best, unfinalized leaf block. RemoveLeafBlock(hash H) error - // Gain access to the import lock around this backend. + // GetImportLock returns access to the import lock for this backend. // // NOTE: Backend isn't expected to acquire the lock by itself ever. Rather // the using components should acquire and hold the lock whenever they do @@ -202,10 +198,10 @@ type Backend[ // a new block or calculating the best head. GetImportLock() *sync.RWMutex - // Tells whether the backend requires full-sync mode. + // RequiresFullSync tells whether the backend requires full-sync mode. RequiresFullSync() bool - // Returns current usage statistics. + // UsageInfo returns current usage statistics. // TODO: implement UsageInfo if we require it // UsageInfo() *UsageInfo } diff --git a/internal/client/api/client.go b/internal/client/api/client.go index d21c886028..133bd2db20 100644 --- a/internal/client/api/client.go +++ b/internal/client/api/client.go @@ -3,7 +3,7 @@ package api -// List of operations to be performed on storage aux data. +// AuxDataOperation is a slice of operations to be performed on storage aux data. // Key is the encoded data key. // Value is the encoded optional data to write. // If Value is nil, the key and the associated data are deleted from storage. diff --git a/internal/client/api/leaves.go b/internal/client/api/leaves.go index b85e6881b4..2da440a911 100644 --- a/internal/client/api/leaves.go +++ b/internal/client/api/leaves.go @@ -45,9 +45,8 @@ func (fo FinalizationOutcome[H, N]) Leaves() []H { return leaves } -// list of leaf hashes ordered by number (descending). -// stored in memory for fast access. -// this allows very fast checking and modification of active leaves. +// LeafSet is the list of leaf hashes ordered by number (descending) stored in memory for fast access. +// This allows very fast checking and modification of active leaves. type LeafSet[H comparable, N runtime.Number] struct { storage btree.Map[N, []H] } diff --git a/internal/client/api/utils/utils.go b/internal/client/api/utils/utils.go index 9a7ba511fa..6a65509f8d 100644 --- a/internal/client/api/utils/utils.go +++ b/internal/client/api/utils/utils.go @@ -8,18 +8,16 @@ import ( "github.com/ChainSafe/gossamer/internal/primitives/runtime" ) -// Hash and parent hash of a block +// HashParent is the hash and parent hash of a block type HashParent[H runtime.Hash] struct { Hash H Parent H } -// Returns a function for checking block ancestry, the returned function will -// return true if the given hash (second parameter) is a descendent of the -// base (first parameter). If current is defined, it should -// represent the current block hash and its parent hash. if current is given, the -// function that is returned will assume that current.Hash isn't part of the local DB -// yet, and all searches in the DB will instead reference the parent. +// IsDescendantOf returns a function for checking block ancestry, the returned function will return true if the given +// hash (second parameter) is a descendent of the base (first parameter). If current is defined, it should represent +// the current block hash and its parent hash. if current is given, the function that is returned will assume that +// current.Hash isn't part of the local DB yet, and all searches in the DB will instead reference the parent. func IsDescendantOf[H runtime.Hash, N runtime.Number, Header runtime.Header[N, H], E runtime.Extrinsic]( client blockchain.Backend[H, N, Header, E], current *HashParent[H], ) func(a H, b H) (bool, error) { diff --git a/internal/client/consensus/grandpa/authorities.go b/internal/client/consensus/grandpa/authorities.go index 261042fe9a..4accb53dd5 100644 --- a/internal/client/consensus/grandpa/authorities.go +++ b/internal/client/consensus/grandpa/authorities.go @@ -3,7 +3,7 @@ package grandpa -// generic representation of hash and number tuple +// HashNumber is a generic representation of hash and number type HashNumber[H, N any] struct { Hash H Number N diff --git a/internal/client/consensus/grandpa/justification.go b/internal/client/consensus/grandpa/justification.go index 3d314de48c..584abaf3c9 100644 --- a/internal/client/consensus/grandpa/justification.go +++ b/internal/client/consensus/grandpa/justification.go @@ -22,14 +22,13 @@ var ( errBlockNotDescendentOfBase = errors.New("block not descendent of base") ) -// A GRANDPA justification for block finality, it includes a commit message and -// an ancestry proof including all headers routing all precommit target blocks -// to the commit target block. Due to the current voting strategy the precommit -// targets should be the same as the commit target, since honest voters don't -// vote past authority set change blocks. +// GrandpaJustification is a GRANDPA justification for block finality, it includes a commit message and an ancestry +// proof including all headers routing all precommit target blocks to the commit target block. Due to the current +// voting strategy the precommit targets should be the same as the commit target, since honest voters don't vote past +// authority set change blocks. // -// This is meant to be stored in the db and passed around the network to other -// nodes, and are used by syncing nodes to prove authority set handoffs. +// This is meant to be stored in the db and passed around the network to other nodes, and are used by syncing nodes +// to prove authority set handoffs. type GrandpaJustification[Hash runtime.Hash, N runtime.Number] struct { // The GRANDPA justification for block finality. Justification primitives.GrandpaJustification[Hash, N] diff --git a/internal/client/db/backend.go b/internal/client/db/backend.go index a5128b77f2..42bb589681 100644 --- a/internal/client/db/backend.go +++ b/internal/client/db/backend.go @@ -37,7 +37,7 @@ import ( var logger = log.NewFromGlobal(log.AddContext("pkg", "client/db")) -// Block pruning settings. +// BlocksPruning represent block pruning settings. type BlocksPruning interface { isBlocksPruning() } @@ -45,20 +45,20 @@ type BlocksPruningValues interface { BlocksPruningKeepAll | BlocksPruningKeepFinalized | BlocksPruningSome } -// Keep full block history, of every block that was ever imported. +// BlocksPruningKeepAll keeps full block history, of every block that was ever imported. type BlocksPruningKeepAll struct{} -// Keep full finalized block history. +// BlocksPruningKeepFinalized keeps full finalized block history. type BlocksPruningKeepFinalized struct{} -// Keep N recent finalized blocks. +// BlocksPruningSome keep a defined number of recent finalized blocks. type BlocksPruningSome uint32 func (BlocksPruningKeepAll) isBlocksPruning() {} func (BlocksPruningKeepFinalized) isBlocksPruning() {} func (BlocksPruningSome) isBlocksPruning() {} -// Where to find the database.. +// DatabaseSource is the source of the database. // NOTE: only uses a custom already-open database. type DatabaseSource struct { // the handle to the custom storage @@ -67,12 +67,12 @@ type DatabaseSource struct { RequireCreateFlag bool } -// DB-backed patricia trie state, transaction type is an overlay of changes to commit. +// DBState is a db backed patricia trie state, transaction type is an overlay of changes to commit. type DBState[H runtime.Hash, Hasher runtime.Hasher[H]] struct { *statemachine.TrieBackend[H, Hasher] } -// A reference tracking state. +// refTrackingState is a reference tracking state. // // It makes sure that the hash we are using stays pinned in storage // until this structure is dropped. @@ -88,23 +88,21 @@ func (rts *refTrackingState[H, Hasher]) Drop() { } } -// Database configuration. +// DatabaseConfig is the database configuration. type DatabaseConfig struct { - // The maximum trie cache size in bytes. - // + // TrieCacheMaximumSize is the maximum trie cache size in bytes. // If nil is given, the cache is disabled. TrieCacheMaximumSize *uint - // Requested state pruning mode. + // StatePruning is the requested state pruning mode. StatePruning statedb.PruningMode - // Where to find the database. + // Source is the source of the database Source DatabaseSource - // Block pruning mode. - // + // BlocksPruning is the block pruning mode. // NOTE: only finalized blocks are subject for removal! BlocksPruning BlocksPruning } -// wrapper that implements trait required for state_db +// wrapper around [database.Database] that implements [statedb.MetaDB] type stateMetaDB struct { db database.Database[hash.H256] } @@ -123,7 +121,7 @@ type finalizedBlock[H runtime.Hash] struct { *runtime.Justification } -// [Backend] block import operation which represents a transaction +// BlockImportOperation is [Backend] block import operation which represents a transaction. type BlockImportOperation[ H runtime.Hash, Hasher runtime.Hasher[H], @@ -366,9 +364,7 @@ func newEmptyStorage[H runtime.Hash, Hasher runtime.Hasher[H]]() emptyStorage[H] return emptyStorage[H]{root} } -// Disk backend. -// -// Disk backend keeps data in a key-value store. In archive mode, trie nodes are kept from all +// Backend keeps data in a key-value store. In archive mode, trie nodes are kept from all // blocks. Otherwise, trie nodes are kept only from some recent blocks. type Backend[ H runtime.Hash, @@ -389,7 +385,7 @@ type Backend[ sharedTrieCache *cache.SharedTrieCache[H] // can be nil to respresent no shared trie cache } -// Create a new instance of database backend. +// NewBackend creates a new instance of database backend. // // dbConfig is of type [DatabaseConfig] and contains both state and block history pruning settings. // canonicalizationDelay represents the number of blocks it waits to canonicalize the block and initiate @@ -497,7 +493,7 @@ func newBackendFromDatabase[ return &backend, nil } -// Reset the shared trie cache. +// ResetTrieCache resets the shared trie cache. func (b *Backend[H, Hasher, N, E, Header]) ResetTrieCache() { if b.sharedTrieCache != nil { b.sharedTrieCache.Reset() @@ -509,13 +505,13 @@ type numberHash[H, N any] struct { Hash H } -// Handle setting head within a transaction. routeTo should be the last +// Handles setting head within a transaction. routeTo should be the last // block that existed in the database. bestTo should be the best block // to be set. // // In the case where the new best block is a block to be imported, routeTo // should be the parent of bestTO. In the case where we set an existing block -// to be best, routTo should equal to bestTo. +// to be best, routeTo should equal to bestTo. func (b *Backend[H, Hasher, N, E, Header]) setHeadWithTransaction( transaction *database.Transaction[hash.H256], routeTo H, bestTo numberHash[H, N], ) ([2][]H, error) { diff --git a/internal/client/db/columns/columns.go b/internal/client/db/columns/columns.go index 1fe38db590..b0bc24e605 100644 --- a/internal/client/db/columns/columns.go +++ b/internal/client/db/columns/columns.go @@ -6,18 +6,15 @@ package columns import "github.com/ChainSafe/gossamer/internal/primitives/database" const ( - Meta database.ColumnID = 0 - State database.ColumnID = 1 - StateMeta database.ColumnID = 2 - // maps hashes to lookup keys and numbers to canon hashes. - KeyLookup database.ColumnID = 3 + Meta database.ColumnID = 0 + State database.ColumnID = 1 + StateMeta database.ColumnID = 2 + KeyLookup database.ColumnID = 3 // maps hashes to lookup keys and numbers to canon hashes. Header database.ColumnID = 4 Body database.ColumnID = 5 Justifications database.ColumnID = 6 Aux database.ColumnID = 8 - // Offchain workers local storage - Offchain database.ColumnID = 9 - // Transactions - Transaction database.ColumnID = 11 - BodyIndex database.ColumnID = 12 + Offchain database.ColumnID = 9 // offchain workers local storage + Transaction database.ColumnID = 11 + BodyIndex database.ColumnID = 12 ) diff --git a/internal/client/db/metakeys/metakeys.go b/internal/client/db/metakeys/metakeys.go index e5978f33c7..a5959599d3 100644 --- a/internal/client/db/metakeys/metakeys.go +++ b/internal/client/db/metakeys/metakeys.go @@ -1,10 +1,9 @@ // Copyright 2024 ChainSafe Systems (ON) // SPDX-License-Identifier: LGPL-3.0-only +// package metakeys contain the keys of entries in meta column. package metakeys -// Keys of entries in COLUMN_META. - // Type of storage (full or light). var Type = []byte("type") diff --git a/internal/client/db/offchain/offchain.go b/internal/client/db/offchain/offchain.go index 4bba8bc23e..f91f6a7c7d 100644 --- a/internal/client/db/offchain/offchain.go +++ b/internal/client/db/offchain/offchain.go @@ -13,7 +13,7 @@ import ( "github.com/ChainSafe/gossamer/internal/primitives/database" ) -// Offchain local storage +// LocalStorage is local offchain storage. Implements offchain.OffchainStorage type LocalStorage struct { db database.Database[hash.H256] locks map[string]*sync.Mutex @@ -88,7 +88,7 @@ func (ls *LocalStorage) CompareAndSet(prefix, itemKey, oldValue, newValue []byte return isSet } -// Concatenate the prefix and key to create an offchain key in the db. +// ConcatenatePrefixAndKey will concatenate the prefix and key to create an offchain key in the db. func ConcatenatePrefixAndKey(prefix, key []byte) []byte { return append(prefix, key...) } diff --git a/internal/cost-lru/cost_lru.go b/internal/cost-lru/cost_lru.go index 54dd00ba6f..cedc44449c 100644 --- a/internal/cost-lru/cost_lru.go +++ b/internal/cost-lru/cost_lru.go @@ -19,7 +19,7 @@ type LRU[K comparable, V any] struct { *freelru.LRU[K, V] } -// Costructor for [LRU]. +// New is constructor for [LRU]. func New[K comparable, V any]( maxCost uint, hash freelru.HashKeyCallback[K], costFunc func(K, V) uint32, ) (*LRU[K, V], error) { diff --git a/internal/hash-db/hash_db.go b/internal/hash-db/hash_db.go index 4b2d891a6d..aea78cf72c 100644 --- a/internal/hash-db/hash_db.go +++ b/internal/hash-db/hash_db.go @@ -5,8 +5,7 @@ package hashdb import "golang.org/x/exp/constraints" -// A trie node prefix, it is the nibble path from the trie root -// to the trie node. +// Prefix is a trie node prefix, it is the nibble path from the trie root to the trie node. // For a node containing no partial key value it is the full key. // For a value node or node containing a partial key, it is the full key minus its node partial // nibbles (the node key can be split into prefix and node partial). @@ -18,7 +17,7 @@ type Prefix struct { Padded *byte } -// An empty prefix constant. +// EmptyPrefix is the empty prefix constant. // Can be use when the prefix is not used internally or for root nodes. var EmptyPrefix = Prefix{} diff --git a/internal/kvdb/kvdb.go b/internal/kvdb/kvdb.go index 9ec70d2267..0114f3265b 100644 --- a/internal/kvdb/kvdb.go +++ b/internal/kvdb/kvdb.go @@ -5,10 +5,10 @@ package kvdb import "iter" -// Database value. +// DBValue is the database value. type DBValue []byte -// Database keys. +// DBKey is the database key. type DBKey []byte type DBKeyValue struct { @@ -16,7 +16,7 @@ type DBKeyValue struct { Value DBValue } -// Database operation. +// DBOp is a database operation. type DBOp interface { Key() []byte Col() uint32 @@ -59,20 +59,20 @@ func (idbo DeletePrefixDBOp) Col() uint32 { return idbo.col } -// Write transaction. Batches a sequence of put/delete operations for efficiency. +// DBTransaction is a write transaction. Batches a sequence of put/delete operations for efficiency. type DBTransaction struct { // Database operations. Ops []DBOp } -// Create new transaction. +// NewDBTransaction creates new transaction. func NewDBTransaction() DBTransaction { return DBTransaction{ Ops: make([]DBOp, 0), } } -// Insert a key-value pair in the transaction. Any existing value will be overwritten upon write. +// Put inserts a key-value pair in the transaction. Any existing value will be overwritten upon write. func (dbt *DBTransaction) Put(col uint32, key, value []byte) { dbt.Ops = append(dbt.Ops, InsertDBOp{ col: col, @@ -89,7 +89,7 @@ func (dbt *DBTransaction) Delete(col uint32, key []byte) { }) } -// Delete all values with the given key prefix. +// DeletePrefix deletes all values with the given key prefix. // Using an empty prefix here will remove all keys // (all keys start with the empty prefix). func (dbt *DBTransaction) DeletePrefix(col uint32, prefix []byte) { @@ -99,9 +99,9 @@ func (dbt *DBTransaction) DeletePrefix(col uint32, prefix []byte) { }) } -// Generic key-value database. +// KeyValueDB is a generic key-value database. // -// The KeyValueDB deals with "column families", which can be thought of as distinct +// KeyValueDB deals with "column families", which can be thought of as distinct // stores within a database. Keys written in one column family will not be accessible from // any other. The number of column families must be specified at initialization, with a // differing interface for each database. @@ -129,7 +129,7 @@ type KeyValueDB interface { HasPrefix(col uint32, prefix []byte) (bool, error) } -// For a given start prefix (inclusive), returns the correct end prefix (non-inclusive). +// EndPrefix when called for a given start prefix (inclusive), returns the correct end prefix (non-inclusive). // This assumes the key bytes are ordered in lexicographical order. // Since key length is not limited, for some case we return nil because there is // no bounded limit (every keys in the series [], [255], [255, 255] ...). diff --git a/internal/memory-db/memory_db.go b/internal/memory-db/memory_db.go index 803c1563ae..b43a631a4c 100644 --- a/internal/memory-db/memory_db.go +++ b/internal/memory-db/memory_db.go @@ -24,7 +24,7 @@ type Value interface { ~[]byte } -// Reference-counted memory-based [hashdb.HashDB] implementation. +// MemoryDB is a reference-counted memory-based [hashdb.HashDB] implementation. type MemoryDB[H Hash, Hasher hashdb.Hasher[H], Key constraints.Ordered, KF KeyFunction[H, Key]] struct { data map[Key]dataRC hashedNullNode H @@ -65,7 +65,7 @@ func (mdb *MemoryDB[H, Hasher, Key, KF]) Purge() { } } -// Return the internal key-value Map, clearing the current state. +// Drain returns the internal key-value Map, clearing the current state. func (mdb *MemoryDB[H, Hasher, Key, KF]) Drain() map[Key]dataRC { data := mdb.data mdb.data = make(map[Key]dataRC) @@ -217,21 +217,21 @@ type KeyFunction[Hash constraints.Ordered, Key any] interface { Key(hash Hash, prefix hashdb.Prefix) Key } -// Key function that only uses the hash +// HashKey is KeyFunction that only uses the hash type HashKey[H Hash] struct{} func (HashKey[Hash]) Key(hash Hash, prefix hashdb.Prefix) Hash { return hash } -// Key function that concatenates prefix and hash. +// PrefixedKey is KeyFunction that concatenates prefix and hash. type PrefixedKey[H Hash] struct{} func (PrefixedKey[H]) Key(key H, prefix hashdb.Prefix) string { return string(NewPrefixedKey(key, prefix)) } -// Derive a database key from hash value of the node (key) and the node prefix. +// NewPrefixedKey derives a database key from hash value of the node (key) and the node prefix. func NewPrefixedKey[H Hash](key H, prefix hashdb.Prefix) []byte { prefixedKey := prefix.Key if prefix.Padded != nil { diff --git a/internal/primitives/blockchain/backend.go b/internal/primitives/blockchain/backend.go index 1468371762..47a1053a98 100644 --- a/internal/primitives/blockchain/backend.go +++ b/internal/primitives/blockchain/backend.go @@ -10,103 +10,95 @@ import ( "github.com/ChainSafe/gossamer/internal/primitives/runtime/generic" ) -// Header is the blockchain database header backend. Does not perform any validation. +// HeaderBackend is the blockchain database header backend. Does not perform any validation. type HeaderBackend[Hash runtime.Hash, N runtime.Number, Header runtime.Header[N, Hash]] interface { - // Get block header. Returns nil if block is not found. + // Header returns the block header. Returns nil if block is not found. Header(hash Hash) (*Header, error) - // Get blockchain info. + // Info returns blockchain [Info]. Info() Info[Hash, N] - // Get block status. + // Status returns [BlockStatus]. Status(hash Hash) (BlockStatus, error) - // Get block number by hash. Returns nil if the header is not in the chain. + // Number returns block number by hash. Returns nil if the header is not in the chain. Number(hash Hash) (*N, error) - // Get block hash by number. Returns nil if the header is not in the chain. + // Hash returns block hash by number. Returns nil if the header is not in the chain. Hash(number N) (*Hash, error) - // Convert an arbitrary block ID into a block hash. + // BlockHashFromID converts an arbitrary block ID into a block hash. BlockHashFromID(id generic.BlockID) (*Hash, error) - // Convert an arbitrary block ID into a block hash. + // BlockNumberFromID converts an arbitrary block ID into a block hash. BlockNumberFromID(id generic.BlockID) (*N, error) } -// Blockchain database backend. Does not perform any validation. +// Backend is a blockchain database backend. Does not perform any validation. type Backend[Hash runtime.Hash, N runtime.Number, Header runtime.Header[N, Hash], E runtime.Extrinsic] interface { HeaderBackend[Hash, N, Header] HeaderMetadata[Hash, N] - // Get block body. Returns nil if block is not found. + // Body returns block body. Returns nil if block is not found. Body(hash Hash) ([]E, error) - // Get block justifications. Returns nil if no justification exists. + // Justifications returns block justifications. Returns nil if no justification exists. Justifications(hash Hash) (runtime.Justifications, error) - // Get last finalized block hash. + // LastFinalized returns last finalized block hash. LastFinalized() (Hash, error) - // Returns hashes of all blocks that are leaves of the block tree. + // Leaves returns hashes of all blocks that are leaves of the block tree. // in other words, that have no children, are chain heads. // Results must be ordered best (longest, highest) chain first. Leaves() ([]Hash, error) - // Returns displaced leaves after the given block would be finalized. - // + // DisplacedLeavesAfterFinalizing returns displaced leaves after the given block would be finalized. // The returned leaves do not contain the leaves from the same height as blockNumber. DisplacedLeavesAfterFinalizing(blockNumber N) ([]Hash, error) - // Return hashes of all blocks that are children of the block with parentHash. + // Children returns hashes of all blocks that are children of the block with parentHash. Children(parentHash Hash) ([]Hash, error) - // Get the most recent block hash of the longest chain that contains + // LongestContaining gets the most recent block hash of the longest chain that contains // a block with the given baseHash. - // + // The search space is always limited to blocks which are in the finalized // chain or descendents of it. // // Returns nil if basehash is not found in search space. LongestContaining(baseHash Hash, importLock *sync.RWMutex) (*Hash, error) - // Get single indexed transaction by content hash. Note that this will only fetch transactions + // IndexedTransaction returns single indexed transaction by content hash. Note that this will only fetch transactions // that are indexed by the runtime with storage_index_transaction. IndexedTransaction(hash Hash) ([]byte, error) - // Check if indexed transaction exists. + // HasIndexedTransaction checks if indexed transaction exists. HasIndexedTransaction(hash Hash) (bool, error) + // BlockIndexedBody will return the indexed body if it exists. BlockIndexedBody(hash Hash) ([][]byte, error) } -// Blockchain info +// Info is the blockchain info type Info[H, N any] struct { - // Best block hash. - BestHash H - // Best block number. - BestNumber N - // Genesis block hash. - GenesisHash H - // The head of the finalized chain. - FinalizedHash H - // Last finalized block number. - FinalizedNumber N - // Last finalized state. - FinalizedState *struct { + BestHash H // Best block hash. + BestNumber N // Best block number. + GenesisHash H // Genesis block hash. + FinalizedHash H // The head of the finalized chain. + FinalizedNumber N // Last finalized block number. + FinalizedState *struct { // Last finalized state. Hash H Number N } - // Number of concurrent leave forks. - NumberLeaves uint - // Missing blocks after warp sync. (start, end). - BlockGap *[2]N + NumberLeaves uint // Number of concurrent leave forks. + BlockGap *[2]N // Missing blocks after warp sync. (start, end). } // BlockStatus is block status. type BlockStatus uint const ( - // Already in the blockchain. + // BlockStatusInChain represents block is already in the blockchain. BlockStatusInChain BlockStatus = iota - // Not in the queue or the blockchain. + // BlockStatusUnknown represents block is not in the queue or the blockchain. BlockStatusUnknown ) diff --git a/internal/primitives/blockchain/header_metadata.go b/internal/primitives/blockchain/header_metadata.go index 5964cc8631..784bd3d657 100644 --- a/internal/primitives/blockchain/header_metadata.go +++ b/internal/primitives/blockchain/header_metadata.go @@ -11,7 +11,7 @@ import ( lru "github.com/hashicorp/golang-lru/v2" ) -// Get lowest common ancestor between two blocks in the tree. +// LowestCommonAncestor will get lowest common ancestor between two blocks in the tree. // // This implementation is efficient because our trees have very few and // small branches, and because of our current query pattern: @@ -93,7 +93,7 @@ func LowestCommonAncestor[H runtime.Hash, N runtime.Number]( return HashNumber[H, N]{Hash: header1.Hash, Number: header1.Number}, nil } -// Compute a tree-route between two blocks. See tree-route docs for more details. +// NewTreeRoute computes a [TreeRoute] between two blocks. See [TreeRoute] docs for more details. func NewTreeRoute[H runtime.Hash, N runtime.Number]( backend HeaderMetadata[H, N], from, to H, ) (TreeRoute[H, N], error) { @@ -154,7 +154,7 @@ func NewTreeRoute[H runtime.Hash, N runtime.Number]( return TreeRoute[H, N]{Route: fromBranch, Pivot: pivot}, nil } -// Hash and number of a block. +// HashNumber is the hash and number of a block. type HashNumber[H runtime.Hash, N runtime.Number] struct { // The number of the block. Number N @@ -162,7 +162,7 @@ type HashNumber[H runtime.Hash, N runtime.Number] struct { Hash H } -// A tree-route from one block to another in the chain. +// A TreeRoute from one block to another in the chain. // // All blocks prior to the pivot in the deque is the reverse-order unique ancestry // of the first block, the block at the pivot index is the common ancestor, @@ -202,14 +202,14 @@ func (tr TreeRoute[H, N]) Enacted() []HashNumber[H, N] { return tr.Route[tr.Pivot+1:] } -// Handles header metadata: hash, number, parent hash, etc. +// HeaderMetadata handles header metadata: hash, number, parent hash, etc. type HeaderMetadata[H, N any] interface { HeaderMetadata(hash H) (CachedHeaderMetadata[H, N], error) InsertHeaderMetadata(hash H, headerMetadata CachedHeaderMetadata[H, N]) RemoveHeaderMetadata(hash H) } -// Caches header metadata in an in-memory LRU cache. +// HeaderMetadataCache caches header metadata in an in-memory LRU cache. type HeaderMetadataCache[H comparable, N any] struct { cache *lru.Cache[H, CachedHeaderMetadata[H, N]] sync.RWMutex @@ -269,7 +269,7 @@ type CachedHeaderMetadata[H, N any] struct { ancestor H } -// NewCachedHeaderMetadata is constructor for CachedHeaderMetadata +// NewCachedHeaderMetadata is constructor for [CachedHeaderMetadata] func NewCachedHeaderMetadata[H runtime.Hash, N runtime.Number](header runtime.Header[N, H]) CachedHeaderMetadata[H, N] { return CachedHeaderMetadata[H, N]{ Hash: header.Hash(), diff --git a/internal/primitives/core/ed25519/ed25519.go b/internal/primitives/core/ed25519/ed25519.go index 9f6a296625..e3f14d9527 100644 --- a/internal/primitives/core/ed25519/ed25519.go +++ b/internal/primitives/core/ed25519/ed25519.go @@ -21,7 +21,7 @@ import ( // A secret seed. type seed [32]byte -// A Public key. +// Public is a public key. type Public [32]byte // Bytes returns a byte slice diff --git a/internal/primitives/core/offchain/offchain.go b/internal/primitives/core/offchain/offchain.go index 11b0d93fd0..0a8c289c12 100644 --- a/internal/primitives/core/offchain/offchain.go +++ b/internal/primitives/core/offchain/offchain.go @@ -3,33 +3,33 @@ package offchain -// Offchain DB persistent (non-fork-aware) storage. +// OffchainStorage is offchain DB persisted (non-fork-aware) storage. type OffchainStorage interface { - // Persist a value in storage under given key and prefix. + // Set persists a value in storage under given key and prefix. Set(prefix, key, value []byte) - // Clear a storage entry under given key and prefix. + // Remove clears a storage entry under given key and prefix. Remove(prefix, key []byte) - // Retrieve a value from storage under given key and prefix. + // Get retrieves a value from storage under given key and prefix. Get(prefix, key []byte) []byte - // Replace the value in storage if given old_value matches the current one. + // CompareAndSet will replace the value in storage if given oldValue matches the current one. // // Returns true if the value has been set and false otherwise. CompareAndSet(prefix, key, oldValue, newValue []byte) bool } -// Change to be applied to the offchain worker db in regards to a key. +// OffchainOverlayedChanges is a change to be applied to the offchain worker db in regards to a key. type OffchainOverlayedChanges interface { OffchainOverlayedChangeRemove | OffchainOverlayedChangeSetValue } -// Change to be applied to the offchain worker db in regards to a key. +// OffchainOverlayedChange is a change to be applied to the offchain worker db in regards to a key. type OffchainOverlayedChange any -// Remove the data associated with the key +// OffchainOverlayedChangeRemove removes the data associated with the key type OffchainOverlayedChangeRemove struct{} -// Overwrite the value of an associated key +// OffchainOverlayedChangeSetValue overwrites the value of an associated key type OffchainOverlayedChangeSetValue []byte diff --git a/internal/primitives/database/kvdb.go b/internal/primitives/database/kvdb.go index e9aa748a8c..9e7cce7e53 100644 --- a/internal/primitives/database/kvdb.go +++ b/internal/primitives/database/kvdb.go @@ -11,7 +11,7 @@ import ( "github.com/ChainSafe/gossamer/internal/primitives/runtime" ) -// A wrapper around [kvdb.KeyValueDB] that implements [Database] interface +// DBAdapter is a wrapper around [kvdb.KeyValueDB] that implements [Database] interface type DBAdapter[H runtime.Hash] struct { db kvdb.KeyValueDB } diff --git a/internal/primitives/database/mem.go b/internal/primitives/database/mem.go index e0db49e83e..a007192a21 100644 --- a/internal/primitives/database/mem.go +++ b/internal/primitives/database/mem.go @@ -88,7 +88,7 @@ func (mdb *MemDB[H]) Commit(transaction Transaction[H]) error { return nil } -// Retrieve the value previously stored against key or nil if key is not currently in the database. +// Get retrieves the value previously stored against key or nil if key is not currently in the database. func (mdb *MemDB[H]) Get(col ColumnID, key []byte) []byte { mdb.RLock() defer mdb.RUnlock() @@ -103,7 +103,7 @@ func (mdb *MemDB[H]) Get(col ColumnID, key []byte) []byte { return nil } -// Check if the value exists in the database without retrieving it. +// Contains checks if the value exists in the database without retrieving it. func (mdb *MemDB[H]) Contains(col ColumnID, key []byte) bool { return mdb.Get(col, key) != nil } diff --git a/internal/primitives/runtime/digest.go b/internal/primitives/runtime/digest.go index 28a1bc4018..6b60bb5670 100644 --- a/internal/primitives/runtime/digest.go +++ b/internal/primitives/runtime/digest.go @@ -9,13 +9,12 @@ import ( "github.com/ChainSafe/gossamer/pkg/scale" ) -// Digest item that is able to encode/decode 'system' digest items and -// provide opaque access to other items. +// DigestItemTypes is interface constraint of [DigestItem] type DigestItemTypes interface { PreRuntime | Consensus | Seal | Other | RuntimeEnvironmentUpdated } -// Digest item that is able to encode/decode 'system' digest items and +// DigestItem is able to encode/decode "system" digest items and // provide opaque access to other items. type DigestItem struct { inner any @@ -95,7 +94,7 @@ func (mvdt DigestItem) String() string { return fmt.Sprintf("%s", mvdt.inner) } -// A pre-runtime digest. +// PreRuntime is a pre-runtime digest. // // These are messages from the consensus engine to the runtime, although // the consensus engine can (and should) read them itself to avoid @@ -112,7 +111,7 @@ type PreRuntime struct { Bytes []byte } -// A message from the runtime to the consensus engine. This should *never* +// Consensus is a message from the runtime to the consensus engine. This should *never* // be generated by the native code of any consensus engine, but this is not // checked (yet). type Consensus struct { @@ -127,10 +126,10 @@ type Seal struct { Bytes []byte } -// Some other thing. Unsupported and experimental. +// Some Other thing. Unsupported and experimental. type Other []byte -// An indication for the light clients that the runtime execution +// RuntimeEnvironmentUpdated is an indication for the light clients that the runtime execution // environment is updated. type RuntimeEnvironmentUpdated struct{} diff --git a/internal/primitives/runtime/generic/block.go b/internal/primitives/runtime/generic/block.go index d0d9986e8e..a43cbb6c6a 100644 --- a/internal/primitives/runtime/generic/block.go +++ b/internal/primitives/runtime/generic/block.go @@ -10,7 +10,7 @@ import ( "github.com/ChainSafe/gossamer/internal/primitives/runtime" ) -// Something to identify a block. +// BlockID is used to identify a block. type BlockID interface { isBlockID() } diff --git a/internal/primitives/state-machine/backend.go b/internal/primitives/state-machine/backend.go index 67a7b009c2..44b2671c03 100644 --- a/internal/primitives/state-machine/backend.go +++ b/internal/primitives/state-machine/backend.go @@ -12,24 +12,24 @@ import ( "github.com/ChainSafe/gossamer/pkg/trie/triedb" ) -// A struct containing arguments for iterating over the storage. +// IterArgs is a struct containing arguments for iterating over the storage. type IterArgs struct { - // The prefix of the keys over which to iterate. + // Prefix of the keys over which to iterate. Prefix []byte - // The prefix from which to start the iteration from. + // StartAt is the prefix from which to start the iteration from. // // This is inclusive and the iteration will include the key which is specified here. StartAt []byte - // If this is true then the iteration will *not* include + // If StartAtExclusive is true then the iteration will *not* include // the key specified in StartAt, if there is such a key. StartAtExclusive bool - // The info of the child trie over which to iterate over. + // ChildInfo is the info of the child trie over which to iterate over. ChildInfo storage.ChildInfo - // Whether to stop iteration when a missing trie node is reached. + // StopOnIncompleteDatabase represents whether to stop iteration when a missing trie node is reached. // // When a missing trie node is reached the iterator will: // - return an error if this is set to false (default) @@ -37,7 +37,7 @@ type IterArgs struct { StopOnIncompleteDatabase bool } -// An interface for a raw storage iterator. +// StorageIterator is the interface for a raw storage iterator. type StorageIterator[Hash runtime.Hash, Hasher runtime.Hasher[Hash]] interface { // Fetches the next key from the storage. NextKey(backend *TrieBackend[Hash, Hasher]) (StorageKey, error) @@ -49,7 +49,7 @@ type StorageIterator[Hash runtime.Hash, Hasher runtime.Hasher[Hash]] interface { Complete() bool } -// An iterator over storage keys and values. +// PairsIter is an iterator over storage keys and values. type PairsIter[H runtime.Hash, Hasher runtime.Hasher[H]] struct { backend *TrieBackend[H, Hasher] rawIter StorageIterator[H, Hasher] @@ -76,7 +76,7 @@ func (pi *PairsIter[H, Hasher]) All() iter.Seq2[StorageKeyValue, error] { } } -// An iterator over storage keys. +// KeysIter is an iterator over storage keys. type KeysIter[H runtime.Hash, Hasher runtime.Hasher[H]] struct { backend *TrieBackend[H, Hasher] rawIter StorageIterator[H, Hasher] @@ -103,7 +103,7 @@ func (ki *KeysIter[H, Hasher]) All() iter.Seq2[StorageKey, error] { } } -// The transaction type used by [Backend]. +// BackendTransaction is the transaction type used by [Backend]. // // This transaction contains all the changes that need to be applied to the backend to create the // state for a new block. @@ -115,71 +115,69 @@ func NewBackendTransaction[Hash runtime.Hash, Hasher runtime.Hasher[Hash]]() Bac return BackendTransaction[Hash, Hasher]{trie.NewPrefixedMemoryDB[Hash, Hasher]()} } -// Reexport of [trie.KeyValue] +// Delta is reexport of [trie.KeyValue] type Delta = trie.KeyValue +// ChildDelta is child trie deltas type ChildDelta struct { storage.ChildInfo Deltas []Delta } -// A state backend is used to read state data and can have changes committed -// to it. -// -// The clone operation (if implemented) should be cheap. +// A state Backend is used to read state data and can have changes committed to it. type Backend[Hash runtime.Hash, H runtime.Hasher[Hash]] interface { - // Get keyed storage or nil if there is nothing associated. + // Storage gets keyed storage or nil if there is nothing associated. Storage(key []byte) (StorageValue, error) - // Get keyed storage value hash or nil if there is nothing associated. + // StorageHash get keyed storage value hash or nil if there is nothing associated. StorageHash(key []byte) (*Hash, error) - // Get the merkle value or nil if there is nothing associated. + // ClosestMerkleValue gets the merkle value or nil if there is nothing associated. ClosestMerkleValue(key []byte) (triedb.MerkleValue[Hash], error) - // Get the child merkle value or nil if there is nothing associated. + // ChildClosestMerkleValue gets the child merkle value or nil if there is nothing associated. ChildClosestMerkleValue(childInfo storage.ChildInfo, key []byte) (triedb.MerkleValue[Hash], error) - // Get keyed child storage or nil if there is nothing associated. + // ChildStorage gets keyed child storage or nil if there is nothing associated. ChildStorage(childInfo storage.ChildInfo, key []byte) (StorageValue, error) - // Get child keyed storage value hash or nil if there is nothing associated. + // ChildStorageHash gets child keyed storage value hash or nil if there is nothing associated. ChildStorageHash(childInfo storage.ChildInfo, key []byte) (*Hash, error) - // true if a key exists in storage. + // ExistsStorage returns true if a key exists in storage. ExistsStorage(key []byte) (bool, error) - // true if a key exists in child storage. + // ExistsChildStorage returns true if a key exists in child storage. ExistsChildStorage(childInfo storage.ChildInfo, key []byte) (bool, error) - // Return the next key in storage in lexicographic order or nil if there is no value. + // NextStorageKey returns the next key in storage in lexicographic order or nil if there is no value. NextStorageKey(key []byte) (StorageKey, error) - // Return the next key in child storage in lexicographic order or nil if there is no value. + // NextChildStorageKey returns the next key in child storage in lexicographic order or nil if there is no value. NextChildStorageKey(childInfo storage.ChildInfo, key []byte) (StorageKey, error) - // Calculate the storage root, with given delta over what is already stored in + // StorageRoot calculates the storage root, with given delta over what is already stored in // the backend, and produce a "transaction" that can be used to commit. // Does not include child storage updates. StorageRoot(delta []Delta, stateVersion storage.StateVersion) (Hash, BackendTransaction[Hash, H]) - // Calculate the child storage root, with given delta over what is already stored in + // ChildStorageRoot calculates the child storage root, with given delta over what is already stored in // the backend, and produce a "transaction" that can be used to commit. The second argument // is true if child storage root equals default storage root. ChildStorageRoot( childInfo storage.ChildInfo, delta []Delta, stateVersion storage.StateVersion, ) (Hash, bool, BackendTransaction[Hash, H]) - // Returns a lifetimeless raw storage iterator. + // RawIter returns a raw storage iterator. RawIter(args IterArgs) (StorageIterator[Hash, H], error) - // Get an iterator over key/value pairs. + // Pairs returns an iterator over key/value pairs. Pairs(args IterArgs) (PairsIter[Hash, H], error) - // Get an iterator over keys. + // Keys returns an iterator over keys. Keys(args IterArgs) (KeysIter[Hash, H], error) - // Calculate the storage root, with given delta over what is already stored + // FullStorageRoot calculates the storage root, with given delta over what is already stored // in the backend, and produce a "transaction" that can be used to commit. // Does include child storage updates. FullStorageRoot( diff --git a/internal/primitives/state-machine/in_memory_backend.go b/internal/primitives/state-machine/in_memory_backend.go index 883aed4a38..4ec2d182d9 100644 --- a/internal/primitives/state-machine/in_memory_backend.go +++ b/internal/primitives/state-machine/in_memory_backend.go @@ -14,7 +14,7 @@ type MemoryDBTrieBackend[H runtime.Hash, Hasher runtime.Hasher[H]] struct { *TrieBackend[H, Hasher] } -// Create a new empty instance of in-memory backend. +// NewMemoryDBTrieBackend creates a new empty instance of in-memory backend. func NewMemoryDBTrieBackend[H runtime.Hash, Hasher runtime.Hasher[H]]() MemoryDBTrieBackend[H, Hasher] { mdb := trie.NewPrefixedMemoryDB[H, Hasher]() root := (*new(Hasher)).Hash([]byte{0}) diff --git a/internal/primitives/state-machine/overlayed_changes.go b/internal/primitives/state-machine/overlayed_changes.go index 1e6b8b89d1..bcf7a98847 100644 --- a/internal/primitives/state-machine/overlayed_changes.go +++ b/internal/primitives/state-machine/overlayed_changes.go @@ -5,28 +5,28 @@ package statemachine import "github.com/ChainSafe/gossamer/internal/primitives/core/offchain" -// Storage key. +// StorageKey is a storage key. type StorageKey []byte -// Storage value. Value can be nil +// StorageValue is a storage value. Value can be nil type StorageValue []byte -// Storage key and value. +// StorageKeyValue is storage key and value. type StorageKeyValue struct { StorageKey StorageValue } -// In memory array of storage values. +// StorageCollection is a slice of storage values. type StorageCollection []StorageKeyValue -// In memory arrays of storage values for multiple child tries. +// ChildStorageCollection is a slice of storage values for multiple child tries. type ChildStorageCollection []struct { StorageKey StorageCollection } -// In memory array of storage values. +// OffchainChangesCollection is slice of storage values. type OffchainChangesCollection []struct { PrefixKey struct { Prefix []byte @@ -35,17 +35,17 @@ type OffchainChangesCollection []struct { ValueOperation offchain.OffchainOverlayedChange } -// Transaction index operation. +// IndexOperations is interface constraint of [IndexOperation]. type IndexOperations interface { IndexOperationInsert | IndexOperationRenew } -// Transaction index operation. +// IndexOperation is a transaction index operation. type IndexOperation interface { isIndexOperation() } -// Insert transaction into index. +// IndexOperationInsert is an insert transaction into index. type IndexOperationInsert struct { // Extrinsic index in the current block. Extrinsic uint32 @@ -55,7 +55,7 @@ type IndexOperationInsert struct { Size uint32 } -// Renew existing transaction storage. +// IndexOperationRenew renews existing transaction storage. type IndexOperationRenew struct { // Extrinsic index in the current block. Extrinsic uint32 diff --git a/internal/primitives/state-machine/trie_backend.go b/internal/primitives/state-machine/trie_backend.go index fb0b20d1ea..89032848d2 100644 --- a/internal/primitives/state-machine/trie_backend.go +++ b/internal/primitives/state-machine/trie_backend.go @@ -18,9 +18,9 @@ import ( triedb "github.com/ChainSafe/gossamer/pkg/trie/triedb" ) -// A provider of trie caches that are compatible with [triedb.TrieDB]. +// TrieCacheProvider is a provider of trie caches that are compatible with [triedb.TrieDB]. type TrieCacheProvider[H runtime.Hash, Cache triedb.TrieCache[H]] interface { - // Return a [triedb.TrieDB] compatible cache. + // TrieCache returns a [triedb.TrieDB] compatible cache. // // The storage_root parameter *must* be the storage root of the trie this cache is used for. // @@ -28,7 +28,7 @@ type TrieCacheProvider[H runtime.Hash, Cache triedb.TrieCache[H]] interface { // may belong to different tries. TrieCache(storageRoot H) (cache Cache, unlock func()) - // Returns a cache that can be used with a [triedb.TrieDB] where mutations are performed. + // TrieCacheMut returns a cache that can be used with a [triedb.TrieDB] where mutations are performed. // // When finished with the operation on the trie, it is required to call [TrieCacheProvider.Merge] to // merge the cached items for the correct storage root. @@ -46,14 +46,14 @@ type cachedIter[H runtime.Hash, Hasher runtime.Hasher[H]] struct { iter rawIter[H, Hasher] } -// Patricia trie-based backend. Transaction type is an overlay of changes to commit. +// TrieBackend is a patricia trie-based backend. Transaction type is an overlay of changes to commit. type TrieBackend[H runtime.Hash, Hasher runtime.Hasher[H]] struct { essence trieBackendEssence[H, Hasher] nextStorageKeyCache *cachedIter[H, Hasher] nextStorageKeyCacheMtx sync.Mutex } -// Constructor for [TrieBackend]. +// NewTrieBackend is constructor for [TrieBackend]. func NewTrieBackend[H runtime.Hash, Hasher runtime.Hasher[H]]( storage TrieBackendStorage[H], root H, @@ -65,7 +65,7 @@ func NewTrieBackend[H runtime.Hash, Hasher runtime.Hasher[H]]( } } -// Wrap the given [TrieBackend]. +// NewWrappedTrieBackend will wrap the given [TrieBackend]. // // This can be used for example if all accesses to the trie should // be recorded while some other functionality still uses the non-recording @@ -85,7 +85,7 @@ func NewWrappedTrieBackend[H runtime.Hash, Hasher runtime.Hasher[H]]( ) } -// Create a backend used for checking the proof. +// NewProofCheckTrieBackend creates a backend used for checking the proof. // // proof and root must match, i.e. root must be the correct root of proof nodes. func NewProofCheckTrieBackend[H runtime.Hash, Hasher runtime.Hasher[H]]( diff --git a/internal/primitives/storage/keys/keys.go b/internal/primitives/storage/keys/keys.go index 14607dedc1..832b862782 100644 --- a/internal/primitives/storage/keys/keys.go +++ b/internal/primitives/storage/keys/keys.go @@ -9,11 +9,11 @@ import ( // List of all well known keys and prefixes in storage. var ( - // Prefix of the default child storage keys in the top trie. + // DefaultChildStorageKeyPrefix is a prefix of the default child storage keys in the top trie. DefaultChildStorageKeyPrefix = []byte(":child_storage:default:") ) -// Whether a key is a child storage key. +// IsChildStorageKey returns whether a key is a child storage key. // // This is convenience function which basically checks if the given key starts // with [DefaultChildStorageKeyPrefix]. diff --git a/internal/primitives/storage/storage.go b/internal/primitives/storage/storage.go index 3c5b4fc7a2..ff95d2b727 100644 --- a/internal/primitives/storage/storage.go +++ b/internal/primitives/storage/storage.go @@ -11,21 +11,19 @@ import ( "github.com/tidwall/btree" ) -// Storage key. +// StorageKey is a storage key. type StorageKey []byte -// Storage key of a child trie, it contains the prefix to the key. +// PrefixedStorageKey is a storage key of a child trie, it contains the prefix to the key. type PrefixedStorageKey []byte -// Child trie storage data. +// StorageChild is child trie storage data. type StorageChild struct { - // Child data for storage. - Data btree.Map[string, []byte] - // Associated child info for a child trie. - ChildInfo ChildInfo + Data btree.Map[string, []byte] // Child data for storage. + ChildInfo ChildInfo // Associated child info for a child trie. } -// Struct containing data needed for a storage. +// Storage contains data needed for a storage. type Storage struct { // Top trie storage data. Top btree.Map[string, []byte] @@ -34,52 +32,50 @@ type Storage struct { ChildrenDefault map[string]StorageChild } -// Information related to a child state. +// ChildInfo is information related to a child state. type ChildInfo interface { - // Returns byte sequence (keyspace) that can be use by underlying db to isolate keys. + // Keyspace returns byte sequence (keyspace) that can be use by underlying db to isolate keys. // This is a unique id of the child trie. The collision resistance of this value // depends on the type of child info use. For [ChildTypeParentKeyID] it is and need to be. Keyspace() []byte - // Returns a reference to the location in the direct parent of - // this trie but without the common prefix for this kind of - // child trie. + // StorageKey returns a reference to the location in the direct parent of + // this trie but without the common prefix for this kind of child trie. StorageKey() StorageKey - // Return a the full location in the direct parent of - // this trie. + // PrefixedStorageKey returns the full location in the direct parent of this trie. PrefixedStorageKey() PrefixedStorageKey - // Returns the type for this child info. + // ChildType returns the type for this child info. ChildType() ChildType } -// This is the one used by default. +// ChildInfoParentKeyID is the default ChildTrieParentKeyID. type ChildInfoParentKeyID ChildTrieParentKeyID -// Returns byte sequence (keyspace) that can be use by underlying db to isolate keys. +// Keyspace returns byte sequence (keyspace) that can be use by underlying db to isolate keys. // This is a unique id of the child trie. The collision resistance of this value // depends on the type of child info use. func (cipkid ChildInfoParentKeyID) Keyspace() []byte { return cipkid.StorageKey() } -// Returns a reference to the location in the direct parent of +// StorageKey returns a reference to the location in the direct parent of // this trie but without the common prefix for this kind of // child trie. func (cipkid ChildInfoParentKeyID) StorageKey() StorageKey { return ChildTrieParentKeyID(cipkid).data } -// Return a the full location in the direct parent of +// PrefixedStorageKey returns a the full location in the direct parent of // this trie. func (cipkid ChildInfoParentKeyID) PrefixedStorageKey() PrefixedStorageKey { return ChildTypeParentKeyID.NewPrefixedKey(cipkid.data) } -// Returns the type for this child info. +// ChildType returns the type for this child info. func (cipkid ChildInfoParentKeyID) ChildType() ChildType { return ChildTypeParentKeyID } -// Instantiates child information for a default child trie +// NewDefaultChildInfo instantiates child information for a default child trie // of kind ChildInfoParentKeyID, using an unprefixed parent // storage key. func NewDefaultChildInfo(storageKey []byte) ChildInfo { @@ -88,7 +84,7 @@ func NewDefaultChildInfo(storageKey []byte) ChildInfo { } } -// Type of child. +// ChildType is the type of child. // It does not strictly define different child type, it can also // be related to technical consideration or api variant. type ChildType uint32 @@ -99,7 +95,7 @@ const ( ChildTypeParentKeyID ChildType = iota + 1 ) -// Transform a prefixed key into a tuple of the child type +// NewChildTypeFromPrefixedKey transforms a prefixed key into a tuple of the child type // and the unprefixed representation of the key. func NewChildTypeFromPrefixedKey(storageKey PrefixedStorageKey) *struct { ChildType @@ -117,14 +113,14 @@ func NewChildTypeFromPrefixedKey(storageKey PrefixedStorageKey) *struct { } } -// Produce a prefixed key for a given child type. +// NewPrefixedKey produces a prefixed key for a given child type. func (ct ChildType) NewPrefixedKey(key []byte) PrefixedStorageKey { parentPrefix := ct.ParentPrefix() result := append(parentPrefix, key...) return PrefixedStorageKey(result) } -// Returns the location reserved for this child trie in their parent trie if there +// ParentPrefix returns the location reserved for this child trie in their parent trie if there // is one. func (ct ChildType) ParentPrefix() []byte { switch ct { @@ -135,7 +131,7 @@ func (ct ChildType) ParentPrefix() []byte { } } -// A child trie of default type. +// ChildTrieParentKeyID is a child trie of default type. // // It uses the same default implementation as the top trie, top trie being a child trie with no // keyspace and no storage key. Its keyspace is the variable (unprefixed) part of its storage key. @@ -147,7 +143,7 @@ type ChildTrieParentKeyID struct { data []byte } -// Different possible state version. +// StateVersion represents different possible state version. // // V0 and V1 uses a same trie implementation, but V1 will write external value node in the trie for // value with size greater than 32 bytes. diff --git a/internal/primitives/trie/cache/cache.go b/internal/primitives/trie/cache/cache.go index ca196f618e..3a03742baa 100644 --- a/internal/primitives/trie/cache/cache.go +++ b/internal/primitives/trie/cache/cache.go @@ -58,7 +58,7 @@ func (nc nodeCached[H]) ByteSize() uint { return nc.Node.ByteSize() } -// The local trie cache. +// LocalTrieCache is a local trie cache. // // This cache should be used per state instance created by the backend. One state instance is // referring to the state of one block. It will cache all the accesses that are done to the state @@ -137,7 +137,7 @@ func (ltc *LocalTrieCache[H]) Commit() { sharedInner.valueCache.Update(added, accessed) } -// Returns a [triedb.TrieDB] compatible [triedb.TrieCache]. +// TrieCache returns a [triedb.TrieDB] compatible [triedb.TrieCache]. // // The given storageRoot needs to be the storage root of the trie this cache is used for. func (ltc *LocalTrieCache[H]) TrieCache(storageRoot H) (cache *TrieCache[H], unlock func()) { @@ -162,7 +162,7 @@ func (ltc *LocalTrieCache[H]) TrieCache(storageRoot H) (cache *TrieCache[H], unl }, unlock } -// Returns a [triedb.TrieDB] compatible [triedb.TrieCache]. +// TrieCacheMut returns a [triedb.TrieDB] compatible [triedb.TrieCache]. // // After finishing all operations with [triedb.TrieDB] and having obtained // the new storage root, [TrieCache.MergeInto] should be called to update this local @@ -248,7 +248,7 @@ func (fsrvc forStorageRootValueCache[H]) insert(key []byte, value triedb.CachedV fsrvc.localValueCache.Add(vck.ValueCacheKeyComparable(), value) } -// The [triedb.TrieCache] implementation. +// TrieCache is a [triedb.TrieCache] implementation. // // If this instance was created using [LocalTrieCache.TrieCacheMut], it needs to // be merged back into the [LocalTrieCache] with [LocalTrieCache.MergeInto] after all operations are @@ -259,7 +259,7 @@ type TrieCache[H runtime.Hash] struct { valueCache valueCache[H] } -// Merge this cache into the given [LocalTrieCache]. +// MergeInto merges this cache into the given [LocalTrieCache]. // // This function is only required to be called when this instance was created through // [LocalTrieCache.TrieCacheMut], otherwise this method is a no-op. The given diff --git a/internal/primitives/trie/cache/shared_cache.go b/internal/primitives/trie/cache/shared_cache.go index 8bbc70f470..c481cf87ce 100644 --- a/internal/primitives/trie/cache/shared_cache.go +++ b/internal/primitives/trie/cache/shared_cache.go @@ -98,7 +98,8 @@ func (snc *sharedNodeCache[H]) Reset() { snc.lru.Purge() } -// The comparable type that identifies this instance of storage root and storage key, used in [sharedValueCache] LRU. +// ValueCacheKeyComparable is the comparable type that identifies this instance of storage root and storage key, used +// in sharedValueCache LRU. type ValueCacheKeyComparable[H runtime.Hash] struct { StorageRoot H StorageKey string @@ -111,7 +112,7 @@ func (vckh ValueCacheKeyComparable[H]) ValueCacheKey() ValueCacheKey[H] { } } -// The key type that is being used to address a [CachedValue]. +// ValueCacheKey is the key type that is being used to address a [CachedValue]. type ValueCacheKey[H runtime.Hash] struct { // The storage root of the trie this key belongs to. StorageRoot H @@ -134,7 +135,7 @@ type sharedValueCache[H runtime.Hash] struct { itemsEvicted uint } -// Constructor for [sharedValueCache]. +// Constructor for sharedValueCache. func newSharedValueCache[H runtime.Hash](size uint) *sharedValueCache[H] { var svc sharedValueCache[H] itemsEvictedPtr := &svc.itemsEvicted @@ -227,7 +228,7 @@ type sharedTrieCacheInner[H runtime.Hash] struct { valueCache *sharedValueCache[H] } -// The shared trie cache. +// SharedTrieCache is a shared trie cache. // // It should be instantiated once per node. It will hold the trie nodes and values of all // operations to the state. To not use all available memory it will ensure to stay in the @@ -239,7 +240,7 @@ type SharedTrieCache[H runtime.Hash] struct { mtx sync.RWMutex } -// Create a new [SharedTrieCache]. +// NewSharedTrieCache creates a new [SharedTrieCache]. func NewSharedTrieCache[H runtime.Hash](size uint) *SharedTrieCache[H] { totalBudget := size @@ -255,7 +256,7 @@ func NewSharedTrieCache[H runtime.Hash](size uint) *SharedTrieCache[H] { } } -// Create a new [LocalTrieCache] instance from this shared cache. +// LocalTrieCache creates a new [LocalTrieCache] instance from this shared cache. func (stc *SharedTrieCache[H]) LocalTrieCache() LocalTrieCache[H] { h := hasher[H]{maphash.NewHasher[H]()} nodeCache, err := costlru.New(localNodeCacheMaxSize, h.Hash, func(hash H, node nodeCached[H]) uint32 { @@ -309,7 +310,7 @@ func (stc *SharedTrieCache[H]) Unlock() { stc.mtx.Unlock() } -// Get a copy of the node for key. +// PeekNode gets a copy of the node for key. // // This will temporarily lock the shared cache for reading. // @@ -324,7 +325,7 @@ func (stc *SharedTrieCache[H]) PeekNode(key H) triedb.CachedNode[H] { return nil } -// Get a copy of the [triedb.CachedValue] for key. +// PeekValueByHash gets a copy of the [triedb.CachedValue] for key. // // This will temporarily lock the shared cache for reading. // @@ -346,14 +347,14 @@ func (stc *SharedTrieCache[H]) Reset() { stc.ResetValueCache() } -// Reset the node cache. +// ResetNodeCache resets the node cache. func (stc *SharedTrieCache[H]) ResetNodeCache() { stc.mtx.Lock() defer stc.mtx.Unlock() stc.inner.nodeCache.Reset() } -// Reset the value cache. +// ResetValueCache resets the value cache. func (stc *SharedTrieCache[H]) ResetValueCache() { stc.mtx.Lock() defer stc.mtx.Unlock() diff --git a/internal/primitives/trie/recorder/recorder.go b/internal/primitives/trie/recorder/recorder.go index 532330362a..3321c9910c 100644 --- a/internal/primitives/trie/recorder/recorder.go +++ b/internal/primitives/trie/recorder/recorder.go @@ -63,14 +63,14 @@ type Recorder[H runtime.Hash] struct { encodedSizeEstimationMtx sync.Mutex } -// Constructor for [Recorder]. +// NewRecorder is constructor for [Recorder]. func NewRecorder[H runtime.Hash]() *Recorder[H] { return &Recorder[H]{ inner: newRecorderInner[H](), } } -// Returns the recorder as an implementation of [triedb.TrieRecorder]. +// TrieRecorder returns the recorder as an implementation of [triedb.TrieRecorder]. // // The storage root supplied is of the trie for which accesses are recorded. // This is important when recording access to different tries at once (like top and child tries). @@ -83,7 +83,7 @@ func (r *Recorder[H]) TrieRecorder(storageRoot H) triedb.TrieRecorder { } } -// Drain the recording into a [StorageProof]. +// DrainStorageProof drains the recording into a [StorageProof]. // // While a recorder can be cloned, all share the same internal state. After calling this // function, all other instances will have their internal state reset as well. @@ -110,7 +110,7 @@ func (r *Recorder[H]) storageProof() trie.StorageProof { return trie.NewStorageProof(values) } -// Convert the recording to a [StorageProof]. +// StorageProof converts the recording to a [StorageProof]. // // In contrast to [Recorder.DrainStorageProof] this doesn't consume and clear the // recordings. @@ -122,7 +122,7 @@ func (r *Recorder[H]) StorageProof() trie.StorageProof { return r.storageProof() } -// Returns the estimated encoded size of the proof. +// EstimateEncodedSize returns the estimated encoded size of the proof. // // The estimation is based on all the nodes that were accessed until now while // accessing the trie. @@ -139,14 +139,14 @@ func (r *Recorder[H]) Reset() { r.inner = newRecorderInner[H]() } -// Start a new transaction. +// StartTransaction starts a new transaction. func (r *Recorder[H]) StartTransaction() { r.innerMtx.Lock() defer r.innerMtx.Unlock() r.inner.transactions = append(r.inner.transactions, newTransaction[H]()) } -// Rollback the latest transaction. +// RollBackTransaction will rollback the latest transaction. // // Returns an error if there wasn't any active transaction. func (r *Recorder[H]) RollBackTransaction() error { @@ -199,7 +199,7 @@ func (r *Recorder[H]) RollBackTransaction() error { return nil } -// Commit the latest transaction. +// CommitTransaction commits the latest transaction. // // Returns an error if there wasn't any active transaction. func (r *Recorder[H]) CommitTransaction() error { diff --git a/internal/primitives/trie/storage_proof.go b/internal/primitives/trie/storage_proof.go index 5df11b37cf..104ef51a65 100644 --- a/internal/primitives/trie/storage_proof.go +++ b/internal/primitives/trie/storage_proof.go @@ -9,7 +9,7 @@ import ( "github.com/tidwall/btree" ) -// A proof that some set of key-value pairs are included in the storage trie. The proof contains +// StorageProof is proof that some set of key-value pairs are included in the storage trie. The proof contains // the storage values so that the partial storage backend can be reconstructed by a verifier that // does not already have access to the key-value pairs. // @@ -20,7 +20,7 @@ type StorageProof struct { trieNodes btree.Set[string] } -// Constructs a [StorageProof] from a subset of encoded trie nodes. +// NewStorageProof constructs a [StorageProof] from a subset of encoded trie nodes. func NewStorageProof(trieNodes [][]byte) StorageProof { set := btree.Set[string]{} for _, trieNode := range trieNodes { @@ -31,12 +31,12 @@ func NewStorageProof(trieNodes [][]byte) StorageProof { } } -// Returns whether this is an empty proof. +// Empty returns whether this is an empty proof. func (sp *StorageProof) Empty() bool { return sp.trieNodes.Len() == 0 } -// Returns all the encoded trie ndoes in lexigraphical order from the proof. +// Nodes returns all the encoded trie ndoes in lexigraphical order from the proof. func (sp *StorageProof) Nodes() [][]byte { var ret [][]byte sp.trieNodes.Scan(func(v string) bool { @@ -46,7 +46,7 @@ func (sp *StorageProof) Nodes() [][]byte { return ret } -// Constructs a [MemoryDB] from a [StorageProof] +// NewMemoryDBFromStorageProof constructs a [MemoryDB] from a [StorageProof] func NewMemoryDBFromStorageProof[H runtime.Hash, Hasher runtime.Hasher[H]](sp StorageProof) *MemoryDB[H, Hasher] { db := NewMemoryDB[H, Hasher]() sp.trieNodes.Scan(func(v string) bool { diff --git a/internal/primitives/trie/trie.go b/internal/primitives/trie/trie.go index ce6142c6ec..3bea2a31a7 100644 --- a/internal/primitives/trie/trie.go +++ b/internal/primitives/trie/trie.go @@ -12,26 +12,26 @@ import ( triedb "github.com/ChainSafe/gossamer/pkg/trie/triedb" ) -// Reexport from [memorydb.MemoryDB] where supplied [memorydb.KeyFunction] is [memorydb.PrefixedKey] for prefixing -// keys internally (avoiding key conflict for non random keys). +// PrefixedMemoryDB is reexport from [memorydb.MemoryDB] where supplied [memorydb.KeyFunction] is [memorydb.PrefixedKey] +// for prefixing keys internally (avoiding key conflict for non random keys). type PrefixedMemoryDB[Hash runtime.Hash, Hasher hashdb.Hasher[Hash]] struct { memorydb.MemoryDB[Hash, Hasher, string, memorydb.PrefixedKey[Hash]] } -// Constructor for [PrefixedMemoryDB] +// NewPrefixedMemoryDB is constructor for [PrefixedMemoryDB] func NewPrefixedMemoryDB[Hash runtime.Hash, Hasher hashdb.Hasher[Hash]]() *PrefixedMemoryDB[Hash, Hasher] { return &PrefixedMemoryDB[Hash, Hasher]{ memorydb.NewMemoryDB[Hash, Hasher, string, memorydb.PrefixedKey[Hash]]([]byte{0}), } } -// Reexport from [memorydb.MemoryDB] where supplied [memorydb.KeyFunction] is [memorydb.HashKey] which is a noop -// operation on the supplied prefix, and only uses the hash. +// MemoryDB is reexport from [memorydb.MemoryDB] where supplied [memorydb.KeyFunction] is [memorydb.HashKey] which is +// a noop operation on the supplied prefix, and only uses the hash. type MemoryDB[Hash runtime.Hash, Hasher runtime.Hasher[Hash]] struct { memorydb.MemoryDB[Hash, Hasher, Hash, memorydb.HashKey[Hash]] } -// Constructor for [MemoryDB]. +// NewMemoryDB is constructor for [MemoryDB]. func NewMemoryDB[Hash runtime.Hash, Hasher runtime.Hasher[Hash]]() *MemoryDB[Hash, Hasher] { return &MemoryDB[Hash, Hasher]{ MemoryDB: memorydb.NewMemoryDB[Hash, Hasher, Hash, memorydb.HashKey[Hash]]([]byte{0}), @@ -44,7 +44,7 @@ type KeyValue struct { Value []byte } -// Determine a trie root given a hash DB and delta values. +// DeltaTrieRoot determines a trie root given a hash DB and delta values. func DeltaTrieRoot[H runtime.Hash, Hasher runtime.Hasher[H]]( db hashdb.HashDB[H], root H, @@ -85,7 +85,7 @@ func DeltaTrieRoot[H runtime.Hash, Hasher runtime.Hasher[H]]( return hash, err } -// Read a value from the trie. +// ReadTrieValue reads a value from the trie. func ReadTrieValue[H runtime.Hash, Hasher runtime.Hasher[H]]( db hashdb.HashDB[H], root H, @@ -106,7 +106,7 @@ func ReadTrieValue[H runtime.Hash, Hasher runtime.Hasher[H]]( return nil, nil } -// Read a value from the trie with given [triedb.Query]. +// ReadTrieValueWith reads a value from the trie with given [triedb.Query]. func ReadTrieValueWith[H runtime.Hash, Hasher runtime.Hasher[H]]( db hashdb.HashDB[H], root H, @@ -128,7 +128,7 @@ func ReadTrieValueWith[H runtime.Hash, Hasher runtime.Hasher[H]]( return nil, nil } -// Read the [triedb.MerkleValue] of the node that is the closest descendant for +// ReadTrieFirstDescendantValue reads the [triedb.MerkleValue] of the node that is the closest descendant for // the provided key. func ReadTrieFirstDescendantValue[H runtime.Hash, Hasher runtime.Hasher[H]]( db hashdb.HashDB[H], @@ -170,7 +170,7 @@ func ChildDeltaTrieRoot[H runtime.Hash, Hasher runtime.Hasher[H]]( return DeltaTrieRoot[H, Hasher](ksdb, root, delta, recorder, cache, stateVersion) } -// Read a value from the child trie. +// ReadChildTrieValue reads a value from the child trie. func ReadChildTrieValue[H runtime.Hash, Hasher runtime.Hasher[H]]( keyspace []byte, db hashdb.HashDB[H], @@ -194,7 +194,7 @@ func ReadChildTrieValue[H runtime.Hash, Hasher runtime.Hasher[H]]( return nil, nil } -// Read a hash from the child trie. +// ReadChildTrieHash reads a hash from the child trie. func ReadChildTrieHash[H runtime.Hash, Hasher runtime.Hasher[H]]( keyspace []byte, db hashdb.HashDB[H], @@ -211,7 +211,7 @@ func ReadChildTrieHash[H runtime.Hash, Hasher runtime.Hasher[H]]( return trieDB.GetHash(key) } -// Read the [triedb.MerkleValue] of the node that is the closest descendant for +// ReadChildTrieFirstDescendantValue reads the [triedb.MerkleValue] of the node that is the closest descendant for // the provided child key. func ReadChildTrieFirstDescendantValue[H runtime.Hash, Hasher runtime.Hasher[H]]( keyspace []byte, @@ -236,7 +236,7 @@ type KeyspacedDB[Hash comparable] struct { keySpace []byte } -// Constructor for [KeyspacedDB] +// NewKeyspacedDB is constructor for [KeyspacedDB] func NewKeyspacedDB[Hash comparable](db hashdb.HashDB[Hash], ks []byte) *KeyspacedDB[Hash] { return &KeyspacedDB[Hash]{ db: db,