Skip to content

Commit ab861a1

Browse files
hanabi1224hanabi1224
committed
frc: f3-augmented-snapshot
1 parent 2c4e07a commit ab861a1

2 files changed

Lines changed: 139 additions & 0 deletions

File tree

‎FRCs/frc-f3-augmented-snapshot.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
fip: "####"
3+
title: "Augment Filecoin Snapshot with F3 data"
4+
author: "Hailong Mu (@hanabi1224)"
5+
discussions-to: https://github.com/filecoin-project/go-f3/issues/480
6+
status: Draft
7+
type: "FRC"
8+
created: 2025-06-25
9+
---
10+
11+
# FRC-####: Augment Filecoin Snapshot with F3 data
12+
13+
## Simple Summary
14+
<!--"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the FIP.-->
15+
16+
Downloading F3 finality certificates from scratch takes a long time and increases the p2p network bandwidth usage.
17+
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
18+
a Filecoin node with a Filecoin snapshot.
19+
20+
## Abstract
21+
<!--A short (~200 words) description of the technical issue being addressed.-->
22+
23+
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.
24+
25+
## Motivation
26+
<!--The motivation is critical for FIPs that want to change the Filecoin protocol. It should clearly explain why the existing protocol specification is inadequate to address the problem that the FIP solves. FIP submissions without sufficient motivation may be rejected outright.-->
27+
28+
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.
29+
30+
## Specification
31+
<!--The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any current Filecoin implementations. -->
32+
33+
We propose the blow changes to the Filecoin CAR snapshot format.
34+
35+
- Change CAR roots to be a CID that points to a CBOR-encoded [`SnapshotMetadata`](#snapshotmetadata) struct that is stored as the first data block in the CAR.
36+
- Store the raw [`F3Snapshot`](#f3snapshot) bytes as the second data block in the CAR when `F3Data != nil` in the metadata.
37+
38+
### SnapshotMetadata
39+
40+
```go
41+
type SnapshotMetadata {
42+
HeadTipsetKey []Cid // required
43+
F3Data *Cid // optional
44+
}
45+
```
46+
47+
### F3Snapshot
48+
49+
An F3 snapshot contains one header block and N(N>0) data blocks in the below format:
50+
51+
`[Header block] [Data block] [Data block] [Data block] ...`
52+
53+
A header block is a CBOR-encoded [`F3SnapshotHeader`](#f3snapshotheader) with a length prefix in the below format:
54+
55+
`[varint-encoded length] [CBOR-encoded F3SnapshotHeader]`
56+
57+
### F3SnapshotHeader
58+
59+
```go
60+
type SnapshotHeader struct {
61+
Version uint64
62+
FirstInstance uint64
63+
LatestInstance uint64
64+
InitialPowerTable gpbft.PowerEntries
65+
}
66+
```
67+
68+
A data block is a CBOR-encoded [`FinalityCertificate`](#finalitycertificate) with a length prefix in the below format:
69+
70+
`[varint-encoded length] [CBOR-encoded FinalityCertificate]`
71+
72+
### FinalityCertificate
73+
74+
```go
75+
// FinalityCertificate represents a single finalized GPBFT instance.
76+
type FinalityCertificate struct {
77+
// The GPBFT instance to which this finality certificate corresponds.
78+
GPBFTInstance uint64
79+
// The ECChain finalized during this instance, starting with the last tipset finalized in
80+
// the previous instance.
81+
ECChain *gpbft.ECChain
82+
// Additional data signed by the participants in this instance. Currently used to certify
83+
// the power table used in the next instance.
84+
SupplementalData gpbft.SupplementalData
85+
// Indexes in the base power table of the certifiers (bitset)
86+
Signers bitfield.BitField
87+
// Aggregated signature of the certifiers
88+
Signature []byte
89+
// Changes between the power table used to validate this finality certificate and the power
90+
// used to validate the next finality certificate. Sorted by ParticipantID, ascending.
91+
PowerTableDelta PowerTableDiff `json:"PowerTableDelta,omitempty"`
92+
}
93+
```
94+
95+
Notes:
96+
- `FinalityCertificate`s 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.
97+
- The first and last `FinalityCertificate` instances should match those in the header, respectively.
98+
99+
## Backwards Compatibility
100+
<!--All FIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The FIP must explain how the author proposes to deal with these incompatibilities. FIP submissions without a sufficient backwards compatibility treatise may be rejected outright.-->
101+
102+
- A filecoin node should try to read a snapshot CAR in the proposed format, and fallback to the old format to maintain backward compatibility.
103+
- CLI options should remain unchanged to make it transparent to the node users.
104+
- 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.
105+
106+
## Test Cases
107+
<!--Test cases for an implementation are mandatory for FIPs affecting consensus changes. Other FIPs can choose to include links to test cases if applicable.-->
108+
109+
## Security Considerations
110+
<!--All FIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. FIP submissions missing the "Security Considerations" section will be rejected. A FIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers.-->
111+
112+
This change has minimal security implications as the additional F3 data are also stored in the node database, unencrypted. Key considerations:
113+
114+
- **Integrity**: The F3 snapshot can be validated.
115+
- **Performance** The F3 snapshot data blocks can be read, validated and imported in a stream.
116+
117+
The change does not introduce new attack vectors or modify existing security properties of the protocol.
118+
119+
## Incentive Considerations
120+
<!--All FIPs must contain a section that discusses the incentive implications/considerations relative to the proposed change. Include information that might be important for incentive discussion. A discussion on how the proposed change will incentivize reliable and useful storage is required. FIP submissions missing the "Incentive Considerations" section will be rejected. An FIP cannot proceed to status "Final" without a Incentive Considerations discussion deemed sufficient by the reviewers.-->
121+
122+
Node users should experience faster F3 bootstrapping time and less network bandwidth usage.
123+
124+
## Product Considerations
125+
<!--All FIPs must contain a section that discusses the product implications/considerations relative to the proposed change. Include information that might be important for product discussion. A discussion on how the proposed change will enable better storage-related goods and services to be developed on Filecoin. FIP submissions missing the "Product Considerations" section will be rejected. An FIP cannot proceed to status "Final" without a Product Considerations discussion deemed sufficient by the reviewers.-->
126+
127+
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.
128+
129+
- delay in the readiness of F3-aware RPC APIs
130+
131+
## Implementation
132+
<!--The implementations must be completed before any core FIP is given status "Final", but it need not be completed before the FIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.-->
133+
134+
## Future Work
135+
<!--A section that lists any unresolved issues or tasks that are part of the FIP proposal. Examples of these include performing benchmarking to know gas fees, validate claims made in the FIP once the final implementation is ready, etc. A FIP can only move to a "Last Call" status once all these items have been resolved.-->
136+
137+
## Copyright
138+
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,3 +141,4 @@ This improvement protocol helps achieve that objective for all members of the Fi
141141
| [0103](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0103.md) | Removal of the ExtendSectorExpiration method from the miner actor | FIP | Rod Vagg (@rvagg) | Draft |
142142
| [0106](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0106.md) | Removal of the ProveReplicaUpdates method from the miner actor | FIP | Rod Vagg (@rvagg) | Draft |
143143
| [0107](https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0107.md) | Implicit Messages in Block Receipts | FIP | Rod Vagg (@rvagg) | Draft |
144+
| [XXXX](https://github.com/filecoin-project/FIPs/blob/master/FRPCs/frc-f3-augmented-snapshot.md) | Implicit Messages in Block Receipts | FRC | Hailong Mu (@hanabi1224) | Draft |

0 commit comments

Comments
 (0)