epochs

Documentation

Index

• Constants
• func CheckMachineAccountInfo(log zerolog.Logger, conf MachineAccountValidatorConfig, role flow.Role, ...) error
• func EncodeClusterAssignments(clusterAssignments flow.AssignmentList) []byte
• func WithoutBalanceChecks(conf *MachineAccountValidatorConfig)
• type BaseClient
  • func NewBaseClient(log zerolog.Logger, flowClient module.SDKClientWrapper, accountAddress string, ...) *BaseClient
  • func (c *BaseClient) GetAccount(ctx context.Context) (*sdk.Account, error)
  • func (c *BaseClient) SendTransaction(ctx context.Context, tx *sdk.Transaction) (sdk.Identifier, error)
  • func (c *BaseClient) WaitForSealed(ctx context.Context, txID sdk.Identifier, started time.Time) error
• type EpochConfig
  • func DefaultEpochConfig() EpochConfig
• type EpochLookup
  • func NewEpochLookup(state protocol.State) *EpochLookup
  • func (l *EpochLookup) EpochForView(view uint64) (epochCounter uint64, err error)
  • func (l *EpochLookup) EpochForViewWithFallback(view uint64) (uint64, error)
• type MachineAccountConfigValidator
  • func NewMachineAccountConfigValidator(log zerolog.Logger, flowClient *client.Client, role flow.Role, ...) (*MachineAccountConfigValidator, error)
  • func (validator *MachineAccountConfigValidator) Done() <-chan struct{}
  • func (validator *MachineAccountConfigValidator) Ready() <-chan struct{}
• type MachineAccountValidatorConfig
  • func DefaultMachineAccountValidatorConfig() MachineAccountValidatorConfig
• type MachineAccountValidatorConfigOption
• type MockQCContractClient
  • func NewMockQCContractClient(log zerolog.Logger) *MockQCContractClient
  • func (c *MockQCContractClient) SubmitVote(ctx context.Context, vote *model.Vote) error
  • func (c *MockQCContractClient) Voted(ctx context.Context) (bool, error)
• type QCContractClient
  • func NewQCContractClient(log zerolog.Logger, flowClient module.SDKClientWrapper, ...) *QCContractClient
  • func (c *QCContractClient) SubmitVote(ctx context.Context, vote *model.Vote) error
  • func (c *QCContractClient) Voted(ctx context.Context) (bool, error)
• type RootQCVoter
  • func NewRootQCVoter(log zerolog.Logger, me module.Local, signer hotstuff.Signer, ...) *RootQCVoter
  • func (voter *RootQCVoter) Vote(ctx context.Context, epoch protocol.Epoch) error

Constants

const (

	// TransactionSubmissionTimeout is the time after which we return an error.
	TransactionSubmissionTimeout = 5 * time.Minute

	// TransactionStatusRetryTimeout is the time after which the status of a
	// transaction is checked again
	TransactionStatusRetryTimeout = 1 * time.Second
)

Functions

func CheckMachineAccountInfo

func CheckMachineAccountInfo(
	log zerolog.Logger,
	conf MachineAccountValidatorConfig,
	role flow.Role,
	info bootstrap.NodeMachineAccountInfo,
	account *sdk.Account,
) error

CheckMachineAccountInfo checks a node machine account config, logging anything noteworthy but not critical, and returning an error if the machine account is not configured correctly, or the configuration cannot be checked.

This function checks most aspects of correct configuration EXCEPT for confirming that the account contains the relevant QCVoter or DKGParticipant resource. This is omitted because it is not possible to query private account info from a script.

func EncodeClusterAssignments

func EncodeClusterAssignments(clusterAssignments flow.AssignmentList) []byte

EncodeClusterAssignments encodes a slice of QuorumCertificates into an encoded transaction argument for the deployEpoch transaction used during execution state bootstrapping.

