github.com/MetalBlockchain/metalgo@v1.11.9/snow/consensus/snowball/consensus.go (about)

     1  // Copyright (C) 2019-2024, Ava Labs, Inc. All rights reserved.
     2  // See the file LICENSE for licensing terms.
     3  
     4  package snowball
     5  
     6  import (
     7  	"fmt"
     8  
     9  	"github.com/MetalBlockchain/metalgo/ids"
    10  	"github.com/MetalBlockchain/metalgo/utils/bag"
    11  )
    12  
    13  // Consensus represents a general snow instance that can be used directly to
    14  // process the results of network queries.
    15  type Consensus interface {
    16  	fmt.Stringer
    17  
    18  	// Adds a new choice to vote on
    19  	Add(newChoice ids.ID)
    20  
    21  	// Returns the currently preferred choice to be finalized
    22  	Preference() ids.ID
    23  
    24  	// RecordPoll records the results of a network poll. Assumes all choices
    25  	// have been previously added.
    26  	//
    27  	// If the consensus instance was not previously finalized, this function
    28  	// will return true if the poll was successful and false if the poll was
    29  	// unsuccessful.
    30  	//
    31  	// If the consensus instance was previously finalized, the function may
    32  	// return true or false.
    33  	RecordPoll(votes bag.Bag[ids.ID]) bool
    34  
    35  	// RecordUnsuccessfulPoll resets the snowflake counters of this consensus
    36  	// instance
    37  	RecordUnsuccessfulPoll()
    38  
    39  	// Return whether a choice has been finalized
    40  	Finalized() bool
    41  }
    42  
    43  // Factory produces Nnary and Unary decision instances
    44  type Factory interface {
    45  	NewNnary(params Parameters, choice ids.ID) Nnary
    46  	NewUnary(params Parameters) Unary
    47  }
    48  
    49  // Nnary is a snow instance deciding between an unbounded number of values.
    50  // The caller samples k nodes and calls RecordPoll with the result.
    51  // RecordUnsuccessfulPoll resets the confidence counters when one or
    52  // more consecutive polls fail to reach alphaPreference votes.
    53  type Nnary interface {
    54  	fmt.Stringer
    55  
    56  	// Adds a new possible choice
    57  	Add(newChoice ids.ID)
    58  
    59  	// Returns the currently preferred choice to be finalized
    60  	Preference() ids.ID
    61  
    62  	// RecordPoll records the results of a network poll
    63  	RecordPoll(count int, choice ids.ID)
    64  
    65  	// RecordUnsuccessfulPoll resets the snowflake counter of this instance
    66  	RecordUnsuccessfulPoll()
    67  
    68  	// Return whether a choice has been finalized
    69  	Finalized() bool
    70  }
    71  
    72  // Binary is a snow instance deciding between two values.
    73  // The caller samples k nodes and calls RecordPoll with the result.
    74  // RecordUnsuccessfulPoll resets the confidence counters when one or
    75  // more consecutive polls fail to reach alphaPreference votes.
    76  type Binary interface {
    77  	fmt.Stringer
    78  
    79  	// Returns the currently preferred choice to be finalized
    80  	Preference() int
    81  
    82  	// RecordPoll records the results of a network poll
    83  	RecordPoll(count, choice int)
    84  
    85  	// RecordUnsuccessfulPoll resets the snowflake counter of this instance
    86  	RecordUnsuccessfulPoll()
    87  
    88  	// Return whether a choice has been finalized
    89  	Finalized() bool
    90  }
    91  
    92  // Unary is a snow instance deciding on one value.
    93  // The caller samples k nodes and calls RecordPoll with the result.
    94  // RecordUnsuccessfulPoll resets the confidence counters when one or
    95  // more consecutive polls fail to reach alphaPreference votes.
    96  type Unary interface {
    97  	fmt.Stringer
    98  
    99  	// RecordPoll records the results of a network poll
   100  	RecordPoll(count int)
   101  
   102  	// RecordUnsuccessfulPoll resets the snowflake counter of this instance
   103  	RecordUnsuccessfulPoll()
   104  
   105  	// Return whether a choice has been finalized
   106  	Finalized() bool
   107  
   108  	// Returns a new binary snowball instance with the original choice.
   109  	Extend(originalPreference int) Binary
   110  
   111  	// Returns a new unary snowflake instance with the same state
   112  	Clone() Unary
   113  }