participation

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Dec 10, 2021 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AnswerTextMaxLength           = 255
	AnswerAdditionalInfoMaxLength = 500

	AnswerValueSkipped = 0
	AnswerValueInvalid = 255
)
View Source 
const (
	// BallotPayloadTypeID defines the ballot payload's type ID.
	BallotPayloadTypeID uint32 = 0

	BallotMinQuestionsCount = 1
	BallotMaxQuestionsCount = 10
)
View Source 
const (
	// Holds the events
	ParticipationStoreKeyPrefixEvents byte = 0

	// Holds the messages containing participations
	ParticipationStoreKeyPrefixMessages byte = 1

	// Tracks all active and past participations
	ParticipationStoreKeyPrefixTrackedOutputs      byte = 2
	ParticipationStoreKeyPrefixTrackedSpentOutputs byte = 3

	// Voting
	ParticipationStoreKeyPrefixBallotCurrentVoteBalanceForQuestionAndAnswer     byte = 4
	ParticipationStoreKeyPrefixBallotAccululatedVoteBalanceForQuestionAndAnswer byte = 5

	// Staking
	ParticipationStoreKeyPrefixStakingAddress            byte = 6
	ParticipationStoreKeyPrefixStakingTotalParticipation byte = 7
)
View Source 
const (
	// EventIDLength defines the length of a participation event ID.
	EventIDLength = blake2b.Size256

	EventNameMaxLength           = 255
	EventAdditionalInfoMaxLength = 2000
)
View Source 
const (
	ParticipationsMinParticipationCount = 1
	ParticipationsMaxParticipationCount = 255
)
View Source 
const (
	QuestionTextMaxLength           = 255
	QuestionAdditionalInfoMaxLength = 500

	QuestionMinAnswersCount = 2
	QuestionMaxAnswersCount = 10
)
View Source 
const (
	StakingPayloadTypeID uint32 = 1

	StakingTextMaxLength           = 255
	StakingSymbolMinLength         = 3
	StakingSymbolMaxLength         = 10
	StakingAdditionalInfoMaxLength = 500
)
View Source 
const (
	BallotDenominator = 1000
)

Variables

View Source 
var (
	NullEventID = EventID{}

	ErrUnknownPayloadType               = errors.New("unknown payload type")
	ErrInvalidMilestoneSequence         = errors.New("milestone are not monotonically increasing")
	ErrPayloadEmpty                     = errors.New("payload cannot be empty")
	ErrSerializationStringLengthInvalid = errors.New("invalid string length")
)
View Source 
var (
	ErrParticipationCorruptedStorage               = errors.New("the participation database was not shutdown properly")
	ErrParticipationEventStartedBeforePruningIndex = errors.New("the given participation event started before the pruning index of this node")
	ErrParticipationEventBallotCanOverflow         = errors.New("the given participation duration in combination with the maximum voting weight can overflow uint64")
	ErrParticipationEventStakingCanOverflow        = errors.New("the given participation staking nominator and denominator in combination with the duration can overflow uint64")
	ErrParticipationEventAlreadyExists             = errors.New("the given participation event already exists")
)
View Source 
var (
	ErrUnknownParticipation                  = errors.New("no participation found")
	ErrEventNotFound                         = errors.New("referenced event does not exist")
	ErrInvalidEvent                          = errors.New("invalid event")
	ErrInvalidPreviouslyTrackedParticipation = errors.New("a previously tracked participation changed and is now invalid")
	ErrInvalidCurrentBallotVoteBalance       = errors.New("current ballot vote balance invalid")
	ErrInvalidCurrentStakedAmount            = errors.New("current staked amount invalid")
)
View Source 
var (
	ErrDuplicateAnswerValue = errors.New("duplicate answer value found")
)
View Source 
var (
	ErrInvalidNumeratorOrDenominator = errors.New("numerator and denominator need to be greater than zero")
)
View Source 
var (
	ErrMultipleEventParticipation = errors.New("multiple participations for the same event")
)
View Source 
var (
	ErrParticipationTooManyAnswers = errors.New("participation contains more answers than what a ballot can hold")
)
View Source 
var (
	ErrSerializationReservedValue = errors.New("reserved value used")
)

