Skip to content

frc-f3-augmented-snapshot.md

Latest commit

 

History

History
138 lines (99 loc) · 8.54 KB

frc-f3-augmented-snapshot.md

File metadata and controls

138 lines (99 loc) · 8.54 KB
Raw
fip ####
title Augment Filecoin Snapshot with F3 data
author Hailong Mu (@hanabi1224)
discussions-to filecoin-project/go-f3#480
status Draft
type FRC
created 2025-06-25

FRC-####: Augment Filecoin Snapshot with F3 data

Simple Summary

Downloading F3 finality certificates from scratch takes a long time and increases the p2p network bandwidth usage. An F3 snapshot is proposed to be included in the Filecoin CAR snapshot to reduce F3 catchup time and p2p network bandwidth usage on bootstrapping a Filecoin node with a Filecoin snapshot.

Abstract

We propose extending the Filecoin CAR snapshot with an F3 snapshot as a raw data block, and changing CAR roots to be a CID that points to a CBOR-encoded Filecoin snapshot header struct.

Motivation

The time cost and the network bandwidth usage for a new Filecoin node to catch up with all F3 finality certificates grow over time, which delays the readiness of the F3-aware V2 RPC APIs. By embedding an F3 snapshot into the current Filecoin CAR snapshot, both can be vastly reduced at the cost of a slightly increased Filecoin CAR snapshot size.

Specification

We propose the blow changes to the Filecoin CAR snapshot format.

  • Change CAR roots to be a CID that points to a CBOR-encoded SnapshotMetadata struct that is stored as the first data block in the CAR.
  • Store the raw F3Snapshot bytes as the second data block in the CAR when F3Data != nil in the metadata.

SnapshotMetadata

type SnapshotMetadata {
    HeadTipsetKey []Cid // required
    F3Data        *Cid  // optional
}

F3Snapshot

An F3 snapshot contains one header block and N(N>0) data blocks in the below format:

[Header block] [Data block] [Data block] [Data block] ...

A header block is a CBOR-encoded F3SnapshotHeader with a length prefix in the below format:

[varint-encoded length] [CBOR-encoded F3SnapshotHeader]

F3SnapshotHeader

type SnapshotHeader struct {
	Version           uint64
	FirstInstance     uint64
	LatestInstance    uint64
	InitialPowerTable gpbft.PowerEntries
}

A data block is a CBOR-encoded FinalityCertificate with a length prefix in the below format:

[varint-encoded length] [CBOR-encoded FinalityCertificate]

FinalityCertificate

// FinalityCertificate represents a single finalized GPBFT instance.
type FinalityCertificate struct {
	// The GPBFT instance to which this finality certificate corresponds.
	GPBFTInstance uint64
	// The ECChain finalized during this instance, starting with the last tipset finalized in
	// the previous instance.
	ECChain *gpbft.ECChain
	// Additional data signed by the participants in this instance. Currently used to certify
	// the power table used in the next instance.
	SupplementalData gpbft.SupplementalData
	// Indexes in the base power table of the certifiers (bitset)
	Signers bitfield.BitField
	// Aggregated signature of the certifiers
	Signature []byte
	// Changes between the power table used to validate this finality certificate and the power
	// used to validate the next finality certificate. Sorted by ParticipantID, ascending.
	PowerTableDelta PowerTableDiff `json:"PowerTableDelta,omitempty"`
}

Notes:

  • FinalityCertificates should be ordered by GPBFTInstance in ascending order, thus they can be validated and intermediate power tables can be generated while data blocks are being read in a stream.
  • The first and last FinalityCertificate instances should match those in the header, respectively.

Backwards Compatibility

  • A filecoin node should try to read a snapshot CAR in the proposed format, and fallback to the old format to maintain backward compatibility.
  • CLI options should remain unchanged to make it transparent to the node users.
  • The code change in all Filecoin nodes should be shipped with a network upgrade, and the Filecoin snapshot providers should only start publishing with the new format after the mainnet upgrade finishes to avoid potential errors during snapshot import for node users.

Test Cases

Security Considerations

This change has minimal security implications as the additional F3 data are also stored in the node database, unencrypted. Key considerations:

  • Integrity: The F3 snapshot can be validated.
  • Performance The F3 snapshot data blocks can be read, validated and imported in a stream.

The change does not introduce new attack vectors or modify existing security properties of the protocol.

Incentive Considerations

Node users should experience faster F3 bootstrapping time and less network bandwidth usage.

Product Considerations

Nodes starting from a snapshot should not rely on the certificate exchange protocol to catch up with the F3 data because we expect this will get slower over time. A slow F3 catchup time leads to, e.g.

  • delay in the readiness of F3-aware RPC APIs

Implementation

Future Work

Copyright

Copyright and related rights waived via CC0.