deployment

type AddressBook ¶

type AddressBook interface {
	Save(chainSelector uint64, address string, tv TypeAndVersion) error
	Addresses() (map[uint64]map[string]TypeAndVersion, error)
	AddressesForChain(chain uint64) (map[string]TypeAndVersion, error)
	// Allows for merging address books (e.g. new deployments with existing ones)
	Merge(other AddressBook) error
	Remove(ab AddressBook) error
}

AddressBook is a simple interface for storing and retrieving contract addresses across chains. It is family agnostic as the keys are chain selectors. We store rather than derive typeAndVersion as some contracts do not support it. For ethereum addresses are always stored in EIP55 format.

type AddressBookMap ¶

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

func NewMemoryAddressBook() *AddressBookMap

func NewMemoryAddressBookFromMap(addressesByChain map[uint64]map[string]TypeAndVersion) *AddressBookMap

func (m *AddressBookMap) Addresses() (map[uint64]map[string]TypeAndVersion, error)

func (m *AddressBookMap) AddressesForChain(chainSelector uint64) (map[string]TypeAndVersion, error)

func (m *AddressBookMap) Merge(ab AddressBook) error

func (m *AddressBookMap) Remove(ab AddressBook) error

func (m *AddressBookMap) Save(chainSelector uint64, address string, typeAndVersion TypeAndVersion) error

type AddressesByChain ¶

type AddressesByChain map[uint64]map[string]TypeAndVersion

type ChangeLogic ¶ added in v0.0.6

type ChangeLogic[C any] func(e Environment, config C) (ChangesetOutput, error)

ChangeLogic encapsulates the active behavior of a ChangeSetV2. The config struct contains environment-specific inputs for this logical change. For example, it might contain the chainSelectors against which this change logic should be applied, or certain contract addresses or configuration values to be used in this change. The function should perform any deployment or configuration tasks, compose and propose job-specs, and generate any MCMS proposals necessary. This is the standalone version of ChangeSetV2.Apply for use with CreateChangeSet

ChangeLogic functions should operate on a modest number of chains to reduce the risk of partial failures.

type ChangeSet ¶ added in v0.0.6

type ChangeSet[C any] func(e Environment, config C) (ChangesetOutput, error)

ChangeSet is equivalent to ChangeLogic Deprecated: use the ChangeLogic type, or an instance of a ChangeSetV2 in infrastructure or validation code.

type ChangeSetV2 ¶ added in v0.0.6

type ChangeSetV2[C any] interface {
	// Apply performs the logic of the changeset, including any side effects, such as on-chain (non-MCMS) writes or
	// contract deployments,  job-spec creation and Job-Distributor interaction, MCMS proposal creation, etc. It should
	// return the ingredients of the side effects in a ChangesetOutput.
	Apply(e Environment, config C) (ChangesetOutput, error)

	// VerifyPreconditions function verifies the preconditions of the config. It should have no side effects, instead
	// returning an error if the ChangeSetV2 should not be applied, or nil if the ChangeSetV2 is safe to apply.
	VerifyPreconditions(e Environment, config C) error
}

ChangeSetV2 is a type which encapsulates the logic to perform a set of changes to be made to an environment, in the context of deploying Chainlink's product operations - namely deploying and configuring contracts, generating and proposing TOML job-specs and interacting with the Job Distributor, and creating MCMS proposals.

ChangeSetV2 has a pre-validation function which is optional (can be implemented as a no-op), which execution environments (such as the migrations infrastructure in chainlink-deployments) should execute before invoking the Apply method.

> Note: ChangeSetV2 replaces ChangeSet, though its Apply method is identical in signature to a ChangeSet function.

func CreateChangeSet[C any](applyFunc ChangeLogic[C], verifyFunc func(e Environment, config C) error) ChangeSetV2[C]

func CreateLegacyChangeSet[C any](changeset ChangeSet[C]) ChangeSetV2[C]

type ChangesetOutput ¶ added in v0.0.6

type ChangesetOutput struct {
	// Deprecated: Prefer Jobs instead.
	JobSpecs                   map[string][]string `deprecated:"true"`
	Jobs                       []ProposedJob
	MCMSTimelockProposals      []mcms.TimelockProposal
	DescribedTimelockProposals []string
	MCMSProposals              []mcms.Proposal
	// Deprecated: AddressBook is deprecated and will be removed in future versions.
	// Please use DataStore instead. If you still need to use AddressBook in your code,
	// be aware that you may encounter CI failures due to linting errors.
	// To work around this, you can disable the linter for that specific line using the //nolint directive.
	AddressBook AddressBook
	DataStore   datastore.MutableDataStore
	// Reports are populated by the Operations API with the
	// results of the operations executed in the changeset.
	Reports []operations.Report[any, any]
}

ChangesetOutput is the output of a Changeset function. Think of it like a state transition output. The address book here should contain only new addresses created in this changeset.

type ContractDeploy ¶ added in v0.0.12

