stack

type Cluster ¶

type Cluster interface {
	Common
	ID() ClusterID

	DependencySet() depset.DependencySet
}

Cluster represents a set of chains that interop with each other. This may include L1 chains (although potentially not two-way interop due to consensus-layer limitations).

func SortClusters(elems []Cluster) []Cluster

type ClusterID ¶

type ClusterID genericID

ClusterID identifies a Cluster by name, is type-safe, and can be value-copied and used as map key.

func SortClusterIDs(ids []ClusterID) []ClusterID

func (id ClusterID) MarshalText() ([]byte, error)

func (id ClusterID) Match(elems []Cluster) []Cluster

func (id ClusterID) String() string

func (id *ClusterID) UnmarshalText(data []byte) error

type ClusterMatcher ¶

type ClusterMatcher = Matcher[ClusterID, Cluster]

type CombinedOption ¶

type CombinedOption[O Orchestrator] []Option[O]

CombinedOption is a list of options. For each option lifecycle stage, all options are applied, left to right.

func Combine[O Orchestrator](opts ...Option[O]) CombinedOption[O]

func (c *CombinedOption[O]) Add(other ...Option[O])

func (c CombinedOption[O]) AfterDeploy(orch O)

func (c CombinedOption[O]) BeforeDeploy(orch O)

func (c CombinedOption[O]) Deploy(orch O)

func (c CombinedOption[O]) Finally(orch O)

func (c CombinedOption[O]) PostHydrate(sys System)

type Common ¶

type Common interface {
	T() devtest.T
	Logger() log.Logger

	// Label retrieves a label by key.
	// If the label does not exist, it returns an empty string.
	Label(key string) string

	// SetLabel sets a label by key.
	// Note that labels added by tests are not visible to other tests against the same backend.
	SetLabel(key, value string)
}

type CommonOption ¶

type CommonOption = Option[Orchestrator]

func MakeCommon[O Orchestrator](opt Option[O]) CommonOption

type ControlAction ¶

type ControlAction int

const (
	Start ControlAction = iota
	Stop
)

type ControlPlane ¶

type ControlPlane interface {
	SupervisorState(id SupervisorID, action ControlAction)
	L2CLNodeState(id L2CLNodeID, action ControlAction)
}

ControlPlane is the interface for the orchestrators to control components of the system.

type ELNode ¶

type ELNode interface {
	Common
	ChainID() eth.ChainID
	EthClient() apis.EthClient
}

type ExtensibleL1Network ¶

type ExtensibleL1Network interface {
	ExtensibleNetwork
	L1Network
	AddL1ELNode(v L1ELNode)
	AddL1CLNode(v L1CLNode)
}

type ExtensibleL2Network ¶

type ExtensibleL2Network interface {
	ExtensibleNetwork
	L2Network
	AddL2Batcher(v L2Batcher)
	AddL2Proposer(v L2Proposer)
	AddL2Challenger(v L2Challenger)
	AddL2CLNode(v L2CLNode)
	AddL2ELNode(v L2ELNode)
}

ExtensibleL2Network is an optional extension interface for L2Network, for adding new components to the chain. Used during test-setup, not generally during test execution.

type ExtensibleNetwork ¶

type ExtensibleNetwork interface {
	Network

	AddFaucet(f Faucet)
}

type ExtensibleSystem ¶

type ExtensibleSystem interface {
	System
	AddSuperchain(v Superchain)
	AddCluster(v Cluster)
	AddL1Network(v L1Network)
	AddL2Network(v L2Network)
	AddSupervisor(v Supervisor)
	AddSequencer(v Sequencer)
}

ExtensibleSystem is an extension-interface to add new components to the system. Regular tests should not be modifying the system. Test gates may use this to remediate any shortcomings of an existing system.

type Faucet ¶

type Faucet interface {
	Common
	ID() FaucetID
	API() apis.Faucet
}

func SortFaucets(elems []Faucet) []Faucet

type FaucetID ¶

type FaucetID idWithChain

FaucetID identifies a Faucet by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortFaucetIDs(ids []FaucetID) []FaucetID

func (id FaucetID) MarshalText() ([]byte, error)

func (id FaucetID) Match(elems []Faucet) []Faucet

func (id FaucetID) String() string

func (id *FaucetID) UnmarshalText(data []byte) error

type FaucetMatcher ¶

type FaucetMatcher = Matcher[FaucetID, Faucet]

type FnOption ¶

