Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
57 commits
Select commit Hold shift + click to select a range
a8dea77
Update Filecoin specification to align with FIP-0003
lanzafame Jul 10, 2025
18978dc
Update Filecoin specification to align with FIP-0004
lanzafame Jul 10, 2025
139a4ca
Update Filecoin specification to align with FIP-0005
lanzafame Jul 10, 2025
94d542b
Update Filecoin specification to align with FIP-0007
lanzafame Jul 10, 2025
eb1c8b1
Update Filecoin specification to align with FIP-0008
lanzafame Jul 10, 2025
878c372
Update Filecoin specification to align with FIP-0010
lanzafame Jul 10, 2025
e489529
Update Filecoin specification to align with FIP-0011
lanzafame Jul 10, 2025
1fc6df1
Update Filecoin specification to align with FIP-0012
lanzafame Jul 10, 2025
11b1913
Update Filecoin specification to align with FIP-0013
lanzafame Jul 10, 2025
3c59f4a
Update Filecoin specification to align with FIP-0014
lanzafame Jul 10, 2025
8fdeefa
Update Filecoin specification to align with FIP-0015
lanzafame Jul 10, 2025
b5cee0e
Update Filecoin specification to align with FIP-0018
lanzafame Jul 10, 2025
41914fc
Update Filecoin specification to align with FIP-0019
lanzafame Jul 10, 2025
66254b0
Update Filecoin specification to align with FIP-0020
lanzafame Jul 10, 2025
eef2b8f
Update Filecoin specification to align with FIP-0021
lanzafame Jul 10, 2025
7924ab0
Update Filecoin specification to align with FIP-0022
lanzafame Jul 10, 2025
444df57
Update Filecoin specification to align with FIP-0023
lanzafame Jul 10, 2025
cca3b2c
Update Filecoin specification to align with FIP-0024
lanzafame Jul 10, 2025
d195111
Update Filecoin specification to align with FIP-0026
lanzafame Jul 10, 2025
465586f
Update Filecoin specification to align with FIP-0028
lanzafame Jul 10, 2025
745e21f
Update Filecoin specification to align with FIP-0029
lanzafame Jul 10, 2025
e901ba7
Update Filecoin specification to align with FIP-0030
lanzafame Jul 10, 2025
80dc6a7
Update Filecoin specification to align with FIP-0031
lanzafame Jul 10, 2025
03a353d
Update Filecoin specification to align with FIP-0032
lanzafame Jul 10, 2025
cf3d766
Update Filecoin specification to align with FIP-0034
lanzafame Jul 10, 2025
9925353
Update Filecoin specification to align with FIP-0041
lanzafame Jul 10, 2025
cc02da7
Update Filecoin specification to align with FIP-0044
lanzafame Jul 10, 2025
b480f19
Update Filecoin specification to align with FIP-0045
lanzafame Jul 10, 2025
afb618e
Update Filecoin specification to align with FIP-0048
lanzafame Jul 10, 2025
0fdb9c6
Update Filecoin specification to align with FIP-0049
lanzafame Jul 10, 2025
287ea9a
Update Filecoin specification to align with FIP-0050
lanzafame Jul 10, 2025
3394fd1
Update Filecoin specification to align with FIP-0052
lanzafame Jul 10, 2025
858a1c4
Update Filecoin specification to align with FIP-0054
lanzafame Jul 10, 2025
8f48f24
Update Filecoin specification to align with FIP-0055
lanzafame Jul 10, 2025
df39282
Update Filecoin specification to align with FIP-0057
lanzafame Jul 10, 2025
37fd3f9
Update Filecoin specification to align with FIP-0059
lanzafame Jul 10, 2025
d90b7ae
Update Filecoin specification to align with FIP-0060
lanzafame Jul 10, 2025
87b0602
Update Filecoin specification to align with FIP-0061
lanzafame Jul 10, 2025
52c9bee
Update Filecoin specification to align with FIP-0062
lanzafame Jul 10, 2025
77ea7a0
Update Filecoin specification to align with FIP-0063
lanzafame Jul 10, 2025
4d23623
Update Filecoin specification to align with FIP-0065
lanzafame Jul 10, 2025
418a10f
Update Filecoin specification to align with FIP-0067
lanzafame Jul 10, 2025
f3de654
Update Filecoin specification to align with FIP-0071
lanzafame Jul 10, 2025
a221643
Update Filecoin specification to align with FIP-0072
lanzafame Jul 10, 2025
e65c59e
Update Filecoin specification to align with FIP-0073
lanzafame Jul 10, 2025
c9897c8
Update Filecoin specification to align with FIP-0074
lanzafame Jul 10, 2025
d5e7819
Update Filecoin specification to align with FIP-0075
lanzafame Jul 10, 2025
050702e
Update Filecoin specification to align with FIP-0076
lanzafame Jul 10, 2025
6b97d14
Update Filecoin specification to align with FIP-0079
lanzafame Jul 10, 2025
138600d
Update Filecoin specification to align with FIP-0081
lanzafame Jul 10, 2025
716408b
Update Filecoin specification to align with FIP-0082
lanzafame Jul 10, 2025
971e30a
Update Filecoin specification to align with FIP-0083
lanzafame Jul 10, 2025
62c9bd2
Update Filecoin specification to align with FIP-0084
lanzafame Jul 10, 2025
d3dfa1d
Update Filecoin specification to align with FIP-0085
lanzafame Jul 10, 2025
ee44919
Update Filecoin specification to align with FIP-0086
lanzafame Jul 11, 2025
960df62
Add .gitignore to exclude workspace metadata files
lanzafame Jul 11, 2025
f234b83
Update Filecoin specification to align with FIP-0091
lanzafame Jul 11, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions content/algorithms/crypto/randomness.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ dashboardAudit: wip
dashboardTests: 0
---

