mana

package
v0.9.8 Latest Latest
Warning

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

Go to latest
Published: Sep 6, 2022 License: Apache-2.0, BSD-2-Clause Imports: 19 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// EventTypePledge defines the type of a pledge event.
	EventTypePledge byte = iota
	// EventTypeRevoke defines the event type of a revoke event.
	EventTypeRevoke
	// EventTypeUpdate defines the event type of an updated event.
	EventTypeUpdate
)
View Source
const (
	// PrefixAccess is the storage prefix for access mana storage.
	PrefixAccess byte = iota

	// PrefixConsensus is the storage prefix for consensus mana storage.
	PrefixConsensus

	// PrefixAccessResearch is the storage prefix for research access mana storage.
	PrefixAccessResearch

	// PrefixConsensusResearch is the storage prefix for research consensus mana storage.
	PrefixConsensusResearch

	// PrefixEventStorage is the storage prefix for consensus mana event storage.
	PrefixEventStorage

	// PrefixConsensusPastVector is the storage prefix for consensus mana past vector storage.
	PrefixConsensusPastVector

	// PrefixConsensusPastMetadata is the storage prefix for consensus mana past vector metadata storage.
	PrefixConsensusPastMetadata
)
View Source
const (
	// ConsensusBaseManaPastVectorMetadataStorageKey is the key to the consensus base vector metadata storage.
	ConsensusBaseManaPastVectorMetadataStorageKey = "consensusBaseManaVectorMetadata"
)

Variables

View Source
var (
	// ErrAlreadyUpdated is returned if mana is tried to be updated at a later time.
	ErrAlreadyUpdated = errors.New("already updated to a later timestamp")
	// ErrBaseManaNegative is returned if base mana will become negative.
	ErrBaseManaNegative = errors.New("base mana should never be negative")
	// ErrEffBaseManaNegative is returned if base mana will become negative.
	ErrEffBaseManaNegative = errors.New("effective base mana should never be negative")
	// ErrUnknownManaType is returned if mana type could not be identified.
	ErrUnknownManaType = errors.New("unknown mana type")
	// ErrNodeNotFoundInBaseManaVector is returned if the node is not found in the base mana vector.
	ErrNodeNotFoundInBaseManaVector = errors.New("node not present in base mana vector")
	// ErrInvalidWeightParameter is returned if an invalid weight parameter is passed.
	ErrInvalidWeightParameter = errors.New("invalid weight parameter, outside of [0,1]")
	// ErrInvalidTargetManaType is returned if a research base mana vector can't handle the target mana type.
	ErrInvalidTargetManaType = errors.New("invalid target mana type")
	// ErrUnknownManaEvent is returned if mana event type could not be identified.
	ErrUnknownManaEvent = errors.New("unknown mana event")
)

Functions

func IDFromPubKey

func IDFromPubKey(pubKey string) (iID identity.ID, err error)

IDFromPubKey returns the ID from the given public key.

func IDFromStr

func IDFromStr(idStr string) (iID identity.ID, err error)

IDFromStr decodes and returns an ID from base58.

Types

type AccessManaSnapshot

type AccessManaSnapshot struct {
	Value     float64
	Timestamp time.Time
}

AccessManaSnapshot defines the record for the aMana snapshot of one node.

func (*AccessManaSnapshot) Bytes

func (a *AccessManaSnapshot) Bytes() (serialized []byte)

Bytes returns a serialized version of the AccessManaSnapshot.

func (*AccessManaSnapshot) FromMarshalUtil

func (a *AccessManaSnapshot) FromMarshalUtil(marshalUtil *marshalutil.MarshalUtil) (err error)

FromMarshalUtil reads the AccessManaSnapshot from a MarshalUtil.

func (AccessManaSnapshot) String

func (a AccessManaSnapshot) String() (humanReadable string)

String returns a human-readable version of the AccessManaSnapshot.

type BaseMana

type BaseMana interface {
	BaseValue() float64
	// contains filtered or unexported methods
}

BaseMana is an interface for a collection of base mana values of a single node.

type BaseManaJSON

type BaseManaJSON struct {
	BaseMana float64 `json:"baseMana"`
}

BaseManaJSON is a JSON serializable form of a BaseMana.