type FnOption[O Orchestrator] struct {
	BeforeDeployFn func(orch O)
	DeployFn       func(orch O)
	AfterDeployFn  func(orch O)
	FinallyFn      func(orch O)
	PostHydrateFn  func(sys System)
}

FnOption defines an option with more flexible function instances per option lifecycle stage. Each nil attribute is simply a no-op when not set.

func (f FnOption[O]) AfterDeploy(orch O)

func (f FnOption[O]) BeforeDeploy(orch O)

func (f FnOption[O]) Deploy(orch O)

func (f FnOption[O]) Finally(orch O)

func (f FnOption[O]) PostHydrate(sys System)

type Identifiable ¶

type Identifiable[I comparable] interface {
	ID() I
}

type Keys ¶

type Keys interface {
	Secret(key devkeys.Key) *ecdsa.PrivateKey
	Address(key devkeys.Key) common.Address
}

type Kind ¶

type Kind string

Kind represents a kind of component, this is used to make each ID unique, even when encoded as text.

const ClusterKind Kind = "Cluster"

const FaucetKind Kind = "Faucet"

const L1CLNodeKind Kind = "L1CLNode"

const L1ELNodeKind Kind = "L1ELNode"

const L1NetworkKind Kind = "L1Network"

const L2BatcherKind Kind = "L2Batcher"

const L2CLNodeKind Kind = "L2CLNode"

const L2ChallengerKind Kind = "L2Challenger"

const L2ELNodeKind Kind = "L2ELNode"

const L2NetworkKind Kind = "L2Network"

const L2ProposerKind Kind = "L2Proposer"

const SequencerKind Kind = "Sequencer"

const SuperchainKind Kind = "Superchain"

const SupervisorKind Kind = "Supervisor"

func (k Kind) MarshalText() ([]byte, error)

func (k Kind) String() string

func (k *Kind) UnmarshalText(data []byte) error

type L1CLMatcher ¶

type L1CLMatcher = Matcher[L1CLNodeID, L1CLNode]

type L1CLNode ¶

type L1CLNode interface {
	Common
	ID() L1CLNodeID

	BeaconClient() apis.BeaconClient
}

L1CLNode is a L1 ethereum consensus-layer node, aka Beacon node. This node may not be a full beacon node, and instead run a mock L1 consensus node.

func SortL1CLNodes(elems []L1CLNode) []L1CLNode

type L1CLNodeID ¶

type L1CLNodeID idWithChain

L1CLNodeID identifies a L1CLNode by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL1CLNodeIDs(ids []L1CLNodeID) []L1CLNodeID

func (id L1CLNodeID) MarshalText() ([]byte, error)

func (id L1CLNodeID) Match(elems []L1CLNode) []L1CLNode

func (id L1CLNodeID) String() string

func (id *L1CLNodeID) UnmarshalText(data []byte) error

type L1ELMatcher ¶

type L1ELMatcher = Matcher[L1ELNodeID, L1ELNode]

type L1ELNode ¶

type L1ELNode interface {
	ID() L1ELNodeID

	ELNode
}

L1ELNode is a L1 ethereum execution-layer node

func SortL1ELNodes(elems []L1ELNode) []L1ELNode

type L1ELNodeID ¶

type L1ELNodeID idWithChain

L1ELNodeID identifies a L1ELNode by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL1ELNodeIDs(ids []L1ELNodeID) []L1ELNodeID

func (id L1ELNodeID) MarshalText() ([]byte, error)

func (id L1ELNodeID) Match(elems []L1ELNode) []L1ELNode

func (id L1ELNodeID) String() string

func (id *L1ELNodeID) UnmarshalText(data []byte) error

type L1Network ¶

type L1Network interface {
	Network
	ID() L1NetworkID

	L1ELNode(m L1ELMatcher) L1ELNode
	L1CLNode(m L1CLMatcher) L1CLNode

	L1ELNodeIDs() []L1ELNodeID
	L1CLNodeIDs() []L1CLNodeID

	L1ELNodes() []L1ELNode
	L1CLNodes() []L1CLNode
}

L1Network represents a L1 chain, a collection of configuration and node resources.

func SortL1Networks(elems []L1Network) []L1Network

type L1NetworkID ¶

type L1NetworkID idOnlyChainID

L1NetworkID identifies a L1Network by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL1NetworkIDs(ids []L1NetworkID) []L1NetworkID

func (id L1NetworkID) ChainID() eth.ChainID

func (id L1NetworkID) MarshalText() ([]byte, error)

func (id L1NetworkID) Match(elems []L1Network) []L1Network

