Documentation
¶
Overview ¶
Package sequenceutils provides helpers for building deployment changesets from operations sequences.
Use NewOnChainChangesetFromSequence to wrap a sequence that returns OnChainOutput into a ChangeSetV2 with datastore and MCMS timelock proposal integration.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrBatchOpsWithoutMCMSInput indicates the sequence returned batch operations without MCMS timelock proposal input. ErrBatchOpsWithoutMCMSInput = errors.New("batch operations require MCMS timelock proposal input") )
Functions ¶
func NewOnChainChangesetFromSequence ¶
func NewOnChainChangesetFromSequence[IN any, DEP any, CFG any]( params NewOnChainChangesetFromSequenceParams[IN, DEP, CFG], opts ...OnChainChangesetFromSequenceOption, ) deployment.ChangeSetV2[WithMCMS[CFG]]
NewOnChainChangesetFromSequence creates a ChangeSetV2 from an operations.Sequence that deploys contracts on-chain and performs write operations. It executes the sequence, writes OnChainOutput.Metadata to a datastore, and optionally builds an MCMS timelock proposal from OnChainOutput.BatchOps.
Config is passed as WithMCMS[CFG], which wraps the deployment-specific config (Cfg) and an optional MCMS timelock proposal input (MCMS). When the sequence returns batch operations with transactions, MCMS must be set or Apply returns ErrBatchOpsWithoutMCMSInput.
Usage:
deploySeq := operations.NewSequence(
"deploy-timelock",
semver.MustParse("1.0.0"),
"Deploy timelock contracts",
func(b operations.Bundle, deps DeployDeps, in DeployInput) (OnChainOutput, error) {
// Run operations and collect addresses and/or MCMS batch operations.
return OnChainOutput{
Metadata: datastore.MetadataBundle{
Addresses: []datastore.AddressRef{timelockRef},
},
BatchOps: batchOps, // omit when no MCMS proposal is needed
}, nil
},
)
cs := NewOnChainChangesetFromSequence(
NewOnChainChangesetFromSequenceParams[DeployInput, DeployDeps, DeployConfig]{
Sequence: deploySeq,
ResolveInput: func(e deployment.Environment, cfg DeployConfig) (DeployInput, error) {
return DeployInput{ChainSelector: cfg.ChainSelector}, nil
},
ResolveDep: func(e deployment.Environment, cfg DeployConfig) (DeployDeps, error) {
return DeployDeps{Chain: e.BlockChains.EVMChains()[cfg.ChainSelector]}, nil
},
},
)
wrapped := WithMCMS[DeployConfig]{
Cfg: DeployConfig{ChainSelector: ethMainnetSelector},
MCMS: &deployment.MCMSTimelockProposalInput{
TimelockAction: mcms_types.TimelockActionSchedule,
ValidUntil: validUntil,
TimelockDelay: mcms_types.NewDuration(time.Hour),
Description: "schedule timelock ops",
},
}
if err := cs.VerifyPreconditions(env, wrapped); err != nil {
return err
}
out, err := cs.Apply(env, wrapped)
// out.DataStore holds deployed addresses; out.MCMSTimelockProposals holds proposals.
Types ¶
type NewOnChainChangesetFromSequenceParams ¶
type NewOnChainChangesetFromSequenceParams[IN any, DEP any, CFG any] struct { // Sequence is the operations.Sequence to execute. Sequence *operations.Sequence[IN, OnChainOutput, DEP] // ResolveInput resolves the input for the sequence based on the environment and changeset config. ResolveInput func(e deployment.Environment, cfg CFG) (IN, error) // ResolveDep resolves the dependencies for the sequence based on the environment and changeset config. ResolveDep func(e deployment.Environment, cfg CFG) (DEP, error) // Verify, if non-nil, performs additional validation beyond built-in MCMS checks, params, environment, and resolve. Verify func(e deployment.Environment, wrapped WithMCMS[CFG]) error }
NewOnChainChangesetFromSequenceParams configures NewOnChainChangesetFromSequence.
type OnChainChangesetFromSequenceOption ¶
type OnChainChangesetFromSequenceOption func(*onChainChangesetConfig)
OnChainChangesetFromSequenceOption configures NewOnChainChangesetFromSequence.
func WithMCMSRegistry ¶
func WithMCMSRegistry(registry *deployment.MCMSReaderRegistry) OnChainChangesetFromSequenceOption
WithMCMSRegistry overrides the default MCMS reader registry (deployment.GetMCMSReaderRegistry). In most cases, you should not need to use this method.
type OnChainOutput ¶
type OnChainOutput struct {
// Metadata is written to the changeset datastore (see datastore.MetadataBundle).
// - Addresses: deployed contract addresses (Added)
// - Contracts: contract metadata keyed by address + chain selector (Upserted)
// - Chains: chain metadata keyed by chain selector (Upserted)
// - Env: one env metadata record per environment (Set)
// If writing to a particular key, ensure that you populate all required fields.
Metadata datastore.MetadataBundle
// BatchOps are MCMS batch operations for a single timelock proposal. MCMS input comes from the changeset config.
BatchOps []mcms_types.BatchOperation
}
OnChainOutput is a standard output type for sequences that deploy contracts on-chain and perform write operations.
type WithMCMS ¶
type WithMCMS[CFG any] struct { // MCMS, when non-nil, is validated at verification time and used to build the timelock proposal when the // sequence returns batch operations with transactions. Apply fails if the sequence returns non-empty batch // operations without MCMS input. MCMS *deployment.MCMSTimelockProposalInput Cfg CFG }
Source Files