bootstrap

package
v0.42.2-experimental-b... Latest Latest
Warning

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

 Go to latest Published: Jul 31, 2025 License: AGPL-3.0 Imports: 10 Imported by: 16

Documentation

Overview

Package bootstrap defines canonical models and encoding for bootstrapping.

Index

Constants

View Source 
const (
	DefaultMachineAccountSignAlgo        = sdkcrypto.ECDSA_P256
	DefaultMachineAccountHashAlgo        = sdkcrypto.SHA3_256
	DefaultMachineAccountKeyIndex uint32 = 0
)

Variables

View Source 
var (
	// The Node ID file is used as a helper by the transit scripts
	FilenameNodeID = "node-id"
	PathNodeID     = filepath.Join(DirnamePublicBootstrap, FilenameNodeID)

	// execution state
	DirnameExecutionState = "execution-state"

	// public genesis information
	DirnamePublicBootstrap    = "public-root-information"
	PathInternalNodeInfosPub  = filepath.Join(DirnamePublicBootstrap, "node-internal-infos.pub.json")
	PathFinallist             = filepath.Join(DirnamePublicBootstrap, "finallist.pub.json")
	PathNodeInfosPub          = filepath.Join(DirnamePublicBootstrap, "node-infos.pub.json")
	PathPartnerNodeInfoPrefix = filepath.Join(DirnamePublicBootstrap, "node-info.pub.")
	PathNodeInfoPub           = filepath.Join(DirnamePublicBootstrap, "node-info.pub.%v.json") // %v will be replaced by NodeID
	DirnameRootBlockVotes     = filepath.Join(DirnamePublicBootstrap, "root-block-votes")
	FileNamePartnerWeights    = "partner-weights.json"

	PathRootBlockData                 = filepath.Join(DirnamePublicBootstrap, "root-block.json")
	PathIntermediaryBootstrappingData = filepath.Join(DirnamePublicBootstrap, "intermediary-bootstrapping-data.json")
	PathRootProtocolStateSnapshot     = filepath.Join(DirnamePublicBootstrap, "root-protocol-state-snapshot.json")

	FilenameWALRootCheckpoint = "root.checkpoint"
	PathRootCheckpoint        = filepath.Join(DirnameExecutionState, FilenameWALRootCheckpoint) // only available on an execution node

	// private genesis information
	DirPrivateRoot                   = "private-root-information"
	FilenameRandomBeaconPriv         = "random-beacon.priv.json"
	FilenameSecretsEncryptionKey     = "secretsdb-key"
	PathPrivNodeInfoPrefix           = "node-info.priv."
	FilenameRootBlockVotePrefix      = "root-block-vote."
	PathRootDKGData                  = filepath.Join(DirPrivateRoot, "root-dkg-data.priv.json")
	PathNodeInfoPriv                 = filepath.Join(DirPrivateRoot, "private-node-info_%v", "node-info.priv.json")                 // %v will be replaced by NodeID
	PathNodeMachineAccountPrivateKey = filepath.Join(DirPrivateRoot, "private-node-info_%v", "node-machine-account-key.priv.json")  // %v will be replaced by NodeID
	PathNodeMachineAccountInfoPriv   = filepath.Join(DirPrivateRoot, "private-node-info_%v", "node-machine-account-info.priv.json") // %v will be replaced by NodeID
	PathRandomBeaconPriv             = filepath.Join(DirPrivateRoot, "private-node-info_%v", FilenameRandomBeaconPriv)              // %v will be replaced by NodeID
	PathNodeRootBlockVote            = filepath.Join(DirPrivateRoot, "private-node-info_%v", "root-block-vote.json")
	FilenameRootBlockVote            = FilenameRootBlockVotePrefix + "%v.json"
	PathSecretsEncryptionKey         = filepath.Join(DirPrivateRoot, "private-node-info_%v", FilenameSecretsEncryptionKey) // %v will be replaced by NodeID
)

Canonical filenames/paths for bootstrapping files.

View Source 
var ErrMissingPrivateInfo = fmt.Errorf("can not access private information for a public node type")

ErrMissingPrivateInfo is returned when a method is called on NodeInfo that is only valid on instances containing private info.

Functions

func ToIdentityList 

func ToIdentityList(nodes []NodeInfo) flow.IdentityList

Types

type NodeConfig 

