gpbft

type ActorID uint64

type CID = []byte

type Chain interface {
	// Returns the supplemental data and the chain to propose for a new GPBFT instance.
	// The chain must be a suffix of the chain finalised by the immediately prior instance.
	// The supplemental data must be derived entirely from prior instances and all participants
	// must propose the same supplemental data.
	//
	// Returns an error if the chain for the instance is not available.
	GetProposalForInstance(instance uint64) (data *SupplementalData, chain ECChain, err error)

	// Returns the power table and beacon value to be used for a GPBFT instance.
	// These values should be derived from a chain previously received as final by the host,
	// or known to be final via some other channel (e.g. when bootstrapping the protocol).
	// The offset (how many instances to look back) is determined by the host.
	// Returns an error if the committee for the instance is not available.
	GetCommitteeForInstance(instance uint64) (power *PowerTable, beacon []byte, err error)
}

type ChainKey string

type Clock interface {
	// Returns the current network time.
	Time() time.Time
	// SetAlarm sets an alarm to fire after the given timestamp. At most one alarm
	// can be set at a time. Setting an alarm replaces any previous alarm that has
	// not yet fired. The timestamp may be in the past, in which case the alarm will
	// fire as soon as possible (but not synchronously).
	SetAlarm(at time.Time)
}

type ConvergeTicket struct {
	Sender ActorID
	Ticket Ticket
}

type ConvergeValue struct {
	Chain         ECChain
	Justification *Justification
}

type DecisionReceiver interface {
	// Receives a finality decision from the instance, with signatures from a strong quorum
	// of participants justifying it.
	// The decision payload always has round = 0 and step = DECIDE.
	// The notification must return the timestamp at which the next instance should begin,
	// based on the decision received (which may be in the past).
	// E.g. this might be: finalised tipset timestamp + epoch duration + stabilisation delay.
	ReceiveDecision(decision *Justification) (time.Time, error)
}

type ECChain []TipSet

type GMessage struct {
	// ID of the sender/signer of this message (a miner actor ID).
	Sender ActorID
	// Vote is the payload that is signed by the signature
	Vote Payload
	// Signature by the sender's public key over Instance || Round || Step || Value.
	Signature []byte `cborgen:"maxlen=96"`
	// VRF ticket for CONVERGE messages (otherwise empty byte array).
	Ticket Ticket `cborgen:"maxlen=96"`
	// Justification for this message (some messages must be justified by a strong quorum of messages from some previous step).
	Justification *Justification
}

type Host interface {
	Chain
	Network
	Clock
	Signatures
	DecisionReceiver
}

type Justification struct {
	// Vote is the payload that is signed by the signature
	Vote Payload
	// Indexes in the base power table of the signers (bitset)
	Signers bitfield.BitField
	// BLS aggregate signature of signers
	Signature []byte `cborgen:"maxlen=96"`
}

type MessageBuilder struct {
	NetworkName      NetworkName
	PowerTable       powerTableAccessor
	Payload          Payload
	BeaconForTicket  []byte
	Justification    *Justification
	SigningMarshaler SigningMarshaler
}

type MessageReceiver interface {
	// Receives a validated Granite message from some other participant.
	// Returns an error, wrapping (use errors.Is()/Unwrap()):
	// - ErrValidationTooOld if the message is for a prior instance
	// - ErrValidationWrongBase if the message has an invalid base chain
	// - ErrReceivedAfterTermination if the message is received after the instance has terminated (a programming error)
	// - both ErrReceivedInternalError and a cause if there was an internal error processing the message
	ReceiveMessage(msg ValidatedMessage) error
	// ReceiveAlarm signals the trigger of the alarm set by Clock.SetAlarm.
	ReceiveAlarm() error
}

type MessageValidator interface {
	// Validates a Granite message.
	// An invalid message can never become valid, so may be dropped.
	// Returns an error, wrapping (use errors.Is()/Unwrap()):
	// - ErrValidationTooOld if the message is for a prior instance;
	// - both ErrValidationNoCommittee and an error describing the reason;
	//   if there is no committee available with with to validate the message;
	// - both ErrValidationInvalid and a cause if the message is invalid,
	// Returns a validated message if the message is valid.
	//
	// Implementations must be safe for concurrent use.
	ValidateMessage(msg *GMessage) (valid ValidatedMessage, err error)
}

