run

Documentation

Overview

contains reusable logic that does not know about a CLI. Instead of exiting a program, functions here will return errors.

Index

• func ConstructRootQCsForClusters(log zerolog.Logger, clusterList flow.ClusterList, ...) []*flow.QuorumCertificate
• func GenerateClusterRootQC(signers []bootstrap.NodeInfo, allCommitteeMembers flow.IdentitySkeletonList, ...) (*flow.QuorumCertificate, error)
• func GenerateExecutionState(dbDir string, accountKey flow.AccountPublicKey, chain flow.Chain, ...) (flow.StateCommitment, error)
• func GenerateRecoverEpochTxArgs(log zerolog.Logger, internalNodePrivInfoDir string, nodeConfigJson string, ...) ([]cadence.Value, error)
• func GenerateRecoverTxArgsWithDKG(log zerolog.Logger, internalNodes []bootstrap.NodeInfo, collectionClusters int, ...) ([]cadence.Value, error)
• func GenerateRootBlockVotes(block *flow.Block, participantData *ParticipantData) ([]*model.Vote, error)
• func GenerateRootClusterBlocks(epoch uint64, clusters flow.ClusterList) []*cluster.Block
• func GenerateRootHeader(chainID flow.ChainID, parentID flow.Identifier, height uint64, ...) *flow.Header
• func GenerateRootQC(block *flow.Block, votes []*model.Vote, participantData *ParticipantData, ...) (*flow.QuorumCertificate, []error, error)
• func GenerateRootResult(block *flow.Block, commit flow.StateCommitment, epochSetup *flow.EpochSetup, ...) *flow.ExecutionResult
• func GenerateRootSeal(result *flow.ExecutionResult) (*flow.Seal, error)
• type Participant
• type ParticipantData
  • func GenerateQCParticipantData(allNodes, internalNodes []bootstrap.NodeInfo, dkgData dkg.ThresholdKeySet) (*ParticipantData, error)
  • func (pd *ParticipantData) DKGData() (indexMap flow.DKGIndexMap, keyShares []crypto.PublicKey)
  • func (pd *ParticipantData) Identities() flow.IdentityList

Functions

func ConstructRootQCsForClusters

func ConstructRootQCsForClusters(log zerolog.Logger, clusterList flow.ClusterList, nodeInfos []bootstrap.NodeInfo, clusterBlocks []*cluster.Block) []*flow.QuorumCertificate

ConstructRootQCsForClusters constructs a root QC for each cluster in the list. Args: - log: the logger instance. - clusterList: list of clusters - nodeInfos: list of NodeInfos (must contain all internal nodes) - clusterBlocks: list of root blocks (one for each cluster) Returns: - flow.AssignmentList: the generated assignment list. - flow.ClusterList: the generate collection cluster list.

func GenerateClusterRootQC

func GenerateClusterRootQC(signers []bootstrap.NodeInfo, allCommitteeMembers flow.IdentitySkeletonList, clusterBlock *cluster.Block) (*flow.QuorumCertificate, error)

GenerateClusterRootQC creates votes and generates a QC based on participant data

func GenerateExecutionState

func GenerateExecutionState(
	dbDir string,
	accountKey flow.AccountPublicKey,
	chain flow.Chain,
	bootstrapOptions ...fvm.BootstrapProcedureOption,
) (flow.StateCommitment, error)

func GenerateRecoverEpochTxArgs

func GenerateRecoverEpochTxArgs(log zerolog.Logger,
	internalNodePrivInfoDir string,
	nodeConfigJson string,
	collectionClusters int,
	recoveryEpochCounter uint64,
	rootChainID flow.ChainID,
	numViewsInStakingAuction uint64,
	numViewsInEpoch uint64,
	recoveryEpochTargetDuration uint64,
	unsafeAllowOverWrite bool,
	excludeNodeIDs flow.IdentifierList,
	includeNodeIDs flow.IdentifierList,
	snapshot *inmem.Snapshot,
) ([]cadence.Value, error)

GenerateRecoverEpochTxArgs generates the required transaction arguments for the `recoverEpoch` transaction. No errors are expected during normal operation.

func GenerateRecoverTxArgsWithDKG

func GenerateRecoverTxArgsWithDKG(log zerolog.Logger,
	internalNodes []bootstrap.NodeInfo,
	collectionClusters int,
	recoveryEpochCounter uint64,
	rootChainID flow.ChainID,
	numViewsInStakingAuction uint64,
	numViewsInEpoch uint64,
	recoveryEpochTargetDuration uint64,
	unsafeAllowOverWrite bool,
	dkgIndexMap flow.DKGIndexMap,
	dkgParticipantKeys []crypto.PublicKey,
	dkgGroupKey crypto.PublicKey,
	excludeNodeIDs flow.IdentifierList,
	includeNodeIDs flow.IdentifierList,
	snapshot *inmem.Snapshot,
) ([]cadence.Value, error)

GenerateRecoverTxArgsWithDKG generates the required transaction arguments for the `recoverEpoch` transaction. No errors are expected during normal operation.

func GenerateRootBlockVotes

func GenerateRootBlockVotes(block *flow.Block, participantData *ParticipantData) ([]*model.Vote, error)

