agreement

README

Agreement

Abstract

During the conduction of a technical analysis of sortition based consensus algorithms, the team has discovered a vulnerability, which increases the probability of a the consensus forking, dubbed a timeout fork. As a result, the team has concluded that SBA requires an additional step in the inner loop to guarantee statistical finality under the basic assumptions of the protocol.

Block Agreement is an asynchronous algorithm running in parallel with the inner loop. Successful termination of the algorithm indicates that the relevant inner loop has been successfully executed and the protocol can proceed to the next loop. The algorithm provides a statistical guarantee that at least one honest node has received a set of votes exceeding the minimum threshold required to successfully terminate the respective phase of the protocol.

Values

Block Agreement Event

Field	Type
Aggregated public keys*	BLS APK
Committee bit-representation*	uint64
Aggregated signatures*	BLS Signature
Signature of all fields	BLS Signature

* These fields appear twice, once for each step of Reduction.

Architecture

The agreement component is a special case - the Coordinator has different state-based filtering rules for Agreement messages, since this phase runs asynchronously from all the others, and does not make use of any timers. The agreement component will listen for messages the moment it is initialized, also slightly differing from the other consensus components.

The agreement component filters incoming messages by checking their validity from a voting committee perspective, and by checking the validity of the aggregated signatures and public keys. Verified events will be sent to the Accumulator, which acts as a store for Agreement messages, sorting them by step (since these messages are the product of a two-step reduction cycle). If enough messages for a given step enter the Accumulator and it reaches quorum, the Accumulator signals the agreement component to send two messages: a Finalize message, which notifies the Coordinator to disconnect the current roundStore and instantiate a fresh one, and a Certificate message. The Certificate message is generated from one of the Agreement messages collected for the winning step, and is published internally via the consensus.Signer.

Documentation

Index

• Constants
• func CreateCommitteeVoteSet(p *user.Provisioners, k []key.ConsensusKeys, hash []byte, committeeSize int, ...) []consensus.Event
• func Marshal(r *bytes.Buffer, a Agreement) error
• func MarshalStepVotes(r *bytes.Buffer, vote *StepVotes) error
• func MarshalVotes(r *bytes.Buffer, votes []*StepVotes) error
• func MockAgreement(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, ...) *bytes.Buffer
• func MockConsensusEvent(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, ...) consensus.Event
• func MockWire(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, ...) *bytes.Buffer
• func ReconstructApk(subcommittee sortedset.Set) (*bls.Apk, error)
• func Sign(a *Agreement, keys key.ConsensusKeys) error
• func Unmarshal(r *bytes.Buffer, a *Agreement) error
• func UnmarshalVotes(r *bytes.Buffer, votes []*StepVotes) error
• type Accumulator
  • func (a *Accumulator) Accumulate()
  • func (a *Accumulator) CreateWorkers(amount int)
  • func (a *Accumulator) Process(ev Agreement)
  • func (a *Accumulator) Stop()
• type Agreement
  • func MockAgreementEvent(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, ...) *Agreement
  • func New(h header.Header) *Agreement
  • func (a Agreement) Cmp(other Agreement) int
  • func (a Agreement) Equal(ev wire.Event) bool
  • func (a Agreement) Sender() []byte
  • func (a *Agreement) SetSignature(signedVotes []byte)
  • func (a Agreement) SignedVotes() []byte
• type Factory
  • func NewFactory(publisher eventbus.Publisher, keys key.ConsensusKeys) *Factory
  • func (f *Factory) Instantiate() consensus.Component
• type Handler
• type Helper
  • func LaunchHelper(eb *eventbus.EventBus, nr int) (*Helper, []byte)
  • func NewHelper(eb *eventbus.EventBus, provisioners int) *Helper
  • func ProduceWinningHash(eb *eventbus.EventBus, nr int) (*Helper, []byte)
  • func (hlp *Helper) Initialize(ru consensus.RoundUpdate)
  • func (hlp *Helper) SendBatch(hash []byte)
  • func (hlp *Helper) Spawn(hash []byte) []consensus.Event