The resulting argument has type [{String: UInt64}] which represents a list of weight mappings for each cluster. The full Cluster struct is constructed within the transaction in Cadence for simplicity here.

func WithoutBalanceChecks

func WithoutBalanceChecks(conf *MachineAccountValidatorConfig)

WithoutBalanceChecks sets minimum balances to 0 to effectively disable minimum balance checks. This is useful for test networks where transaction fees are disabled.

Types

type BaseClient

type BaseClient struct {
	Log zerolog.Logger // default logger

	ContractAddress string                  // contract address
	FlowClient      module.SDKClientWrapper // flow access node client

	AccountAddress  sdk.Address      // account belonging to node interacting with the contract
	AccountKeyIndex uint             // account key index
	Signer          sdkcrypto.Signer // signer used to sign transactions
}

BaseClient represents the core fields and methods needed to create a client to a contract on the Flow Network.

func NewBaseClient

func NewBaseClient(
	log zerolog.Logger,
	flowClient module.SDKClientWrapper,
	accountAddress string,
	accountKeyIndex uint,
	signer sdkcrypto.Signer,
	contractAddress string,
) *BaseClient

NewBaseClient creates a instance of BaseClient

func (*BaseClient) GetAccount

func (c *BaseClient) GetAccount(ctx context.Context) (*sdk.Account, error)

func (*BaseClient) SendTransaction

func (c *BaseClient) SendTransaction(ctx context.Context, tx *sdk.Transaction) (sdk.Identifier, error)

SendTransaction submits a transaction to Flow. Requires transaction to be signed.

func (*BaseClient) WaitForSealed

func (c *BaseClient) WaitForSealed(ctx context.Context, txID sdk.Identifier, started time.Time) error

WaitForSealed waits for a transaction to be sealed

type EpochConfig

type EpochConfig struct {
	EpochTokenPayout             cadence.UFix64
	RewardCut                    cadence.UFix64
	CurrentEpochCounter          cadence.UInt64
	NumViewsInEpoch              cadence.UInt64
	NumViewsInStakingAuction     cadence.UInt64
	NumViewsInDKGPhase           cadence.UInt64
	NumCollectorClusters         cadence.UInt16
	FLOWsupplyIncreasePercentage cadence.UFix64
	RandomSource                 cadence.String
	CollectorClusters            flow.AssignmentList
	ClusterQCs                   []*flow.QuorumCertificate
	DKGPubKeys                   []crypto.PublicKey
}

EpochConfig is a placeholder for config values used to deploy the epochs smart-contract.

func DefaultEpochConfig

func DefaultEpochConfig() EpochConfig

DefaultEpochConfig returns an EpochConfig with default values used for testing.

type EpochLookup

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

EpochLookup implements the EpochLookup interface using protocol state to match views to epochs.

func NewEpochLookup

func NewEpochLookup(state protocol.State) *EpochLookup

NewEpochLookup instantiates a new EpochLookup

func (*EpochLookup) EpochForView

func (l *EpochLookup) EpochForView(view uint64) (epochCounter uint64, err error)

EpochForView returns the counter of the epoch that the view belongs to. The protocol.State#Epochs object exposes previous, current, and next epochs, which should be all we need. In general, we can't guarantee that a node will have access to epoch data beyond these three, so it is safe to throw an error for a query that doesn't fit within the view bounds of these three epochs (even if the node does happen to have that stored in the underlying storage) -- these queries indicate a bug in the querier.

func (*EpochLookup) EpochForViewWithFallback

func (l *EpochLookup) EpochForViewWithFallback(view uint64) (uint64, error)

EpochForViewWithFallback returns the counter of the epoch that the input view belongs to, with the same rules as EpochForView, except that this function will return the last committed epoch counter in perpetuity in the case that any epoch preparation. For example, if we are in epoch 10, and reach the final view of epoch 10 before epoch 11 has finished being setup, this function will return 10 even after the final view of epoch 10.

