environment

package
v0.122.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2026 License: MIT Imports: 46 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	Local          = "local"
	StagingTestnet = "staging_testnet"
	StagingMainnet = "staging_mainnet"
	Staging        = "staging" // Note this is currently the equivalent of staging_testnet.
	ProdMainnet    = "prod_mainnet"
	ProdTestnet    = "prod_testnet"
	Prod           = "prod"

	// Legacy environments to be cleaned up once the migration to the above environments is completed.
	Testnet    = "testnet"
	Mainnet    = "mainnet"
	SolStaging = "solana-staging" // Note this is testnet staging for Solana.
)

Variables

This section is empty.

Functions

func Build added in v0.122.0 

func Build(ctx context.Context, params BuildParams, opts ...BuildOption) (fdeployment.Environment, error)

Build constructs an environment from supplied parameters, rather than from a domain directory on disk as Load does. no domain directory/config is read from disk: chains come from params.Networks and the datastore is loaded from the catalog service named in params.Catalog (chain loaders may still read files referenced by params.Onchain).

The returned environment omits the offchain client, OCR secrets and CRE runner, and its address book is empty. This is suitable for MCMS Execution, but not for Changeset execution.

func BuildFromYAML added in v0.122.0 

func BuildFromYAML(ctx context.Context, data []byte, opts ...BuildOption) (fdeployment.Environment, error)

BuildFromYAML builds an environment from a YAML encoded BuildParams document.

Decoding is strict: an unrecognised key is an error rather than a silently ignored field, so that a mistyped key cannot leave a zero value in its place.

WARNING: BuildParams carries secrets (deployer keys, KMS identifiers, catalog credentials). Prefer sourcing those from the environment and supplying them on the BuildParams directly over committing them to a file. If you must use them as a file, ensure it is stored securely and access is restricted.

func Load added in v0.40.0 

func Load(
	ctx context.Context,
	domain clddomain.Domain,
	envKey string,
	opts ...LoadEnvironmentOption,
) (fdeployment.Environment, error)

func LoadDataStore added in v0.114.2 

func LoadDataStore(
	ctx context.Context, cfg *config.Config, loadcfg *LoadConfig, domain clddomain.Domain, envKey string,
) (fdatastore.DataStore, error)

Types

type AnvilChainsOutput added in v0.41.0 

type AnvilChainsOutput struct {
	Chains       map[uint64]fevm.Chain
	ForkClients  map[uint64]ForkedOnchainClient
	ChainConfigs map[uint64]ChainConfig
	Containers   map[uint64]testcontainers.Container
}

AnvilChainsOutput represents the output of the newAnvilChains function.

type BuildConfig added in v0.122.0 

type BuildConfig struct {
	// contains filtered or unexported fields
}

BuildConfig holds the options applied to a Build, each with a default that the corresponding BuildWith* option overrides.

func (*BuildConfig) Configure added in v0.122.0 

func (c *BuildConfig) Configure(opts []BuildOption)

Configure applies the given options, overriding the defaults.

type BuildOption added in v0.122.0 

type BuildOption func(*BuildConfig)

BuildOption is a functional option type for configuring an environment build.

func BuildWithLogger added in v0.122.0 

func BuildWithLogger(lggr logger.Logger) BuildOption

BuildWithLogger supplies the logger used during the build and carried on the resulting environment. Defaults to a new logger.

func BuildWithOperationRegistry added in v0.122.0 

func BuildWithOperationRegistry(registry *operations.OperationRegistry) BuildOption

BuildWithOperationRegistry supplies a pre-populated operation registry. Defaults to an empty registry.

func BuildWithReporter added in v0.122.0 

func BuildWithReporter(reporter operations.Reporter) BuildOption

BuildWithReporter supplies the operations reporter. Defaults to an in-memory reporter.

type BuildParams added in v0.122.0 