type BaseManaVector

type BaseManaVector interface {
	// Type returns the type of the base mana vector (access/consensus).
	Type() Type
	// Size returns the size of the base mana vector.
	Size() int
	// Has tells if a certain node is present in the base mana vector.
	Has(identity.ID) bool
	// InitializeWithData loads the initial mana state into the base mana vector.
	InitializeWithData(map[identity.ID]float64)
	// Book books mana into the base mana vector.
	Book(*TxInfo)
	// BookEpoch books all outputs created and spent in an epoch.
	BookEpoch(created []*ledger.OutputWithMetadata, spent []*ledger.OutputWithMetadata)
	// GetMana returns the mana value of a node with default weights.
	GetMana(identity.ID) (float64, time.Time, error)
	// GetManaMap returns the map derived from the vector.
	GetManaMap() (NodeMap, time.Time, error)
	// GetHighestManaNodes returns the n highest mana nodes in descending order.
	GetHighestManaNodes(uint) ([]Node, time.Time, error)
	// GetHighestManaNodesFraction returns the highest mana that own 'p' percent of total mana.
	GetHighestManaNodesFraction(p float64) ([]Node, time.Time, error)
	// SetMana sets the base mana for a node.
	SetMana(identity.ID, BaseMana)
	// ForEach executes a callback function for each entry in the vector.
	ForEach(func(identity.ID, BaseMana) bool)
	// ToPersistables converts the BaseManaVector to a list of persistable mana objects.
	ToPersistables() []*PersistableBaseMana
	// FromPersistable fills the BaseManaVector from persistable mana objects.
	FromPersistable(*PersistableBaseMana) error
	// RemoveZeroNodes removes all zero mana nodes from the mana vector.
	RemoveZeroNodes()
}

BaseManaVector is an interface for vectors that store base mana values of nodes in the network.

func NewBaseManaVector

func NewBaseManaVector(manaType Type) BaseManaVector

NewBaseManaVector creates and returns a new base mana vector for the specified type.

type ConsensusBasePastManaVectorMetadata

type ConsensusBasePastManaVectorMetadata struct {
	objectstorage.StorableObjectFlags
	Timestamp time.Time `serix:"0" json:"timestamp"`
	// contains filtered or unexported fields
}

ConsensusBasePastManaVectorMetadata holds metadata for the past consensus mana vector.

func (*ConsensusBasePastManaVectorMetadata) Bytes

Bytes marshals the consensus base past mana vector metadata into a sequence of bytes.

func (*ConsensusBasePastManaVectorMetadata) FromBytes

FromBytes unmarshalls bytes into a metadata.

func (*ConsensusBasePastManaVectorMetadata) FromObjectStorage

func (c *ConsensusBasePastManaVectorMetadata) FromObjectStorage(_, value []byte) error

FromObjectStorage creates an ConsensusBasePastManaVectorMetadata from sequences of key and bytes.

func (*ConsensusBasePastManaVectorMetadata) ObjectStorageKey

func (c *ConsensusBasePastManaVectorMetadata) ObjectStorageKey() []byte

ObjectStorageKey returns the key of the metadata.

func (*ConsensusBasePastManaVectorMetadata) ObjectStorageValue

func (c *ConsensusBasePastManaVectorMetadata) ObjectStorageValue() []byte

ObjectStorageValue returns the bytes of the metadata.

type Event

type Event interface {
	// Type returns the type of the event.
	Type() byte
	// ToJSONSerializable returns a struct that can be serialized into JSON object.
	ToJSONSerializable() interface{}
	// ToPersistable returns an event that can be persisted.
	ToPersistable() *PersistableEvent
	// String returns a human readable version of the event.
	String() string
}

Event is the interface definition of an event.

func FromPersistableEvent

func FromPersistableEvent(p *PersistableEvent) (Event, error)

FromPersistableEvent parses a persistable event to a regular event.

type EventSlice

type EventSlice []Event

EventSlice is a slice of events.

func (EventSlice) Sort

func (e EventSlice) Sort()

Sort sorts a slice of events ASC by their timestamp with preference for RevokedEvent.

type InputInfo

