deployment

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2025 License: MIT Imports: 39 Imported by: 186

Documentation

Index

Constants

View Source 
const (
	// Default retry configuration for RPC calls
	RPCDefaultRetryAttempts = 10
	RPCDefaultRetryDelay    = 1000 * time.Millisecond

	// Default retry configuration for dialing RPC endpoints
	RPCDefaultDialRetryAttempts = 10
	RPCDefaultDialRetryDelay    = 1000 * time.Millisecond
)
View Source 
const (
	ProgramIDPrefix                 = "Program Id: "
	BufferIDPrefix                  = "Buffer: "
	SolDefaultCommitment            = rpc.CommitmentConfirmed
	RouterProgramName               = "ccip_router"
	OffRampProgramName              = "ccip_offramp"
	FeeQuoterProgramName            = "fee_quoter"
	BurnMintTokenPoolProgramName    = "burnmint_token_pool"
	LockReleaseTokenPoolProgramName = "lockrelease_token_pool"
	AccessControllerProgramName     = "access_controller"
	TimelockProgramName             = "timelock"
	McmProgramName                  = "mcm"
	RMNRemoteProgramName            = "rmn_remote"
	ReceiverProgramName             = "test_ccip_receiver"
)

Variables

View Source 
var (
	ErrInvalidChainSelector = errors.New("invalid chain selector")
	ErrInvalidAddress       = errors.New("invalid address")
	ErrChainNotFound        = errors.New("chain not found")
)
View Source 
var (
	ErrInvalidConfig      = errors.New("invalid changeset config")
	ErrInvalidEnvironment = errors.New("invalid environment")
)

Functions

func AddressBookContains 

func AddressBookContains(ab AddressBook, chain uint64, addrToFind string) (bool, error)

func ChainInfo added in v0.0.6 

func ChainInfo(cs uint64) (chain_selectors.ChainDetails, error)

func EnsureDeduped 

func EnsureDeduped(addrs map[string]TypeAndVersion, bundle []TypeAndVersion) (bool, error)

EnsureDeduped ensures that each contract in the bundle only appears once in the address map. It returns an error if there are more than one instance of a contract. Returns true if every value in the bundle is found once, false otherwise.

func GetSolanaProgramBytes added in v0.0.6 

func GetSolanaProgramBytes() map[string]int

https://docs.google.com/document/d/1Fk76lOeyS2z2X6MokaNX_QTMFAn5wvSZvNXJluuNV1E/edit?tab=t.0#heading=h.uij286zaarkz https://docs.google.com/document/d/1nCNuam0ljOHiOW0DUeiZf4ntHf_1Bw94Zi7ThPGoKR4/edit?tab=t.0#heading=h.hju45z55bnqd

func MaybeDataErr 

func MaybeDataErr(err error) error

func MergeChangesetOutput added in v0.0.6 

func MergeChangesetOutput(env Environment, dest *ChangesetOutput, src ChangesetOutput) error

MergeChangesetOutput merges the source ChangesetOutput into the destination ChangesetOutput. It is useful to combine multiple ChangesetOutput objects into one to create one consolidated changeset from multiple granular changesets. Ensure to run proposalutils.AggregateProposals at the end of consolidated changeset to ensure the proposals are merged correctly.

func SearchAddressBook 

func SearchAddressBook(ab AddressBook, chain uint64, typ ContractType) (string, error)

SearchAddressBook search an address book for a given chain and contract type and return the first matching address.

Types

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 

func NewMemoryAddressBook() *AddressBookMap

TODO: Maybe could add an environment argument which would ensure only mainnet/testnet chain selectors are used for further safety?

func NewMemoryAddressBookFromMap 

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

func (*AddressBookMap) Addresses 

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

func (*AddressBookMap) AddressesForChain 

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

func (*AddressBookMap) Merge 

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

Merge will merge the addresses from another address book into this one. It will error on any existing addresses.

func (*AddressBookMap) Remove 

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

Remove removes the address book addresses specified via the argument from the AddressBookMap. Errors if all the addresses in the given address book are not contained in the AddressBookMap.

func (*AddressBookMap) Save 

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

Save will save an address for a given chain selector. It will error if there is a conflicting existing address. thread safety version of the save method

type AddressesByChain 

type AddressesByChain map[uint64]map[string]TypeAndVersion

type AptosChain added in v0.0.6 

type AptosChain struct {
	Selector       uint64
	Client         aptos.AptosRpcClient
	DeployerSigner aptos.TransactionSigner
	URL            string

	Confirm func(txHash string, opts ...any) error
}

AptosChain represents an Aptos chain.

type Chain added in v0.0.6 

type Chain struct {
	// Selectors used as canonical chain identifier.
	Selector uint64
	Client   OnchainClient
	// Note the Sign function can be abstract supporting a variety of key storage mechanisms (e.g. KMS etc).
	DeployerKey *bind.TransactOpts
	Confirm     func(tx *types.Transaction) (uint64, error)
	// Users are a set of keys that can be used to interact with the chain.
	// These are distinct from the deployer key.
	Users []*bind.TransactOpts
}

