api

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)
}

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

type EpochTime uint64

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

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

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

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

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(ctx context.Context) (<-chan *PVSSEvent, *pubsub.Subscription, error)
}

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

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

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

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

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

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

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

type RoundState uint8

type SetableBackend interface {
	Backend

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