type InputInfo struct {
	// Amount is the balance of the input.
	Amount float64
	// PledgeID is a map of mana types and the node to which the transaction that created the output pledges its mana type to.
	PledgeID map[Type]identity.ID
	// InputID is the input consumed.
	InputID utxo.OutputID
}

InputInfo holds mana related info about an input within a transaction.

type ManaBase

type ManaBase struct {
	model.Mutable[ManaBase, *ManaBase, manaBaseModel] `serix:"0"`
}

ManaBase holds information about the consensus base mana values of a single node.

func NewManaBase

func NewManaBase(value float64) *ManaBase

func (*ManaBase) BaseValue

func (m *ManaBase) BaseValue() float64

BaseValue returns the base mana value (BM1).

type ManaBaseVector

type ManaBaseVector struct {
	model.Mutable[ManaBaseVector, *ManaBaseVector, manaBaseVectorModel] `serix:"0"`
}

ManaBaseVector represents a base mana vector.

func (*ManaBaseVector) Book

func (m *ManaBaseVector) Book(txInfo *TxInfo)

Book books mana for a transaction.

func (*ManaBaseVector) BookEpoch

func (m *ManaBaseVector) BookEpoch(created []*ledger.OutputWithMetadata, spent []*ledger.OutputWithMetadata)

BookEpoch takes care of the booking of consensus mana for the given committed epoch.

func (*ManaBaseVector) ForEach

func (m *ManaBaseVector) ForEach(callback func(ID identity.ID, bm BaseMana) bool)

ForEach iterates over the vector and calls the provided callback.

func (*ManaBaseVector) FromPersistable

func (m *ManaBaseVector) FromPersistable(p *PersistableBaseMana) (err error)

FromPersistable fills the BaseManaVector from persistable mana objects.

func (*ManaBaseVector) GetHighestManaNodes

func (m *ManaBaseVector) GetHighestManaNodes(n uint) (res []Node, t time.Time, err error)

GetHighestManaNodes return the n-highest mana nodes in descending order. It also updates the mana values for each node. If n is zero, it returns all nodes.

func (*ManaBaseVector) GetHighestManaNodesFraction

func (m *ManaBaseVector) GetHighestManaNodesFraction(p float64) (res []Node, t time.Time, err error)

GetHighestManaNodesFraction returns the highest mana that own 'p' percent of total mana. It also updates the mana values for each node. If p is zero or greater than one, it returns all nodes.

func (*ManaBaseVector) GetMana

func (m *ManaBaseVector) GetMana(nodeID identity.ID) (manaAmount float64, t time.Time, err error)

GetMana returns the Effective Base Mana.

func (*ManaBaseVector) GetManaMap

func (m *ManaBaseVector) GetManaMap() (res NodeMap, t time.Time, err error)

GetManaMap returns mana perception of the node.

func (*ManaBaseVector) Has

func (m *ManaBaseVector) Has(nodeID identity.ID) bool

Has returns if the given node has mana defined in the vector.

func (*ManaBaseVector) InitializeWithData

func (m *ManaBaseVector) InitializeWithData(dataByNode map[identity.ID]float64)

InitializeWithData initializes the mana vector data.

func (*ManaBaseVector) RemoveZeroNodes

func (m *ManaBaseVector) RemoveZeroNodes()

RemoveZeroNodes removes the zero mana nodes from the vector.

func (*ManaBaseVector) SetMana

func (m *ManaBaseVector) SetMana(nodeID identity.ID, bm BaseMana)

SetMana sets the base mana for a node.

func (*ManaBaseVector) Size

func (m *ManaBaseVector) Size() int

Size returns the size of this mana vector.

func (*ManaBaseVector) ToPersistables

func (m *ManaBaseVector) ToPersistables() []*PersistableBaseMana

ToPersistables converts the baseManaVector to a list of persistable mana objects.

func (*ManaBaseVector) Type

func (m *ManaBaseVector) Type() Type

Type returns the type of this mana vector.

func (*ManaBaseVector) Vector

func (m *ManaBaseVector) Vector() map[identity.ID]*ManaBase

Vector returns the ManaBase vector.

type ManaEvents

type ManaEvents struct {
	// Fired when mana was pledged to a node.
	Pledged *event.Event[*PledgedEvent]
	// Fired when mana was revoked from a node.
	Revoked *event.Event[*RevokedEvent]
	// Fired when mana of a node was updated.
	Updated *event.Event[*UpdatedEvent]
}

