node

Documentation

Overview

Package node implements the reactive component of a Babble node.

This is the part of Babble that controls the gossip routines and accesses the underlying hashgraph to execute the consensus algorithm. Node implements a state machine where the states are defined in the state package.

Gossip

Babble nodes communicate with other Babble nodes in a fully connected p2p network. Nodes gossip by repeatedly choosing another node at random and telling eachother what they know about the hashgraph. The gossip protocol is extremely simple and serves the dual purpose of gossiping about transactions and about the gossip itself (the hashgraph). The hashgraph contains enough information to compute a consensus ordering of transactions.

The communication mechanism is a custom RPC protocol over network transport as defined in the net package. It implements a Pull-Push gossip system which relies on two RPC commands: Sync and EagerSync. When node A wants to sync with node B, it sends a SyncRequest to B containing a description of what it knows about the hashgraph. B computes what it knows that A doesn't know and returns a SyncResponse with the corresponding events in topological order. Upon receiving the SyncResponse, A updates its hashgraph accordingly and calculates the consensus order. Then, A sends an EagerSyncRequest to B with the Events that it knows and B doesn't know. Upon receiving the EagerSyncRequest, B updates its hashgraph and runs the consensus methods.

Dynamic Membership

A Babble node is started with a genesis peer-set (genesis.peers.json) and a current peer-set (peers.json). If its public-key does not belong to the current peer-set, the node will enter the Joining state, where it will attempt to join the peer-set. It does so by signing an InternalTransaction and submitting it for consensus via a JoinRequest to one of the current nodes.

If the JoinRequest was successful, and the new node makes it into the peer-set, it will either enter the Babbling state directly, or the CatchingUp state, depending on whether the FastSync option was enabled. In the former case, the node will have to retrieve the entire history of the hashgraph and commit all the blocks it missed one-by-one. This is where it is important to have the genesis peer-set, to allow the joining node to validate the consensus decisions and peer-set changes from the beginning of the hashgraph.

The protocol for removing peers is almost identical, with the difference that a node submits a LeaveRequest for itself upon capturing a SIGINT signal when the Babble process is terminated cleanly.

FastSync

When a node is started and belongs to the current validator-set, it will either enter the Babbling state, or the CatchingUp state, depending on whether the FastSync option was enablied in the configuration.

In the CatchingUp state, a node determines the best node to fast-sync from (the node which has the longest hashgraph) and attempts to fast-forward to their last consensus snapshot, until the operation succeeds. Hence, FastSync introduces a new type of command in the communication protocol: FastForward.

Upon receiving a FastForwardRequest, a node must respond with the last consensus snapshot, as well as the corresponding Hashgraph section (the Frame) and Block. With this information, and having verified the Block signatures against the other items as well as the known validator set, the requesting node attempts to reset its Hashgraph from the Frame, and restore the application from the snapshot.

Index

• type Graph
  • func NewGraph(n *Node) *Graph
  • func (g *Graph) GetBlocks() []*hg.Block
  • func (g *Graph) GetInfos() (Infos, error)
  • func (g *Graph) GetParticipantEvents() (map[string]map[string]*hg.Event, error)
  • func (g *Graph) GetRounds() []*hg.RoundInfo
• type Infos
• type Node
  • func NewNode(conf *config.Config, validator *Validator, peers *peers.PeerSet, ...) *Node
  • func (n *Node) GetAllValidatorSets() (map[int][]*peers.Peer, error)
  • func (n *Node) GetBlock(blockIndex int) (*hg.Block, error)
  • func (n *Node) GetID() uint32
  • func (n *Node) GetLastBlockIndex() int
  • func (n *Node) GetLastConsensusRoundIndex() int
  • func (n *Node) GetPeers() []*peers.Peer
  • func (n *Node) GetPubKey() string
  • func (n *Node) GetStats() map[string]string
  • func (n *Node) GetValidatorSet(round int) ([]*peers.Peer, error)
  • func (n *Node) Init() error
  • func (n *Node) Leave() error
  • func (n *Node) Run(gossip bool)
  • func (n *Node) RunAsync(gossip bool)
  • func (n *Node) Shutdown()
  • func (n *Node) Suspend()
• type Validator
  • func NewValidator(key *ecdsa.PrivateKey, moniker string) *Validator
  • func (v *Validator) ID() uint32
  • func (v *Validator) PublicKeyBytes() []byte
  • func (v *Validator) PublicKeyHex() string

Types

type Graph

type Graph struct {
	*Node
}

Graph is a struct containing a node which is is used to collect information about the underlying Hashgraph in view of producing a visual representation of the Hashgraph.

func NewGraph

func NewGraph(n *Node) *Graph