<!-- YAML
added: FIP-0000
changes:
- fip: FIP-0075
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0075.md
description: Moved entropy mixing from FVM syscalls to actor code, introduced proportional gas costs for lookback operations.
-->

# Randomness

Randomness is used throughout the protocol in order to generate values and extend the blockchain.
Expand Down Expand Up @@ -66,6 +74,52 @@ GetRandomness(dst, l, s):
return H(buffer)
```

## FVM Randomness Syscalls

The FVM provides two syscalls for fetching randomness:
- `get_chain_randomness(round: ChainEpoch)` - Returns randomness from the ticket chain
- `get_beacon_randomness(round: ChainEpoch)` - Returns randomness from the beacon

These syscalls return the raw randomness value without any entropy mixing. Actors must perform their own randomness drawing by mixing in entropy using the following algorithm:

```rust
pub fn draw_randomness(
rbase: &[u8; 32],
pers: i64,
round: i64,
entropy: &[u8],
) -> [u8; 32] {
let mut data = Vec::with_capacity(32 + 8 + 8 + entropy.len());

// Append the personalization value (DST)
let i64_bytes = pers.to_be_bytes();
data.extend_from_slice(&i64_bytes);

// Append the randomness
data.extend_from_slice(rbase);

// Append the round
let i64_bytes = round.to_be_bytes();
data.extend_from_slice(&i64_bytes);

// Append the entropy
data.extend_from_slice(entropy);

// Hash this data using Blake2b
fvm::crypto::hash_blake2b(&data)
}
```

### Gas Costs for Randomness Lookback

Both `get_chain_randomness` and `get_beacon_randomness` operations, as well as the `get_tipset_cid` operation, have gas costs proportional to the lookback distance (the difference between the current epoch and the requested epoch):

**Gas cost formula**: `75 * lookback + 146200`

This pricing ensures that operations requiring deep chain traversal are appropriately charged based on the computational work required. The formula accounts for:
- 75 gas per epoch of lookback (based on skiplist traversal)
- 146,200 gas for base overhead (serialization, hashing, and syscall costs)

## Drawing tickets from the VRF-chain for proof inclusion

In some places, the protocol needs randomness drawn from the Filecoin blockchain's VRF-chain (which generates [tickets](storage_power_consensus#tickets) with each new block) rather than from the random beacon, in order to tie certain proofs to a particular set of Filecoin blocks (i.e. a given chain or fork).
Expand Down
63 changes: 63 additions & 0 deletions content/algorithms/crypto/signatures.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ dashboardAudit: coming
dashboardTests: 0
---

<!-- YAML
added: FIP-0000
changes:
- fip: FIP-0079
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0079.md
description: Added FVM syscall for BLS aggregate signature verification and removed generic verify_signature syscall.
-->

# Signatures

Signatures are cryptographic functions that attest to the origin of a particular
Expand Down Expand Up @@ -139,3 +147,58 @@ to avoid replay attacks. As a direct consequence, every message is unique
thereby the aggregation is done on distinct messages. Obviously, the
**assumption** here is that the block producer **enforces that distinction** and
the other miners will **check all messages** to make sure they are valid.

## FVM Signature Verification

### Syscalls

The FVM provides specialized syscalls for signature verification:

- **`verify_bls_aggregate`**: Verifies BLS aggregate signatures (also supports non-aggregate BLS signatures)
- **`hash`**: Computes cryptographic hashes
- **`recover_secp_public_key`**: Recovers public key from Secp256k1 signatures

The generic `verify_signature` syscall was removed in favor of these specialized syscalls for better performance and security.

### BLS Aggregate Signature Verification

The `verify_bls_aggregate` syscall supports verification of both aggregate and non-aggregate BLS signatures:

```rust
pub fn verify_bls_aggregate(
num_signers: u32,
sig_off: *const u8,
pub_keys_off: *const [u8; BLS_PUB_LEN],
plaintexts_off: *const u8,
plaintext_lens_off: *const u32,
) -> Result<i32>;
```

**Key Features**:
- Supports multiple signers signing multiple messages with a single signature
- Enforces plaintext uniqueness (no duplicate messages)
- Rejects public keys that are the G1 identity/zero point
- Returns 0 for valid signatures, -1 for invalid

**Gas Pricing**:
```rust
const BLS_GAS_PER_PLAINTEXT_BYTE: usize = 7;
const BLS_GAS_PER_PAIRING: usize = 8_299_302;

