External Entry Points

Entry points are the places where control flow is expected to move from the package user to the package, and vice versa. Input points are places where control flow moves from the package user to the package. Most input points are functions on interfaces implemented by the package (e.g. the Hyperdrive interface). Output points are places where control flow moves from the package to the package user. These are usually defined as callbacks: functions or interfaces defined by the package user to alter the behaviour of the package without needing to alter the package.

Hyperdrive uses this pattern of input/output points to communicate between packages (for example, package hyperdrive should be considered a package user of package replica). However, this page discusses external entry points, where the package user is external to the Hyperdrive codebase. These package users are called external package users (e.g. a codebase that implements a blockchain using Hyperdrive consensus is an external package user).

Behaviour

Package	Interface	Func	Point	Description
hyperdrive	Hyperdrive	New	input
hyperdrive	Hyperdrive	Start	input
hyperdrive	Hyperdrive	Rebase	input

Package	Interface	Point	Description
hyperdrive	BlockIterator	output	Implementing BlockIterator allows the external package user to control the building of a proposed Block. Hyperdrive calls out to this interface whenever it needs to propose a Block.
hyperdrive	Validator	output	Implementing Validator allows the external package user to control the validation of a proposed Block. Hyperdrive calls out to this interface whenever it needs to validate a Block. The existence of this interface is necessary, given that the external package user is able to implement BlockIterator.
hyperdrive	Observer	output	Implementing Observer allows the external package user to react to interesting consensus events. Hyperdrive calls out to this interface whenever an interesting consensus event is triggered (for example, when a Block is committed).

Networking

Package	Interface	Func	Point	Description
hyperdrive	Hyperdrive	HandleMessage	input	HandleMessage should be called by the external package user whenever a message has been received over the network.
hyperdrive	Broadcaster	Broadcast	output	Hyperdrive will call Broadcast whenever it is trying to send a message from one instance to another instance over the network. Different external implementations of Broadcaster can be used to support different types of networks. For example, a chan based implementation is used in testing to define a simple in-memory network. In practice, an implementation that abstracts over aw is used.

Storage

Package	Interface	Point	Description
hyperdrive	ProcessStorage	output	Implementing ProcessStorage allows the external package user to define the storage driver for ProcessState. The external package user is expected to use the JSON/binary (un)marshaling functionality available on most Hyperdrive types to save/restore data to/from the disk. In practice, an implementation that abstracts over kv is used.
hyperdrive	BlockStorage	output	Implementing BlockStorage allows the external package user to define the storage driver for Blocks. Hyperdrive calls out to this interface whenever it needs to access Blocks from a specific Shard. This interface is aware of the specific Shard, and returns implementations of Blockchain that are bound to a specific Shard. The external package user is expected to use the JSON/binary (un)marshaling functionality available on most Hyperdrive types to save/restore data to/from the disk. In practice, an implementation that abstracts over kv is used.
hyperdrive	Blockchain	output	Implementing Blockchcain allows the external package user to define the storage driver for hyperdrive.Blocks. Hyperdrive calls out to this interface whenever it needs to access Blocks at specific heights. Implementations of this interface must be bound to a specific Shard. In practice, an implementation that abstracts over kv is used.