type NodeConfig struct {
	// Role is the flow role of the node (ex Collection, Consensus, ...)
	Role flow.Role

	// Address is the networking address of the node (IP:PORT), not to be
	// confused with the address of the flow account associated with the node's
	// machine account.
	Address string

	// Weight is the weight of the node
	Weight uint64
}

NodeConfig contains configuration information used as input to the bootstrap process.

func (*NodeConfig) UnmarshalJSON added in v0.25.0 

func (conf *NodeConfig) UnmarshalJSON(b []byte) error

type NodeInfo deprecated 

type NodeInfo struct {

	// NodeID is the unique identifier of the node in the network
	NodeID flow.Identifier

	// Role is the flow role of the node (collection, consensus, etc...)
	Role flow.Role

	// Address is the networking address of the node (IP:PORT), not to be
	// confused with the address of the flow account associated with the node's
	// machine account.
	Address string

	// Weight is the weight of the node
	Weight uint64
	// contains filtered or unexported fields
}

NodeInfo contains information for a node. This is used during the bootstrapping process to represent each node. When writing node information to disk, use `Public` or `Private` to obtain the appropriate canonical structure.

A NodeInfo instance can contain EITHER public keys OR private keys, not both. This can be ensured by using only using the provided constructors and NOT manually constructing an instance.