• type StepVotes
  • func GenVotes(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, ...) []*StepVotes
  • func NewStepVotes() *StepVotes
  • func UnmarshalStepVotes(r *bytes.Buffer) (*StepVotes, error)
  • func (sv *StepVotes) Add(signature, sender []byte, step uint8) error
  • func (sv *StepVotes) Equal(other *StepVotes) bool

Constants

const MaxCommitteeSize = 64

Functions

func CreateCommitteeVoteSet

func CreateCommitteeVoteSet(p *user.Provisioners, k []key.ConsensusKeys, hash []byte, committeeSize int, round uint64, step uint8) []consensus.Event

func Marshal

func Marshal(r *bytes.Buffer, a Agreement) error

Marshal an Agreement event into a buffer.

func MarshalStepVotes

func MarshalStepVotes(r *bytes.Buffer, vote *StepVotes) error

MarshalStepVotes marshals the aggregated form of the BLS PublicKey and Signature for an ordered set of votes

func MarshalVotes

func MarshalVotes(r *bytes.Buffer, votes []*StepVotes) error

MarshalVotes marshals an array of StepVotes

func MockAgreement

func MockAgreement(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, p *user.Provisioners, i ...int) *bytes.Buffer

MockAgreement mocks an Agreement event, and returns the marshalled representation of it as a `*bytes.Buffer`. The `i` parameter is used to diversify the mocks to avoid duplicates NOTE: it does not include the topic nor the Header

func MockConsensusEvent

func MockConsensusEvent(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, p *user.Provisioners, i ...int) consensus.Event

MockConsensusEvent mocks a consensus.Event with an Agreement payload.

func MockWire

func MockWire(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, p *user.Provisioners, i ...int) *bytes.Buffer

MockWire creates a buffer representing an Agreement travelling to other Provisioners

func ReconstructApk

func ReconstructApk(subcommittee sortedset.Set) (*bls.Apk, error)

ReconstructApk reconstructs an aggregated BLS public key from a subcommittee.

func Sign

func Sign(a *Agreement, keys key.ConsensusKeys) error

Sign signs an aggregated agreement event

func Unmarshal

func Unmarshal(r *bytes.Buffer, a *Agreement) error

Unmarshal unmarshals the buffer into an Agreement Field order is the following: * Header [BLS Public Key; Round; Step] * Agreement [Signed Vote Set; Vote Set; BlockHash]

func UnmarshalVotes

func UnmarshalVotes(r *bytes.Buffer, votes []*StepVotes) error

UnmarshalVotes unmarshals the array of StepVotes for a single Agreement

Types

type Accumulator

type Accumulator struct {
	CollectedVotesChan chan []Agreement
	// contains filtered or unexported fields
}

Accumulator is an event accumulator, that will accumulate events until it reaches a certain threshold.

func (*Accumulator) Accumulate

func (a *Accumulator) Accumulate()

Accumulate agreements per block hash until a quorum is reached or a stop is detected (by closing the internal event channel). Supposed to run in a goroutine

func (*Accumulator) CreateWorkers

func (a *Accumulator) CreateWorkers(amount int)

func (*Accumulator) Process

func (a *Accumulator) Process(ev Agreement)

Process a received Event, by passing it to a worker in the worker pool (if the event sender is part of the voting committee).

func (*Accumulator) Stop

func (a *Accumulator) Stop()

Stop kills the thread pool and shuts down the Accumulator.

type Agreement

type Agreement struct {
	header.Header

	VotesPerStep []*StepVotes
	// contains filtered or unexported fields
}

Agreement is the Event created at the end of the Reduction process. It includes the aggregated compressed signatures of all voters

func MockAgreementEvent

func MockAgreementEvent(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, p *user.Provisioners, iterativeIdx ...int) *Agreement

