api

Documentation

Overview

Package api implements the random beacon and time keeping APIs.

Index

• Constants
• type BeaconEvent
• type ConsensusParameters
• type EpochEvent
• type EpochTime
• type EpochTimeState
• type Genesis
• type InsecureParameters
• type PrevVRFState
• type VRFEvent
• type VRFParameters
• type VRFProve
• type VRFState

Constants

const (
	// ModuleName is a unique module name for the beacon module.
	ModuleName = "beacon"

	// BeaconSize is the size of the beacon in bytes.
	BeaconSize = 32

	// EpochInvalid is the placeholder invalid epoch.
	EpochInvalid EpochTime = 0xffffffffffffffff // ~50 quadrillion years away.

	// EpochMax is the end of time.
	EpochMax EpochTime = 0xfffffffffffffffe

	// BackendInsecure is the name of the insecure backend.
	BackendInsecure = "insecure"

	// BackendVRF is the name of the VRF backend.
	BackendVRF = "vrf"
)

const GasOpVRFProve transaction.Op = "vrf_prove"

GasOpVRFProve is the gas operation identifier for VRF proof submission.

Types

type BeaconEvent

type BeaconEvent struct {
	// Beacon is the new beacon value.
	Beacon []byte `json:"beacon,omitempty"`
}

BeaconEvent is the beacon event.

type ConsensusParameters

type ConsensusParameters struct {
	// Backend is the beacon backend.
	Backend string `json:"backend"`

	// DebugMockBackend is flag for enabling the mock epochtime backend.
	DebugMockBackend bool `json:"debug_mock_backend,omitempty"`

	// InsecureParameters are the beacon parameters for the insecure backend.
	InsecureParameters *InsecureParameters `json:"insecure_parameters,omitempty"`

	// VRFParameters are the beacon parameters for the VRF backend.
	VRFParameters *VRFParameters `json:"vrf_parameters,omitempty"`
}

ConsensusParameters are the beacon consensus parameters.

type EpochEvent

type EpochEvent struct {
	// Epoch is the new epoch.
	Epoch EpochTime `json:"epoch,omitempty"`
}

EpochEvent is the epoch event.

type EpochTime

type EpochTime = original.EpochTime

EpochTime is the number of intervals (epochs) since a fixed instant in time/block height (epoch date/height).

type EpochTimeState

type EpochTimeState struct {
	Epoch  EpochTime `json:"epoch"`
	Height int64     `json:"height"`
}

EpochTimeState is the epoch state.

type Genesis

type Genesis struct {
	// Base is the starting epoch.
	Base EpochTime `json:"base"`

	// Parameters are the beacon consensus parameters.
	Parameters ConsensusParameters `json:"params"`
}

Genesis is the genesis state.

type InsecureParameters

type InsecureParameters struct {
	// Interval is the epoch interval (in blocks).
	Interval int64 `json:"interval,omitempty"`
}

InsecureParameters are the beacon parameters for the insecure backend.

type PrevVRFState

type PrevVRFState struct {
	// Pi is the accumulated pi_string (VRF proof) outputs for the
	// previous epoch.
	Pi map[signature.PublicKey]*signature.Proof `json:"pi.omitempty"`

	// CanElectCommittees is true iff the previous alpha was generated
	// from high quality input such that committee elections are possible.
	CanElectCommittees bool `json:"can_elect,omitempty"`
}

PrevVRFState is the previous epoch's VRF state that is to be used for elections.

type VRFEvent

type VRFEvent struct {
	// Epoch is the epoch that Alpha is valid for.
	Epoch EpochTime `json:"epoch,omitempty"`

	// Alpha is the active VRF alpha_string input.
	Alpha []byte `json:"alpha,omitempty"`

	// SubmitAfter is the block height after which nodes may submit
	// VRF proofs for the current epoch.
	SubmitAfter int64 `json:"submit_after"`
}

VRFEvent is a VRF backend event.

type VRFParameters

type VRFParameters struct {
	// AlphaHighQualityThreshold is the minimum number of proofs (Pi)
	// that must be received for the next input (Alpha) to be considered
	// high quality.  If the VRF input is not high quality, runtimes will
	// be disabled for the next epoch.
	AlphaHighQualityThreshold uint64 `json:"alpha_hq_threshold,omitempty"`

	// Interval is the epoch interval (in blocks).
	Interval int64 `json:"interval,omitempty"`

	// ProofSubmissionDelay is the wait peroid in blocks after an epoch
	// transition that nodes MUST wait before attempting to submit a
	// VRF proof for the next epoch's elections.
	ProofSubmissionDelay int64 `json:"proof_delay,omitempty"`

	// GasCosts are the VRF proof gas costs.
	GasCosts transaction.Costs `json:"gas_costs,omitempty"`
}

VRFParameters are the beacon parameters for the VRF backend.

type VRFProve

type VRFProve struct {
	Epoch EpochTime `json:"epoch"`

	Pi []byte `json:"pi"`
}

VRFProve is a VRF proof transaction payload.

type VRFState

type VRFState struct {
	// Epoch is the epoch for which this alpha is valid.
	Epoch EpochTime `json:"epoch,omitempty"`

	// Alpha is the active VRF alpha_string input.
	Alpha []byte `json:"alpha,omitempty"`

	// Pi is the accumulated pi_string (VRF proof) outputs.
	Pi map[signature.PublicKey]*signature.Proof `json:"pi,omitempty"`

	// AlphaIsHighQuality is true iff the alpha was generated from
	// high quality input such that elections will be possible.
	AlphaIsHighQuality bool `json:"alpha_hq,omitempty"`

	// SubmitAfter is the block height after which nodes may submit
	// VRF proofs for the current epoch.
	SubmitAfter int64 `json:"submit_after,omitempty"`

	// PrevState is the VRF state from the previous epoch, for the
	// current epoch's elections.
	PrevState *PrevVRFState `json:"prev_state,omitempty"`
}

VRFState is the VRF backend state.