type ContractDeploy[C any] struct {
	Address  common.Address     // We leave this incase a Go binding doesn't have Address()
	Contract C                  // Expected to be a Go binding
	Tx       *types.Transaction // Incase the caller needs for example tx hash info for
	Tv       TypeAndVersion
	Err      error
}

ContractDeploy represents the result of an EVM contract deployment via an abigen Go binding. It contains all the return values as they are useful in different ways.

func DeployContract[C any](
	lggr logger.Logger,
	chain cldf_evm.Chain,
	addressBook AddressBook,
	deploy func(chain cldf_evm.Chain) ContractDeploy[C],
) (*ContractDeploy[C], error)

type ContractType ¶

type ContractType string

ContractType is a simple string type for identifying contract types.

func (ct ContractType) String() string

type Environment ¶ added in v0.0.6

type Environment struct {
	Name   string
	Logger logger.Logger
	// Deprecated: AddressBook is deprecated and will be removed in future versions.
	// Please use DataStore instead. If you still need to use AddressBook in your code,
	// be aware that you may encounter CI failures due to linting errors.
	// To work around this, you can disable the linter for that specific line using the //nolint directive.
	ExistingAddresses AddressBook
	DataStore         datastore.DataStore

	Catalog datastore.CatalogStore

	NodeIDs    []string
	Offchain   offchain.Client
	GetContext func() context.Context
	OCRSecrets ocr.OCRSecrets
	// OperationsBundle contains dependencies required by the operations API.
	OperationsBundle operations.Bundle
	// BlockChains is the container of all chains in the environment.
	BlockChains chain.BlockChains
}

Environment represents an instance of a deployed product including on and offchain components. It is intended to be cross-family to enable a coherent view of a product deployed to all its chains. TODO: Add SolChains, AptosChain etc. using Go bindings/libraries from their respective repositories i.e. chainlink-solana, chainlink-cosmos You can think of ExistingAddresses as a set of family agnostic "onchain pointers" meant to be used in conjunction with chain fields to read/write relevant chain state. Similarly, you can think of NodeIDs as "offchain pointers" to be used in conjunction with the Offchain client to read/write relevant offchain state (i.e. state in the DON(s)).

func NewEnvironment(
	name string,
	logger logger.Logger,
	existingAddrs AddressBook,
	dataStore datastore.DataStore,
	nodeIDs []string,
	offchain offchain.Client,
	ctx func() context.Context,
	secrets ocr.OCRSecrets,
	blockChains chain.BlockChains,
	opts ...EnvironmentOption,
) *Environment

func (e Environment) Clone() Environment

type EnvironmentOption ¶ added in v0.18.0

type EnvironmentOption func(*Environment)

EnvironmentOption is a functional option for configuring an Environment

func WithCatalog(catalog datastore.CatalogStore) EnvironmentOption

type LabelSet ¶

type LabelSet map[string]struct{}

LabelSet represents a set of labels on an address book entry.

func NewLabelSet(labels ...string) LabelSet

func (ls LabelSet) Add(labels string)

func (ls LabelSet) Contains(labels string) bool

func (ls LabelSet) Equal(other LabelSet) bool

func (ls LabelSet) IsEmpty() bool

func (ls LabelSet) List() []string

func (ls LabelSet) Remove(labels string)

func (ls LabelSet) String() string

type PreconditionVerifier ¶ added in v0.0.6

type PreconditionVerifier[C any] func(e Environment, config C) error

PreconditionVerifier functions should evaluate the supplied config, in the context of an environment, to ensure that the config struct is correct, and that the environmental preconditions are as expected. This is the standalone version of ChangeSetV2.VerifyPreconditions for use with CreateChangeSet

If the configuration is unexpected type or format, the changeset should return ErrInvalidConfig. If there are surprising aspects in the environment (a contract expected to be present cannot be located, etc.), then ErrInvalidEnvironment should be returned.

type ProposedJob ¶ added in v0.0.6

type ProposedJob struct {
	JobID string
	Node  string
	Spec  string
}

ProposedJob represents a job spec which has been proposed to a node, with the JobID returned by the Job Distributor.

type TypeAndVersion ¶

type TypeAndVersion struct {
	Type    ContractType   `json:"Type"`
	Version semver.Version `json:"Version"`
	Labels  LabelSet       `json:"Labels,omitempty"`
}

func MustTypeAndVersionFromString(s string) TypeAndVersion

func NewTypeAndVersion(t ContractType, v semver.Version) TypeAndVersion

func TypeAndVersionFromString(s string) (TypeAndVersion, error)

func (tv *TypeAndVersion) AddLabel(label string)

func (tv TypeAndVersion) Equal(other TypeAndVersion) bool

func (tv TypeAndVersion) String() string

type ViewState ¶ added in v0.0.6

type ViewState func(e Environment) (json.Marshaler, error)

ViewState produces a product specific JSON representation of the on and offchain state of the environment.

type ViewStateV2 ¶ added in v0.0.6

type ViewStateV2 func(e Environment, previousView json.Marshaler) (json.Marshaler, error)