coordinator

package
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2023 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoTipsGiven is returned when no tips were given to issue a checkpoint.
	ErrNoTipsGiven = errors.New("no tips given")
	// ErrNetworkBootstrapped is returned when the flag for bootstrap network was given, but a state file already exists.
	ErrNetworkBootstrapped = errors.New("network already bootstrapped")
	// ErrNodeLoadTooHigh is returned if the backpressure func says the node load is too high.
	ErrNodeLoadTooHigh = errors.New("node load too high")
	// ErrMilestoneTimestampDidNotIncrease is returned when the new milestone timestamp is not newer than the last milestone's timestamp.
	ErrMilestoneTimestampDidNotIncrease = errors.New("new milestone timestamp must be newer than the last milestone's timestamp")
)
View Source 
var (
	// ErrQuorumMerkleTreeHashMismatch is fired when a client in the quorum returns a different merkle tree hash.
	ErrQuorumMerkleTreeHashMismatch = errors.New("coordinator quorum merkle tree hash mismatch")
	// ErrQuorumGroupNoAnswer is fired when none of the clients in a quorum group answers.
	ErrQuorumGroupNoAnswer = errors.New("coordinator quorum group did not answer in time")
)

Functions

func CheckpointCaller 

func CheckpointCaller(handler interface{}, params ...interface{})

CheckpointCaller is used to signal issued checkpoints.

func MilestoneCaller 

func MilestoneCaller(handler interface{}, params ...interface{})

MilestoneCaller is used to signal issued milestones.

func QuorumFinishedCaller 

func QuorumFinishedCaller(handler interface{}, params ...interface{})

QuorumFinishedCaller is used to signal a finished quorum call.

func WithBlockBackups added in v1.0.0 

func WithBlockBackups(blockBackupsEnabled bool, blockBackupsFolderPath string) options.Option[Coordinator]

WithBlockBackups defines whether all blocks that are issued by the coordinator should be stored to disk before being submitted to the network.

func WithDebugFakeMilestoneTimestamps added in v1.0.0 

func WithDebugFakeMilestoneTimestamps(debugFakeMilestoneTimestamps bool) options.Option[Coordinator]

WithDebugFakeMilestoneTimestamps defines whether the coordinator will fake timestamps of milestones if the interval is below 1s (use for tests only!)

func WithLogger 

func WithLogger(log *logger.Logger) options.Option[Coordinator]

WithLogger enables logging within the coordinator.

func WithMilestoneInterval 

func WithMilestoneInterval(milestoneInterval time.Duration) options.Option[Coordinator]

WithMilestoneInterval defines interval milestones are issued.

func WithMilestoneTimeout added in v1.0.0 

func WithMilestoneTimeout(milestoneTimeout time.Duration) options.Option[Coordinator]

WithMilestoneTimeout defines the duration after which an event is triggered if no new milestones are received.

func WithQuorum 

func WithQuorum(quorumEnabled bool, quorumGroups map[string][]*QuorumClientConfig, timeout time.Duration) options.Option[Coordinator]

WithQuorum defines a quorum, which is used to check the correct ledger state of the coordinator. If no quorumGroups are given, the quorum is disabled.

func WithSigningRetryAmount 

func WithSigningRetryAmount(amount int) options.Option[Coordinator]

WithSigningRetryAmount defines signing retry amount.

func WithSigningRetryTimeout 

func WithSigningRetryTimeout(timeout time.Duration) options.Option[Coordinator]

WithSigningRetryTimeout defines signing retry timeout.

func WithStateFilePath 

func WithStateFilePath(stateFilePath string) options.Option[Coordinator]

WithStateFilePath defines the path to the state file of the coordinator.

Types

type BackPressureFunc 

type BackPressureFunc func() bool

BackPressureFunc is a function which tells the Coordinator to stop issuing milestones and checkpoints under high load.

type ComputeMilestoneMerkleRoots 

type ComputeMilestoneMerkleRoots = func(ctx context.Context, index iotago.MilestoneIndex, timestamp uint32, parents iotago.BlockIDs, previousMilestoneID iotago.MilestoneID) (*MilestoneMerkleRoots, error)

type Coordinator 

type Coordinator struct {
	// the logger used to log events.
	*logger.WrappedLogger

	// events of the coordinator.
	Events *Events
	// contains filtered or unexported fields
}