Chain represents an EVM chain.

func (Chain) Name added in v0.0.6 

func (c Chain) Name() string

func (Chain) String added in v0.0.6 

func (c Chain) String() string

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 added in v0.0.6 

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

CreateChangeSet creates a ChangeSetV2 from an existing execution function (or an older ChangeSet) and a precondition verification function.

func CreateLegacyChangeSet added in v0.0.6 

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
	// Deprecated: Prefer MCMSTimelockProposals instead, will be removed in future
	Proposals                  []timelock.MCMSWithTimelockProposal
	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[datastore.DefaultMetadata, datastore.DefaultMetadata]
	// 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 ContractType 

type ContractType string

ContractType is a simple string type for identifying contract types.

func (ContractType) String 

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[
		datastore.DefaultMetadata,
		datastore.DefaultMetadata,
	]
	Chains      map[uint64]Chain
	SolChains   map[uint64]SolChain
	AptosChains map[uint64]AptosChain
	NodeIDs     []string
	Offchain    OffchainClient
	GetContext  func() context.Context
	OCRSecrets  OCRSecrets
	// OperationsBundle contains dependencies required by the operations API.
	OperationsBundle operations.Bundle
}

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 added in v0.0.6 

func NewEnvironment(
	name string,
	logger logger.Logger,
	existingAddrs AddressBook,
	dataStore datastore.DataStore[
		datastore.DefaultMetadata,
		datastore.DefaultMetadata,
	],
	chains map[uint64]Chain,
	solChains map[uint64]SolChain,
	aptosChains map[uint64]AptosChain,
	nodeIDs []string,
	offchain OffchainClient,
	ctx func() context.Context,
	secrets OCRSecrets,
) *Environment

func (Environment) AllChainSelectors added in v0.0.6 

func (e Environment) AllChainSelectors() []uint64

func (Environment) AllChainSelectorsAllFamilies added in v0.0.6 

func (e Environment) AllChainSelectorsAllFamilies() []uint64

func (Environment) AllChainSelectorsAllFamiliesExcluding added in v0.0.6 

func (e Environment) AllChainSelectorsAllFamiliesExcluding(excluding []uint64) []uint64

func (Environment) AllChainSelectorsAptos added in v0.0.6 

func (e Environment) AllChainSelectorsAptos() []uint64

func (Environment) AllChainSelectorsExcluding added in v0.0.6 

func (e Environment) AllChainSelectorsExcluding(excluding []uint64) []uint64

func (Environment) AllChainSelectorsSolana added in v0.0.6 

func (e Environment) AllChainSelectorsSolana() []uint64

func (Environment) AllDeployerKeys added in v0.0.6 

func (e Environment) AllDeployerKeys() []common.Address

func (Environment) Clone added in v0.0.6 

func (e Environment) Clone() Environment

Clone creates a copy of the environment with a new reference to the address book.

type LabelSet 

type LabelSet map[string]struct{}

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

func NewLabelSet 

func NewLabelSet(labels ...string) LabelSet

NewLabelSet initializes a new LabelSet with any number of labels.

func (LabelSet) Add 

func (ls LabelSet) Add(labels string)

Add inserts a labels into the set.

func (LabelSet) Contains 

func (ls LabelSet) Contains(labels string) bool

Contains checks if the set contains the given labels.

func (LabelSet) Equal 

func (ls LabelSet) Equal(other LabelSet) bool

Equal checks if two LabelSets are equal.

func (LabelSet) IsEmpty 

func (ls LabelSet) IsEmpty() bool

func (LabelSet) List 

func (ls LabelSet) List() []string

List returns the labels as a sorted slice of strings.

func (LabelSet) Remove 

func (ls LabelSet) Remove(labels string)

Remove deletes a labels from the set, if it exists.

func (LabelSet) String 

func (ls LabelSet) String() string

String returns the labels as a sorted, space-separated string. It implements the fmt.Stringer interface.

type MultiClient 

type MultiClient struct {
	*ethclient.Client
	Backups     []*ethclient.Client
	RetryConfig RetryConfig
	// contains filtered or unexported fields
}

func NewMultiClient 

func NewMultiClient(lggr logger.Logger, rpcsCfg RPCConfig, opts ...func(client *MultiClient)) (*MultiClient, error)

func (*MultiClient) CallContract 

func (mc *MultiClient) CallContract(ctx context.Context, msg ethereum.CallMsg, blockNumber *big.Int) ([]byte, error)

func (*MultiClient) CallContractAtHash 

func (mc *MultiClient) CallContractAtHash(ctx context.Context, msg ethereum.CallMsg, blockHash common.Hash) ([]byte, error)

func (*MultiClient) CodeAt 

func (mc *MultiClient) CodeAt(ctx context.Context, account common.Address, blockNumber *big.Int) ([]byte, error)

func (*MultiClient) CodeAtHash 

func (mc *MultiClient) CodeAtHash(ctx context.Context, account common.Address, blockHash common.Hash) ([]byte, error)

