Skip to content

Commit

Permalink
fix comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@timwu20
timwu20 committed Dec 12, 2024
1 parent dcb2073 commit 6b5f058
Show file tree
Hide file tree
Showing 17 changed files with 252 additions and 248 deletions.
182 changes: 91 additions & 91 deletions internal/client/api/backend.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,15 @@ import (
"github.com/ChainSafe/gossamer/internal/primitives/storage"
)

// / State of a new block.
// State of a new block.
type NewBlockState uint

const (
/// Normal block.
// Normal block.
NewBlockStateNormal NewBlockState = iota
/// New best block.
// New best block.
NewBlockStateBest
/// Newly finalized block (implicitly best).
// Newly finalized block (implicitly best).
NewBlockStateFinal
)

Expand All @@ -33,22 +33,22 @@ func (nbs NewBlockState) IsFinal() bool {
return nbs == NewBlockStateFinal
}

// / Block insertion operation.
// /
// / Keeps hold if the inserted block state and data.
// Block insertion operation.
//
// Keeps hold if the inserted block state and data.
type BlockImportOperation[
N runtime.Number,
H runtime.Hash,
Hasher runtime.Hasher[H],
Header runtime.Header[N, H],
E runtime.Extrinsic,
] interface {
/// Returns pending state.
///
/// Returns nil for backends with locally-unavailable state data.
// Returns pending state.
//
// Returns nil for backends with locally-unavailable state data.
State() (statemachine.Backend[H, Hasher], error)

/// Append block data to the transaction.
// Append block data to the transaction.
SetBlockData(
header Header,
body []E,
Expand All @@ -57,35 +57,35 @@ type BlockImportOperation[
state NewBlockState,
) error

/// Inject storage data into the database.
// 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
/// to the database.
// 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.
// Inject storage data into the database replacing any existing data.
ResetStorage(storage storage.Storage, stateVersion storage.StateVersion) (H, error)

/// Set storage changes.
// Set storage changes.
UpdateStorage(update statemachine.StorageCollection, childUpdate statemachine.ChildStorageCollection) error

/// Write offchain storage changes to the database.
// Write offchain storage changes to the database.
UpdateOffchainStorage(offchainUpdate statemachine.OffchainChangesCollection) error

/// Insert auxiliary keys.
///
/// Values that are nil respresent the keys should be deleted.
// Insert auxiliary keys.
//
// Values that are nil respresent the keys should be deleted.
InsertAux(ops AuxDataOperations) error

/// Mark a block as finalized.
// Mark a block as finalized.
MarkFinalized(hash H, justification *runtime.Justification) error

/// Mark a block as new head. If both block import and set head are specified, set head
/// overrides block import's best block rule.
// Mark a block as new head. If both block import and set head are specified, set head
// overrides block import's best block rule.
MarkHead(hash H) error

/// Add a transaction index operation.
// Add a transaction index operation.
UpdateTransactionIndex(index []statemachine.IndexOperation) error
}

Expand All @@ -94,118 +94,118 @@ type KeyValue struct {
Value []byte
}

// / 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
// / case.
// 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
// case.
type AuxStore interface {
/// Insert auxiliary data into key-value store.
///
/// Deletions occur after insertions.
// Insert auxiliary data into key-value store.
//
// Deletions occur after insertions.
InsertAux(insert []KeyValue, delete [][]byte) error

/// Query auxiliary data from key-value store.
// Query auxiliary data from key-value store.
GetAux(key []byte) ([]byte, error)
}

// / Client backend.
// /
// / Manages the data layer.
// /
// / # State Pruning
// /
// / While an object from StateAt is alive, the state
// / should not be pruned. The backend should internally reference-count
// / its state objects.
// /
// / The same applies for live BlockImportOperation instances: while an import operation building on a
// / parent P is alive, the state for P should not be pruned.
// /
// / # Block Pruning
// /
// / Users can pin blocks in memory by calling PinBlock. When
// / a block would be pruned, its value is kept in an in-memory cache
// / until it is unpinned via UnpinBlock.
// /
// / While a block is pinned, its state is also preserved.
// /
// / The backend should internally reference count the number of pin / unpin calls.
// Client backend.
//
// Manages the data layer.
//
// # State Pruning
//
// While an object from StateAt is alive, the state
// should not be pruned. The backend should internally reference-count
// its state objects.
//
// The same applies for live BlockImportOperation instances: while an import operation building on a
// parent P is alive, the state for P should not be pruned.
//
// # Block Pruning
//
// Users can pin blocks in memory by calling PinBlock. When
// a block would be pruned, its value is kept in an in-memory cache
// until it is unpinned via UnpinBlock.
//
// While a block is pinned, its state is also preserved.
//
// The backend should internally reference count the number of pin / unpin calls.
type Backend[
H runtime.Hash,
N runtime.Number,
Hasher runtime.Hasher[H],
Header runtime.Header[N, H],
E runtime.Extrinsic,
] interface {
/// Insert auxiliary data into key-value store.
// Insert auxiliary data into key-value store.
AuxStore

/// Begin a new block insertion transaction with given parent block id.
///
/// When constructing the genesis, this is called with all-zero hash.
// Begin 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.
// Note an operation to contain state transition.
BeginStateOperation(operation BlockImportOperation[N, H, Hasher, Header, E], block H) error

/// Commit block insertion.
// Commit block insertion.
CommitOperation(transaction BlockImportOperation[N, H, Hasher, Header, E]) error

/// Finalize block with given `hash`.
///
/// This should only be called if the parent of the given block has been finalized.
// 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.
///
/// This should only be called for blocks that are already finalized.
// Append 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.
// Returns reference to blockchain backend.
Blockchain() blockchain.Backend[H, N, Header]

/// Returns a pointer to offchain storage.
// Returns a pointer to offchain storage.
OffchainStorage() offchain.OffchainStorage

/// Pin 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.
// Pin 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

/// Unpin the block to allow pruning.
// Unpin the block to allow pruning.
UnpinBlock(hash H)

/// Returns true if state for given block is available.
// Returns true if state for given block is available.
HaveStateAt(hash H, number N) bool

/// Returns state backend with post-state of given block.
// 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 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.
///
/// Returns the number of blocks that were successfully reverted and the list of finalized
/// blocks that has been reverted.
// 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.
//
// Returns the number of blocks that were successfully reverted and the list of finalized
// blocks that has been reverted.
Revert(n N, revertFinalized bool) (N, map[H]any, error)

/// Discard non-best, unfinalized leaf block.
// Discard non-best, unfinalized leaf block.
RemoveLeafBlock(hash H) error

/// Gain access to the import lock around 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
/// something that the import of a block would interfere with, e.g. importing
/// a new block or calculating the best head.
// Gain access to the import lock around 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
// something that the import of a block would interfere with, e.g. importing
// a new block or calculating the best head.
GetImportLock() *sync.RWMutex

/// Tells whether the backend requires full-sync mode.
// Tells whether the backend requires full-sync mode.
RequiresFullSync() bool

/// Returns current usage statistics.
// Returns current usage statistics.
// TODO: implement UsageInfo if we require it
// UsageInfo() *UsageInfo
}
8 changes: 4 additions & 4 deletions internal/client/api/client.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@

package api

// / List 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.
// List 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.
type AuxDataOperation struct {
Key []byte
Data []byte
Expand Down
12 changes: 6 additions & 6 deletions internal/client/api/utils/utils.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,12 @@ type HashParent[H runtime.Hash] struct {
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.
// 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]](
client blockchain.Backend[H, N, Header], current *HashParent[H],
) func(a H, b H) (bool, error) {
Expand Down
Loading

0 comments on commit 6b5f058

Please sign in to comment.