Documentation ¶
Index ¶
- Constants
- func VerifyTicket(beacon []byte, instance uint64, round uint64, source PubKey, host VRFHost, ...) bool
- type ActorID
- type Chain
- type ChainKey
- type Clock
- type ConvergeTicket
- type ConvergeValue
- type DecisionReceiver
- type ECChain
- func (c ECChain) Base() TipSet
- func (c ECChain) BaseChain() ECChain
- func (c ECChain) Eq(other ECChain) bool
- func (c ECChain) Extend(tip TipSet) ECChain
- func (c ECChain) HasBase(t TipSet) bool
- func (c ECChain) HasPrefix(other ECChain) bool
- func (c ECChain) HasTipset(t TipSet) bool
- func (c ECChain) Head() TipSet
- func (c ECChain) IsZero() bool
- func (c ECChain) Key() ChainKey
- func (c ECChain) Prefix(to int) ECChain
- func (c ECChain) SameBase(other ECChain) bool
- func (c ECChain) String() string
- func (c ECChain) Suffix() []TipSet
- func (c ECChain) Validate() error
- type GMessage
- type Host
- type Justification
- type MessageReceiver
- type Network
- type NetworkName
- type Option
- type PanicError
- type Participant
- func (p *Participant) CurrentRound() uint64
- func (p *Participant) Describe() string
- func (p *Participant) ID() ActorID
- func (p *Participant) ReceiveAlarm() (err error)
- func (p *Participant) ReceiveMessage(msg *GMessage, validated bool) (accepted bool, err error)
- func (p *Participant) Start() (err error)
- func (p *Participant) ValidateMessage(msg *GMessage) (checked bool, err error)
- type Payload
- type Phase
- type PowerEntry
- type PowerTable
- func (p *PowerTable) Add(entries ...PowerEntry) error
- func (p *PowerTable) Copy() *PowerTable
- func (p *PowerTable) Get(id ActorID) (*StoragePower, PubKey)
- func (p *PowerTable) Has(id ActorID) bool
- func (p *PowerTable) Len() int
- func (p *PowerTable) Less(i, j int) bool
- func (p *PowerTable) Swap(i, j int)
- func (p *PowerTable) Validate() error
- type PubKey
- type QuorumResult
- type Receiver
- type Signer
- type StoragePower
- type Ticket
- type TipSet
- type Tracer
- type VRFHost
- type Verifier
Constants ¶
const DOMAIN_SEPARATION_TAG = "GPBFT"
const DOMAIN_SEPARATION_TAG_VRF = "VRF"
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Chain ¶
type Chain interface { // Returns the best EC chain, and the power table and beacon value for its base. // These will be used as input to a subsequent instance of the protocol. GetCanonicalChain() (chain ECChain, power PowerTable, beacon []byte) }
type Clock ¶
type Clock interface { // Returns the current network time. Time() time.Time // 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 ¶
type ConvergeValue ¶
type ConvergeValue struct { Chain ECChain Justification *Justification }
type DecisionReceiver ¶
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 }
type ECChain ¶
type ECChain []TipSet
A chain of tipsets comprising a base (the last finalised tipset from which the chain extends). and (possibly empty) suffix. Tipsets are assumed to be built contiguously on each other, though epochs may be missing due to null rounds. The zero value is not a valid chain, and represents a "bottom" value when used in a Granite message.
func (ECChain) BaseChain ¶
Returns a new chain with the same base and no suffix. Invalid for a zero value.
func (ECChain) HasBase ¶
Check whether a chain has a specific base tipset. Always false for a zero value.
func (ECChain) HasPrefix ¶
Checks whether a chain has some prefix (including the base). Always false for a zero value.
func (ECChain) Head ¶
Returns the last tipset in the chain. This could be the base tipset if there is no suffix. This will panic on a zero value.
func (ECChain) Key ¶
Returns an identifier for the chain suitable for use as a map key. This must completely determine the sequence of tipsets in the chain.
func (ECChain) Prefix ¶
Returns a chain with suffix (after the base) truncated to a maximum length. Prefix(0) returns the base chain. Invalid for a zero value.
func (ECChain) SameBase ¶
Checks whether two chains have the same base. Always false for a zero value.
func (ECChain) Suffix ¶
Returns the suffix of the chain after the base. An empty slice for a zero value.
func (ECChain) Validate ¶
Validate verifies the integrity of the chain, returning an error if it finds any issues. A chain is valid if it meets the following criteria: 1) All contained elements have non-zero values. Use TipSet.IsZero to check for zero-valued elements. 2) TipSets are arranged in strictly increasing order by their epochs, without any repetitions. An entirely zero-valued chain itself is deemed valid. See ECChain.IsZero.
type GMessage ¶
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 // VRF ticket for CONVERGE messages (otherwise empty byte array). Ticket Ticket // Justification for this message (some messages must be justified by a strong quorum of messages from some previous step). Justification *Justification }
A message in the Granite protocol. The same message structure is used for all rounds and phases. Note that the message is self-attesting so no separate envelope or signature is needed. - The signature field fixes the included sender ID via the implied public key; - The signature payload includes all fields a sender can freely choose; - The ticket field is a signature of the same public key, so also self-attesting.
type Justification ¶
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 }
func (*Justification) MarshalCBOR ¶
func (t *Justification) MarshalCBOR(w io.Writer) error
func (*Justification) UnmarshalCBOR ¶
func (t *Justification) UnmarshalCBOR(r io.Reader) (err error)
type MessageReceiver ¶
type MessageReceiver interface { // Validates a message received from another participant, if possible. // Returns whether the message could be validated, and an error if it was invalid. ValidateMessage(msg *GMessage) (bool, error) // Receives a message from another participant. // The `validated` parameter indicates whether the message has already passed validation. ReceiveMessage(msg *GMessage, validated bool) (bool, error) ReceiveAlarm() error }
Receives a Granite protocol message.
type Network ¶
type Network interface { // Returns the network's name (for signature separation) NetworkName() NetworkName // Sends a message to all other participants. // The message's sender must be one that the network interface can sign on behalf of. Broadcast(msg *GMessage) }
Endpoint to which participants can send messages.
type NetworkName ¶
type NetworkName string
NetworkName provides separation between different networks it is implicitly included in all signatures and VRFs
func (NetworkName) DatastorePrefix ¶
func (nn NetworkName) DatastorePrefix() datastore.Key
func (NetworkName) PubSubTopic ¶
func (nn NetworkName) PubSubTopic() string
type Option ¶
type Option func(*options) error
Option represents a configurable parameter.
func WithDelta ¶
WithDelta sets the expected bound on message propagation latency. Defaults to 3 seconds if unspecified. Delta must be larger than zero.
The default of 3 seconds for the value of Dela is based on the current EC propagation time (i.e. round-trip time of 6 seconds) as the initial propagation timeout. The actual propagation time may be significantly lower. However, until further measurements confirm it a 3 second value for delta seems reasonable.
func WithDeltaBackOffExponent ¶
WithDeltaBackOffExponent sets the delta back-off exponent for each round. Defaults to 1.3 if unspecified. It must be larger than zero.
func WithInitialInstance ¶
WithInitialInstance sets the first instance number. Defaults to zero if unspecified.
func WithTracer ¶
WithTracer sets the Tracer for this gPBFT instance, which receives diagnostic logs about the state mutation. Defaults to no tracer if unspecified.
type PanicError ¶
type PanicError struct {
Err any
}
func (*PanicError) Error ¶
func (e *PanicError) Error() string
type Participant ¶
type Participant struct {
// contains filtered or unexported fields
}
An F3 participant runs repeated instances of Granite to finalise longer chains.
func NewParticipant ¶
func NewParticipant(id ActorID, host Host, o ...Option) (*Participant, error)
func (*Participant) CurrentRound ¶
func (p *Participant) CurrentRound() uint64
func (*Participant) Describe ¶
func (p *Participant) Describe() string
func (*Participant) ID ¶
func (p *Participant) ID() ActorID
func (*Participant) ReceiveAlarm ¶
func (p *Participant) ReceiveAlarm() (err error)
func (*Participant) ReceiveMessage ¶
func (p *Participant) ReceiveMessage(msg *GMessage, validated bool) (accepted bool, err error)
Receives a Granite message from some other participant. If the message is for the current instance, it is delivered immediately. If it is for a future instance, it is locally queued, to be delivered when that instance begins. If it is for a previous instance, it is dropped.
This method checks message validity only if the validated parameter is false. Validity can only be checked when the messages instance begins. Returns whether the message was for the current instance, and an error if it was invalid or could not be processed.
func (*Participant) Start ¶
func (p *Participant) Start() (err error)
Fetches the preferred EC chain for the instance and begins the GPBFT protocol.
func (*Participant) ValidateMessage ¶
func (p *Participant) ValidateMessage(msg *GMessage) (checked bool, err error)
Validates a message received from another participant, if possible. An invalid message can never become valid, so may be dropped. A message can only be validated if it is for the currently-executing protocol instance. Returns whether the message could be validated, and an error if it was invalid.
type Payload ¶
type Payload struct { // GossiPBFT instance (epoch) number. Instance uint64 // GossiPBFT round number. Round uint64 // GossiPBFT step name. Step Phase // Chain of tipsets proposed/voted for finalisation. // Always non-empty; the first entry is the base tipset finalised in the previous instance. Value ECChain }
Fields of the message that make up the signature payload.
func (Payload) MarshalForSigning ¶
func (p Payload) MarshalForSigning(nn NetworkName) []byte
type PowerEntry ¶
type PowerEntry struct { ID ActorID Power *StoragePower PubKey PubKey }
PowerEntry represents a single entry in the PowerTable, including ActorID and its StoragePower and PubKey.
type PowerTable ¶
type PowerTable struct { Entries []PowerEntry // Slice to maintain the order. Meant to be maintained in order in order by (Power descending, ID ascending) Lookup map[ActorID]int // Maps ActorID to the index of the associated entry in Entries Total *StoragePower }
PowerTable maps ActorID to a unique index in the range [0, len(powerTable.Entries)). Entries is the reverse mapping to a PowerEntry.
func NewPowerTable ¶
func NewPowerTable() *PowerTable
NewPowerTable creates a new PowerTable from a slice of PowerEntry . It is more efficient than Add, as it only needs to sort the entries once. Note that the function takes ownership of the slice - it must not be modified afterwards.
func (*PowerTable) Add ¶
func (p *PowerTable) Add(entries ...PowerEntry) error
Add inserts one or more entries to this PowerTable.
Each inserted entry must meet the following criteria: * It must not already be present int the PowerTable. * It must have StoragePower larger than zero. * It must have a non-zero length public key.
func (*PowerTable) Copy ¶
func (p *PowerTable) Copy() *PowerTable
Copy creates a deep copy of this PowerTable.
func (*PowerTable) Get ¶
func (p *PowerTable) Get(id ActorID) (*StoragePower, PubKey)
Get retrieves the StoragePower and PubKey for the given id, if present in the table. Otherwise, returns nil.
func (*PowerTable) Has ¶
func (p *PowerTable) Has(id ActorID) bool
Has check whether this PowerTable contains an entry for the given id.
func (*PowerTable) Len ¶
func (p *PowerTable) Len() int
Len returns the number of entries in this PowerTable.
func (*PowerTable) Less ¶
func (p *PowerTable) Less(i, j int) bool
Less determines if the entry at index i should be sorted before the entry at index j. Entries are sorted descending order of their power, where entries with equal power are sorted by ascending order of their ID. This ordering is guaranteed to be stable, since a valid PowerTable cannot contain entries with duplicate IDs; see Validate.
func (*PowerTable) Swap ¶
func (p *PowerTable) Swap(i, j int)
Swap swaps the entry at index i with the entry at index j. This function must not be called directly since it is used as part of sort.Interface.
func (*PowerTable) Validate ¶
func (p *PowerTable) Validate() error
Validate checks the validity of this PowerTable. Such table must meet the following criteria: * Its entries must be in order as defined by Less. * It must not contain any entries with duplicate ID. * All entries must have power larger than zero * All entries must have non-zero public key. * PowerTable.Total must correspond to the total aggregated power of entries. * PowerTable.Lookup must contain the expected mapping of entry actor ID to index.
type QuorumResult ¶
type QuorumResult struct { // Signers is an array of indexes into the powertable, sorted in increasing order Signers []int PubKeys []PubKey Signatures [][]byte }
func (QuorumResult) SignersBitfield ¶
func (q QuorumResult) SignersBitfield() bitfield.BitField
type Receiver ¶
type Receiver interface { ID() ActorID // Begins executing the protocol. // The node will request the canonical chain to propose from the host. Start() error MessageReceiver }
Interface which network participants must implement.
type StoragePower ¶
func NewStoragePower ¶
func NewStoragePower(value int64) *StoragePower
Creates a new StoragePower struct with a specific value and returns the result
type Ticket ¶
type Ticket []byte
A ticket is a signature over some common payload.
func MakeTicket ¶
type TipSet ¶
type TipSet = []byte
Opaque type representing a tipset. This is expected to be: - a canonical sequence of CIDs of block headers identifying a tipset, - a commitment to the resulting power table, - a commitment to additional derived values. However, GossipPBFT doesn't need to know anything about that structure.
type Tracer ¶
Tracer collects trace logs that capture logical state changes. The primary purpose of Tracer is to aid debugging and simulation.
type Verifier ¶
type Verifier interface { // Verifies a signature for the given public key Verify(pubKey PubKey, msg, sig []byte) error // Aggregates signatures from a participants Aggregate(pubKeys []PubKey, sigs [][]byte) ([]byte, error) // VerifyAggregate verifies an aggregate signature. VerifyAggregate(payload, aggSig []byte, signers []PubKey) error }