ManaEvents represents events happening in the mana package.

var Events *ManaEvents

type ManaRetrievalFunc

type ManaRetrievalFunc func(identity.ID, ...time.Time) (float64, time.Time, error)

ManaRetrievalFunc returns the mana value of a node with default weights.

type ManaVectorUpdateEvent added in v0.9.6

type ManaVectorUpdateEvent struct {
	// EI is the index of committable epoch.
	EI epoch.Index
	// Spent are outputs that is spent in a transaction.
	Spent []*ledger.OutputWithMetadata
	// Created are the outputs created in a transaction.
	Created []*ledger.OutputWithMetadata
}

ManaVectorUpdateEvent is a container that acts as a dictionary for the EpochCommittable event related parameters.

type Node

type Node struct {
	ID   identity.ID
	Mana float64
}

Node represents a node and its mana value.

func (Node) ToNodeStr

func (n Node) ToNodeStr() NodeStr

ToNodeStr converts a Node to a Nodestr

type NodeMap

type NodeMap map[identity.ID]float64

NodeMap is a map of nodeID and mana value.

func (NodeMap) GetPercentile

func (n NodeMap) GetPercentile(node identity.ID) (float64, error)

GetPercentile returns the top percentile the node belongs to relative to the network in terms of mana.

func (NodeMap) ToNodeStrList

func (n NodeMap) ToNodeStrList() []NodeStr

ToNodeStrList converts a NodeMap to list of NodeStr.

type NodeMapStr

type NodeMapStr map[string]float64

NodeMapStr is a NodeMap but with string id.

type NodeStr

type NodeStr struct {
	ShortNodeID string  `json:"shortNodeID"`
	NodeID      string  `json:"nodeID"`
	Mana        float64 `json:"mana"`
}

NodeStr defines a node and its mana value. The node ID is stringified.

type PersistableBaseMana

type PersistableBaseMana struct {
	model.Storable[identity.ID, PersistableBaseMana, *PersistableBaseMana, persistableBaseManaModel] `serix:"0"`
}

PersistableBaseMana represents a base mana vector that can be persisted.

func NewPersistableBaseMana

func NewPersistableBaseMana(nodeID identity.ID, manaType Type, baseValues, effectiveValues []float64, lastUpdated time.Time) *PersistableBaseMana

func (*PersistableBaseMana) BaseValues

func (v *PersistableBaseMana) BaseValues() []float64

func (*PersistableBaseMana) EffectiveValues

func (v *PersistableBaseMana) EffectiveValues() []float64

func (*PersistableBaseMana) LastUpdated

func (v *PersistableBaseMana) LastUpdated() time.Time

func (*PersistableBaseMana) ManaType

func (v *PersistableBaseMana) ManaType() Type

func (*PersistableBaseMana) NodeID

func (v *PersistableBaseMana) NodeID() identity.ID

type PersistableEvent

type PersistableEvent struct {
	objectstorage.StorableObjectFlags
	Type          byte               `serix:"0"` // pledge or revoke
	ManaType      Type               `serix:"1"` // access or consensus
	NodeID        identity.ID        `serix:"2"`
	Time          time.Time          `serix:"3"`
	TransactionID utxo.TransactionID `serix:"4"`
	Amount        float64            `serix:"5"`
	InputID       utxo.OutputID      `serix:"6"` // for revoke event
	// contains filtered or unexported fields
}

PersistableEvent is a persistable event.

func (*PersistableEvent) Bytes

func (p *PersistableEvent) Bytes() []byte

Bytes marshals the persistable event into a sequence of bytes.

func (*PersistableEvent) FromBytes

func (p *PersistableEvent) FromBytes(data []byte) (result *PersistableEvent, err error)

FromBytes unmarshalls bytes into a persistable event.

func (*PersistableEvent) FromObjectStorage

func (p *PersistableEvent) FromObjectStorage(_, value []byte) error

FromObjectStorage creates an PersistableEvent from sequences of key and bytes.

func (*PersistableEvent) ObjectStorageKey

func (p *PersistableEvent) ObjectStorageKey() []byte

