api

Documentation

Overview

Package api implements the Oasis timekeeping API and common types.

Index

• Constants
• type Backend
• type ConsensusParameters
• type EpochTime
• type Genesis
  • func (g *Genesis) GetInitialEpoch(height int64) EpochTime
  • func (g *Genesis) SanityCheck() error
• type SetableBackend

Constants

const ModuleName = "epochtime"

ModuleName is a unique module name for the epochtime module.

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 `0`, should return the
	// epoch of latest known block.
	GetEpoch(context.Context, int64) (EpochTime, error)

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

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

	// WatchLatestEpoch returns a channel that produces a stream of messages on
	// epoch transitions. If an epoch transition hapens before previous epoch
	// is read from channel, the old epochs is overwritten.
	//
	// Upon subscription the current epoch is sent immediately.
	WatchLatestEpoch() (<-chan EpochTime, *pubsub.Subscription)

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

Backend is a timekeeping implementation.

type ConsensusParameters

type ConsensusParameters struct {
	// Interval is the epoch interval (in blocks).
	Interval int64 `json:"interval"`

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

ConsensusParameters are the epochtime consensus parameters.

type EpochTime

type EpochTime uint64

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

const EpochInvalid EpochTime = 0xffffffffffffffff // ~50 quadrillion years away.

EpochInvalid is the placeholder invalid epoch.

type Genesis

type Genesis struct {
	// Parameters are the epochtime consensus parameters.
	Parameters ConsensusParameters `json:"params"`

	// Base is the starting epoch.
	Base EpochTime `json:"base"`
}

Genesis is the initial genesis state for allowing configurable timekeeping.

func (*Genesis) GetInitialEpoch

func (g *Genesis) GetInitialEpoch(height int64) EpochTime

GetInitialEpoch returns the initial epoch based on the given genesis document.

func (*Genesis) SanityCheck

func (g *Genesis) SanityCheck() error

SanityCheck does basic sanity checking on the genesis state.

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.