Coordinator is used to issue signed blocks, called "milestones" to secure an IOTA network and prevent double spends.

func New 

func New(
	merkleRootFunc ComputeMilestoneMerkleRoots,
	nodeSyncedFunc IsNodeSyncedFunc,
	protoParamsFunc ProtocolParameteresFunc,
	signerProvider MilestoneSignerProvider,
	migratorService *migrator.Service,
	treasuryOutputFunc UnspentTreasuryOutputFunc,
	sendBlockFunc SendBlockFunc,
	opts ...options.Option[Coordinator]) (*Coordinator, error)

New creates a new coordinator instance.

func (*Coordinator) AddBackPressureFunc 

func (coo *Coordinator) AddBackPressureFunc(bpFunc BackPressureFunc)

AddBackPressureFunc adds a BackPressureFunc. This function can be called multiple times to add additional BackPressureFunc.

func (*Coordinator) Bootstrap 

func (coo *Coordinator) Bootstrap() (iotago.BlockID, error)

Bootstrap creates the first milestone, if the network was not bootstrapped yet. Returns critical errors.

func (*Coordinator) DebugFakeMilestoneTimestamps added in v1.0.0 

func (coo *Coordinator) DebugFakeMilestoneTimestamps() bool

func (*Coordinator) InitState 

func (coo *Coordinator) InitState(bootstrap bool, startIndex iotago.MilestoneIndex, latestMilestone *LatestMilestoneInfo) error

InitState loads an existing state file or bootstraps the network. All errors are critical.

func (*Coordinator) Interval 

func (coo *Coordinator) Interval() time.Duration

Interval returns the interval milestones should be issued.

func (*Coordinator) IssueCheckpoint 

func (coo *Coordinator) IssueCheckpoint(checkpointIndex int, lastCheckpointBlockID iotago.BlockID, tips iotago.BlockIDs) (iotago.BlockID, error)

IssueCheckpoint tries to create and send a "checkpoint" to the network. a checkpoint can contain multiple chained blocks to reference big parts of the unreferenced cone. this is done to keep the confirmation rate as high as possible, even if there is an attack ongoing. new checkpoints always reference the last checkpoint or the last milestone if it is the first checkpoint after a new milestone.

func (*Coordinator) IssueMilestone 

func (coo *Coordinator) IssueMilestone(parents iotago.BlockIDs) (iotago.BlockID, error)

IssueMilestone creates the next milestone. Returns non-critical and critical errors.

func (*Coordinator) QuorumStats 

func (coo *Coordinator) QuorumStats() []QuorumClientStatistic

QuorumStats returns statistics about the response time and errors of every node in the quorum.

func (*Coordinator) ResetMilestoneTimeoutTicker added in v1.0.0 

func (coo *Coordinator) ResetMilestoneTimeoutTicker()

ResetMilestoneTimeoutTicker stops a running milestone timeout ticker and starts a new one. MilestoneTimeout event is fired periodically if ResetMilestoneTimeoutTicker is not called within milestoneTimeout.

func (*Coordinator) State 

func (coo *Coordinator) State() *State

State returns the current state of the coordinator.

func (*Coordinator) StopMilestoneTimeoutTicker added in v1.0.0 

func (coo *Coordinator) StopMilestoneTimeoutTicker()

StopMilestoneTimeoutTicker stops the milestone timeout ticker.

type Events 

type Events struct {
	// Fired when a checkpoint block is issued.
	// params: checkpointIndex int, tipIndex int, tipsTotal int, blockID iotago.BlockID
	IssuedCheckpointBlock *event.Event4[int, int, int, iotago.BlockID]
	// Fired when a milestone is issued.
	// params: index iotago.MilestoneIndex, milestoneID iotago.MilestoneID, blockID iotago.BlockID
	IssuedMilestone *event.Event3[iotago.MilestoneIndex, iotago.MilestoneID, iotago.BlockID]
	// SoftError is triggered when a soft error is encountered.
	SoftError *event.Event1[error]
	// QuorumFinished is triggered after a coordinator quorum call was finished.
	QuorumFinished *event.Event1[*QuorumFinishedResult]
	// MilestoneTimeout is triggered if no new milestones are received for some time.
	MilestoneTimeout *event.Event
}