type MachineAccountConfigValidator

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

MachineAccountConfigValidator is used to validate that a machine account is configured correctly.

func NewMachineAccountConfigValidator

func NewMachineAccountConfigValidator(
	log zerolog.Logger,
	flowClient *client.Client,
	role flow.Role,
	info bootstrap.NodeMachineAccountInfo,
	opts ...MachineAccountValidatorConfigOption,
) (*MachineAccountConfigValidator, error)

func (*MachineAccountConfigValidator) Done

func (validator *MachineAccountConfigValidator) Done() <-chan struct{}

Done will cancel the context of the unit, which will end the validator goroutine, if it is still running.

func (*MachineAccountConfigValidator) Ready

func (validator *MachineAccountConfigValidator) Ready() <-chan struct{}

Ready will launch the validator function in a goroutine.

type MachineAccountValidatorConfig

type MachineAccountValidatorConfig struct {
	SoftMinBalanceLN cadence.UFix64
	HardMinBalanceLN cadence.UFix64
	SoftMinBalanceSN cadence.UFix64
	HardMinBalanceSN cadence.UFix64
}

MachineAccountValidatorConfig defines configuration options for MachineAccountConfigValidator.

func DefaultMachineAccountValidatorConfig

func DefaultMachineAccountValidatorConfig() MachineAccountValidatorConfig

type MachineAccountValidatorConfigOption

type MachineAccountValidatorConfigOption func(*MachineAccountValidatorConfig)

type MockQCContractClient

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

func NewMockQCContractClient

func NewMockQCContractClient(log zerolog.Logger) *MockQCContractClient

func (*MockQCContractClient) SubmitVote

func (c *MockQCContractClient) SubmitVote(ctx context.Context, vote *model.Vote) error

func (*MockQCContractClient) Voted

func (c *MockQCContractClient) Voted(ctx context.Context) (bool, error)

type QCContractClient

type QCContractClient struct {
	BaseClient
	// contains filtered or unexported fields
}

QCContractClient is a client to the Quorum Certificate contract. Allows the client to functionality to submit a vote and check if collection node has voted already.

func NewQCContractClient

func NewQCContractClient(
	log zerolog.Logger,
	flowClient module.SDKClientWrapper,
	flowClientANID flow.Identifier,
	nodeID flow.Identifier,
	accountAddress string,
	accountKeyIndex uint,
	qcContractAddress string,
	signer sdkcrypto.Signer,
) *QCContractClient

NewQCContractClient returns a new client to the Quorum Certificate contract

func (*QCContractClient) SubmitVote

func (c *QCContractClient) SubmitVote(ctx context.Context, vote *model.Vote) error

SubmitVote submits the given vote to the cluster QC aggregator smart contract. This function returns only once the transaction has been processed by the network. An error is returned if the transaction has failed and should be re-submitted.

func (*QCContractClient) Voted

func (c *QCContractClient) Voted(ctx context.Context) (bool, error)

Voted returns true if we have successfully submitted a vote to the cluster QC aggregator smart contract for the current epoch.

type RootQCVoter

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

RootQCVoter is responsible for generating and submitting votes for the root quorum certificate of the upcoming epoch for this node's cluster.

func NewRootQCVoter

func NewRootQCVoter(
	log zerolog.Logger,
	me module.Local,
	signer hotstuff.Signer,
	state protocol.State,
	contractClients []module.QCContractClient,
) *RootQCVoter

NewRootQCVoter returns a new root QC voter, configured for a particular epoch.

func (*RootQCVoter) Vote

func (voter *RootQCVoter) Vote(ctx context.Context, epoch protocol.Epoch) error

Vote handles the full procedure of generating a vote, submitting it to the epoch smart contract, and verifying submission. Returns an error only if there is a critical error that would make it impossible for the vote to be submitted. Otherwise, exits when the vote has been successfully submitted.

It is safe to run multiple times within a single setup phase.