chain

Documentation

Index

• type DKGResult
  • func (r *DKGResult) Equals(r2 *DKGResult) bool
• type DKGResultHash
  • func DKGResultHashFromBytes(bytes []byte) (DKGResultHash, error)
• type DKGResultsVotes
• type DistributedKeyGenerationInterface
• type GroupInterface
• type GroupMemberIndex
• type GroupRegistrationInterface
• type GroupSelectionInterface
• type Interface
• type RelayEntryInterface
• type StakerAddress
• type Ticket
• type TicketProof

Types

type DKGResult

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
}

DKGResult is a result of distributed key generation protocol.

If the protocol execution finishes with an acceptable number of disqualified or inactive members, the group with remaining list of honest members will be added to the signing groups list for the threshold relay.

Otherwise, group creation will not finish, which will be due to either the number of inactive or disqualified participants, or the results (signatures) being disputed in a way where the correct outcome cannot be ascertained.

func (*DKGResult) Equals

func (r *DKGResult) Equals(r2 *DKGResult) bool

Equals checks if two DKG results are equal.

type DKGResultHash

type DKGResultHash [hashByteSize]byte

DKGResultHash is a 256-bit hash of DKG Result. The hashing algorithm should be the same as the one used on-chain.

func DKGResultHashFromBytes

func DKGResultHashFromBytes(bytes []byte) (DKGResultHash, error)

DKGResultHashFromBytes converts bytes slice to DKG Result Hash. It requires provided bytes slice size to be exactly 32 bytes.

type DKGResultsVotes

type DKGResultsVotes map[DKGResultHash]int

DKGResultsVotes is a map of votes for each DKG Result.

type DistributedKeyGenerationInterface

type DistributedKeyGenerationInterface interface {
	// 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,
	) *async.EventDKGResultSubmissionPromise
	// 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, error)
	// IsGroupRegistered checks if group with the given public key is registered
	// on-chain.
	IsGroupRegistered(groupPublicKey []byte) (bool, error)
	// CalculateDKGResultHash calculates 256-bit hash of DKG result in standard
	// specific for the chain. Operation is performed off-chain.
	CalculateDKGResultHash(dkgResult *DKGResult) (DKGResultHash, error)
}

DistributedKeyGenerationInterface defines the subset of the relay chain interface that pertains specifically to group formation's distributed key generation process.

type GroupInterface

type GroupInterface interface {
	GroupSelectionInterface
	GroupRegistrationInterface
}

GroupInterface defines the subset of the relay chain interface that pertains specifically to relay group management.

type GroupMemberIndex

type GroupMemberIndex = uint8

GroupMemberIndex is an index of a threshold relay group member. Maximum value accepted by the chain is 255.

type GroupRegistrationInterface

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, error)
	// 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)
	// GetGroupMembers returns `GroupSize` slice of addresses of
	// participants which have been selected to the group with given public key.
	GetGroupMembers(groupPublicKey []byte) ([]StakerAddress, error)
}

GroupRegistrationInterface defines the subset of the relay chain interface that pertains to relay group registration activities.

type GroupSelectionInterface

type GroupSelectionInterface interface {
	// OnGroupSelectionStarted is a callback that is invoked when an on-chain
	// group selection started and the contract is ready to accept tickets.
	OnGroupSelectionStarted(
		func(groupSelectionStarted *event.GroupSelectionStart),
	) (subscription.EventSubscription, error)
	// SubmitTicket submits a ticket corresponding to the virtual staker to
	// the chain, and returns a promise to track the submission. The promise
	// is fulfilled with the entry as seen on-chain, or failed if there is an
	// error submitting the entry.
	SubmitTicket(ticket *Ticket) *async.EventGroupTicketSubmissionPromise
	// GetSubmittedTickets gets the submitted group candidate tickets so far.
	GetSubmittedTickets() ([]uint64, error)
	// GetSelectedParticipants returns `GroupSize` slice of addresses of
	// candidates which have been selected to the currently assembling group.
	GetSelectedParticipants() ([]StakerAddress, error)
}

GroupSelectionInterface defines the subset of the relay chain interface that pertains to relay group selection activities.

type Interface

type Interface interface {
	// GetConfig returns the expected configuration of the threshold relay.
	GetConfig() (*config.Chain, error)
	// GetKeys returns the key pair used to attest for messages being sent to
	// the chain.
	GetKeys() (*operator.PrivateKey, *operator.PublicKey)

	GroupInterface
	RelayEntryInterface
	DistributedKeyGenerationInterface
}

Interface represents the interface that the relay expects to interact with the anchoring blockchain on.

type RelayEntryInterface

type RelayEntryInterface interface {
	// SubmitRelayEntry submits an entry in the threshold relay and returns a
	// promise to track the submission progress. The promise is fulfilled when
	// the entry has been successfully submitted to the on-chain, or failed if
	// the entry submission failed.
	SubmitRelayEntry(entry []byte) *async.EventEntrySubmittedPromise
	// OnRelayEntrySubmitted is a callback that is invoked when an on-chain
	// notification of a new, valid relay entry is seen.
	OnRelayEntrySubmitted(
		func(entry *event.EntrySubmitted),
	) (subscription.EventSubscription, error)
	// OnRelayEntryRequested is a callback that is invoked when an on-chain
	// notification of a new, valid relay request is seen.
	OnRelayEntryRequested(
		func(request *event.Request),
	) (subscription.EventSubscription, error)
	// 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
}

RelayEntryInterface defines the subset of the relay chain interface that pertains specifically to submission and retrieval of relay requests and entries.

type StakerAddress

type StakerAddress []byte

StakerAddress represents chain-specific address of the staker.

type Ticket

type Ticket struct {
	Value [8]byte // W_k
	Proof *TicketProof
}

Ticket represents group selection ticket as seen on-chain.

type TicketProof

type TicketProof struct {
	StakerValue        *big.Int
	VirtualStakerIndex *big.Int
}

TicketProof represents group selection ticket proof as seen on-chain.