func (*MultiClient) NonceAt 

func (mc *MultiClient) NonceAt(ctx context.Context, account common.Address, block *big.Int) (uint64, error)

func (*MultiClient) NonceAtHash 

func (mc *MultiClient) NonceAtHash(ctx context.Context, account common.Address, blockHash common.Hash) (uint64, error)

func (*MultiClient) SendTransaction 

func (mc *MultiClient) SendTransaction(ctx context.Context, tx *types.Transaction) error

func (*MultiClient) WaitMined 

func (mc *MultiClient) WaitMined(ctx context.Context, tx *types.Transaction) (*types.Receipt, error)

type OCRSecrets added in v0.0.5 

type OCRSecrets struct {
	SharedSecret [16]byte
	EphemeralSk  [32]byte
}

OCRSecrets are used to disseminate a shared secret to OCR nodes through the blockchain where OCR configuration is stored. Its a low value secret used to derive transmission order etc. They are extracted here such that they can common across signers when multiple signers are signing the same OCR config.

func XXXGenerateTestOCRSecrets added in v0.0.5 

func XXXGenerateTestOCRSecrets() OCRSecrets

func (OCRSecrets) IsEmpty added in v0.0.5 

func (s OCRSecrets) IsEmpty() bool

type OffchainClient added in v0.0.5 

type OffchainClient interface {
	jobv1.JobServiceClient
	nodev1.NodeServiceClient
	csav1.CSAServiceClient
}

OffchainClient interacts with the job-distributor which is a family agnostic interface for performing DON operations.

type OnchainClient 

type OnchainClient interface {
	bind.ContractBackend
	bind.DeployBackend
	BalanceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (*big.Int, error)
	NonceAt(ctx context.Context, account common.Address, blockNumber *big.Int) (uint64, error)
}

OnchainClient is an EVM chain client. For EVM specifically we can use existing geth interface to abstract chain clients.

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 RPC 

type RPC struct {
	Name               string
	WSURL              string
	HTTPURL            string
	PreferredURLScheme URLSchemePreference
}

func (RPC) ToEndpoint 

func (r RPC) ToEndpoint() (string, error)

ToEndpoint returns the correct endpoint based on the preferred URL scheme If the preferred URL scheme is not set, it will return the WS URL If the preferred URL scheme is set to WS, it will return the WS URL If the preferred URL scheme is set to HTTP, it will return the HTTP URL

type RPCConfig 

type RPCConfig struct {
	ChainSelector uint64
	RPCs          []RPC
}

RPCConfig is a configuration for a chain. It contains a chain selector and a list of RPCs

type RetryConfig 

type RetryConfig struct {
	Attempts uint
	Delay    time.Duration
}

type SolChain added in v0.0.6 

type SolChain struct {
	// Selectors used as canonical chain identifier.
	Selector uint64
	// RPC client
	Client *solRpc.Client
	URL    string
	WSURL  string
	// TODO: raw private key for now, need to replace with a more secure way
	DeployerKey *solana.PrivateKey
	Confirm     func(instructions []solana.Instruction, opts ...solCommonUtil.TxModifier) error

	// deploy uses the solana CLI which needs a keyfile
	KeypairPath  string
	ProgramsPath string
}

SolChain represents a Solana chain.

func (SolChain) DeployProgram added in v0.0.6 

func (c SolChain) DeployProgram(logger logger.Logger, programName string, isUpgrade bool) (string, error)

func (SolChain) GetAccountDataBorshInto added in v0.0.6 

func (c SolChain) GetAccountDataBorshInto(ctx context.Context, pubkey solana.PublicKey, accountState interface{}) error

func (SolChain) Name added in v0.0.6 

func (c SolChain) Name() string

func (SolChain) String added in v0.0.6 

func (c SolChain) String() string

type TypeAndVersion 

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

func MustTypeAndVersionFromString 

func MustTypeAndVersionFromString(s string) TypeAndVersion

func NewTypeAndVersion 

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

func TypeAndVersionFromString 

func TypeAndVersionFromString(s string) (TypeAndVersion, error)

Note this will become useful for validation. When we want to assert an onchain call to typeAndVersion yields whats expected.

func (*TypeAndVersion) AddLabel 

func (tv *TypeAndVersion) AddLabel(label string)

AddLabel adds a string to the LabelSet in the TypeAndVersion.

func (TypeAndVersion) Equal 

func (tv TypeAndVersion) Equal(other TypeAndVersion) bool

func (TypeAndVersion) String 

func (tv TypeAndVersion) String() string

type URLSchemePreference 

type URLSchemePreference int
const (
	URLSchemePreferenceNone URLSchemePreference = iota
	URLSchemePreferenceWS
	URLSchemePreferenceHTTP
)

func URLSchemePreferenceFromString 

func URLSchemePreferenceFromString(s string) (URLSchemePreference, error)

func (*URLSchemePreference) UnmarshalText 

func (u *URLSchemePreference) UnmarshalText(text []byte) error

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)

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.