api.go

package rebro

import (
	"context"

	"github.com/iykyk-syn/unison/crypto"
)

// Broadcaster reliably broadcasts, delivers and commits over messages. It verifies Messages
// delivered from other quorum participants and accumulates them into QuorumCertificate until its
// finalized.
//
// Broadcaster defines interface for asynchronous byzantine reliable quorum broadcast.
// It is responsible for reliable broadcasting and certification of an arbitrary data without
// partial synchrony. It enables parallel quorum certificates and multiple broadcasters can propose
// their Messages simultaneously that other quorum participants attest to.
//
// Broadcaster enables optionality(through polymorphism) for networking algorithms
// (leader-based or mesh-based) by decoupling certificate data structure.
//
// It signs over broadcasted MessageIDs automatically after verifying them using Signer.
// TODO: Explain rules around rounds
type Broadcaster interface {
	// Broadcast broadcasts and delivers messages from quorum participants and signatures over them
	// until QuorumCertificate is finalized.
	// Broadcast takes full ownership over QuorumCertificate, and it must not be modified until
	// Broadcast finishes execution.
	Broadcast(context.Context, Message, QuorumCertificate) error
}

// Certifier performs application-specific stateful certification of messages.
// It used by Broadcaster during broadcasting rounds.
type Certifier interface {
	// Certify executes verification of every Message delivered to QuorumCertificate
	// within a broadcasting round.
	// Message is guaranteed to be valid by the rules in QuorumCertificate.
	Certify(context.Context, Message) error
}

// Hasher hashes Messages to cross-check their validity with MessageID.Hash
type Hasher interface {
	Hash(Message) ([]byte, error)
}

// NetworkID identifies a particular network of nodes.
type NetworkID string

// String returns string representation of NetworkID.
func (nid NetworkID) String() string {
	return string(nid)
}

// Orchestrator orchestrates multiple Broadcaster instances.
type Orchestrator interface {
	// NewBroadcaster instantiates a new Broadcaster.
	NewBroadcaster(NetworkID, crypto.Signer, Certifier, Hasher, MessageIDDecoder) (Broadcaster, error)
}