GenerateRootBlockVotes generates votes for root block based on participantData

func GenerateRootClusterBlocks

func GenerateRootClusterBlocks(epoch uint64, clusters flow.ClusterList) []*cluster.Block

func GenerateRootHeader

func GenerateRootHeader(chainID flow.ChainID, parentID flow.Identifier, height uint64, timestamp time.Time) *flow.Header

func GenerateRootQC

func GenerateRootQC(block *flow.Block, votes []*model.Vote, participantData *ParticipantData, identities flow.IdentityList) (
	*flow.QuorumCertificate,
	[]error,
	error,
)

GenerateRootQC generates QC for root block, caller needs to provide votes for root QC and participantData to build the QC. NOTE: at the moment, we require private keys for one node because we we re-using the full business logic, which assumes that only consensus participants construct QCs, which also have produce votes.

TODO: modularize QC construction code (and code to verify QC) to be instantiated without needing private keys. It returns (qc, nil, nil) if a QC can be constructed with enough votes, and there is no invalid votes It returns (qc, invalidVotes, nil) if there are some invalid votes, but a QC can still be constructed It returns (nil, invalidVotes, err) if no qc can be constructed with not enough votes or running any any exception

func GenerateRootResult

func GenerateRootResult(
	block *flow.Block,
	commit flow.StateCommitment,
	epochSetup *flow.EpochSetup,
	epochCommit *flow.EpochCommit,
) *flow.ExecutionResult

func GenerateRootSeal

func GenerateRootSeal(result *flow.ExecutionResult) (*flow.Seal, error)

Types

type Participant

type Participant struct {
	bootstrap.NodeInfo
	RandomBeaconPrivKey crypto.PrivateKey
}

type ParticipantData

type ParticipantData struct {
	// Participants of the signing process: only members of the consensus committee can vote, i.e. contribute to the random
	// beacon (formally Participants ⊊ 𝒞). However, we allow for consensus committee members that are _not_ part of the DKG
	// committee 𝒟 (formally ∅ ≠ Participants \ 𝒟).
	Participants []Participant

	DKGCommittee map[flow.Identifier]flow.DKGParticipant // DKG committee 𝒟 (to set up the random beacon)
	DKGGroupKey  crypto.PublicKey                        // group key for the DKG committee 𝒟
}

ParticipantData represents a subset of all consensus participants that contribute to some signing process (at the moment, we only use it for the contributors for the root QC). For mainnet, this a *strict subset* of all consensus participants:

• In an early step during the bootstrapping process, every node operator locally generates votes for the root block from the nodes they operate. During the vote-generation step, (see function `constructRootVotes`), `Participants` represents only the operator's own nodes (generally a small minority of the entire consensus committee).
• During a subsequent step of the bootstrapping process, the Flow Foundation collects a supermajority of votes from the consensus participants and constructs the root QC (see function `constructRootQC`). Here, `Participants` is only populated with the information of the internal nodes that the Flow Foundation runs, but not used.

Furthermore, ParticipantData contains auxiliary data about the DKG to set up the random beacon. Note that the consensus committee 𝒞 and the DKG committee 𝒟 are generally _not_ identical. We explicitly want to support that _either_ set can have nodes that are not in the other set (formally 𝒟 \ 𝒞 ≠ ∅ and 𝒞 \ 𝒟 ≠ ∅). ParticipantData has no direct representation of the consensus committee 𝒞.

func GenerateQCParticipantData

func GenerateQCParticipantData(allNodes, internalNodes []bootstrap.NodeInfo, dkgData dkg.ThresholdKeySet) (*ParticipantData, error)

GenerateQCParticipantData assembles the private information of a subset (`internalNodes`) of the consensus committee (`allNodes`).

LIMITATION: this function only supports the 'trusted dealer' model, where for the consensus committee (`allNodes`) a trusted dealer generated the threshold-signature key (`dkgData` containing key shares and group key). Therefore, `allNodes` must be in the same order that was used when running the DKG.

func (*ParticipantData) DKGData

func (pd *ParticipantData) DKGData() (indexMap flow.DKGIndexMap, keyShares []crypto.PublicKey)

DKGData links nodes to their respective public DKG values. We cover the DKG committee 𝒟, meaning all nodes that were authorized to participate in the DKG (even if they did not participate or were unsuccessful). Specifically, the function returns:

• indexMap: a bijective mapping from the node IDs of the DKG committee to {0, 1, …, n-1}, with n = |𝒟| the size of the DKG committee 𝒟. In a nutshell, for a nodeID `d`, integer value i := DKGIndexMap[d] denotes the index, by which the low-level cryptographic DKG protocol references the participant. For details, please see the documentation of flow.DKGIndexMap.
• keyShares: holds the public key share for every member of the DKG committee 𝒟 (irrespective of successful participation). For a member of the DKG committee with nodeID `d`, the respective public key share is keyShares[DKGIndexMap[d]].

CAUTION: the returned DKG data may include identifiers for nodes which do not exist in the consensus committee and may NOT include entries for all nodes in the consensus committee.

func (*ParticipantData) Identities

func (pd *ParticipantData) Identities() flow.IdentityList