-
Notifications
You must be signed in to change notification settings - Fork 651
/
consensus.go
133 lines (103 loc) · 4.15 KB
/
consensus.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
// Copyright (C) 2019-2024, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.
package snowball
import (
"fmt"
"github.com/ava-labs/avalanchego/ids"
"github.com/ava-labs/avalanchego/utils/bag"
)
// Consensus represents a general snow instance that can be used directly to
// process the results of network queries.
type Consensus interface {
fmt.Stringer
// Adds a new choice to vote on
Add(newChoice ids.ID)
// Returns the currently preferred choice to be finalized
Preference() ids.ID
// RecordPoll records the results of a network poll. Assumes all choices
// have been previously added.
//
// If the consensus instance was not previously finalized, this function
// will return true if the poll was successful and false if the poll was
// unsuccessful.
//
// If the consensus instance was previously finalized, the function may
// return true or false.
RecordPoll(votes bag.Bag[ids.ID]) bool
// RecordUnsuccessfulPoll resets the snowflake counters of this consensus
// instance
RecordUnsuccessfulPoll()
// Return whether a choice has been finalized
Finalized() bool
}
// Factory produces Nnary and Unary decision instances
type Factory interface {
NewNnary(params Parameters, choice ids.ID) Nnary
NewUnary(params Parameters) Unary
}
// Nnary is a snow instance deciding between an unbounded number of values.
// The caller samples k nodes and then calls
// 1. RecordSuccessfulPoll if choice collects >= alphaConfidence votes
// 2. RecordPollPreference if choice collects >= alphaPreference votes
// 3. RecordUnsuccessfulPoll otherwise
type Nnary interface {
fmt.Stringer
// Adds a new possible choice
Add(newChoice ids.ID)
// Returns the currently preferred choice to be finalized
Preference() ids.ID
// RecordSuccessfulPoll records a successful poll towards finalizing the
// specified choice. Assumes the choice was previously added.
RecordSuccessfulPoll(choice ids.ID)
// RecordPollPreference records a poll that preferred the specified choice
// but did not contribute towards finalizing the specified choice. Assumes
// the choice was previously added.
RecordPollPreference(choice ids.ID)
// RecordUnsuccessfulPoll resets the snowflake counter of this instance
RecordUnsuccessfulPoll()
// Return whether a choice has been finalized
Finalized() bool
}
// Binary is a snow instance deciding between two values.
// The caller samples k nodes and then calls
// 1. RecordSuccessfulPoll if choice collects >= alphaConfidence votes
// 2. RecordPollPreference if choice collects >= alphaPreference votes
// 3. RecordUnsuccessfulPoll otherwise
type Binary interface {
fmt.Stringer
// Returns the currently preferred choice to be finalized
Preference() int
// RecordSuccessfulPoll records a successful poll towards finalizing the
// specified choice
RecordSuccessfulPoll(choice int)
// RecordPollPreference records a poll that preferred the specified choice
// but did not contribute towards finalizing the specified choice
RecordPollPreference(choice int)
// RecordUnsuccessfulPoll resets the snowflake counter of this instance
RecordUnsuccessfulPoll()
// Return whether a choice has been finalized
Finalized() bool
}
// Unary is a snow instance deciding on one value.
// The caller samples k nodes and then calls
// 1. RecordSuccessfulPoll if choice collects >= alphaConfidence votes
// 2. RecordPollPreference if choice collects >= alphaPreference votes
// 3. RecordUnsuccessfulPoll otherwise
type Unary interface {
fmt.Stringer
// RecordSuccessfulPoll records a successful poll that reaches an alpha
// confidence threshold.
RecordSuccessfulPoll()
// RecordPollPreference records a poll that receives an alpha preference
// threshold, but not an alpha confidence threshold.
RecordPollPreference()
// RecordUnsuccessfulPoll resets the snowflake counter of this instance
RecordUnsuccessfulPoll()
// Return whether a choice has been finalized
Finalized() bool
// Returns a new binary snowball instance with the agreement parameters
// transferred. Takes in the new beta value and the original choice
Extend(beta, originalPreference int) Binary
// Returns a new unary snowflake instance with the same state
Clone() Unary
}