f3

README

Go implementation of Fast Finality in Filecoin

This repository contains the golang implementation of the Fast Finality (F3) protocol for Filecoin as specified by FIP-0086. This protocol uses GossipPBFT consensus protocol to finalize tipsets when voted for by more than two-thirds of the storage power.

Key Features

• Core Implementation of GossipBFT Consensus Protocol: The heart of Go-F3.
• F3 Filecoin Integration Module: Streamlines the integration of the F3 protocol within the broader Filecoin ecosystem, specifically Lotus and other Filecoin full nodes.
• Simulation Package: Includes a robust simulation environment with various adversary models, enabling rigorous testing of the protocol under different network conditions and attack scenarios.
• Emulator Package: Facilitates message-by-message interaction with the GossipPBFT protocol, providing a detailed view of protocol mechanics and performance.
• Standalone F3 Participant Implementation: A complete implementation of an F3 protocol participant, capable of operating independently within the Filecoin network.
• Finality Certificate: Implements the generation and management of finality certificates, which cary transportable proofs of finality.
• Finality Certificate Exchange Protocol: Features an adaptive self-configuring polling mechanism, enhancing the efficiency and reliability of certificate exchange among participants.

Status

🧪 Under Passive Testing

The implementation of Go-F3 is complete and is currently undergoing passive testing in nv23. It has also been integrated into Lotus.

Project Structure

• blssig: BLS signature schemes.
• certexchange: Certificate exchange mechanisms.
• certstore: Certificate storage.
• cmd: Command line to run a standalone F3 participant.
• ec: Expected Consensus utilities.
• emulator: Network emulation tools.
• gpbft: GossipPBFT protocol implementation.
• merkle: Merkle tree implementations.
• sim: Simulation harness.
• test: Test suite for various components.

License

This project is dual-licensed under the MIT and Apache 2.0 licenses. See LICENSE-APACHE and LICENSE-MIT for more details.

Documentation

Index

• Variables
• type BroadcastMessage
• type F3
  • func New(_ctx context.Context, manifest manifest.Manifest, ds datastore.Datastore, ...) (*F3, error)
  • func (m *F3) Broadcast(ctx context.Context, signatureBuilder *gpbft.SignatureBuilder, msgSig []byte, ...)
  • func (m *F3) GetCert(ctx context.Context, instance uint64) (*certs.FinalityCertificate, error)
  • func (m *F3) GetLatestCert(context.Context) (*certs.FinalityCertificate, error)
  • func (m *F3) GetPowerTable(ctx context.Context, ts gpbft.TipSetKey) (gpbft.PowerEntries, error)
  • func (m *F3) GetPowerTableByInstance(ctx context.Context, instance uint64) (gpbft.PowerEntries, error)
  • func (m *F3) IsRunning() bool
  • func (m *F3) Manifest() manifest.Manifest
  • func (m *F3) MessagesToSign() <-chan *gpbft.MessageBuilder
  • func (m *F3) Progress() (instant gpbft.InstanceProgress)
  • func (m *F3) Start(startCtx context.Context) (_err error)
  • func (m *F3) Stop(ctx context.Context) (_err error)

Variables

var ErrF3NotRunning = errors.New("f3 is not running")

ErrF3NotRunning is returned when an operation is attempted on a non-running F3 instance.

Types

type BroadcastMessage

type BroadcastMessage func(*gpbft.MessageBuilder)

type F3

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

func New

func New(_ctx context.Context, manifest manifest.Manifest, ds datastore.Datastore, h host.Host,
	ps *pubsub.PubSub, verif gpbft.Verifier, ecBackend ec.Backend, diskPath string) (*F3, error)

New creates and setups f3 with libp2p The context is used for initialization not runtime.

func (*F3) Broadcast

func (m *F3) Broadcast(ctx context.Context, signatureBuilder *gpbft.SignatureBuilder, msgSig []byte, vrf []byte)

func (*F3) GetCert

func (m *F3) GetCert(ctx context.Context, instance uint64) (*certs.FinalityCertificate, error)

func (*F3) GetLatestCert

func (m *F3) GetLatestCert(context.Context) (*certs.FinalityCertificate, error)

func (*F3) GetPowerTable

func (m *F3) GetPowerTable(ctx context.Context, ts gpbft.TipSetKey) (gpbft.PowerEntries, error)

GetPowerTable returns the power table for the given tipset Used mainly for testing purposes

func (*F3) GetPowerTableByInstance

func (m *F3) GetPowerTableByInstance(ctx context.Context, instance uint64) (gpbft.PowerEntries, error)

GetPowerTableByInstance returns the power table (committee) used to validate the specified instance.

func (*F3) IsRunning

func (m *F3) IsRunning() bool

IsRunning returns true if gpbft is running Used mainly for testing purposes

func (*F3) Manifest

func (m *F3) Manifest() manifest.Manifest

func (*F3) MessagesToSign

func (m *F3) MessagesToSign() <-chan *gpbft.MessageBuilder

MessagesToSign returns a channel of outbound messages that need to be signed by the client(s). - The same channel is shared between all callers and will never be closed. - GPBFT will block if this channel is not read from.

func (*F3) Progress

func (m *F3) Progress() (instant gpbft.InstanceProgress)

func (*F3) Start

func (m *F3) Start(startCtx context.Context) (_err error)

Start the module, call Stop to exit. Canceling the past context will cancel the request to start F3, it won't stop the service after it has started.

func (*F3) Stop

func (m *F3) Stop(ctx context.Context) (_err error)

Stop F3.