NewGraph instantiates a Graph from a Node.

func (*Graph) GetBlocks

func (g *Graph) GetBlocks() []*hg.Block

GetBlocks returns all the recorded blocks.

func (*Graph) GetInfos

func (g *Graph) GetInfos() (Infos, error)

GetInfos returns an Infos struct representing the entire Hashgraph.

func (*Graph) GetParticipantEvents

func (g *Graph) GetParticipantEvents() (map[string]map[string]*hg.Event, error)

GetParticipantEvents returns all the Events for all the participants that have been members of the group.

func (*Graph) GetRounds

func (g *Graph) GetRounds() []*hg.RoundInfo

GetRounds returns all the recorded Hashgraph rounds.

type Infos

type Infos struct {
	ParticipantEvents map[string]map[string]*hg.Event
	Rounds            []*hg.RoundInfo
	Blocks            []*hg.Block
}

Infos is the object used by Graph to collect information about a Hashgraph.

type Node

type Node struct {
	// The node is implemented as a state-machine. The embedded state Manager
	// object is used to manage the node's state.
	_state.Manager
	// contains filtered or unexported fields
}

Node defines a babble node

func NewNode

func NewNode(conf *config.Config,
	validator *Validator,
	peers *peers.PeerSet,
	genesisPeers *peers.PeerSet,
	store hg.Store,
	trans net.Transport,
	proxy proxy.AppProxy,
) *Node

NewNode instantiates a new Node and initializes it's Hashgraph with the genesis peers and backend store.

func (*Node) GetAllValidatorSets

func (n *Node) GetAllValidatorSets() (map[int][]*peers.Peer, error)

GetAllValidatorSets returns the entire history of validator-sets per round.

func (*Node) GetBlock

func (n *Node) GetBlock(blockIndex int) (*hg.Block, error)

GetBlock returns a block by index.

func (*Node) GetID

func (n *Node) GetID() uint32

GetID returns the numeric ID of the node's validator, which is derived from its public key.

func (*Node) GetLastBlockIndex

func (n *Node) GetLastBlockIndex() int

GetLastBlockIndex returns the index of the last known block.

func (*Node) GetLastConsensusRoundIndex

func (n *Node) GetLastConsensusRoundIndex() int

GetLastConsensusRoundIndex returns the index of the last consensus round.

func (*Node) GetPeers

func (n *Node) GetPeers() []*peers.Peer

GetPeers returns the list of currently known peers, which is not necessarily equal to the current validator-set.

func (*Node) GetPubKey

func (n *Node) GetPubKey() string

GetPubKey return the hexadecimal representation of the validator's public key.

func (*Node) GetStats

func (n *Node) GetStats() map[string]string

GetStats returns information about the node.

func (*Node) GetValidatorSet

func (n *Node) GetValidatorSet(round int) ([]*peers.Peer, error)

GetValidatorSet returns the validator-set that is autoritative at a given round.

func (*Node) Init

func (n *Node) Init() error

Init controls the bootstrap process and sets the node's initial state based on configuration (Babbling, CatchingUp, Joining, or Suspended).

func (*Node) Leave

func (n *Node) Leave() error

Leave causes the node to politely leave the network with a LeaveRequest and to wait for its validator to be removed from the validator-set via consensus.

func (*Node) Run

func (n *Node) Run(gossip bool)

Run invokes the main loop of the node. The gossip parameter controls whether to actively participate in gossip or not.

func (*Node) RunAsync

func (n *Node) RunAsync(gossip bool)

RunAsync runs the node in a separate goroutine

func (*Node) Shutdown

func (n *Node) Shutdown()

Shutdown attempts to cleanly shutdown the node by waiting for pending work to be finished, stopping the control-timer, and closing the transport.

func (*Node) Suspend

func (n *Node) Suspend()

Suspend puts the node in Suspended mode. It doesn't close the transport because it needs to respond to incoming SyncRequests.

type Validator

type Validator struct {
	Key     *ecdsa.PrivateKey
	Moniker string
	// contains filtered or unexported fields
}

Validator represents the peer that operates a node. It has control over it's private key to sign messages.

func NewValidator

func NewValidator(key *ecdsa.PrivateKey, moniker string) *Validator

NewValidator creates a new Validator from a private key and moniker.

func (*Validator) ID

func (v *Validator) ID() uint32

ID returns the validator's unique numeric ID which is derived from it's key.

func (*Validator) PublicKeyBytes

func (v *Validator) PublicKeyBytes() []byte

PublicKeyBytes returns the validator's public key as a byte slice.

func (*Validator) PublicKeyHex

func (v *Validator) PublicKeyHex() string

PublicKeyHex returns the validator's public key as a hex string.