Deprecated: There is a concern about the current usage pattern of `NodeInfo“. There are no build-time enforcements of using `NodeInfo` for either the private or public usage. The struct can mistakenly be used for both cases. Other than introducing a confusing design, developers can accidentally confuse the private usage as a public one, for instance by writing the private info (including the private keys) into a file that is publicly shared. There is an ongoing attempt to replace `NodeInfo` by the explicit structures `NodeInfoPriv` and `NodeInfoPub` in https://github.com/onflow/flow-go/pull/7476. It is recommended to not use `NodeInfo` in new code development in order to limit the structure usage, and to use `NodeInfoPriv` and `NodeInfoPub` instead.

func FilterByRole 

func FilterByRole(nodes []NodeInfo, role flow.Role) []NodeInfo

func NewPrivateNodeInfo 

func NewPrivateNodeInfo(
	nodeID flow.Identifier,
	role flow.Role,
	addr string,
	weight uint64,
	networkKey crypto.PrivateKey,
	stakingKey crypto.PrivateKey,
) (NodeInfo, error)

func NewPublicNodeInfo 

func NewPublicNodeInfo(
	nodeID flow.Identifier,
	role flow.Role,
	addr string,
	weight uint64,
	networkKey crypto.PublicKey,
	stakingKey crypto.PublicKey,
	stakingPoP crypto.Signature,
) NodeInfo

func PrivateNodeInfoFromIdentity added in v0.20.0 

func PrivateNodeInfoFromIdentity(identity *flow.Identity, networkKey, stakingKey crypto.PrivateKey) (NodeInfo, error)

PrivateNodeInfoFromIdentity builds a NodeInfo from a flow Identity. WARNING: Nothing enforces that the output NodeInfo's keys are corresponding to the input Identity.

func Sort added in v0.17.0 

func Sort(nodes []NodeInfo, order flow.IdentityOrder[flow.Identity]) []NodeInfo

Sort sorts the NodeInfo list using the given ordering.

The sorted list is returned and the original list is untouched.

func (NodeInfo) Identity 

func (node NodeInfo) Identity() *flow.Identity

Identity returns the node info as a public Flow identity.

func (NodeInfo) NetworkPubKey 

func (node NodeInfo) NetworkPubKey() crypto.PublicKey

func (NodeInfo) PartnerPublic 

func (node NodeInfo) PartnerPublic() (PartnerNodeInfoPub, error)

PartnerPublic returns the public data for a partner node.

func (NodeInfo) Private 

func (node NodeInfo) Private() (NodeInfoPriv, error)

Private returns the canonical private encodable structure.

func (NodeInfo) PrivateKeys 

func (node NodeInfo) PrivateKeys() (*NodePrivateKeys, error)

func (NodeInfo) Public 

func (node NodeInfo) Public() (NodeInfoPub, error)

Public returns the canonical encodable structure holding the node's public information. It derives the networking and staking public keys, as well as the Proof of Possession (PoP) of the staking private key if they are not already provided in the NodeInfo.

It errors, if there is a problem generating the staking key PoP.

func (NodeInfo) StakingPoP added in v0.43.0 

func (node NodeInfo) StakingPoP() (crypto.Signature, error)

func (NodeInfo) StakingPubKey 

func (node NodeInfo) StakingPubKey() crypto.PublicKey

func (NodeInfo) Type 

func (node NodeInfo) Type() NodeInfoType

Type returns the type of the node info instance.

type NodeInfoPriv 

type NodeInfoPriv struct {
	Role           flow.Role
	Address        string
	NodeID         flow.Identifier
	NetworkPrivKey encodable.NetworkPrivKey
	StakingPrivKey encodable.StakingPrivKey
}

NodeInfoPriv defines the canonical structure for encoding private node info.

type NodeInfoPub 

type NodeInfoPub struct {
	Role          flow.Role
	Address       string
	NodeID        flow.Identifier
	Weight        uint64
	NetworkPubKey encodable.NetworkPubKey
	StakingPubKey encodable.StakingPubKey
	StakingPoP    encodable.StakingKeyPoP
}

NodeInfoPub defines the canonical structure for encoding public node info.

func ToPublicNodeInfoList 

func ToPublicNodeInfoList(nodes []NodeInfo) ([]NodeInfoPub, error)

func (*NodeInfoPub) Equals added in v0.33.1 

func (info *NodeInfoPub) Equals(other *NodeInfoPub) bool

func (*NodeInfoPub) UnmarshalJSON added in v0.25.0 

func (info *NodeInfoPub) UnmarshalJSON(b []byte) error

type NodeInfoType 

type NodeInfoType int

NodeInfoType enumerates the two different options for 

const (
	NodeInfoTypeInvalid NodeInfoType = iota
	NodeInfoTypePublic
	NodeInfoTypePrivate
)

type NodeMachineAccountInfo added in v0.20.0 

type NodeMachineAccountInfo struct {
	// Address is the flow address of the machine account, not to be confused
	// with the network address of the node.
	Address string

	// EncodedPrivateKey is the private key of the machine account
	EncodedPrivateKey []byte

	// KeyIndex is the index of the key in the associated machine account
	KeyIndex uint32

	// SigningAlgorithm is the algorithm used by the machine account along with
	// the above private key to create cryptographic signatures
	SigningAlgorithm sdkcrypto.SignatureAlgorithm

	// HashAlgorithm is the algorithm used for hashing
	HashAlgorithm sdkcrypto.HashAlgorithm
}

NodeMachineAccountInfo defines the structure for a bootstrapping file containing private information about the node's machine account. The machine account is used by the protocol software to interact with Flow as a client autonomously as needed, in particular to run the DKG and generate root cluster quorum certificates when preparing for an epoch.

func (NodeMachineAccountInfo) FlowAddress added in v0.22.0 

func (info NodeMachineAccountInfo) FlowAddress() flow.Address

func (NodeMachineAccountInfo) MustPrivateKey added in v0.22.0 

func (info NodeMachineAccountInfo) MustPrivateKey() crypto.PrivateKey

func (NodeMachineAccountInfo) PrivateKey added in v0.22.0 

func (info NodeMachineAccountInfo) PrivateKey() (crypto.PrivateKey, error)

func (NodeMachineAccountInfo) SDKAddress added in v0.22.0 

func (info NodeMachineAccountInfo) SDKAddress() sdk.Address

type NodeMachineAccountKey added in v0.20.0 

type NodeMachineAccountKey struct {
	PrivateKey encodable.MachineAccountPrivKey
}

NodeMachineAccountKey contains the private configration need to construct a NodeMachineAccountInfo object. This is used as an intemediary by the bootstrap scripts for storing the private key before generating a NodeMachineAccountInfo.

type NodePrivateKeys 

type NodePrivateKeys struct {
	StakingKey crypto.PrivateKey
	NetworkKey crypto.PrivateKey
}

NodePrivateKeys is a wrapper for the private keys for a node, comprising all sensitive information for a node.

type PartnerNodeInfoPub 

type PartnerNodeInfoPub struct {
	Role          flow.Role
	Address       string
	NodeID        flow.Identifier
	NetworkPubKey encodable.NetworkPubKey
	StakingPubKey encodable.StakingPubKey
	StakingPoP    []byte
}

PartnerNodeInfoPub represents public information about a partner/external node. It is identical to NodeInfoPub, but without weight information, as this is determined externally to the process that generates this information.

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.