api

package
v0.2507.0 Latest Latest
Warning

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

 Go to latest Published: Nov 6, 2025 License: Apache-2.0 Imports: 9 Imported by: 24

Documentation

Overview

Package api implements the random beacon and time keeping APIs.

Index

Constants

View Source 
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"
)
View Source 
const GasOpVRFProve transaction.Op = "vrf_prove"

GasOpVRFProve is the gas operation identifier for VRF proof submission.

Variables

View Source 
var (
	// ErrInvalidArgument is the error returned on malformed argument(s).
	ErrInvalidArgument = errors.New(ModuleName, 1, "beacon: invalid argument")

	// ErrBeaconNotAvailable is the error returned when a beacon is not
	// available for the requested height for any reason.
	ErrBeaconNotAvailable = errors.New(ModuleName, 2, "beacon: random beacon not available")

	// MethodSetEpoch is the method name for setting epochs.
	MethodSetEpoch = transaction.NewMethodName(ModuleName, "SetEpoch", EpochTime(0))

	// Methods is a list of all methods supported by the beacon backend.
	Methods = []transaction.MethodName{
		MethodSetEpoch,
		MethodVRFProve,
	}
)
View Source 
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,
	}
)

Functions

func RegisterService added in v0.2100.0 

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.

type BeaconEvent added in v0.2200.0 

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

BeaconEvent is the beacon event.

func (*BeaconEvent) EventKind added in v0.2200.0 

func (ev *BeaconEvent) EventKind() string

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

type Client added in v0.2501.0 

type Client struct {
	// contains filtered or unexported fields
}

Client is a gRPC beacon client.

func NewClient added in v0.2501.0 

func NewClient(c *grpc.ClientConn) *Client

NewClient creates a new gRPC beacon client.

func (*Client) Cleanup added in v0.2501.0 

func (c *Client) Cleanup()

func (*Client) ConsensusParameters added in v0.2501.0 

func (c *Client) ConsensusParameters(ctx context.Context, height int64) (*ConsensusParameters, error)

func (*Client) GetBaseEpoch added in v0.2501.0 

func (c *Client) GetBaseEpoch(ctx context.Context) (EpochTime, error)

func (*Client) GetBeacon added in v0.2501.0 

func (c *Client) GetBeacon(ctx context.Context, height int64) ([]byte, error)

func (*Client) GetEpoch added in v0.2501.0 

func (c *Client) GetEpoch(ctx context.Context, height int64) (EpochTime, error)

func (*Client) GetEpochBlock added in v0.2501.0 

func (c *Client) GetEpochBlock(ctx context.Context, epoch EpochTime) (int64, error)

func (*Client) GetFutureEpoch added in v0.2501.0 

func (c *Client) GetFutureEpoch(ctx context.Context, height int64) (*EpochTimeState, error)

func (*Client) StateToGenesis added in v0.2501.0 

func (c *Client) StateToGenesis(ctx context.Context, height int64) (*Genesis, error)

func (*Client) WaitEpoch added in v0.2501.0 

func (c *Client) WaitEpoch(ctx context.Context, epoch EpochTime) error

func (*Client) WatchEpochs added in v0.2501.0 

func (c *Client) WatchEpochs(ctx context.Context) (<-chan EpochTime, pubsub.ClosableSubscription, error)

func (*Client) WatchLatestEpoch added in v0.2501.0 

func (c *Client) WatchLatestEpoch(context.Context) (<-chan EpochTime, pubsub.ClosableSubscription, error)

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.

func (*ConsensusParameters) Interval added in v0.2300.0 

func (p *ConsensusParameters) Interval() int64

Interval returns the epoch interval (in blocks).

func (*ConsensusParameters) SanityCheck added in v0.2202.0 

func (p *ConsensusParameters) SanityCheck() error

SanityCheck performs a sanity check on the consensus parameters.

type EpochEvent added in v0.2200.0 

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

EpochEvent is the epoch event.

func (*EpochEvent) EventKind added in v0.2200.0 

func (ev *EpochEvent) EventKind() string

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

type EpochTime added in v0.2100.0 

type EpochTime uint64

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

func (EpochTime) AbsDiff added in v0.2100.0 

func (e EpochTime) AbsDiff(other EpochTime) EpochTime

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

type EpochTimeState added in v0.2100.0 

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 added in v0.2100.0 

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 added in v0.2200.0 

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 VRFBackend added in v0.2200.0 

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 added in v0.2200.0 

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 added in v0.2200.0 

func (ev *VRFEvent) EventKind() string

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

func (*VRFEvent) FromState added in v0.2200.0 

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

type VRFParameters added in v0.2200.0 

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 period 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 added in v0.2200.0 

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

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

VRFProve is a VRF proof transaction payload.

type VRFState added in v0.2200.0 

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.

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.