func (id L1NetworkID) String() string

func (id *L1NetworkID) UnmarshalText(data []byte) error

type L1NetworkMatcher ¶

type L1NetworkMatcher = Matcher[L1NetworkID, L1Network]

type L2Batcher ¶

type L2Batcher interface {
	Common
	ID() L2BatcherID
	ActivityAPI() apis.BatcherActivity
}

L2Batcher represents an L2 batch-submission service, posting L2 data of an L2 to L1.

func SortL2Batchers(elems []L2Batcher) []L2Batcher

type L2BatcherID ¶

type L2BatcherID idWithChain

L2BatcherID identifies a L2Batcher by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL2BatcherIDs(ids []L2BatcherID) []L2BatcherID

func (id L2BatcherID) MarshalText() ([]byte, error)

func (id L2BatcherID) Match(elems []L2Batcher) []L2Batcher

func (id L2BatcherID) String() string

func (id *L2BatcherID) UnmarshalText(data []byte) error

type L2BatcherMatcher ¶

type L2BatcherMatcher = Matcher[L2BatcherID, L2Batcher]

type L2CLMatcher ¶

type L2CLMatcher = Matcher[L2CLNodeID, L2CLNode]

type L2CLNode ¶

type L2CLNode interface {
	Common
	ID() L2CLNodeID

	RollupAPI() apis.RollupClient
	P2PAPI() apis.P2PClient

	// ELs returns the engine(s) that this L2CLNode is connected to.
	// This may be empty, if the L2CL is not connected to any.
	ELs() []L2ELNode
}

L2CLNode is a L2 ethereum consensus-layer node

func SortL2CLNodes(elems []L2CLNode) []L2CLNode

type L2CLNodeID ¶

type L2CLNodeID idWithChain

L2CLNodeID identifies a L2CLNode by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL2CLNodeIDs(ids []L2CLNodeID) []L2CLNodeID

func (id L2CLNodeID) MarshalText() ([]byte, error)

func (id L2CLNodeID) Match(elems []L2CLNode) []L2CLNode

func (id L2CLNodeID) String() string

func (id *L2CLNodeID) UnmarshalText(data []byte) error

type L2Challenger ¶

type L2Challenger interface {
	Common
	ID() L2ChallengerID
}

func SortL2Challengers(elems []L2Challenger) []L2Challenger

type L2ChallengerID ¶

type L2ChallengerID idWithChain

L2ChallengerID identifies a L2Challenger by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL2ChallengerIDs(ids []L2ChallengerID) []L2ChallengerID

func (id L2ChallengerID) MarshalText() ([]byte, error)

func (id L2ChallengerID) Match(elems []L2Challenger) []L2Challenger

func (id L2ChallengerID) String() string

func (id *L2ChallengerID) UnmarshalText(data []byte) error

type L2ChallengerMatcher ¶

type L2ChallengerMatcher = Matcher[L2ChallengerID, L2Challenger]

type L2Deployment ¶

type L2Deployment interface {
	SystemConfigProxyAddr() common.Address
	DisputeGameFactoryProxyAddr() common.Address
}

type L2ELMatcher ¶

type L2ELMatcher = Matcher[L2ELNodeID, L2ELNode]

type L2ELNode ¶

type L2ELNode interface {
	ID() L2ELNodeID
	L2EthClient() apis.L2EthClient

	ELNode
}

L2ELNode is a L2 ethereum execution-layer node

func SortL2ELNodes(elems []L2ELNode) []L2ELNode

type L2ELNodeID ¶

type L2ELNodeID idWithChain

L2ELNodeID identifies a L2ELNode by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL2ELNodeIDs(ids []L2ELNodeID) []L2ELNodeID

func (id L2ELNodeID) MarshalText() ([]byte, error)

func (id L2ELNodeID) Match(elems []L2ELNode) []L2ELNode

func (id L2ELNodeID) String() string

func (id *L2ELNodeID) UnmarshalText(data []byte) error

type L2Network ¶