Events are the events issued by the coordinator.

type InMemoryEd25519MilestoneIndexSigner 

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

InMemoryEd25519MilestoneIndexSigner is an in memory signer for a particular milestone.

func (*InMemoryEd25519MilestoneIndexSigner) PublicKeys 

func (s *InMemoryEd25519MilestoneIndexSigner) PublicKeys() []iotago.MilestonePublicKey

PublicKeys returns a slice of the used public keys.

func (*InMemoryEd25519MilestoneIndexSigner) PublicKeysSet 

func (s *InMemoryEd25519MilestoneIndexSigner) PublicKeysSet() iotago.MilestonePublicKeySet

PublicKeysSet returns a map of the used public keys.

func (*InMemoryEd25519MilestoneIndexSigner) SigningFunc 

func (s *InMemoryEd25519MilestoneIndexSigner) SigningFunc() iotago.MilestoneSigningFunc

SigningFunc returns a function to sign the particular milestone.

type InMemoryEd25519MilestoneSignerProvider 

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

InMemoryEd25519MilestoneSignerProvider provides InMemoryEd25519MilestoneIndexSigner.

func NewInMemoryEd25519MilestoneSignerProvider 

func NewInMemoryEd25519MilestoneSignerProvider(privateKeys []ed25519.PrivateKey, keyManager *keymanager.KeyManager, publicKeysCount int) *InMemoryEd25519MilestoneSignerProvider

NewInMemoryEd25519MilestoneSignerProvider creates a new InMemoryEd25519MilestoneSignerProvider.

func (*InMemoryEd25519MilestoneSignerProvider) MilestoneIndexSigner 

func (p *InMemoryEd25519MilestoneSignerProvider) MilestoneIndexSigner(index iotago.MilestoneIndex) MilestoneIndexSigner

MilestoneIndexSigner returns a new signer for the milestone index.

func (*InMemoryEd25519MilestoneSignerProvider) PublicKeysCount 

func (p *InMemoryEd25519MilestoneSignerProvider) PublicKeysCount() int

PublicKeysCount returns the amount of public keys in a milestone.

type InsecureRemoteEd25519MilestoneIndexSigner 

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

InsecureRemoteEd25519MilestoneIndexSigner is an in memory signer for a particular milestone.

func (*InsecureRemoteEd25519MilestoneIndexSigner) PublicKeys 

func (s *InsecureRemoteEd25519MilestoneIndexSigner) PublicKeys() []iotago.MilestonePublicKey

PublicKeys returns a slice of the used public keys.

func (*InsecureRemoteEd25519MilestoneIndexSigner) PublicKeysSet 

func (s *InsecureRemoteEd25519MilestoneIndexSigner) PublicKeysSet() iotago.MilestonePublicKeySet

PublicKeysSet returns a map of the used public keys.

func (*InsecureRemoteEd25519MilestoneIndexSigner) SigningFunc 

func (s *InsecureRemoteEd25519MilestoneIndexSigner) SigningFunc() iotago.MilestoneSigningFunc

SigningFunc returns a function to sign the particular milestone.

type InsecureRemoteEd25519MilestoneSignerProvider 

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

InsecureRemoteEd25519MilestoneSignerProvider provides InsecureRemoteEd25519MilestoneIndexSigner.

func NewInsecureRemoteEd25519MilestoneSignerProvider 

func NewInsecureRemoteEd25519MilestoneSignerProvider(remoteEndpoint string, keyManager *keymanager.KeyManager, publicKeysCount int) *InsecureRemoteEd25519MilestoneSignerProvider

NewInsecureRemoteEd25519MilestoneSignerProvider creates a new InsecureRemoteEd25519MilestoneSignerProvider.

func (*InsecureRemoteEd25519MilestoneSignerProvider) MilestoneIndexSigner 

func (p *InsecureRemoteEd25519MilestoneSignerProvider) MilestoneIndexSigner(index iotago.MilestoneIndex) MilestoneIndexSigner

MilestoneIndexSigner returns a new signer for the milestone index.

func (*InsecureRemoteEd25519MilestoneSignerProvider) PublicKeysCount 

func (p *InsecureRemoteEd25519MilestoneSignerProvider) PublicKeysCount() int

PublicKeysCount returns the amount of public keys in a milestone.

type IsNodeSyncedFunc 