Functions

func PayloadSelector 

func PayloadSelector(payloadType uint32) (serializer.Serializable, error)

PayloadSelector implements SerializableSelectorFunc for payload types.

Types

type Answer 

type Answer struct {
	// Value is the value that should be used to pick this answer. It must be unique for each answer in a given question. Reserved values are 0 and 255.
	Value uint8
	// Text is the text of the answer.
	Text string
	// AdditionalInfo is an additional description text about the answer.
	AdditionalInfo string
}

Answer is a possible answer to a Ballot Question

func (*Answer) Deserialize 

func (a *Answer) Deserialize(data []byte, deSeriMode serializer.DeSerializationMode) (int, error)

func (*Answer) MarshalJSON 

func (a *Answer) MarshalJSON() ([]byte, error)

func (*Answer) Serialize 

func (a *Answer) Serialize(deSeriMode serializer.DeSerializationMode) ([]byte, error)

func (*Answer) UnmarshalJSON 

func (a *Answer) UnmarshalJSON(bytes []byte) error

type AnswerStatus 

type AnswerStatus struct {
	// Value is the value that identifies this answer.
	Value uint8 `json:"value"`
	// Current is the current voting weight of the answer.
	Current uint64 `json:"current"`
	// Accumulated is the accumulated voting weight of the answer.
	Accumulated uint64 `json:"accumulated"`
}

AnswerStatus holds the current and accumulated vote for an answer.

type Ballot 

type Ballot struct {
	// Questions are the questions of the ballot and their possible answers.
	Questions serializer.Serializables
}

Ballot can be used to define a voting participation with variable questions.

func (*Ballot) Deserialize 

func (q *Ballot) Deserialize(data []byte, deSeriMode serializer.DeSerializationMode) (int, error)

func (*Ballot) MarshalJSON 

func (q *Ballot) MarshalJSON() ([]byte, error)

func (*Ballot) Serialize 

func (q *Ballot) Serialize(deSeriMode serializer.DeSerializationMode) ([]byte, error)

func (*Ballot) UnmarshalJSON 

func (q *Ballot) UnmarshalJSON(bytes []byte) error

type BallotBuilder 

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

BallotBuilder is used to easily build up a Ballot.

func NewBallotBuilder 

func NewBallotBuilder() *BallotBuilder

NewBallotBuilder creates a new BallotBuilder.

func (*BallotBuilder) AddQuestion 

func (qb *BallotBuilder) AddQuestion(entry *Question) *BallotBuilder

AddQuestion adds the given question to the Ballot.

func (*BallotBuilder) Build 

func (qb *BallotBuilder) Build() (*Ballot, error)

Build builds the Ballot.

type Event 

type Event struct {
	// Name is the name of the event.
	Name string
	// MilestoneIndexCommence is the milestone index the commencing period starts.
	MilestoneIndexCommence uint32
	// MilestoneIndexStart is the milestone index the holding period starts.
	MilestoneIndexStart uint32
	// MilestoneIndexEnd is the milestone index the event ends.
	MilestoneIndexEnd uint32
	// Payload is the payload of the event (ballot/staking).
	Payload serializer.Serializable
	// AdditionalInfo is an additional description text about the event.
	AdditionalInfo string
}

Event

func (*Event) Ballot 

func (e *Event) Ballot() *Ballot

Ballot returns the Ballot payload if this participation is for a Ballot event.

func (*Event) BallotCanOverflow 

func (e *Event) BallotCanOverflow() bool

BallotCanOverflow returns whether a Ballot event can overflow.

func (*Event) BallotQuestions 

func (e *Event) BallotQuestions() []*Question

BallotQuestions returns the questions contained in the Ballot payload if this participation contains a Ballot.

func (*Event) CommenceMilestoneIndex 

func (e *Event) CommenceMilestoneIndex() milestone.Index

CommenceMilestoneIndex returns the milestone index the commencing phase of the participation starts.

func (*Event) Deserialize 

func (e *Event) Deserialize(data []byte, deSeriMode serializer.DeSerializationMode) (int, error)

func (*Event) EndMilestoneIndex 

