Merge branch 'main' into tt-1717-docs-concurrency-logging

Author: Tofel

lib/client/github.go

@@ -17,6 +17,8 @@ type GithubClient struct {
 
 const WITHOUT_TOKEN = ""
 
+// NewGithubClient creates a new instance of GithubClient, optionally authenticating with a personal access token.
+// This is useful for making authenticated requests to the GitHub API, helping to avoid rate limits.
 func NewGithubClient(token string) *GithubClient {
 	// Optional: Authenticate with a personal access token if necessary
 	// This is recommended to avoid rate limits for unauthenticated requests

lib/client/mockserver.go

@@ -160,6 +160,9 @@ func (em *MockserverClient) SetAnyValuePath(path string, v interface{}) error {
 	return err
 }
 
+// SetAnyValueResponse configures a mock server to return a specified value for a given path.
+// It ensures the path starts with a '/', sanitizes it, and logs the operation.
+// This function is useful for testing and simulating API responses in a controlled environment.
 func (em *MockserverClient) SetAnyValueResponse(path string, v interface{}) error {
 	if !strings.HasPrefix(path, "/") {
 		path = fmt.Sprintf("/%s", path)

lib/client/postgres.go

@@ -54,6 +54,8 @@ func NewPostgresConnector(cfg *PostgresConfig) (*PostgresConnector, error) {
 	return &PostgresConnector{DB: db, Cfg: cfg}, nil
 }
 
+// ConnectDB establishes a connection to a PostgreSQL database using the provided environment settings.
+// It returns a PostgresConnector instance or an error if the connection fails.
 func ConnectDB(nodeNum int, e *environment.Environment) (*PostgresConnector, error) {
 	spl := strings.Split(e.URLs["chainlink_db"][nodeNum], ":")
 	port := spl[len(spl)-1]

lib/client/rpc.go

@@ -233,6 +233,10 @@ func (m *RPCClient) BlockNumber() (int64, error) {
 	return bn, nil
 }
 
+// GethSetHead sets the Ethereum node's head to a specified block in the past.
+// This function is useful for testing and debugging by allowing developers to
+// manipulate the blockchain state to a previous block. It returns an error
+// if the operation fails.
 func (m *RPCClient) GethSetHead(blocksBack int) error {
 	decimalLastBlock, err := m.BlockNumber()
 	if err != nil {
@@ -274,6 +278,9 @@ type GethContainer struct {
 	URL string
 }
 
+// StartAnvil initializes and starts an Anvil container for Ethereum development.
+// It returns an AnvilContainer instance containing the container and its accessible URL.
+// This function is useful for developers needing a local Ethereum node for testing and development.
 func StartAnvil(params []string) (*AnvilContainer, error) {
 	entryPoint := []string{"anvil", "--host", "0.0.0.0"}
 	entryPoint = append(entryPoint, params...)

lib/docker/docker.go

@@ -15,6 +15,8 @@ import (
 const RetryAttempts = 3
 const defaultRyukImage = "testcontainers/ryuk:0.5.1"
 
+// CreateNetwork initializes a new Docker network with a unique name.
+// It ensures no duplicate networks exist and returns the created network or an error if the operation fails.
 func CreateNetwork(l zerolog.Logger) (*tc.DockerNetwork, error) {
 	uuidObj, _ := uuid.NewRandom()
 	var networkName = fmt.Sprintf("network-%s", uuidObj.String())

lib/docker/test_env/besu_base.go

@@ -44,12 +44,17 @@ type Besu struct {
 	powSettings
 }
 
+// WithTestInstance sets up the execution client for testing by assigning a test logger and the testing context.
+// This allows for better logging and error tracking during test execution.
 func (g *Besu) WithTestInstance(t *testing.T) ExecutionClient {
 	g.l = logging.GetTestLogger(t)
 	g.t = t
 	return g
 }
 
+// StartContainer initializes and starts a Besu container for Ethereum execution.
+// It configures network settings based on the Ethereum version and returns the
+// network configuration along with any errors encountered during the process.
 func (g *Besu) StartContainer() (blockchain.EVMNetwork, error) {
 	var r *tc.ContainerRequest
 	var err error
@@ -121,48 +126,69 @@ func (g *Besu) StartContainer() (blockchain.EVMNetwork, error) {
 	return networkConfig, nil
 }
 
+// GetInternalExecutionURL returns the internal execution URL for the Besu client.
+// It is used to retrieve the endpoint for executing transactions in Ethereum 2.0 networks,
+// ensuring compatibility with the Ethereum version in use.
 func (g *Besu) GetInternalExecutionURL() string {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		panic("eth1 node doesn't have an execution URL")
 	}
 	return g.InternalExecutionURL
 }
 
+// GetExternalExecutionURL returns the external execution URL for the Besu instance.
+// It panics if the Ethereum version is Eth1, as Eth1 nodes do not support execution URLs.
 func (g *Besu) GetExternalExecutionURL() string {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		panic("eth1 node doesn't have an execution URL")
 	}
 	return g.ExternalExecutionURL
 }
 
+// GetInternalHttpUrl returns the internal HTTP URL of the Besu client.
+// This URL is essential for establishing communication with the Besu node in a private network setup.
 func (g *Besu) GetInternalHttpUrl() string {
 	return g.InternalHttpUrl
 }
 
+// GetInternalWsUrl returns the internal WebSocket URL for the Besu client.
+// This URL is essential for establishing WebSocket connections to the Besu node for real-time data and event subscriptions.
 func (g *Besu) GetInternalWsUrl() string {
 	return g.InternalWsUrl
 }
 
+// GetExternalHttpUrl returns the external HTTP URL of the Besu client.
+// This URL is used to interact with the Besu node from external applications or services.
 func (g *Besu) GetExternalHttpUrl() string {
 	return g.ExternalHttpUrl
 }
 
+// GetExternalWsUrl returns the external WebSocket URL for the Besu client.
+// This URL is essential for connecting to the Besu node from external services or clients.
 func (g *Besu) GetExternalWsUrl() string {
 	return g.ExternalWsUrl
 }
 
+// GetContainerName returns the name of the container associated with the Besu instance.
+// This function is useful for identifying and managing the container in a Docker environment.
 func (g *Besu) GetContainerName() string {
 	return g.ContainerName
 }
 
+// GetContainer returns a pointer to the container associated with the Besu instance.
+// This function is useful for accessing the container's properties and methods in other operations.
 func (g *Besu) GetContainer() *tc.Container {
 	return &g.Container
 }
 
+// GetEthereumVersion returns the current Ethereum version of the Besu instance.
+// This information is crucial for determining the appropriate container configuration and consensus mechanism.
 func (g *Besu) GetEthereumVersion() config_types.EthereumVersion {
 	return g.ethereumVersion
 }
 
+// WaitUntilChainIsReady blocks until the Ethereum chain is ready for operations.
+// It is useful for ensuring that the execution client has fully synchronized with the network before proceeding with further actions.
 func (g *Besu) WaitUntilChainIsReady(ctx context.Context, waitTime time.Duration) error {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		return nil
@@ -171,7 +197,10 @@ func (g *Besu) WaitUntilChainIsReady(ctx context.Context, waitTime time.Duration
 	return waitForFirstBlock.WaitUntilReady(ctx, *g.GetContainer())
 }
 
-func (g *Besu) GethConsensusMechanism() ConsensusMechanism {
+// GetConsensusMechanism returns the consensus mechanism used by the Besu instance.
+// It identifies whether the Ethereum version is Eth1 or not, returning either Proof of Authority (PoA)
+// or Proof of Stake (PoS) accordingly. This is useful for understanding the network's validation method.
+func (g *Besu) GetConsensusMechanism() ConsensusMechanism {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		return ConsensusMechanism_PoA
 	}

lib/docker/test_env/env_component.go

@@ -33,6 +33,9 @@ type EnvComponent struct {
 
 type EnvComponentOption = func(c *EnvComponent)
 
+// WithContainerName sets the container name for an EnvComponent.
+// It allows customization of the container's identity, enhancing clarity
+// and organization in containerized environments.
 func WithContainerName(name string) EnvComponentOption {
 	return func(c *EnvComponent) {
 		if name != "" {
@@ -41,6 +44,9 @@ func WithContainerName(name string) EnvComponentOption {
 	}
 }
 
+// WithStartupTimeout sets a custom startup timeout for an EnvComponent.
+// This option allows users to specify how long to wait for the component to start
+// before timing out, enhancing control over component initialization.
 func WithStartupTimeout(timeout time.Duration) EnvComponentOption {
 	return func(c *EnvComponent) {
 		if timeout != 0 {
@@ -49,6 +55,9 @@ func WithStartupTimeout(timeout time.Duration) EnvComponentOption {
 	}
 }
 
+// WithContainerImageWithVersion sets the container image and version for an EnvComponent.
+// It splits the provided image string by ':' and assigns the values accordingly.
+// This function is useful for configuring specific container images in a deployment.
 func WithContainerImageWithVersion(imageWithVersion string) EnvComponentOption {
 	return func(c *EnvComponent) {
 		split := strings.Split(imageWithVersion, ":")
@@ -59,6 +68,8 @@ func WithContainerImageWithVersion(imageWithVersion string) EnvComponentOption {
 	}
 }
 
+// WithLogLevel sets the logging level for an environment component.
+// It allows customization of log verbosity, enhancing debugging and monitoring capabilities.
 func WithLogLevel(logLevel string) EnvComponentOption {
 	return func(c *EnvComponent) {
 		if logLevel != "" {
@@ -67,28 +78,38 @@ func WithLogLevel(logLevel string) EnvComponentOption {
 	}
 }
 
+// WithPostStartsHooks sets the PostStarts hooks for an EnvComponent.
+// This allows users to define custom actions that should occur after the component starts.
 func WithPostStartsHooks(hooks ...tc.ContainerHook) EnvComponentOption {
 	return func(c *EnvComponent) {
 		c.PostStartsHooks = hooks
 	}
 }
 
+// WithPostStopsHooks sets the PostStops hooks for an EnvComponent.
+// This allows users to define custom actions that should occur after the component stops.
 func WithPostStopsHooks(hooks ...tc.ContainerHook) EnvComponentOption {
 	return func(c *EnvComponent) {
 		c.PostStopsHooks = hooks
 	}
 }
 
+// WithPreTerminatesHooks sets the pre-termination hooks for an EnvComponent.
+// This allows users to define custom behavior that should occur before the component is terminated.
 func WithPreTerminatesHooks(hooks ...tc.ContainerHook) EnvComponentOption {
 	return func(c *EnvComponent) {
 		c.PreTerminatesHooks = hooks
 	}
 }
 
+// SetDefaultHooks initializes the default hooks for the environment component.
+// This function is useful for ensuring that the component has a consistent starting state before further configuration.
 func (ec *EnvComponent) SetDefaultHooks() {
 	// no default hooks
 }
 
+// GetImageWithVersion returns the container image name combined with its version.
+// This function is useful for generating a complete image identifier needed for container requests.
 func (ec *EnvComponent) GetImageWithVersion() string {
 	return fmt.Sprintf("%s:%s", ec.ContainerImage, ec.ContainerVersion)
 }

lib/docker/test_env/erigon_base.go

@@ -36,12 +36,17 @@ type Erigon struct {
 	posContainerSettings
 }
 
+// WithTestInstance sets up the execution client with a test logger and test context.
+// This is useful for running tests that require a specific logging setup and context.
 func (g *Erigon) WithTestInstance(t *testing.T) ExecutionClient {
 	g.l = logging.GetTestLogger(t)
 	g.t = t
 	return g
 }
 
+// StartContainer initializes and starts an Erigon container for Ethereum execution.
+// It configures network settings based on the Ethereum version and returns the
+// blockchain network configuration along with any errors encountered during the process.
 func (g *Erigon) StartContainer() (blockchain.EVMNetwork, error) {
 	var r *tc.ContainerRequest
 	var err error
@@ -105,48 +110,69 @@ func (g *Erigon) StartContainer() (blockchain.EVMNetwork, error) {
 	return networkConfig, nil
 }
 
+// GetInternalExecutionURL returns the internal execution URL for the Erigon client.
+// It is used to retrieve the execution layer's endpoint, essential for connecting to the Ethereum network.
+// If the Ethereum version is Eth1, it panics as Eth1 nodes do not support execution URLs.
 func (g *Erigon) GetInternalExecutionURL() string {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		panic("eth1 node doesn't have an execution URL")
 	}
 	return g.InternalExecutionURL
 }
 
+// GetExternalExecutionURL returns the external execution URL for the Erigon instance.
+// It panics if the Ethereum version is Eth1, as Eth1 nodes do not support execution URLs.
 func (g *Erigon) GetExternalExecutionURL() string {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		panic("eth1 node doesn't have an execution URL")
 	}
 	return g.ExternalExecutionURL
 }
 
+// GetInternalHttpUrl returns the internal HTTP URL of the Erigon client.
+// This URL is used to connect to the Erigon execution layer for internal communications.
 func (g *Erigon) GetInternalHttpUrl() string {
 	return g.InternalHttpUrl
 }
 
+// GetInternalWsUrl returns the internal WebSocket URL for the Erigon client.
+// This URL is used to establish a WebSocket connection for real-time communication with the Erigon node.
 func (g *Erigon) GetInternalWsUrl() string {
 	return g.InternalWsUrl
 }
 
+// GetExternalHttpUrl returns the external HTTP URL for the Erigon client.
+// This URL is used to interact with the Erigon execution layer over HTTP.
 func (g *Erigon) GetExternalHttpUrl() string {
 	return g.ExternalHttpUrl
 }
 
+// GetExternalWsUrl returns the external WebSocket URL for the Erigon client.
+// This URL is essential for connecting to the Erigon node for real-time data and event subscriptions.
 func (g *Erigon) GetExternalWsUrl() string {
 	return g.ExternalWsUrl
 }
 
+// GetContainerName returns the name of the container associated with the Erigon instance.
+// This function is useful for identifying and managing the container in a Docker environment.
 func (g *Erigon) GetContainerName() string {
 	return g.ContainerName
 }
 
+// GetContainer returns a pointer to the Container associated with the Erigon instance.
+// This function is useful for accessing the container's properties and methods in a structured manner.
 func (g *Erigon) GetContainer() *tc.Container {
 	return &g.Container
 }
 
+// GetEthereumVersion returns the current Ethereum version of the Erigon instance.
+// This information is essential for determining the appropriate execution URLs and consensus mechanisms.
 func (g *Erigon) GetEthereumVersion() config_types.EthereumVersion {
 	return g.ethereumVersion
 }
 
+// WaitUntilChainIsReady blocks until the Ethereum chain is ready for use, waiting for the first block to be built.
+// It returns an error if the chain does not become ready within the specified wait time.
 func (g *Erigon) WaitUntilChainIsReady(ctx context.Context, waitTime time.Duration) error {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		return nil
@@ -155,7 +181,9 @@ func (g *Erigon) WaitUntilChainIsReady(ctx context.Context, waitTime time.Durati
 	return waitForFirstBlock.WaitUntilReady(ctx, *g.GetContainer())
 }
 
-func (g *Erigon) GethConsensusMechanism() ConsensusMechanism {
+// GetConsensusMechanism returns the consensus mechanism used by the Erigon instance.
+// It identifies whether the Ethereum version is Eth1 (Proof of Work) or a later version (Proof of Stake).
+func (g *Erigon) GetConsensusMechanism() ConsensusMechanism {
 	if g.GetEthereumVersion() == config_types.EthereumVersion_Eth1 {
 		return ConsensusMechanism_PoW
 	}

lib/docker/test_env/eth2_init_helpers.go

@@ -29,6 +29,8 @@ type AfterGenesisHelper struct {
 	posContainerSettings
 }
 
+// NewInitHelper initializes a new AfterGenesisHelper instance with the provided chain configuration and directory paths.
+// It sets up necessary environment components and options, facilitating the management of post-genesis operations in a blockchain network.
 func NewInitHelper(chainConfig config.EthereumChainConfig, generatedDataHostDir, generatedDataContainerDir string, opts ...EnvComponentOption) *AfterGenesisHelper {
 	g := &AfterGenesisHelper{
 		EnvComponent: EnvComponent{
@@ -47,12 +49,16 @@ func NewInitHelper(chainConfig config.EthereumChainConfig, generatedDataHostDir,
 	return g
 }
 
+// WithTestInstance sets up the AfterGenesisHelper for testing by assigning a logger and test context.
+// This allows for better logging and error tracking during test execution.
 func (g *AfterGenesisHelper) WithTestInstance(t *testing.T) *AfterGenesisHelper {
 	g.l = logging.GetTestLogger(t)
 	g.t = t
 	return g
 }
 
+// StartContainer initializes and starts the After Genesis Helper container.
+// It handles container requests and logs the startup process, ensuring the container is ready for use.
 func (g *AfterGenesisHelper) StartContainer() error {
 	r, err := g.getContainerRequest(g.Networks)
 	if err != nil {

lib/docker/test_env/eth_common.go

@@ -42,7 +42,7 @@ type ExecutionClient interface {
 	GetExternalHttpUrl() string
 	GetExternalWsUrl() string
 	GetEthereumVersion() config_types.EthereumVersion
-	GethConsensusMechanism() ConsensusMechanism
+	GetConsensusMechanism() ConsensusMechanism
 	WaitUntilChainIsReady(ctx context.Context, waitTime time.Duration) error
 	WithTestInstance(t *testing.T) ExecutionClient
 }