chain

type Config struct {
	// GroupSize is the size of a group in the random beacon.
	GroupSize int
	// HonestThreshold is the minimum number of active participants behaving
	// according to the protocol needed to generate a new relay entry.
	HonestThreshold int
	// ResultPublicationBlockStep is the duration (in blocks) that has to pass
	// before group member with the given index is eligible to submit the
	// result.
	// Nth player becomes eligible to submit the result after
	// T_dkg + (N-1) * T_step
	// where T_dkg is time for phases 1-12 to complete and T_step is the result
	// publication block step.
	ResultPublicationBlockStep uint64
	// RelayEntryTimeout is a timeout in blocks on-chain for a relay
	// entry to be published by the selected group. Blocks are
	// counted from the moment relay request occur.
	RelayEntryTimeout uint64
}

type DKGResult struct {
	// Group public key generated by the protocol execution, empty if the protocol failed.
	GroupPublicKey []byte
	// Misbehaved members are all members either inactive or disqualified.
	// Misbehaved members are represented as a slice of bytes for optimizing
	// on-chain storage. Each byte is an inactive or disqualified member index.
	Misbehaved []byte
}

type DKGResultHash [hashByteSize]byte

type DKGResultsVotes map[DKGResultHash]int

type DistributedKeyGenerationInterface interface {
	// OnDKGStarted registers a callback that is invoked when an on-chain
	// notification of the DKG process start is seen.
	OnDKGStarted(
		func(event *event.DKGStarted),
	) subscription.EventSubscription
	// SubmitDKGResult sends DKG result to a chain, along with signatures over
	// result hash from group participants supporting the result.
	// Signatures over DKG result hash are collected in a map keyed by signer's
	// member index.
	SubmitDKGResult(
		participantIndex GroupMemberIndex,
		dkgResult *DKGResult,
		signatures map[GroupMemberIndex][]byte,
	) error
	// OnDKGResultSubmitted registers a callback that is invoked when an on-chain
	// notification of a new, valid submitted result is seen.
	OnDKGResultSubmitted(
		func(event *event.DKGResultSubmission),
	) subscription.EventSubscription
	// CalculateDKGResultHash calculates 256-bit hash of DKG result in standard
	// specific for the chain. Operation is performed off-chain.
	CalculateDKGResultHash(dkgResult *DKGResult) (DKGResultHash, error)
}

type GroupInterface interface {
	GroupSelectionInterface
	GroupRegistrationInterface
}

type GroupMemberIndex = uint8

type GroupRegistrationInterface interface {
	// OnGroupRegistered is a callback that is invoked when an on-chain
	// notification of a new, valid group being registered is seen.
	OnGroupRegistered(
		func(groupRegistration *event.GroupRegistration),
	) subscription.EventSubscription
	// IsGroupRegistered checks if group with the given public key is registered
	// on-chain.
	IsGroupRegistered(groupPublicKey []byte) (bool, error)
	// IsStaleGroup checks if a group with the given public key is considered
	// as stale on-chain. Group is considered as stale if it is expired and when
	// its expiration time and potentially executed operation timeout are both
	// in the past. Stale group is never selected by the chain to any new
	// operation.
	IsStaleGroup(groupPublicKey []byte) (bool, error)
}

type GroupSelectionInterface interface {
	// SelectGroup returns the group members for the group generated by
	// the given seed. This function can return an error if the beacon chain's
	// state does not allow for group selection at the moment.
	SelectGroup(seed *big.Int) (chain.Addresses, error)
}

type Interface interface {
	// GetConfig returns the expected configuration of the random beacon.
	GetConfig() *Config
	// BlockCounter returns the chain's block counter.
	BlockCounter() (chain.BlockCounter, error)
	// Signing returns the chain's signer.
	Signing() chain.Signing
	// OperatorKeyPair returns the key pair of the operator assigned to this
	// chain handle.
	OperatorKeyPair() (*operator.PrivateKey, *operator.PublicKey, error)

	sortition.Chain
	GroupInterface
	RelayEntryInterface
	DistributedKeyGenerationInterface
}

type RelayEntryInterface interface {
	// SubmitRelayEntry submits a newly created relay entry to the chain.
	SubmitRelayEntry(entry []byte) error
	// OnRelayEntrySubmitted is a callback that is invoked when an on-chain
	// notification of a new, valid relay entry is seen.
	OnRelayEntrySubmitted(
		func(entry *event.RelayEntrySubmitted),
	) subscription.EventSubscription
	// OnRelayEntryRequested is a callback that is invoked when an on-chain
	// notification of a new, valid relay request is seen.
	OnRelayEntryRequested(
		func(request *event.RelayEntryRequested),
	) subscription.EventSubscription
	// ReportRelayEntryTimeout notifies the chain when a selected group which was
	// supposed to submit a relay entry, did not deliver it within a specified
	// time frame (relayEntryTimeout) counted in blocks.
	ReportRelayEntryTimeout() error
	// IsEntryInProgress checks if a new relay entry is currently in progress.
	IsEntryInProgress() (bool, error)
	// CurrentRequestStartBlock returns a start block of a current entry.
	CurrentRequestStartBlock() (*big.Int, error)
	// CurrentRequestPreviousEntry returns previous entry of a current request.
	CurrentRequestPreviousEntry() ([]byte, error)
	// CurrentRequestGroupPublicKey returns group public key for the current request.
	CurrentRequestGroupPublicKey() ([]byte, error)
}