ObjectStorageKey returns the key of the persistable mana.

func (*PersistableEvent) ObjectStorageValue

func (p *PersistableEvent) ObjectStorageValue() []byte

ObjectStorageValue returns the bytes of the event.

func (*PersistableEvent) ToStringKeys

func (p *PersistableEvent) ToStringKeys() []string

ToStringKeys returns the keys (properties) of the persistable event as a list of strings.

func (*PersistableEvent) ToStringValues

func (p *PersistableEvent) ToStringValues() []string

ToStringValues returns the persistableEvents values as a string array.

type PledgedEvent

type PledgedEvent struct {
	NodeID        identity.ID
	Amount        float64
	Time          time.Time
	ManaType      Type // access or consensus
	TransactionID utxo.TransactionID
}

PledgedEvent is the struct that is passed along with triggering a Pledged event.

func (*PledgedEvent) String

func (p *PledgedEvent) String() string

String returns a human readable version of the event.

func (*PledgedEvent) Timestamp

func (p *PledgedEvent) Timestamp() time.Time

Timestamp returns time the event was fired.

func (*PledgedEvent) ToJSONSerializable

func (p *PledgedEvent) ToJSONSerializable() interface{}

ToJSONSerializable returns a struct that can be serialized into JSON object.

func (*PledgedEvent) ToPersistable

func (p *PledgedEvent) ToPersistable() *PersistableEvent

ToPersistable returns an event that can be persisted.

func (*PledgedEvent) Type

func (p *PledgedEvent) Type() byte

Type returns the type of the event.

type PledgedEventJSON

type PledgedEventJSON struct {
	ManaType string  `json:"manaType"`
	NodeID   string  `json:"nodeID"`
	Time     int64   `json:"time"`
	TxID     string  `json:"txID"`
	Amount   float64 `json:"amount"`
}

PledgedEventJSON is a JSON serializable form of a PledgedEvent.

type RevokedEvent

type RevokedEvent struct {
	NodeID        identity.ID
	Amount        float64
	Time          time.Time
	ManaType      Type // shall only be consensus for now
	TransactionID utxo.TransactionID
	InputID       utxo.OutputID
}

RevokedEvent is the struct that is passed along with triggering a Revoked event.

func (*RevokedEvent) String

func (r *RevokedEvent) String() string

String returns a human readable version of the event.

func (*RevokedEvent) Timestamp

func (r *RevokedEvent) Timestamp() time.Time

Timestamp returns time the event was fired.

func (*RevokedEvent) ToJSONSerializable

func (r *RevokedEvent) ToJSONSerializable() interface{}

ToJSONSerializable returns a struct that can be serialized into JSON object.

func (*RevokedEvent) ToPersistable

func (r *RevokedEvent) ToPersistable() *PersistableEvent

ToPersistable returns an event that can be persisted.

func (*RevokedEvent) Type

func (r *RevokedEvent) Type() byte

Type returns the type of the event.

type RevokedEventJSON

type RevokedEventJSON struct {
	ManaType string  `json:"manaType"`
	NodeID   string  `json:"nodeID"`
	Time     int64   `json:"time"`
	TxID     string  `json:"txID"`
	Amount   float64 `json:"amount"`
	InputID  string  `json:"inputID"`
}

RevokedEventJSON is a JSON serializable form of a RevokedEvent.

type SnapshotNode

type SnapshotNode struct {
	AccessMana       *AccessManaSnapshot
	SortedTxSnapshot SortedTxSnapshot
}

SnapshotNode defines the record for the mana snapshot of one node.

func (*SnapshotNode) AccessManaUpdateTime

func (s *SnapshotNode) AccessManaUpdateTime() (maxTime time.Time)

func (*SnapshotNode) AdjustAccessManaUpdateTime

func (s *SnapshotNode) AdjustAccessManaUpdateTime(diff time.Duration)

func (*SnapshotNode) Bytes

func (s *SnapshotNode) Bytes() (serialized []byte)

Bytes returns a serialized version of the SnapshotNode.

func (*SnapshotNode) FromMarshalUtil

func (s *SnapshotNode) FromMarshalUtil(marshalUtil *marshalutil.MarshalUtil) (err error)