type BuildParams struct {
	// Domain and Environment identify which slice of the catalog to load, and
	// Environment becomes the resulting Environment.Name.
	Domain      string `yaml:"domain"`
	Environment string `yaml:"environment"`

	// Onchain supplies the deployer keys and KMS settings used to load chains.
	Onchain cfgenv.OnchainConfig `yaml:"onchain"`
	// Catalog locates the catalog service that backs the datastore.
	Catalog cfgenv.CatalogConfig `yaml:"catalog"`

	// Networks lists the networks to load. Type is derived from the chain
	// selector when unset; when set it must agree with the selector.
	Networks []cfgnet.Network `yaml:"networks"`

	// DefaultRPCBaseURL is an optional RPC proxy base. When set, each network
	// gets a "<base>/<chain selector>" RPC prepended ahead of its own. Any
	// trailing slashes on the base are trimmed before the selector is appended.
	DefaultRPCBaseURL string `yaml:"default_rpc_base_url"`
}

BuildParams provides all the necessary parameters to build an environment.

The onchain, catalog and network fields reuse the same types as the file based configuration, so their schemas match a domain's .config/local.yaml and .config/networks/*.yaml respectively.

type ChainConfig added in v0.41.0 

type ChainConfig struct {
	ChainID  string // chain id as per EIP-155
	HTTPRPCs []RPCs // http rpcs to connect to the chain
}

ChainConfig represents the configuration for a chain.

type ForkedEnvironment added in v0.41.0 

type ForkedEnvironment struct {
	fdeployment.Environment
	ChainConfigs map[uint64]ChainConfig
	ForkClients  map[uint64]ForkedOnchainClient
	Containers   map[uint64]testcontainers.Container
}

ForkedEnvironment represents a forked deployment environment. It embeds a standard environment with the addition of a client for forking per fchain.

func LoadFork added in v0.47.0 

func LoadFork(
	ctx context.Context,
	domain fdomain.Domain,
	env string,
	blockNumbers map[uint64]*big.Int,
	opts ...LoadEnvironmentOption,
) (ForkedEnvironment, error)

LoadFork loads a deployment environment in which the chains are forks of real networks. Provides access to a forking client per chain that allows users to send transactions without signatures.

Limitations: - EVM only

func (ForkedEnvironment) ApplyChangesetOutput added in v0.41.0 

func (e ForkedEnvironment) ApplyChangesetOutput(ctx context.Context, output fdeployment.ChangesetOutput) (ForkedEnvironment, error)

ApplyChangesetOutput executes MCMS proposals and merges addresses into the address book.

type ForkedOnchainClient added in v0.41.0 

type ForkedOnchainClient interface {
	// SendTransaction sends transaction data from one address to another.
	// Implementations should ensure that the transaction doesn't need a valid signature to be accepted.
	SendTransaction(ctx context.Context, from string, to string, data []byte) error
}

ForkedOnchainClient is a client for a fork of a blockchain node. It should be able to send transactions from any address without the need for a private key.

type LoadConfig added in v0.38.0 

type LoadConfig struct {
	// contains filtered or unexported fields
}

LoadConfig contains configuration parameters for loading an environment.

This struct holds all the configurable options that affect how an environment is loaded, including which components to initialize, which chains to load, and various behavioral flags.

func (*LoadConfig) Configure added in v0.47.0 

func (c *LoadConfig) Configure(opts []LoadEnvironmentOption)

Configure applies a slice of LoadEnvironmentOption functions to the LoadConfig.

This method is used internally by the Load function to apply user-provided configuration options to the default LoadConfig instance.

type LoadEnvironmentOption added in v0.40.0 

type LoadEnvironmentOption func(*LoadConfig)

LoadEnvironmentOption is a functional option type for configuring environment loading.

func OnlyLoadChainsFor added in v0.40.0 

func OnlyLoadChainsFor(chainsSelectors []uint64) LoadEnvironmentOption

OnlyLoadChainsFor configures the environment to load only specified chains for a changeset.