MockAgreementEvent returns a mocked Agreement Event, to be used for testing purposes. It includes a vararg iterativeIdx to help avoiding duplicates when testing

func New

func New(h header.Header) *Agreement

New returns an empty Agreement event.

func (Agreement) Cmp

func (a Agreement) Cmp(other Agreement) int

func (Agreement) Equal

func (a Agreement) Equal(ev wire.Event) bool

func (Agreement) Sender

func (a Agreement) Sender() []byte

func (*Agreement) SetSignature

func (a *Agreement) SetSignature(signedVotes []byte)

func (Agreement) SignedVotes

func (a Agreement) SignedVotes() []byte

type Factory

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

Factory creates the agreement component.

func NewFactory

func NewFactory(publisher eventbus.Publisher, keys key.ConsensusKeys) *Factory

NewFactory instantiates a Factory.

func (*Factory) Instantiate

func (f *Factory) Instantiate() consensus.Component

Instantiate an agreement component and return it. Implements consensus.ComponentFactory.

type Handler

type Handler interface {
	AmMember(uint64, uint8) bool
	IsMember([]byte, uint64, uint8) bool
	Committee(uint64, uint8) user.VotingCommittee
	Quorum(uint64) int
	VotesFor([]byte, uint64, uint8) int
	Verify(Agreement) error
}

Handler interface is handy for tests

type Helper

type Helper struct {
	Bus             *eventbus.EventBus
	P               *user.Provisioners
	Keys            []key.ConsensusKeys
	Aggro           *agreement
	CertificateChan chan bytes.Buffer
	// contains filtered or unexported fields
}

Helper is a struct that facilitates sending semi-real Events with minimum effort

func LaunchHelper

func LaunchHelper(eb *eventbus.EventBus, nr int) (*Helper, []byte)

func NewHelper

func NewHelper(eb *eventbus.EventBus, provisioners int) *Helper

NewHelper creates a Helper

func ProduceWinningHash

func ProduceWinningHash(eb *eventbus.EventBus, nr int) (*Helper, []byte)

ProduceWinningHash is used to produce enough valid Events to reach Quorum and trigger sending a winning hash to the channel

func (*Helper) Initialize

func (hlp *Helper) Initialize(ru consensus.RoundUpdate)

Initialize the Agreement with a Round update

func (*Helper) SendBatch

func (hlp *Helper) SendBatch(hash []byte)

SendBatch let agreement collect additional batches of consensus events

func (*Helper) Spawn

func (hlp *Helper) Spawn(hash []byte) []consensus.Event

Spawn a number of different valid events to the Agreement component bypassing the EventBus

type StepVotes

type StepVotes struct {
	Apk       *bls.Apk
	BitSet    uint64
	Signature *bls.Signature
	Step      uint8
}

StepVotes represents the aggregated votes for one reduction step. Normally an Agreement event includes two of these structures. They need to be kept separated since the BitSet representation of the Signees does not admit duplicates, whereas the same provisioner may very well be included in the committee for both Reduction steps

func GenVotes

func GenVotes(hash []byte, round uint64, step uint8, keys []key.ConsensusKeys, p *user.Provisioners) []*StepVotes

GenVotes randomly generates a slice of StepVotes with the indicated lenght. Albeit random, the generation is consistent with the rules of Votes

func NewStepVotes

func NewStepVotes() *StepVotes

NewStepVotes returns a new StepVotes structure for a given round, step and block hash

func UnmarshalStepVotes

func UnmarshalStepVotes(r *bytes.Buffer) (*StepVotes, error)

UnmarshalStepVotes unmarshals a single StepVote

func (*StepVotes) Add

func (sv *StepVotes) Add(signature, sender []byte, step uint8) error

Add a vote to the StepVotes struct.

func (*StepVotes) Equal

func (sv *StepVotes) Equal(other *StepVotes) bool

Equal checks if two StepVotes structs are the same.