func (e *Event) EndMilestoneIndex() milestone.Index

EndMilestoneIndex returns the milestone index the participation ends.

func (*Event) ID 

func (e *Event) ID() (EventID, error)

ID returns the ID of the event.

func (*Event) IsAcceptingParticipation 

func (e *Event) IsAcceptingParticipation(atIndex milestone.Index) bool

IsAcceptingParticipation returns true if the event already commenced or started the holding phase for the given milestone index.

func (*Event) IsCountingParticipation 

func (e *Event) IsCountingParticipation(atIndex milestone.Index) bool

IsCountingParticipation returns true if the event already started the holding phase for the given milestone index.

func (*Event) MarshalJSON 

func (e *Event) MarshalJSON() ([]byte, error)

func (*Event) Serialize 

func (e *Event) Serialize(deSeriMode serializer.DeSerializationMode) ([]byte, error)

func (*Event) ShouldAcceptParticipation 

func (e *Event) ShouldAcceptParticipation(forIndex milestone.Index) bool

ShouldAcceptParticipation returns true if the event should accept the participation for the given milestone index.

func (*Event) ShouldCountParticipation 

func (e *Event) ShouldCountParticipation(forIndex milestone.Index) bool

ShouldCountParticipation returns true if the event should count the participation for the given milestone index.

func (*Event) Staking 

func (e *Event) Staking() *Staking

Staking returns the staking payload if this participation is for a Staking event.

func (*Event) StakingCanOverflow 

func (e *Event) StakingCanOverflow() bool

StakingCanOverflow returns whether a Staking event can overflow.

func (*Event) StartMilestoneIndex 

func (e *Event) StartMilestoneIndex() milestone.Index

StartMilestoneIndex returns the milestone index the holding phase of the participation starts.

func (*Event) Status 

func (e *Event) Status(atIndex milestone.Index) string

Status returns a human-readable status of the event. Possible values are "upcoming", "commencing", "holding" and "ended".

func (*Event) UnmarshalJSON 

func (e *Event) UnmarshalJSON(bytes []byte) error

type EventBuilder 

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

EventBuilder is used to easily build up a Event.

func NewEventBuilder 

func NewEventBuilder(name string, milestoneCommence milestone.Index, milestoneBeginHolding milestone.Index, milestoneEnd milestone.Index, additionalInfo string) *EventBuilder

NewEventBuilder creates a new EventBuilder.

func (*EventBuilder) Build 

func (rb *EventBuilder) Build() (*Event, error)

Build builds the Event.

func (*EventBuilder) Payload 

func (rb *EventBuilder) Payload(seri serializer.Serializable) *EventBuilder

Payload sets the payload to embed within the message.

type EventID 

type EventID = [EventIDLength]byte

EventID is the ID of an event.

func ParseEventID 

func ParseEventID(ms *marshalutil.MarshalUtil) (EventID, error)

ParseEventID helps to parse an EventID using marshalutil.

type EventStatus 

type EventStatus struct {
	// MilestoneIndex is the milestone index the status was calculated for.
	MilestoneIndex milestone.Index `json:"milestoneIndex"`
	// Status is the status of the event. Valid options are: "upcoming", "commencing", "holding" and "ended".
	Status string `json:"status"`
	// Questions holds the answer status of the different questions of the event.
	Questions []*QuestionStatus `json:"questions,omitempty"`
	// Staking is the staking status of the event.
	Staking *StakingStatus `json:"staking,omitempty"`
	// Checksum is the SHA256 checksum of all the question and answer status or the staking amount and rewards calculated for this MilestoneIndex.
	Checksum string `json:"checksum"`
}

EventStatus holds the status of the event

type IterateOption 

type IterateOption func(*IterateOptions)

func FilterRequiredMinimumRewards 

func FilterRequiredMinimumRewards(filter bool) IterateOption

func MaxResultCount 

func MaxResultCount(count int) IterateOption

type IterateOptions 

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

type Option 

type Option func(opts *Options)

Option is a function setting a ParticipationManager option.

func WithIndexationMessage 

func WithIndexationMessage(indexationMessage string) Option

WithIndexationMessage defines the ParticipationManager indexation payload to track.

type Options 

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

Options define options for the ParticipationManager.

type Participation 

type Participation struct {
	// EventID is the ID of the event the participation is made for.
	EventID EventID
	// Answers holds the IDs of the answers to the questions of the ballot.
	Answers []byte
}

Participation holds the participation for an event and the optional answer to a ballot

func (*Participation) Deserialize 

func (p *Participation) Deserialize(data []byte, deSeriMode serializer.DeSerializationMode) (int, error)

func (*Participation) MarshalJSON 

func (p *Participation) MarshalJSON() ([]byte, error)

func (*Participation) Serialize 

func (p *Participation) Serialize(deSeriMode serializer.DeSerializationMode) ([]byte, error)

func (*Participation) UnmarshalJSON 

func (p *Participation) UnmarshalJSON(bytes []byte) error

type ParticipationManager 

type ParticipationManager struct {
	// lock used to secure the state of the ParticipationManager.
	syncutils.RWMutex
	// contains filtered or unexported fields
}

ParticipationManager is used to track the outcome of participation in the tangle.

func NewManager 

func NewManager(
	dbStorage *storage.Storage,
	syncManager *syncmanager.SyncManager,
	participationStore kvstore.KVStore,
	opts ...Option) (*ParticipationManager, error)

NewManager creates a new ParticipationManager instance.

func (*ParticipationManager) AccumulatedBallotVoteBalanceForQuestionAndAnswer 

func (pm *ParticipationManager) AccumulatedBallotVoteBalanceForQuestionAndAnswer(eventID EventID, milestone milestone.Index, questionIdx uint8, answerIdx uint8) (uint64, error)

func (*ParticipationManager) ApplyNewConfirmedMilestoneIndex 

func (pm *ParticipationManager) ApplyNewConfirmedMilestoneIndex(index milestone.Index) error

ApplyNewConfirmedMilestoneIndex iterates over each counting ballot participation and applies the current vote balance for each question to the total vote balance

func (*ParticipationManager) ApplyNewUTXO 

func (pm *ParticipationManager) ApplyNewUTXO(index milestone.Index, newOutput *utxo.Output) error

ApplyNewUTXO checks if the new UTXO is part of a participation transaction. The following rules must be satisfied:

  • Must be a value transaction
  • Inputs must all come from the same address. Multiple inputs are allowed.
  • Has a singular output going to the same address as all input addresses.
  • Output Type 0 (SigLockedSingleOutput) and Type 1 (SigLockedDustAllowanceOutput) are both valid for this.
  • The Indexation must match the configured Indexation.
  • The participation data must be parseable.

func (*ParticipationManager) ApplySpentUTXO 

func (pm *ParticipationManager) ApplySpentUTXO(index milestone.Index, spent *utxo.Spent) error

ApplySpentUTXO checks if the spent UTXO was part of a participation transaction.

func (*ParticipationManager) CloseDatabase 

func (pm *ParticipationManager) CloseDatabase() error

CloseDatabase flushes the store and closes the underlying database

func (*ParticipationManager) CurrentBallotVoteBalanceForQuestionAndAnswer 

func (pm *ParticipationManager) CurrentBallotVoteBalanceForQuestionAndAnswer(eventID EventID, milestone milestone.Index, questionIdx uint8, answerIdx uint8) (uint64, error)

func (*ParticipationManager) DeleteEvent 

func (pm *ParticipationManager) DeleteEvent(eventID EventID) error

DeleteEvent deletes the event for the given eventID if it exists, else returns ErrEventNotFound.

func (*ParticipationManager) Event 

func (pm *ParticipationManager) Event(eventID EventID) *Event

Event returns the event for the given eventID if it exists

func (*ParticipationManager) EventIDs 

func (pm *ParticipationManager) EventIDs(eventPayloadType ...uint32) []EventID

EventIDs return the IDs of all known events. Can be optionally filtered by event payload type.

func (*ParticipationManager) EventStatus 

func (pm *ParticipationManager) EventStatus(eventID EventID, milestone ...milestone.Index) (*EventStatus, error)

EventStatus returns the EventStatus for an event with the given eventID.