type L2Network interface {
	Network
	ID() L2NetworkID
	RollupConfig() *rollup.Config
	Deployment() L2Deployment
	Keys() Keys

	Superchain() Superchain
	L1() L1Network
	Cluster() Cluster

	L2Batcher(m L2BatcherMatcher) L2Batcher
	L2Proposer(m L2ProposerMatcher) L2Proposer
	L2Challenger(m L2ChallengerMatcher) L2Challenger
	L2CLNode(m L2CLMatcher) L2CLNode
	L2ELNode(m L2ELMatcher) L2ELNode

	L2BatcherIDs() []L2BatcherID
	L2ProposerIDs() []L2ProposerID
	L2ChallengerIDs() []L2ChallengerID
	L2CLNodeIDs() []L2CLNodeID
	L2ELNodeIDs() []L2ELNodeID

	L2Batchers() []L2Batcher
	L2Proposers() []L2Proposer
	L2Challengers() []L2Challenger
	L2CLNodes() []L2CLNode
	L2ELNodes() []L2ELNode
}

L2Network represents a L2 chain, a collection of configuration and node resources. There is an extension-interface ExtensibleL2Network for adding new components to the chain.

func SortL2Networks(elems []L2Network) []L2Network

type L2NetworkID ¶

type L2NetworkID idOnlyChainID

L2NetworkID identifies a L2Network by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL2NetworkIDs(ids []L2NetworkID) []L2NetworkID

func (id L2NetworkID) ChainID() eth.ChainID

func (id L2NetworkID) MarshalText() ([]byte, error)

func (id L2NetworkID) Match(elems []L2Network) []L2Network

func (id L2NetworkID) String() string

func (id *L2NetworkID) UnmarshalText(data []byte) error

type L2NetworkMatcher ¶

type L2NetworkMatcher = Matcher[L2NetworkID, L2Network]

type L2Proposer ¶

type L2Proposer interface {
	Common
	ID() L2ProposerID
}

L2Proposer is a L2 output proposer, posting claims of L2 state to L1.

func SortL2Proposers(elems []L2Proposer) []L2Proposer

type L2ProposerID ¶

type L2ProposerID idWithChain

L2ProposerID identifies a L2Proposer by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortL2ProposerIDs(ids []L2ProposerID) []L2ProposerID

func (id L2ProposerID) MarshalText() ([]byte, error)

func (id L2ProposerID) Match(elems []L2Proposer) []L2Proposer

func (id L2ProposerID) String() string

func (id *L2ProposerID) UnmarshalText(data []byte) error

type L2ProposerMatcher ¶

type L2ProposerMatcher = Matcher[L2ProposerID, L2Proposer]

type Lifecycle ¶

type Lifecycle interface {
	Start()
	Stop()
}

Lifecycle represents a controllable component by ControlPlane

type LinkableL2CLNode ¶

type LinkableL2CLNode interface {
	// Links the nodes. Does not make any backend changes, just registers the EL as connected to this CL.
	LinkEL(el L2ELNode)
}

type Matcher ¶

type Matcher[I comparable, E Identifiable[I]] interface {
	// Match finds the elements that pass the matcher.
	// If no element passes, it returns an empty slice.
	// Callers should guarantee a stable order of ids, to ensure a deterministic match.
	Match(elems []E) []E

	// String must describe the matcher for debugging purposes.
	// This does not get used for matching.
	String() string
}

Matcher abstracts what can be used as getter-method argument. All ID types implement this interface, and lookup functions check if the argument is an ID before searching for a match. This enables lookups such as getting a component by labels, by its state, by its relation to other components, etc.

type Network ¶

type Network interface {
	Common

	ChainID() eth.ChainID

	ChainConfig() *params.ChainConfig

	Faucet(m FaucetMatcher) Faucet
	Faucets() []Faucet
	FaucetIDs() []FaucetID
}

Network is an interface to an ethereum chain and its resources, with common properties between L1 and L2. For L1 or L2 specifics, see L1Network and L2Network extensions. A network hosts configuration resources and tracks participating nodes.

type Option ¶

type Option[O Orchestrator] interface {
	// BeforeDeploy runs before any chain is created/deployed
	BeforeDeploy(orch O)
	// Deploy runs the deployment
	Deploy(orch O)
	// AfterDeploy runs after chains are created/deployed
	AfterDeploy(orch O)
	// Finally runs at the very end of orchestrator setup,
	// but before any test-scope is created.
	Finally(orch O)
	// SystemHook is embedded: Options may expose system hooks, to run in test-scope.
	SystemHook
}

Option is used to define a change that inspects and/or changes a System during the lifecycle.

func AfterDeploy[O Orchestrator](fn func(orch O)) Option[O]

func BeforeDeploy[O Orchestrator](fn func(orch O)) Option[O]

func Deploy[O Orchestrator](fn func(orch O)) Option[O]

func Finally[O Orchestrator](fn func(orch O)) Option[O]

func PostHydrate[O Orchestrator](fn func(sys System)) Option[O]

