api

Documentation

Overview

Package api implements the random beacon and time keeping APIs.

Index

• Constants
• Variables
• func RegisterService(server *grpc.Server, service Backend)
• type Backend
  • func NewBeaconClient(c *grpc.ClientConn) Backend
• type BeaconEvent
  • func (ev *BeaconEvent) EventKind() string
• type ConsensusParameters
• type EpochEvent
  • func (ev *EpochEvent) EventKind() string
• type EpochTime
  • func (e EpochTime) AbsDiff(other EpochTime) EpochTime
• type EpochTimeState
• type Genesis
  • func (g *Genesis) SanityCheck() error
• type InsecureParameters
• type PrevVRFState
• type SetableBackend
• type VRFBackend
• type VRFEvent
  • func (ev *VRFEvent) EventKind() string
  • func (ev *VRFEvent) FromState(state *VRFState)
• 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.

	// 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.

Variables

var (
	// MethodVRFProve is the method name for a VRF proof.
	MethodVRFProve = transaction.NewMethodName(ModuleName, "VRFProve", VRFProve{})

	// DefaultVRFGasCosts are the default gas costs for VRF operations.
	DefaultVRFGasCosts = transaction.Costs{
		GasOpVRFProve: 1000,
	}
)

var ErrBeaconNotAvailable = errors.New(ModuleName, 1, "beacon: random beacon not available")

ErrBeaconNotAvailable is the error returned when a beacon is not available for the requested height for any reason.

Functions

func RegisterService

func RegisterService(server *grpc.Server, service Backend)

RegisterService registers a new beacon service with the given gRPC server.

Types

type Backend

type Backend interface {
	// GetBaseEpoch returns the base epoch.
	GetBaseEpoch(context.Context) (EpochTime, error)

	// GetEpoch returns the epoch number at the specified block height.
	// Calling this method with height `consensus.HeightLatest`, should
	// return the epoch of latest known block.
	GetEpoch(context.Context, int64) (EpochTime, error)

	// GetFutureEpoch returns any future epoch that is currently scheduled
	// to occur at a specific height.
	//
	// Note that this may return a nil state in case no future epoch is
	// currently scheduled.
	GetFutureEpoch(context.Context, int64) (*EpochTimeState, error)

	// GetEpochBlock returns the block height at the start of the said
	// epoch.
	GetEpochBlock(context.Context, EpochTime) (int64, error)

	// WaitEpoch waits for a specific epoch.
	//
	// Note that an epoch is considered reached even if any epoch greater
	// than the one specified is reached (e.g., that the current epoch
	// is already in the future).
	WaitEpoch(ctx context.Context, epoch EpochTime) error

	// WatchEpochs returns a channel that produces a stream of messages
	// on epoch transitions.
	//
	// Upon subscription the current epoch is sent immediately.
	WatchEpochs(ctx context.Context) (<-chan EpochTime, pubsub.ClosableSubscription, error)

	// WatchLatestEpoch returns a channel that produces a stream of
	// messages on epoch transitions. If an epoch transition happens
	// before the previous epoch is read from the channel, the old
	// epochs are overwritten.
	//
	// Upon subscription the current epoch is sent immediately.
	WatchLatestEpoch(ctx context.Context) (<-chan EpochTime, pubsub.ClosableSubscription, error)

	// GetBeacon gets the beacon for the provided block height.
	// Calling this method with height `consensus.HeightLatest` should
	// return the beacon for the latest finalized block.
	GetBeacon(context.Context, int64) ([]byte, error)

	// StateToGenesis returns the genesis state at specified block height.
	StateToGenesis(context.Context, int64) (*Genesis, error)

	// ConsensusParameters returns the beacon consensus parameters.
	ConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, error)
}

Backend is a random beacon/time keeping implementation.

func NewBeaconClient

func NewBeaconClient(c *grpc.ClientConn) Backend

NewBeaconClient creates a new gRPC scheduler client service.

type BeaconEvent

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

BeaconEvent is the beacon event.

func (*BeaconEvent) EventKind

func (ev *BeaconEvent) EventKind() string

EventKind returns a string representation of this event's kind.

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"`

	// VRFParamenters 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.

func (*EpochEvent) EventKind

func (ev *EpochEvent) EventKind() string

EventKind returns a string representation of this event's kind.

type EpochTime

type EpochTime uint64

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

func (EpochTime) AbsDiff

func (e EpochTime) AbsDiff(other EpochTime) EpochTime

AbsDiff returns the absolute difference (in epochs) between two epochtimes.

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.

func (*Genesis) SanityCheck

func (g *Genesis) SanityCheck() error

SanityCheck does basic sanity checking on 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 SetableBackend

type SetableBackend interface {
	Backend

	// SetEpoch sets the current epoch.
	SetEpoch(context.Context, EpochTime) error
}

SetableBackend is a Backend that supports setting the current epoch.

type VRFBackend

type VRFBackend interface {
	Backend

	// GetVRFState gets the VRF state for the provided block height.
	GetVRFState(context.Context, int64) (*VRFState, error)

	// WatchLatestVRFEvent returns a channel that produces a stream
	// of messages on VRF events.  If an epoch transition happens
	// before the previous epoch event is read from the channel, old
	// events are overwritten.
	//
	// Upon subscription the current epoch event is sent immediately.
	WatchLatestVRFEvent(ctx context.Context) (<-chan *VRFEvent, *pubsub.Subscription, error)
}

VRFBackend is a Backend that is backed by VRFs.

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.

func (*VRFEvent) EventKind

func (ev *VRFEvent) EventKind() string

EventKind returns a string representation of this event's kind.

func (*VRFEvent) FromState

func (ev *VRFEvent) FromState(state *VRFState)

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.