doc: all the things

Author: ARR4N

core/state/statedb.go

@@ -28,14 +28,16 @@ import (
 	"github.com/ava-labs/libevm/core/state/snapshot"
 	"github.com/ava-labs/libevm/core/types"
 	"github.com/ava-labs/libevm/crypto"
-	"github.com/ava-labs/libevm/libevm/stateconf"
 	"github.com/ava-labs/libevm/log"
 	"github.com/ava-labs/libevm/metrics"
 	"github.com/ava-labs/libevm/params"
 	"github.com/ava-labs/libevm/trie"
 	"github.com/ava-labs/libevm/trie/trienode"
 	"github.com/ava-labs/libevm/trie/triestate"
 	"github.com/holiman/uint256"
+
+	// libevm extra imports
+	"github.com/ava-labs/libevm/libevm/stateconf"
 )
 
 const (

core/state/statedb.libevm.go

@@ -54,14 +54,35 @@ func clearTypedNilPointer(snaps SnapshotTree) SnapshotTree {
 	return snaps
 }
 
+// StateDBHooks modify the behaviour of [StateDB] instances.
 type StateDBHooks interface {
-	TransformStateKey(common.Address, common.Hash) common.Hash
+	// TransformStateKey receives the arguments passed to [StateDB.GetState],
+	// [StateDB.GetCommittedState] or [StateDB.SetState], and returns the key
+	// that each of those methods will use for accessing state. This method will
+	// not, however, be called if any of the aforementioned [StateDB] methods
+	// receives a [stateconf.SkipStateKeyTransformation] option.
+	//
+	// This method SHOULD NOT be used for anything other than achieving
+	// backwards compatibility with an existing chain. In the event that other
+	// methods are added to the [StateDBHooks] interface and no key
+	// transformation is required, it is acceptable for this method to echo the
+	// [common.Hash], unchanged.
+	TransformStateKey(_ common.Address, key common.Hash) (newKey common.Hash)
 }
 
+// RegisterExtras registers the [StateDBHooks] such that they modify the
+// behaviour of all [StateDB] instances. It is expected to be called in an
+// `init()` function and MUST NOT be called more than once.
 func RegisterExtras(s StateDBHooks) {
 	registeredExtras.MustRegister(s)
 }
 
+// TestOnlyClearRegisteredExtras clears the arguments previously passed to
+// [RegisterExtras]. It panics if called from a non-testing call stack.
+//
+// In tests it SHOULD be called before every call to [RegisterExtras] and then
+// defer-called afterwards, either directly or via testing.TB.Cleanup(). This is
+// a workaround for the single-call limitation on [RegisterExtras].
 func TestOnlyClearRegisteredExtras() {
 	registeredExtras.TestOnlyClear()
 }

eth/tracers/logger/logger_test.go

@@ -25,9 +25,11 @@ import (
 	"github.com/ava-labs/libevm/common"
 	"github.com/ava-labs/libevm/core/state"
 	"github.com/ava-labs/libevm/core/vm"
-	"github.com/ava-labs/libevm/libevm/stateconf"
 	"github.com/ava-labs/libevm/params"
 	"github.com/holiman/uint256"
+
+	// libevm extra imports
+	"github.com/ava-labs/libevm/libevm/stateconf"
 )
 
 type dummyContractRef struct {

libevm/stateconf/conf.go

@@ -114,18 +114,26 @@ func ExtractTrieDBUpdatePayload(opts ...TrieDBUpdateOption) (common.Hash, common
 	return *conf.parentBlockHash, *conf.currentBlockHash, true
 }
 
+// A StateDBStateOption configures the behaviour of state.StateDB methods for
+// getting and setting state: GetState(), GetCommittedState(), and SetState().
 type StateDBStateOption = options.Option[stateDBStateConfig]
 
 type stateDBStateConfig struct {
 	skipKeyTransformation bool
 }
 
+// SkipStateKeyTransformation causes any registered state-key transformation
+// hook to be ignored. See state.RegisterExtras() for details.
 func SkipStateKeyTransformation() StateDBStateOption {
 	return options.Func[stateDBStateConfig](func(c *stateDBStateConfig) {
 		c.skipKeyTransformation = true
 	})
 }
 
+// ShouldTransformStateKey parses the options, returning whether or not any
+// registered state-key transformation hook should be used; i.e. it returns
+// `true` i.f.f. there are no [SkipStateKeyTransformation] options in the
+// arguments.
 func ShouldTransformStateKey(opts ...StateDBStateOption) bool {
 	return !options.As(opts...).skipKeyTransformation
 }