type Orchestrator ¶

type Orchestrator interface {
	// P is the test-handle of the orchestrator.
	// This may not be a Go-test handle.
	// Orchestrators may be instantiated by dev-tools or test-package TestMain functions.
	P() devtest.P

	// Hydrate adds all services that the orchestrator is aware of to the given system.
	// An orchestrator may be asked to hydrate different systems, one for each test.
	Hydrate(sys ExtensibleSystem)

	ControlPlane() ControlPlane
}

Orchestrator is the base interface for all system orchestrators. It imposes some common things across all orchestrators, but may also have optional extensions, that not every type of backend might support.

type Sequencer ¶

type Sequencer interface {
	Common
	ID() SequencerID

	AdminAPI() apis.SequencerAdminAPI
	BuildAPI() apis.SequencerBuildAPI
	IndividualAPI(chainID eth.ChainID) apis.SequencerIndividualAPI
}

Sequencer

func SortSequencers(elems []Sequencer) []Sequencer

type SequencerID ¶

type SequencerID genericID

SequencerID identifies a Sequencer by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortSequencerIDs(ids []SequencerID) []SequencerID

func (id SequencerID) MarshalText() ([]byte, error)

func (id SequencerID) String() string

func (id *SequencerID) UnmarshalText(data []byte) error

type SequencerMatcher ¶

type SequencerMatcher = Matcher[SequencerID, Sequencer]

type Superchain ¶

type Superchain interface {
	Common
	ID() SuperchainID

	Deployment() SuperchainDeployment
}

Superchain is a collection of L2 chains with common rules and shared configuration on L1

func SortSuperchains(elems []Superchain) []Superchain

type SuperchainDeployment ¶

type SuperchainDeployment interface {
	ProtocolVersionsAddr() common.Address
	SuperchainConfigAddr() common.Address
}

type SuperchainID ¶

type SuperchainID genericID

SuperchainID identifies a Superchain by name, is type-safe, and can be value-copied and used as map key.

func SortSuperchainIDs(ids []SuperchainID) []SuperchainID

func (id SuperchainID) MarshalText() ([]byte, error)

func (id SuperchainID) Match(elems []Superchain) []Superchain

func (id SuperchainID) String() string

func (id *SuperchainID) UnmarshalText(data []byte) error

type SuperchainMatcher ¶

type SuperchainMatcher = Matcher[SuperchainID, Superchain]

type Supervisor ¶

type Supervisor interface {
	Common
	ID() SupervisorID

	AdminAPI() apis.SupervisorAdminAPI
	QueryAPI() apis.SupervisorQueryAPI
}

Supervisor is an interop service, used to cross-verify messages between chains.

func SortSupervisors(elems []Supervisor) []Supervisor

type SupervisorID ¶

type SupervisorID genericID

SupervisorID identifies a Supervisor by name and chainID, is type-safe, and can be value-copied and used as map key.

func SortSupervisorIDs(ids []SupervisorID) []SupervisorID

func (id SupervisorID) MarshalText() ([]byte, error)

func (id SupervisorID) Match(elems []Supervisor) []Supervisor

func (id SupervisorID) String() string

func (id *SupervisorID) UnmarshalText(data []byte) error

type SupervisorMatcher ¶

type SupervisorMatcher = Matcher[SupervisorID, Supervisor]

type System ¶

type System interface {
	Common

	Superchain(m SuperchainMatcher) Superchain
	Cluster(m ClusterMatcher) Cluster
	L1Network(m L1NetworkMatcher) L1Network
	L2Network(m L2NetworkMatcher) L2Network

	Network(id eth.ChainID) Network

	Supervisor(m SupervisorMatcher) Supervisor
	Sequencer(id SequencerMatcher) Sequencer

	SuperchainIDs() []SuperchainID
	ClusterIDs() []ClusterID
	L1NetworkIDs() []L1NetworkID
	L2NetworkIDs() []L2NetworkID
	SupervisorIDs() []SupervisorID

	Superchains() []Superchain
	Clusters() []Cluster
	L1Networks() []L1Network
	L2Networks() []L2Network
	Supervisors() []Supervisor
	Sequencers() []Sequencer
}

System represents a collection of L1 and L2 chains, any superchains or clusters, and any peripherals.

type SystemHook ¶

type SystemHook interface {
	// PostHydrate runs after a system is hydrated, to run any checks.
	// This may register validation that runs at the end of the test, using the sys.T().Cleanup function.
	PostHydrate(sys System)
}