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 ConsensusParameters
• type EpochTime
  • func (e EpochTime) AbsDiff(other EpochTime) EpochTime
• type EpochTimeState
• type Genesis
  • func (g *Genesis) SanityCheck() error
• type InsecureParameters
• type PVSSBackend
• type PVSSCommit
  • func (pc PVSSCommit) MethodMetadata() transaction.MethodMetadata
• type PVSSEvent
  • func (ev *PVSSEvent) FromState(state *PVSSState)
• type PVSSParameters
• type PVSSReveal
  • func (pr PVSSReveal) MethodMetadata() transaction.MethodMetadata
• type PVSSState
• type RoundState
  • func (s RoundState) String() string
• type SetableBackend

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"

	// BackendPVSS is the name of the PVSS backend.
	BackendPVSS = "pvss"
)

Variables

var (
	// MethodPVSSCommit is the method name for a PVSS commitment.
	MethodPVSSCommit = transaction.NewMethodName(ModuleName, "PVSSCommit", PVSSCommit{})

	// MethodPVSSReveal is the method name for a PVSS reveal.
	MethodPVSSReveal = transaction.NewMethodName(ModuleName, "PVSSReveal", PVSSReveal{})
)

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

	// DebugDeterministic is true iff the output should be deterministic.
	DebugDeterministic bool `json:"debug_deterministic,omitempty"`

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

	// PVSSParameters are the beacon parameters for the PVSS backend.
	PVSSParameters *PVSSParameters `json:"pvss_parameters,omitempty"`
}

ConsensusParameters are the beacon consensus parameters.

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 PVSSBackend

type PVSSBackend interface {
	Backend

	// GetPVSSState gets the PVSS beacon round state for the
	// provided block height.  Calling this method with height
	// `consensus.HeightLatest` should return the beacon for
	// the latest finalized block.
	GetPVSSState(context.Context, int64) (*PVSSState, error)

	// WatchLatestPVSSEvent returns a channel that produces a
	// stream of mesages on PVSS round events.  If a round
	// transition happens before the previous round event is read
	// from the channel, old events are overwritten.
	//
	// Upon subscription the current round event is sent immediately.
	WatchLatestPVSSEvent() (<-chan *PVSSEvent, *pubsub.Subscription)
}

PVSSBackend is a Backend that is backed by PVSS.

type PVSSCommit

type PVSSCommit struct {
	Epoch EpochTime `json:"epoch"`
	Round uint64    `json:"round"`

	Commit *pvss.Commit `json:"commit,omitempty"`
}

PVSSCommit is a PVSS commitment transaction payload.

func (PVSSCommit) MethodMetadata

func (pc PVSSCommit) MethodMetadata() transaction.MethodMetadata

Implements transaction.MethodMetadataProvider.

type PVSSEvent

type PVSSEvent struct {
	Height int64 `json:"height,omitempty"`

	Epoch EpochTime  `json:"epoch,omitempty"`
	Round uint64     `json:"round,omitempty"`
	State RoundState `json:"state,omitempty"`

	Participants []signature.PublicKey `json:"participants,omitempty"`
}

PVSSEvent is a PVSS backend event.

func (*PVSSEvent) FromState

func (ev *PVSSEvent) FromState(state *PVSSState)

type PVSSParameters

type PVSSParameters struct {
	Participants uint32 `json:"participants"`
	Threshold    uint32 `json:"threshold"`

	CommitInterval  int64 `json:"commit_interval"`
	RevealInterval  int64 `json:"reveal_interval"`
	TransitionDelay int64 `json:"transition_delay"`

	DebugForcedParticipants []signature.PublicKey `json:"debug_forced_participants,omitempty"`
}

PVSSParameters are the beacon parameters for the PVSS backend.

type PVSSReveal

type PVSSReveal struct {
	Epoch EpochTime `json:"epoch"`
	Round uint64    `json:"round"`

	Reveal *pvss.Reveal `json:"reveal,omitempty"`
}

PVSSReveal is a PVSS reveal transaction payload.

func (PVSSReveal) MethodMetadata

func (pr PVSSReveal) MethodMetadata() transaction.MethodMetadata

Implements transaction.MethodMetadataProvider.

type PVSSState

type PVSSState struct {
	Height int64 `json:"height,omitempty"`

	Epoch EpochTime  `json:"epoch,omitempty"`
	Round uint64     `json:"round,omitempty"`
	State RoundState `json:"state,omitempty"`

	Instance     *pvss.Instance        `json:"instance,omitempty"`
	Participants []signature.PublicKey `json:"participants,omitempty"`
	Entropy      []byte                `json:"entropy,omitempty"`

	BadParticipants map[signature.PublicKey]bool `json:"bad_participants,omitempty"`

	CommitDeadline   int64 `json:"commit_deadline,omitempty"`
	RevealDeadline   int64 `json:"reveal_deadline,omitempty"`
	TransitionHeight int64 `json:"transition_height,omitempty"`

	RuntimeDisableHeight int64 `json:"runtime_disable_height,omitempty"`
}

PVSSState is the PVSS backend state.

type RoundState

type RoundState uint8

RoundState is a PVSS round state.

const (
	StateInvalid  RoundState = 0
	StateCommit   RoundState = 1
	StateReveal   RoundState = 2
	StateComplete RoundState = 3
)

func (RoundState) String

func (s RoundState) String() string

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.