fn verify_bls_aggregate_gas(plaintexts: &[&[u8]]) -> usize {
let total_plaintext_len = plaintexts.iter().map(|p| p.len()).sum();
let num_pairings = plaintexts.len() + 1;
BLS_GAS_PER_PLAINTEXT_BYTE * total_plaintext_len + BLS_GAS_PER_PAIRING * num_pairings
}
```

### SDK Functions

The FVM SDK provides high-level functions for signature verification:

- **`verify_bls_aggregate`**: Verifies BLS aggregate signatures
- **`verify_signature`**: Verifies non-aggregate signatures (Secp256k1 or BLS)

The `verify_signature` SDK function is implemented using the underlying syscalls:
- For Secp256k1: Uses `hash` and `recover_secp_public_key` syscalls
- For BLS: Uses `verify_bls_aggregate` syscall with a single signature
2 changes: 1 addition & 1 deletion content/algorithms/cryptoecon/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The following table summarizes initial parameter recommendations for Filecoin. M
| Percent simple minting vs baseline minting | 30% / 70% |
| Reward delay and linear vesting period | 0 days |
| Linear vesting period | 180 days |
| Sector quality multipliers | Committed Capacity: 1x <br> Regular Deals: 1x <br> Verified Client Deals: 10x |
| Sector quality multipliers | Committed Capacity: 1x <br> Regular Deals: 1x <br> Filecoin Plus Deals: 10x |
| Initial pledge function | 20 days worth of block reward + <br> share of 30% qa power-normalized circulating supply |
| Initial Pledge Cap | 1FIL/32GiB QA Power |
| Minimum sector lifetime | 180 days |
Expand Down
20 changes: 18 additions & 2 deletions content/algorithms/expected_consensus/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,14 @@ potentially long chain scans would be required to compute a given block's weight

### Selecting between Tipsets with equal weight

<!-- YAML
added: FIP-0023
changes:
- fip: FIP-0023
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0023.md
description: Formalized the tie-breaking rule for tipsets of equal weight.
-->

When selecting between Tipsets of equal weight, a miner chooses the one with the smallest final ElectionProof ticket.

In the case where two Tipsets of equal weight have the same minimum VRF output, the miner will compare the next smallest ticket in the Tipset (and select the Tipset with the next smaller ticket). This continues until one Tipset is selected.
Expand Down Expand Up @@ -402,6 +410,14 @@ A single consensus fault results into:

### Detection and Reporting

A node that detects and reports a consensus fault is called "slasher". Any user in Filecoin can be a slasher. They can report consensus faults by calling the `ReportConsensusFault` on the `StorageMinerActor` of the faulty miner. The slasher is rewarded with a portion of the penalty paid by the offending miner's `ConsensusFaultPenalty` for notifying the network of the consensus fault. Note that some slashers might not get the full reward because of the low balance of the offending miners. However rational honest miners are still incentivised to notify the network about consensus faults.
<!-- YAML
added: FIP-0000
changes:
- fip: FIP-0011
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0011.md
description: Removed Dutch auction mechanism; reporter reward is now fixed at BlockReward/4.
-->

A node that detects and reports a consensus fault is called "slasher". Any user in Filecoin can be a slasher. They can report consensus faults by calling the `ReportConsensusFault` on the `StorageMinerActor` of the faulty miner. The slasher is rewarded for notifying the network of the consensus fault.

The reward given to the slasher is a function of some initial share (`SLASHER_INITIAL_SHARE`) and growth rate (`SLASHER_SHARE_GROWTH_RATE`) and it has a maximum `maxReporterShare`. Slasher's share increases exponentially as epoch elapses since the block when the fault is committed (see `RewardForConsensusSlashReport`). Only the first slasher gets their share of the pledge collateral and the remaining pledge collateral is burned. The longer a slasher waits, the higher the likelihood that the slashed collateral will be claimed by another slasher.
Since FIP-0011, the reward given to the slasher is fixed at `BlockReward / 4`, where `BlockReward` is the reward that would be awarded to a single miner at the current epoch. This replaced the previous Dutch auction mechanism that delayed reporting by making rewards increase over time. The fixed reward incentivizes immediate reporting of consensus faults, which is essential for maintaining the fairness of Expected Consensus. Only the first slasher receives the reward.
36 changes: 36 additions & 0 deletions content/algorithms/pos/porep.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,17 @@ dashboardTests: 0

# Proof-of-Replication (PoRep)

<!-- YAML
added: FIP-0000
changes:
- fip: FIP-0059
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0059.md
description: Introduced Synthetic PoRep to reduce temporary storage requirements between PreCommit and ProveCommit.
- fip: FIP-0067
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0067.md
description: Established security policy and replacement sealing mechanism for addressing potential PoRep vulnerabilities.
-->

In order to register a sector with the Filecoin network, the sector has to be sealed. Sealing is a computation-heavy process that produces a unique representation of the data in the form of a proof, called **_Proof-of-Replication_** or PoRep.

The PoRep proof ties together: i) the data itself, ii) the miner actor that performs the sealing and iii) the time when the specific data has been sealed by the specific miner. In other words, if the same miner attempts to seal the same data at a later time, then this will result in a different PoRep proof. Time is included as the blockchain height when sealing took place and the corresponding chain reference is called `SealRandomness`.
Expand All @@ -19,3 +30,28 @@ The PoRep process includes the following two phases:

- **Sealing preCommit phase 1.** In this phase, PoRep SDR [encoding](sdr#encoding) and [replication](sdr#replication) takes place.
- **Sealing preCommit phase 2.** In this phase, [Merkle proof and tree generation](sdr#merkle-proofs) is performed using the Poseidon hashing algorithm.

## Synthetic PoRep

Since FIP-0059, storage providers can optionally use Synthetic PoRep, which significantly reduces the temporary storage requirements between PreCommit and ProveCommit from ~400GiB to ~25GiB, with no impact on security.

### How Synthetic PoRep Works

1. **Challenge Generation**: Based on the CommR, the storage provider generates N_syn = 2^18 synthetic challenges before submitting PreCommit on-chain
2. **Precomputation**: The provider computes vanilla proofs for all synthetic challenges and stores them (~25GiB)
3. **Layer Removal**: Since all possible challenges are precomputed, the provider can delete the ~400GiB of layer data
4. **Interactive Proving**: After PreCommitChallengeDelay (150 epochs), the provider uses on-chain randomness to select N_verified = 176 challenges from the precomputed set
5. **SNARK Generation**: The provider generates SNARK proofs only for the selected challenges

### Benefits

- **Storage Reduction**: >90% reduction in temporary storage requirements
- **Same Security**: No impact on PoRep security guarantees
- **Optional Feature**: Providers can choose between standard and synthetic PoRep
- **No Additional Overhead**: Same proving costs and on-chain flow

### Proof Types

Two new proof types support Synthetic PoRep:
- `RegisteredSealProof_SynthStackedDrg32GiBV1` (32 GiB sectors)
- `RegisteredSealProof_SynthStackedDrg64GiBV1` (64 GiB sectors)
73 changes: 73 additions & 0 deletions content/algorithms/pos/post.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,17 @@ Recall, that the probability of a storage miner being elected to mine a block is

## WindowPoSt

<!-- YAML
added: FIP-0000
changes:
- fip: FIP-0010
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0010.md
description: Introduced off-chain Window PoSt verification with optimistic acceptance and dispute mechanism.
- fip: FIP-0061
pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0061.md
description: Fixed WindowPoSt challenge generation to be independent of sector ordering.
-->

WindowPoSt is the mechanism by which the commitments made by storage miners are audited. In _WindowPoSt_ every 24-hour period is called a _"proving period"_ and is broken down into a series of 30min, non-overlapping _deadlines_, making a total of 48 deadlines within any given 24-hour proving period. Every miner must demonstrate availability of all claimed sectors on a 24hr basis. Constraints on individual proof computations limit a single proof to 2349 sectors (a partition), with 10 challenges each.

In particular, the sectors that a miner has pledged to store are: i) assigned to _deadlines_, and ii) grouped in _partitions_. It is important to highlight that although sectors are assigned to deadlines, sectors are proven in partitions - not individually. In other words, upon every deadline, a miner has to prove a whole partition.
Expand Down Expand Up @@ -85,3 +96,65 @@ There are four relevant epochs associated to a deadline, shown in the table belo
| `Close` | `WPoStChallengeWindow` | Epoch after which a PoSt Proof for this deadline will be rejected. |
| `FaultCutoff` | `-FaultDeclarationCutoff` | Epoch after which a `miner.DeclareFault` and `miner.DeclareFaultRecovered` for sectors in the upcoming deadline are rejected. |
| `Challenge` | `-WPoStChallengeLookback` | Epoch at which the randomness for the challenges is available. |

## Off-chain Verification and Dispute Mechanism

Since FIP-0010, Window PoSt proofs are optimistically accepted on-chain without verification to reduce gas costs and chain bandwidth usage. This creates a trust-but-verify system where proofs can be disputed if they are invalid.

### Optimistic Acceptance
- Window PoSt proofs are accepted without on-chain verification
- Exception: Proofs that recover faulty sectors are still verified on-chain to prevent abuse
- Proofs are stored in the deadline state for the dispute window period

### Dispute Window
- Duration: 1800 epochs (2x finality) after the challenge window closes
- Any party can dispute an invalid proof using `DisputeWindowedPoSt`
- Successful disputes result in:
- All incorrectly proven sectors marked as faulty
- Miner loses power for those sectors
- Miner fined 5.51 times expected block reward per sector plus 20 FIL flat fee
- Disputer receives 4 FIL reward

### Restrictions During Dispute Window
- `CompactPartitions` is forbidden during the dispute window to prevent evasion
- `TerminateSectors` is forbidden for the current and next deadline

This mechanism maintains network security while significantly reducing operational costs for honest miners.

## Challenge Generation

WindowPoSt requires generating cryptographic challenges for each sector to prove continued storage. The challenge generation algorithm determines which specific nodes (data chunks) within each sector must be proven.

### Grindability Fix (FIP-0061)

Prior to FIP-0061, WindowPoSt challenge generation had a vulnerability where challenges depended on the order of sectors provided. This allowed malicious storage providers to potentially manipulate challenges by reordering sectors to gain unfair advantages.

Since FIP-0061, challenge generation is **independent of sector ordering**:

#### Updated Algorithm
```rust
// Challenge generation per sector (post-FIP-0061)
let sector_challenge_indexes = 0..challenge_count_per_sector;
for challenge_index in sector_challenge_indexes {
let rand_int = u64::from_le_bytes(
sha256(chain_randomness || sector_id || challenge_index)[..8]
);
let challenge = rand_int % sector_nodes;
}
```

Key improvements:
- `challenge_index` is now **relative to each sector** (0 to challenge_count_per_sector)
- Previously, `challenge_index` was global across all sectors in the WindowPoSt
- Each sector's challenges are derived independently using only:
- Chain randomness
- Sector ID
- Challenge index within that sector

### New Proof Types

FIP-0061 introduced new proof types to signal the updated behavior:
- `StackedDrgWindow32GiBV1_1` (replacing V1)
- `StackedDrgWindow64GiBV1_1` (replacing V1)

All miners were automatically migrated to V1_1 proof types during the network upgrade, ensuring uniform security improvements across the network.
Loading
Loading