prg

Documentation

Index

• Constants
• Variables
• func CollectorClusterLeaderSelection(clusterIndex uint) []byte
• func New(source []byte, customizer []byte, diversifier []byte) (random.Rand, error)

Constants

const RandomSourceLength = crypto.SignatureLenBLSBLS12381

Variables

var (
	// ConsensusLeaderSelection is the customizer for consensus leader selection
	ConsensusLeaderSelection = customizerFromIndices(0)
	// VerificationChunkAssignment is the customizer for verification chunk assignment
	VerificationChunkAssignment = customizerFromIndices(2)
	// ExecutionEnvironment is the customizer for Flow's transaction execution environment
	// (used for Cadence `random` function)
	ExecutionEnvironment = customizerFromIndices(1, 0)
	// ExecutionRandomSourceHistory is the customizer for Flow's transaction execution environment
	// (used for the source of randomness history core-contract)
	ExecutionRandomSourceHistory = customizerFromIndices(1, 1)
)

Functions

func CollectorClusterLeaderSelection

func CollectorClusterLeaderSelection(clusterIndex uint) []byte

CollectorClusterLeaderSelection returns the indices for the leader selection for the i-th collector cluster

func New

func New(source []byte, customizer []byte, diversifier []byte) (random.Rand, error)

New returns a PRG seeded by the input source of randomness [SoR]. The customizer is used to generate a task-specific PRG. A customizer can be any slice of 12 bytes or less. The diversifier is used to further diversify the PRGs beyond the customizer. A diversifier can be a slice of any length. If no diversification is needed, `diversifier` can be `nil`.

The function uses an extendable-output function (xof) to extract and expand the the input source, so that any source with enough entropy (at least 128 bits) can be used (no need to pre-hash). Current implementation generates a ChaCha20-based CSPRG.

How to use the function in Flow protocol: any sub-protocol that requires deterministic and distributed randomness should rely on the Flow native randomness provided by the Random Beacon. The beacon SoR for block B is part of the QC certifying B and can be extracted using the function `consensus/hotstuff/model.BeaconSignature(*flow.QuorumCertificate)`. It can also be extracted using the `state/protocol/snapshot.RandomSource()` function.

While the output is a distributed source of randomness, it should _not_ be used as random numbers itself. Instead, please use the function `New` to instantiate a PRG, for deterministic generation of random numbers or permutations (check the random.Rand interface).

Every Flow sub-protocol should use its own customizer to create an independent PRG. Use the list in "customizers.go" to add new values. The same sub-protocol can further create independent PRGs by using `diversifier`.