Skip to content

External Entry Points

Loong edited this page Jan 9, 2020 · 3 revisions

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.
Clone this wiki locally