This option optimizes environment loading by restricting it to only the chains required for a specific changeset. This can significantly reduce loading time and resource usage when working with environments that support many chains.

By default, if this option is not specified, all chains are loaded. If chainsSelectors is set to nil or empty, no chains will be loaded.

func WithAnvilKeyAsDeployer added in v0.40.0 

func WithAnvilKeyAsDeployer() LoadEnvironmentOption

WithAnvilKeyAsDeployer configures the environment to use Anvil's default private key as the EVM deployer key.

This option is intended for local development and testing with forked EVM environments. When enabled, the environment will use Anvil's well-known private key instead of generating or loading a different deployer key.

Warning: This should NEVER be used in production environments as the Anvil key is publicly known.

func WithCRERunner added in v0.91.0 

func WithCRERunner(r cre.Runner) LoadEnvironmentOption

WithCRERunner sets the CRE runner for the environment. By default no runner is configured (nil), so CRERunner on the resulting environment will be nil unless this option is used. Example: WithCRERunner(cre.NewRunner(cre.WithCLI(cre.NewCLIRunner("/opt/cre", apiKey))))

func WithDatastoreType added in v0.87.0 

func WithDatastoreType(t cfgdomain.DatastoreType) LoadEnvironmentOption

WithDatastoreType overrides the datastore type from domain config. Use when the caller explicitly requests "file" or "catalog" (e.g. from a CLI flag). Omit to use domain default.

func WithDryRunJobDistributor added in v0.47.0 

func WithDryRunJobDistributor() LoadEnvironmentOption

WithDryRunJobDistributor configures the environment to use a dry-run Job Distributor.

The dry-run Job Distributor is a special mode that allows safe testing of operations that would normally modify the Job Distributor state. In this mode:

  • Read operations are forwarded to the real Job Distributor backend
  • Write operations are stubbed out and logged but not executed
  • This allows testing of changeset logic without affecting production systems

This option is particularly useful for:

  • Running fork tests without affecting the production environment
  • Testing changesets against production environments safely
  • Validating operation logic before actual deployment
  • Debugging issues without side effects

func WithLogger added in v0.47.0 

func WithLogger(lggr logger.Logger) LoadEnvironmentOption

WithLogger configures the environment to use a custom logger instance.

The logger is used throughout the environment loading process and subsequent operations for debugging, informational messages, and error reporting. By default, a new logger instance is created automatically.

This option is useful when you need to:

  • Use a specific logger configuration (log level, format, output)
  • Integrate with existing logging infrastructure
  • Use a test logger for unit tests
  • Share a logger instance across multiple components

func WithOperationRegistry added in v0.40.0 

func WithOperationRegistry(registry *operations.OperationRegistry) LoadEnvironmentOption

WithOperationRegistry configures the environment to use a custom operation registry.

The operation registry contains all available operations that can be executed within the environment. By default, a new empty registry is created. This option allows you to provide a pre-configured registry with custom operations or modified behavior.

func WithReporter added in v0.40.0 

func WithReporter(reporter operations.Reporter) LoadEnvironmentOption

WithReporter configures a custom operations reporter for environment loading.

The reporter is responsible for tracking and recording operations performed during environment loading and subsequent operations. By default, a memory-based reporter is used, but this option allows you to provide a custom implementation.

func WithoutJD added in v0.40.0 

func WithoutJD() LoadEnvironmentOption

WithoutJD configures the environment to skip Job Distributor initialization.

By default, the environment loading process initializes the Job Distributor component. This option disables that initialization, which can be useful for:

  • Changeset executions that don't require offchain components
  • Faster environment loading when JD is not needed
  • Testing scenarios where JD dependencies are not available

WARNING: When this option is used, env.Offchain will be nil. Any code that attempts to use env.Offchain will panic. Ensure your changeset or operation does not depend on Job Distributor functionality.

type RPCs added in v0.41.0 

type RPCs struct {
	External string
}

RPCs represents the internal and external RPCs for a chain.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.