func (*SnapshotNode) String

func (s *SnapshotNode) String() (humanReadable string)

String returns a human-readable version of the SnapshotNode.

type SortedTxSnapshot

type SortedTxSnapshot []*TxSnapshot

SortedTxSnapshot defines a list of SnapshotInfo sorted by timestamp.

func (SortedTxSnapshot) Bytes

func (s SortedTxSnapshot) Bytes() (serialized []byte)

func (*SortedTxSnapshot) FromMarshalUtil

func (s *SortedTxSnapshot) FromMarshalUtil(marshalUtil *marshalutil.MarshalUtil) (err error)

func (SortedTxSnapshot) Len

func (s SortedTxSnapshot) Len() int

func (SortedTxSnapshot) Less

func (s SortedTxSnapshot) Less(i, j int) bool

func (SortedTxSnapshot) String

func (s SortedTxSnapshot) String() (humanReadable string)

func (SortedTxSnapshot) Swap

func (s SortedTxSnapshot) Swap(i, j int)

type TxInfo

type TxInfo struct {
	// Timestamp is the timestamp of the transaction.
	TimeStamp time.Time
	// TransactionID is the ID of the transaction.
	TransactionID utxo.TransactionID
	// TotalBalance is the amount of funds being transferred via the transaction.
	TotalBalance float64
	// PledgeID is a map of mana types and the node to which this transaction pledges its mana type to.
	PledgeID map[Type]identity.ID
	// InputInfos is a slice of InputInfo that holds mana related info about each input within the transaction.
	InputInfos []InputInfo
}

TxInfo holds information related to the transaction which we are processing for mana calculation.

type TxSnapshot

type TxSnapshot struct {
	Value     float64
	TxID      utxo.TransactionID
	Timestamp time.Time
}

TxSnapshot defines the record of one transaction.

func (*TxSnapshot) Bytes

func (t *TxSnapshot) Bytes() (serialized []byte)

func (*TxSnapshot) FromMarshalUtil

func (t *TxSnapshot) FromMarshalUtil(marshalUtil *marshalutil.MarshalUtil) (err error)

func (*TxSnapshot) String

func (t *TxSnapshot) String() (humanReadable string)

String returns a human-readable version of the TxSnapshot.

type Type

type Type byte

Type defines if mana is access or consensus type of mana.

const (
	// AccessMana is mana associated with access to the network.
	AccessMana Type = iota
	// ConsensusMana is mana associated with consensus weights in the network.
	ConsensusMana
	// WeightedMana is a weighted combination of Mana 1 (consensus) and Mana 2 (access) for research purposes.
	WeightedMana
	// ResearchAccess is a special type of WeightedMana, that targets access pledges.
	ResearchAccess
	// ResearchConsensus is a special type of WeightedMana, that targets consensus pledges.
	ResearchConsensus
)

func TypeFromString

func TypeFromString(stringType string) (Type, error)

TypeFromString parses a string and returns the type of mana it defines.

func (Type) String

func (t Type) String() string

String returns a string representation of the type of mana.

type UpdatedEvent

type UpdatedEvent struct {
	NodeID   identity.ID
	OldMana  BaseMana
	NewMana  BaseMana
	ManaType Type // access or consensus
}

UpdatedEvent is the struct that is passed along with triggering an Updated event.

func (*UpdatedEvent) String

func (u *UpdatedEvent) String() string

String returns a human readable version of the event.

func (*UpdatedEvent) ToJSONSerializable

func (u *UpdatedEvent) ToJSONSerializable() interface{}

ToJSONSerializable returns a struct that can be serialized into JSON object.

func (*UpdatedEvent) ToPersistable

func (u *UpdatedEvent) ToPersistable() *PersistableEvent

ToPersistable converts the event to a persistable event.

func (*UpdatedEvent) Type

func (u *UpdatedEvent) Type() byte

Type returns the type of the event.

type UpdatedEventJSON

type UpdatedEventJSON struct {
	NodeID   string      `json:"nodeID"`
	OldMana  interface{} `json:"oldMana"`
	NewMana  interface{} `json:"newMana"`
	ManaType string      `json:"manaType"`
}

UpdatedEventJSON is a JSON serializable form of an UpdatedEvent.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL