participation

package
v1.1.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Dec 3, 2021 License: Apache-2.0 Imports: 20 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
)

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")
	ErrParticipationEventStakingCanOverflow        = errors.New("the given participation staking nominator and denominator in combination with the duration can overflow uint64")
)
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          uint8
	Text           string
	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       uint8  `json:"value"`
	Current     uint64 `json:"current"`
	Accumulated uint64 `json:"accumulated"`
}

AnswerStatus holds the current and accumulated vote for an answer.

type Ballot 

type Ballot struct {
	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                   string
	MilestoneIndexCommence uint32
	MilestoneIndexStart    uint32
	MilestoneIndexEnd      uint32
	Payload                serializer.Serializable
	AdditionalInfo         string
}

Event

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

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 milestone.Index   `json:"milestoneIndex"`
	Status         string            `json:"status"`
	Questions      []*QuestionStatus `json:"questions,omitempty"`
	Staking        *StakingStatus    `json:"staking,omitempty"`
	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.

func WithLogger 

func WithLogger(logger *logger.Logger) Option

WithLogger enables logging within the ParticipationManager.

type Options 

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

Options define options for the ParticipationManager.

type Participation 

type Participation struct {
	EventID EventID
	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 {
	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 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           string
	Answers        serializer.Serializables
	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 []*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   string
	Symbol string

	Numerator   uint32
	Denominator uint32

	RequiredMinimumRewards uint64

	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   uint64 `json:"staked"`
	Rewarded uint64 `json:"rewarded"`
	Symbol   string `json:"symbol"`
}

StakingStatus holds the status of a staking.

type TrackedParticipation 

type TrackedParticipation struct {
	EventID    EventID
	OutputID   *iotago.UTXOInputID
	MessageID  hornet.MessageID
	Amount     uint64
	StartIndex milestone.Index
	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.