type Network interface {
	// Returns the network's name (for signature separation)
	NetworkName() NetworkName
	// Requests that the message is signed and broadcasted, it should also be delivered locally
	RequestBroadcast(mb *MessageBuilder) error
}

type NetworkName string

type Option func(*options) error

type PanicError struct {
	Err any
	// contains filtered or unexported fields
}

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

type Payload struct {
	// GossiPBFT instance (epoch) number.
	Instance uint64
	// GossiPBFT round number.
	Round uint64
	// GossiPBFT step name.
	Step Phase
	// The common data.
	SupplementalData SupplementalData
	// The value agreed-upon in a single instance.
	Value ECChain
}

type Phase uint8

type PowerEntries []PowerEntry

type PowerEntry struct {
	ID     ActorID
	Power  StoragePower
	PubKey PubKey
}

type PowerTable struct {
	Entries     PowerEntries // Slice to maintain the order. Meant to be maintained in order in order by (Power descending, ID ascending)
	ScaledPower []uint16
	Lookup      map[ActorID]int // Maps ActorID to the index of the associated entry in Entries
	Total       StoragePower
	ScaledTotal uint16
}

type PubKey []byte

type QuorumResult struct {
	// Signers is an array of indexes into the powertable, sorted in increasing order
	Signers    []int
	PubKeys    []PubKey
	Signatures [][]byte
}

type Receiver interface {
	// Begins executing the protocol from some instance.
	// The node will subsequently request the canonical chain to propose from the host.
	// If the participant is already executing some instance, it will be abandoned.
	StartInstanceAt(uint64, time.Time) error
	MessageValidator
	MessageReceiver
}

type SignatureBuilder struct {
	NetworkName NetworkName

	ParticipantID ActorID
	Payload       Payload
	Justification *Justification
	PubKey        PubKey
	PayloadToSign []byte
	VRFToSign     []byte
}

type Signatures interface {
	SigningMarshaler
	Verifier
}

type Signer interface {
	// Signs a message with the secret key corresponding to a public key.
	Sign(ctx context.Context, sender PubKey, msg []byte) ([]byte, error)
}

type SignerWithMarshaler interface {
	Signer
	SigningMarshaler
}

type SigningMarshaler interface {
	// MarshalPayloadForSigning marshals the given payload into the bytes that should be signed.
	// This should usually call `Payload.MarshalForSigning(NetworkName)` except when testing as
	// that method is slow (computes a merkle tree that's necessary for testing).
	// Implementations must be safe for concurrent use.
	MarshalPayloadForSigning(NetworkName, *Payload) []byte
}

type StoragePower = big.Int

type SupplementalData struct {
	// Merkle-tree of instance-specific commitments. Currently empty but this will eventually
	// include things like snark-friendly power-table commitments.
	Commitments [32]byte
	// The DagCBOR-blake2b256 CID of the power table used to validate the next instance, taking
	// lookback into account.
	PowerTable CID `cborgen:"maxlen=38"` // []PowerEntry
}

type Ticket []byte

type TipSet struct {
	// The EC epoch (strictly increasing).
	Epoch int64
	// The tipset's key (canonically ordered concatenated block-header CIDs).
	Key TipSetKey `cborgen:"maxlen=760"` // 20 * 38B
	// Blake2b256-32 CID of the CBOR-encoded power table.
	PowerTable CID `cborgen:"maxlen=38"` // []PowerEntry
	// Keccak256 root hash of the commitments merkle tree.
	Commitments [32]byte
}

type TipSetKey = []byte

type Tracer interface {
	Log(format string, args ...any)
}

type ValidatedMessage interface {
	// Returns the validated message.
	Message() *GMessage
}

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

type Verifier interface {
	// Verifies a signature for the given public key.
	// Implementations must be safe for concurrent use.
	Verify(pubKey PubKey, msg, sig []byte) error
	// Aggregates signatures from a participants.
	Aggregate(pubKeys []PubKey, sigs [][]byte) ([]byte, error)
	// VerifyAggregate verifies an aggregate signature.
	// Implementations must be safe for concurrent use.
	VerifyAggregate(payload, aggSig []byte, signers []PubKey) error
}