f3

README

Go implementation of Fast Finality for Filecoin

This repository contains a Go implementation of the Filecoin finality module, F3 (WIP).

This executes an iterative GossiPBFT consensus protocol to declare tipsets as final when voted for by >2/3 of the consensus power.

Status

Work in progress.

This implementation began as a simulation during the protocol design phase. It is currently being transformed into production code, while maintaining and expanding the simulator.

Usage

Run the unit tests to exercise the GossipPBFT protocol.

$ go test ./...

There is also a main entry point to run GossiPBFT instance with honest nodes in simulation.

$ go run ./sim/cmd/f3sim -help
Usage of f3sim:
  -delta-back-off-exponent float
        exponential factor adjusting the delta value per round (default 1.3)
  -granite-delta float
        granite delta parameter (bound on message delay) (default 2)
  -iterations int
        number of simulation iterations (default 1)
  -latency-mean float
        mean network latency in seconds (default 0.5)
  -latency-seed int
        random seed for network latency (default <current time>)
  -max-rounds uint
        max rounds to allow before failing (default 10)
  -participants int
        number of participants (default 3)
  -trace int
        trace verbosity level

Integration

The code does not yet express an API for integration into a Filecoin node. Coming soon!

Structure

Modules:

• f3: the protocol implementation
• sim: the simulation harness
• adversary: specific adversarial behaviors for use in tests
• test: unit tests which execute the protocol in simulation

License

Dual-licensed under MIT + Apache 2.0

Documentation

Index

• type ECBackend
• type F3
  • func New(ctx context.Context, manifest Manifest, ds datastore.Datastore, h host.Host, ...) (*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(ctx context.Context) (*certs.FinalityCertificate, error)
  • func (m *F3) Run(ctx context.Context) error
  • func (m *F3) SubscribeForMessagesToSign(ch chan<- *gpbft.MessageBuilder) (closer func())
• type Logger
• type Manifest
  • func LocalnetManifest() Manifest
• type TipSet

Types

type ECBackend

type ECBackend interface {
	// GetTipsetByEpoch should return a tipset before the one requested if the requested
	// tipset does not exist due to null epochs
	GetTipsetByEpoch(ctx context.Context, epoch int64) (TipSet, error)
	GetTipset(context.Context, gpbft.TipSetKey) (TipSet, error)
	GetHead(context.Context) (TipSet, error)
	GetParent(context.Context, TipSet) (TipSet, error)

	GetPowerTable(context.Context, gpbft.TipSetKey) (gpbft.PowerEntries, error)
}

type F3

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

func New

func New(ctx context.Context, manifest Manifest, ds datastore.Datastore, h host.Host,
	ps *pubsub.PubSub, verif gpbft.Verifier, ec ECBackend, log Logger, signingMarshaller gpbft.SigningMarshaler) (*F3, error)

New creates and setups f3 with libp2p The context is used for initialization not runtime. signingMarshaller can be nil for default SigningMarshaler

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(ctx context.Context) (*certs.FinalityCertificate, error)

func (*F3) Run

func (m *F3) Run(ctx context.Context) error

Run start the module. It will exit when context is cancelled.

func (*F3) SubscribeForMessagesToSign

func (m *F3) SubscribeForMessagesToSign(ch chan<- *gpbft.MessageBuilder) (closer func())

SubscribeForMessagesToSign is used to subscribe to the message broadcast channel. After perparing inputs and signing over them, Broadcast should be called.

If the passed channel is full at any point, it will be dropped from subscription and closed. To stop subscribing, either the closer function can be used, or the channel can be abandoned. Passing a channel multiple times to the Subscribe function will result in a panic.

type Logger

type Logger interface {
	Debug(args ...interface{})
	Debugf(format string, args ...interface{})
	Error(args ...interface{})
	Errorf(format string, args ...interface{})
	Info(args ...interface{})
	Infof(format string, args ...interface{})
	Warn(args ...interface{})
	Warnf(format string, args ...interface{})
}

type Manifest

type Manifest struct {
	NetworkName       gpbft.NetworkName
	InitialInstance   uint64
	InitialPowerTable gpbft.PowerEntries
	BootstrapEpoch    int64

	ECFinality int64
	// The delay after a tipset is produced before we attempt to finalize it.
	ECDelay time.Duration
	// The delay between tipsets.
	ECPeriod         time.Duration
	CommiteeLookback uint64

	//Temporary
	ECBoostrapTimestamp time.Time
}

func LocalnetManifest

func LocalnetManifest() Manifest

type TipSet

type TipSet interface {
	Key() gpbft.TipSetKey
	Beacon() []byte
	Epoch() int64
	Timestamp() time.Time
}