func (*ParticipationManager) Events 

func (pm *ParticipationManager) Events() map[EventID]*Event

Events returns all known events

func (*ParticipationManager) EventsAcceptingParticipation 

func (pm *ParticipationManager) EventsAcceptingParticipation() map[EventID]*Event

EventsAcceptingParticipation returns the events that are currently accepting participation, i.e. commencing or in the holding period.

func (*ParticipationManager) EventsCountingParticipation 

func (pm *ParticipationManager) EventsCountingParticipation() map[EventID]*Event

EventsCountingParticipation returns the events that are currently actively counting participation, i.e. in the holding period

func (*ParticipationManager) ForEachActiveParticipation 

func (pm *ParticipationManager) ForEachActiveParticipation(eventID EventID, consumer TrackedParticipationConsumer, options ...IterateOption) error

func (*ParticipationManager) ForEachPastParticipation 

func (pm *ParticipationManager) ForEachPastParticipation(eventID EventID, consumer TrackedParticipationConsumer, options ...IterateOption) error

func (*ParticipationManager) ForEachStakingAddress 

func (pm *ParticipationManager) ForEachStakingAddress(eventID EventID, consumer StakingRewardsConsumer, options ...IterateOption) error

func (*ParticipationManager) MessageForEventAndMessageID 

func (pm *ParticipationManager) MessageForEventAndMessageID(eventID EventID, messageId hornet.MessageID) (*storage.Message, error)

func (*ParticipationManager) ParticipationForOutputID 

func (pm *ParticipationManager) ParticipationForOutputID(eventID EventID, outputID *iotago.UTXOInputID) (*TrackedParticipation, error)

func (*ParticipationManager) ParticipationsForOutputID 

func (pm *ParticipationManager) ParticipationsForOutputID(outputID *iotago.UTXOInputID) ([]*TrackedParticipation, error)

func (*ParticipationManager) ParticipationsFromMessage 

func (pm *ParticipationManager) ParticipationsFromMessage(msg *storage.Message) (*utxo.Output, []*Participation, error)

func (*ParticipationManager) StakingRewardForAddress 

func (pm *ParticipationManager) StakingRewardForAddress(eventID EventID, address iotago.Address) (uint64, error)

func (*ParticipationManager) StoreEvent 

func (pm *ParticipationManager) StoreEvent(event *Event) (EventID, error)

StoreEvent accepts a new Event the manager should track. The current confirmed milestone index needs to be provided, so that the manager can check if the event can be added.

type Participations 

type Participations struct {
	// Participations holds the participation for multiple events.
	Participations serializer.Serializables
}

Participations holds the participation for multiple events.

func (*Participations) Deserialize 

func (p *Participations) Deserialize(data []byte, deSeriMode serializer.DeSerializationMode) (int, error)

func (*Participations) MarshalJSON 

func (p *Participations) MarshalJSON() ([]byte, error)

func (*Participations) Serialize 

func (p *Participations) Serialize(deSeriMode serializer.DeSerializationMode) ([]byte, error)

func (*Participations) UnmarshalJSON 

func (p *Participations) UnmarshalJSON(bytes []byte) error

type ParticipationsBuilder 

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

ParticipationsBuilder is used to easily build up Participations.

func NewParticipationsBuilder 

func NewParticipationsBuilder() *ParticipationsBuilder

NewParticipationsBuilder creates a new ParticipationsBuilder.

func (*ParticipationsBuilder) AddParticipation 

func (b *ParticipationsBuilder) AddParticipation(entry *Participation) *ParticipationsBuilder

AddParticipation adds the given participation to the participations.

func (*ParticipationsBuilder) Build 

func (b *ParticipationsBuilder) Build() (*Participations, error)

Build builds the Participations.

type Question 

type Question struct {
	// Text is the text of the question.
	Text string
	// Answers are the possible answers to the question.
	Answers serializer.Serializables
	// AdditionalInfo is an additional description text about the question.
	AdditionalInfo string
}

Question defines a single question inside a Ballot that can have multiple Answers.

func (*Question) Deserialize 

func (q *Question) Deserialize(data []byte, deSeriMode serializer.DeSerializationMode) (int, error)

