twins

Documentation

Overview

Package twins implements a framework for testing HotStuff implementations.

Index

• func FixedTimeout(timeout time.Duration) synchronizer.ViewDuration
• type Generator
  • func NewGenerator(logger logging.Logger, settings Settings) *Generator
  • func (g *Generator) NextScenario() (s Scenario, err error)
  • func (g *Generator) Remaining() int64
  • func (g *Generator) Settings() Settings
  • func (g *Generator) Shuffle(seed int64)
• type JSONWriter
  • func ToJSON(settings Settings, wr io.Writer) (*JSONWriter, error)
  • func (jwr *JSONWriter) Close() error
  • func (jwr *JSONWriter) WriteScenario(s Scenario) error
• type Network
  • func NewPartitionedNetwork(views []View, dropTypes ...any) *Network
  • func NewSimpleNetwork() *Network
  • func (n *Network) GetNodeBuilder(id NodeID, pk hotstuff.PrivateKey) modules.Builder
  • func (n *Network) NewConfiguration() modules.Configuration
• type NodeID
  • func (id NodeID) String() string
• type NodeSet
  • func (s NodeSet) Add(v uint32)
  • func (s NodeSet) Contains(v uint32) bool
  • func (s NodeSet) MarshalJSON() ([]byte, error)
  • func (s *NodeSet) UnmarshalJSON(data []byte) error
• type Scenario
  • func (s Scenario) String() string
• type ScenarioResult
  • func ExecuteScenario(scenario Scenario, numNodes, numTwins uint8, numTicks int, ...) (result ScenarioResult, err error)
• type ScenarioSource
  • func FromJSON(rd io.Reader) (ScenarioSource, error)
• type Settings
• type View

Functions

func FixedTimeout

func FixedTimeout(timeout time.Duration) synchronizer.ViewDuration

FixedTimeout returns an ExponentialTimeout with a max exponent of 0.

Types

type Generator

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

Generator generates twins scenarios.

func NewGenerator

func NewGenerator(logger logging.Logger, settings Settings) *Generator

NewGenerator creates a new generator.

func (*Generator) NextScenario

func (g *Generator) NextScenario() (s Scenario, err error)

NextScenario generates the next scenario.

func (*Generator) Remaining

func (g *Generator) Remaining() int64

Remaining returns the number of scenarios remaining to be generated.

func (*Generator) Settings

func (g *Generator) Settings() Settings

Settings returns the settings of the generator.

func (*Generator) Shuffle

func (g *Generator) Shuffle(seed int64)

Shuffle shuffles the list of leaders and partitions.

type JSONWriter

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

JSONWriter writes scenarios to JSON.

func ToJSON

func ToJSON(settings Settings, wr io.Writer) (*JSONWriter, error)

ToJSON returns a JSONWriter that can be used to write scenarios as JSON.

func (*JSONWriter) Close

func (jwr *JSONWriter) Close() error

Close closes the JSON stream.

func (*JSONWriter) WriteScenario

func (jwr *JSONWriter) WriteScenario(s Scenario) error

WriteScenario writes a single scenario to the JSON stream.

type Network

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

Network is a simulated network that supports twins.

func NewPartitionedNetwork

func NewPartitionedNetwork(views []View, dropTypes ...any) *Network

NewPartitionedNetwork creates a new Network with the specified partitions. partitions specifies the network partitions for each view.

func NewSimpleNetwork

func NewSimpleNetwork() *Network

NewSimpleNetwork creates a simple network.

func (*Network) GetNodeBuilder

func (n *Network) GetNodeBuilder(id NodeID, pk hotstuff.PrivateKey) modules.Builder

GetNodeBuilder returns a consensus.Builder instance for a node in the network.

func (*Network) NewConfiguration

func (n *Network) NewConfiguration() modules.Configuration

NewConfiguration returns a new Configuration module for this network.

type NodeID

type NodeID struct {
	ReplicaID hotstuff.ID
	NetworkID uint32
}

NodeID is an ID that is unique to a node in the network. The ReplicaID is the ID that the node uses when taking part in the consensus protocol, while the NetworkID is used to distinguish nodes on the network.

func (NodeID) String

func (id NodeID) String() string

type NodeSet

type NodeSet map[uint32]struct{}

NodeSet is a set of network ids.

func (NodeSet) Add

func (s NodeSet) Add(v uint32)

Add adds a NodeID to the set.

func (NodeSet) Contains

func (s NodeSet) Contains(v uint32) bool

Contains returns true if the set contains the NodeID, false otherwise.

func (NodeSet) MarshalJSON

func (s NodeSet) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON representation of the node set.

func (*NodeSet) UnmarshalJSON

func (s *NodeSet) UnmarshalJSON(data []byte) error

UnmarshalJSON restores the node set from JSON.

type Scenario

type Scenario []View

Scenario specifies the nodes, partitions and leaders for a twins scenario.

func (Scenario) String

func (s Scenario) String() string

type ScenarioResult

type ScenarioResult struct {
	Safe        bool
	Commits     int
	NetworkLog  string
	NodeLogs    map[NodeID]string
	NodeCommits map[NodeID][]*hotstuff.Block
}

ScenarioResult contains the result and logs from executing a scenario.

func ExecuteScenario

func ExecuteScenario(scenario Scenario, numNodes, numTwins uint8, numTicks int, consensusName string) (result ScenarioResult, err error)

ExecuteScenario executes a twins scenario.

type ScenarioSource

type ScenarioSource interface {
	Settings() Settings
	NextScenario() (Scenario, error)
	Remaining() int64
}

ScenarioSource is a source of twins scenarios to execute.

func FromJSON

func FromJSON(rd io.Reader) (ScenarioSource, error)

FromJSON returns a scenario source that reads from the given reader.

type Settings

type Settings struct {
	NumNodes   uint8
	NumTwins   uint8
	Partitions uint8
	Views      uint8
	Ticks      int
	Shuffle    bool
	Seed       int64
}

Settings contains the settings used with the scenario generator.

type View

type View struct {
	Leader     hotstuff.ID `json:"leader"`
	Partitions []NodeSet   `json:"partitions"`
}

View specifies the leader id and the partition scenario for a single view.