type IsNodeSyncedFunc = func() bool

IsNodeSyncedFunc should only return true if the node connected to the coordinator is synced.

type LatestMilestoneInfo 

type LatestMilestoneInfo struct {
	Index       iotago.MilestoneIndex
	Timestamp   uint32
	MilestoneID iotago.MilestoneID
}

LatestMilestoneInfo contains the info of the latest milestone the connected node knows.

type LatestTreasuryOutput 

type LatestTreasuryOutput struct {
	MilestoneID iotago.MilestoneID
	Amount      uint64
}

LatestTreasuryOutput represents the latest treasury output created by the last milestone that contained a migration.

type MilestoneIndexSigner 

type MilestoneIndexSigner interface {
	// PublicKeys returns a slice of the used public keys.
	PublicKeys() []iotago.MilestonePublicKey
	// PublicKeysSet returns a map of the used public keys.
	PublicKeysSet() iotago.MilestonePublicKeySet
	// SigningFunc returns a function to sign the particular milestone.
	SigningFunc() iotago.MilestoneSigningFunc
}

MilestoneIndexSigner is a signer for a particular milestone.

type MilestoneMerkleRoots 

type MilestoneMerkleRoots struct {
	// InclusionMerkleRoot is the root of the merkle tree containing the hash of all included blocks.
	InclusionMerkleRoot iotago.MilestoneMerkleProof
	// AppliedMerkleRoot is the root of the merkle tree containing the hash of all include blocks that mutate the ledger.
	AppliedMerkleRoot iotago.MilestoneMerkleProof
}

MilestoneMerkleRoots contains the merkle roots calculated by whiteflag confirmation.

type MilestoneSignerProvider 

type MilestoneSignerProvider interface {
	// MilestoneIndexSigner returns a new signer for the milestone index.
	MilestoneIndexSigner(index iotago.MilestoneIndex) MilestoneIndexSigner
	// PublicKeysCount returns the amount of public keys in a milestone.
	PublicKeysCount() int
}

MilestoneSignerProvider provides milestone signers.

type ProtocolParameteresFunc added in v1.0.0 

type ProtocolParameteresFunc = func() *iotago.ProtocolParameters

ProtocolParameteresFunc should return the current valid protocol parameters.

type QuorumClientConfig 

type QuorumClientConfig struct {
	// optional alias of the quorum client.
	Alias string `json:"alias" koanf:"alias"`
	// baseURL of the quorum client.
	BaseURL string `json:"baseUrl" koanf:"baseUrl"`
	// optional username for basic auth.
	Username string `json:"username" koanf:"username"`
	// optional password for basic auth.
	Password string `json:"password" koanf:"password"`
}

QuorumClientConfig holds the configuration of a quorum client.

type QuorumClientStatistic 

type QuorumClientStatistic struct {
	// name of the quorum group the client is member of.
	Group string
	// optional alias of the quorum client.
	Alias string
	// baseURL of the quorum client.
	BaseURL string
	// last response time of the whiteflag API call.
	ResponseTimeSeconds float64
	// error of last whiteflag API call.
	Error error
}

QuorumClientStatistic holds statistics of a quorum client.

type QuorumFinishedResult 

type QuorumFinishedResult struct {
	Duration time.Duration
	Err      error
}

QuorumFinishedResult holds statistics of a finished quorum.

type SendBlockFunc 

type SendBlockFunc = func(block *iotago.Block, msIndex ...iotago.MilestoneIndex) (iotago.BlockID, error)

SendBlockFunc is a function which sends a block to the network.

type State 

type State struct {
	LatestMilestoneIndex   iotago.MilestoneIndex
	LatestMilestoneBlockID iotago.BlockID
	LatestMilestoneID      iotago.MilestoneID
	LatestMilestoneTime    time.Time
}

State stores the latest state of the coordinator.

func (*State) MarshalJSON 

func (cs *State) MarshalJSON() ([]byte, error)

func (*State) UnmarshalJSON 

func (cs *State) UnmarshalJSON(data []byte) error

type UnspentTreasuryOutputFunc 

type UnspentTreasuryOutputFunc = func() (*LatestTreasuryOutput, error)

UnspentTreasuryOutputFunc should return the latest unspent LatestTreasuryOutput.

Source Files

View all Source files

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.