func (*Question) MarshalJSON 

func (q *Question) MarshalJSON() ([]byte, error)

func (*Question) QuestionAnswers 

func (q *Question) QuestionAnswers() []*Answer

QuestionAnswers returns the possible answers for a Question

func (*Question) Serialize 

func (q *Question) Serialize(deSeriMode serializer.DeSerializationMode) ([]byte, error)

func (*Question) UnmarshalJSON 

func (q *Question) UnmarshalJSON(bytes []byte) error

type QuestionBuilder 

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

QuestionBuilder is used to easily build up a Question.

func NewQuestionBuilder 

func NewQuestionBuilder(text string, additionalInfo string) *QuestionBuilder

NewQuestionBuilder creates a new QuestionBuilder.

func (*QuestionBuilder) AddAnswer 

func (qb *QuestionBuilder) AddAnswer(entry *Answer) *QuestionBuilder

AddAnswer adds the given answer to the question.

func (*QuestionBuilder) Build 

func (qb *QuestionBuilder) Build() (*Question, error)

Build builds the Question.

type QuestionStatus 

type QuestionStatus struct {
	// Answers holds the status of the answers.
	Answers []*AnswerStatus `json:"answers"`
}

QuestionStatus holds the answers for a question.

func (*QuestionStatus) StatusForAnswerValue 

func (q *QuestionStatus) StatusForAnswerValue(answerValue uint8) *AnswerStatus

type Staking 

type Staking struct {
	// Text is the description text of the staking event.
	Text string
	// Symbol is the symbol of the rewarded tokens.
	Symbol string

	// Numerator is used in combination with Denominator to calculate the rewards per milestone per staked tokens.
	Numerator uint32
	// Denominator is used in combination with Numerator to calculate the rewards per milestone per staked tokens.
	Denominator uint32

	// RequiredMinimumRewards are the minimum rewards required to be included in the staking results.
	RequiredMinimumRewards uint64

	// AdditionalInfo is an additional description text about the staking event.
	AdditionalInfo string
}

func (*Staking) Deserialize 

func (s *Staking) Deserialize(data []byte, deSeriMode serializer.DeSerializationMode) (int, error)

func (*Staking) MarshalJSON 

func (s *Staking) MarshalJSON() ([]byte, error)

func (*Staking) Serialize 

func (s *Staking) Serialize(deSeriMode serializer.DeSerializationMode) ([]byte, error)

func (*Staking) UnmarshalJSON 

func (s *Staking) UnmarshalJSON(bytes []byte) error

type StakingRewardsConsumer 

type StakingRewardsConsumer func(address iotago.Address, rewards uint64) bool

type StakingStatus 

type StakingStatus struct {
	// Staked is the currently staked amount of tokens.
	Staked uint64 `json:"staked"`
	// Rewarded is the total staking reward.
	Rewarded uint64 `json:"rewarded"`
	// Symbol is the symbol of the rewarded tokens.
	Symbol string `json:"symbol"`
}

StakingStatus holds the status of a staking.

type TrackedParticipation 

type TrackedParticipation struct {
	// EventID is the ID of the event the participation is made for.
	EventID EventID
	// OutputID is the ID of the output the participation was made.
	OutputID *iotago.UTXOInputID
	// MessageID is the ID of the message that included the transaction that created the output the participation was made.
	MessageID hornet.MessageID
	// Amount is the amount of tokens that were included in the output the participation was made.
	Amount uint64
	// StartIndex is the milestone index the participation started.
	StartIndex milestone.Index
	// EndIndex is the milestone index the participation ended. 0 if the participation is still active.
	EndIndex milestone.Index
}

TrackedParticipation holds the information the node tracked for the participation.

func TrackedParticipationFromBytes 

func TrackedParticipationFromBytes(key []byte, value []byte) (*TrackedParticipation, error)

func (*TrackedParticipation) ValueBytes 

func (t *TrackedParticipation) ValueBytes() []byte

type TrackedParticipationConsumer 

type TrackedParticipationConsumer func(trackedParticipation *TrackedParticipation) bool

Source Files

View all Source files

Directories

Path Synopsis

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.