diff --git a/content/algorithms/crypto/randomness.md b/content/algorithms/crypto/randomness.md index 5007bd217..3e04cbfe1 100644 --- a/content/algorithms/crypto/randomness.md +++ b/content/algorithms/crypto/randomness.md @@ -7,6 +7,14 @@ dashboardAudit: wip dashboardTests: 0 --- + + # Randomness Randomness is used throughout the protocol in order to generate values and extend the blockchain. @@ -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). diff --git a/content/algorithms/crypto/signatures.md b/content/algorithms/crypto/signatures.md index 9070e47a6..f3f130909 100644 --- a/content/algorithms/crypto/signatures.md +++ b/content/algorithms/crypto/signatures.md @@ -7,6 +7,14 @@ dashboardAudit: coming dashboardTests: 0 --- + + # Signatures Signatures are cryptographic functions that attest to the origin of a particular @@ -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; +``` + +**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 diff --git a/content/algorithms/cryptoecon/_index.md b/content/algorithms/cryptoecon/_index.md index dd5a995d7..a415b46c5 100644 --- a/content/algorithms/cryptoecon/_index.md +++ b/content/algorithms/cryptoecon/_index.md @@ -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
Regular Deals: 1x
Verified Client Deals: 10x | +| Sector quality multipliers | Committed Capacity: 1x
Regular Deals: 1x
Filecoin Plus Deals: 10x | | Initial pledge function | 20 days worth of block reward +
share of 30% qa power-normalized circulating supply | | Initial Pledge Cap | 1FIL/32GiB QA Power | | Minimum sector lifetime | 180 days | diff --git a/content/algorithms/expected_consensus/_index.md b/content/algorithms/expected_consensus/_index.md index 78997d59f..ff0089a8c 100644 --- a/content/algorithms/expected_consensus/_index.md +++ b/content/algorithms/expected_consensus/_index.md @@ -353,6 +353,14 @@ potentially long chain scans would be required to compute a given block's weight ### Selecting between Tipsets with 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. @@ -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. + + +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. diff --git a/content/algorithms/pos/porep.md b/content/algorithms/pos/porep.md index eaf4b0dec..e25977579 100644 --- a/content/algorithms/pos/porep.md +++ b/content/algorithms/pos/porep.md @@ -9,6 +9,17 @@ dashboardTests: 0 # Proof-of-Replication (PoRep) + + 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`. @@ -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) diff --git a/content/algorithms/pos/post.md b/content/algorithms/pos/post.md index 6102f4c94..a44768e8e 100644 --- a/content/algorithms/pos/post.md +++ b/content/algorithms/pos/post.md @@ -38,6 +38,17 @@ Recall, that the probability of a storage miner being elected to mine a block is ## WindowPoSt + + 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. @@ -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. diff --git a/content/algorithms/verified_clients/_index.md b/content/algorithms/verified_clients/_index.md index 473ff7dbf..c6710cc68 100644 --- a/content/algorithms/verified_clients/_index.md +++ b/content/algorithms/verified_clients/_index.md @@ -1,5 +1,5 @@ --- -title: Verified Clients +title: Filecoin Plus weight: 8 dashboardWeight: 2 dashboardState: wip @@ -7,10 +7,70 @@ dashboardAudit: wip dashboardTests: 0 --- -# Verified Clients +# Filecoin Plus -As described earlier, verified clients as a construction make the Filecoin Economy more robust and valuable. While a storage miner may choose to forgo deal payments and self-deal to fill their storage and earn block rewards, this is not as valuable to the economy and should not be heavily subsidized. However, in practice, it is impossible to tell useful data apart from encrypted zeros. Introducing verified clients pragmatically solves this problem through social trust and validation. There will be a simple and open verification process to become a verified client; this process should attract clients who will bring real storage demand to the Filecoin Economy. +Filecoin Plus is a layer of social trust designed to maximize the amount of useful storage on Filecoin. While a storage miner may choose to forgo deal payments and self-deal to fill their storage and earn block rewards, this is not as valuable to the economy and should not be heavily subsidized. However, in practice, it is impossible to tell useful data apart from encrypted zeros. Filecoin Plus pragmatically solves this problem through social trust and validation. The program operates through a decentralized network of Notaries who allocate DataCap to clients, enabling them to make deals that carry a 10x quality multiplier. -Verifiers should eventually form a decentralized, globally distributed network of entities that confirms the useful storage demand of verified clients. If a verifier evaluates and affirms a client’s demand to have real data stored, that client will be able to add up to a certain amount of data to the network as verified client deals; this limit is called a DataCap allocation. Verified clients can request an increased DataCap once they have used their full allocation and Verifiers should perform some due diligence to ensure that the clients are not maliciously exploiting verification. The verification process will evolve over time to become more efficient, decentralized, and robust. +## Roles and Responsibilities -Storage demand on the network will shape the storage offering provided by miners. With the ability to deploy data with a greater sector quality multiplier, verified clients play an even more important role in shaping the quality of service, geographic distribution, degree of decentralization, and consensus security of the network. Verifiers and verified clients must be cognizant of the value and responsibility that come with their role. Additionally, it is conceivable for miners to have a business development team to source valuable and useful datasets in the world, growing demand for the storage they provide. Teams would be incentivized to help their clients through the verification process and start storing data on the Filecoin Network, in addition to providing their clients with strong SLAs. +### Root Key Holders +Root Key Holders are signers to a multisig on chain with the power to grant and remove Notaries. They act as executors for decisions made by community governance, requiring a majority to sign for any action. + +### Notaries + + + +Notaries form a decentralized, globally distributed network of entities that confirm the useful storage demand of Filecoin Plus clients. They are entrusted with DataCap to allocate to clients based on trust and verification. When a Notary evaluates and affirms a client's demand to have real data stored, that client receives a DataCap allocation. + +Since FIP-0012, Filecoin Plus clients can receive additional DataCap allocations to the same address at any time, without needing to fully deplete their existing balance. When topping up an existing client, the new allocation is added to their current DataCap balance. Notaries perform due diligence to ensure clients are not maliciously exploiting the system and should check existing allocations before approving additional DataCap. + +Since FIP-0028, Notaries also have the ability to remove DataCap from client addresses in cases of inactivity or abuse of the Filecoin Plus system. DataCap removal requires approval from two Notaries and two Root Key Holders, ensuring appropriate checks and balances. When a client's DataCap is reduced to zero or below, their verified client status is revoked. + +### Filecoin Plus Clients +Clients are active participants with DataCap allocation for their use cases. They can use DataCap to incentivize miners to provide additional features and service levels. Clients must deploy DataCap responsibly in accordance with program principles. + +## Technical Implementation + +The Filecoin Plus mechanism interfaces with the on-chain protocol through the Verified Registry Actor. When clients make storage deals using their DataCap, these deals receive a 10x quality multiplier, providing greater quality-adjusted power to miners who store Filecoin Plus data. + +### DataCap Allocations and Claims + +Since FIP-0045, the Filecoin Plus system operates through a two-stage process that decouples DataCap from specific market implementations: + +1. **Allocations**: Clients create DataCap allocations by transferring DataCap tokens to the Verified Registry Actor. An allocation specifies: + - The storage provider who can claim it + - The data CID to be stored + - Term limits (minimum and maximum duration) + - Expiration deadline for the provider to claim it + +2. **Claims**: Storage providers claim allocations when they commit the specified data to a sector. Claims represent the provider's commitment to store the data and enable them to receive quality-adjusted power for the storage duration. + +This decoupling enables: +- Future user-programmed market actors to broker Filecoin Plus deals +- Simplified quality-adjusted power calculations +- Term extensions independent of market deal terms +- DataCap to be represented as fungible tokens + +Storage demand on the network shapes the storage offering provided by miners. With the 10x sector quality multiplier for Filecoin Plus deals, clients play a crucial role in shaping the quality of service, geographic distribution, degree of decentralization, and consensus security of the network. All participants - Root Key Holders, Notaries, and Filecoin Plus clients - must be cognizant of the value and responsibility that come with their roles. + +## Governance + +The Filecoin Plus program is governed through community-driven processes, with different layers of governance: +- **Principles**: Core values and goals (modified only through FIPs) +- **Mechanisms**: Specific implementations of principles +- **Operations**: Day-to-day processes and guidelines +- **Markets**: Dynamic ecosystem interactions + +For detailed operational guidelines and to participate in governance, see the [Filecoin Plus Governance repository](https://github.com/filecoin-project/notary-governance). \ No newline at end of file diff --git a/content/appendix/address.md b/content/appendix/address.md index 20575a2e6..1fbe44588 100644 --- a/content/appendix/address.md +++ b/content/appendix/address.md @@ -73,6 +73,7 @@ The **protocol indicator** byte describes how a method should interpret the info - `1` : SECP256K1 Public Key - `2` : Actor - `3` : BLS Public Key +- `4` : Delegated (f4) An example description in golang: @@ -85,6 +86,7 @@ const ( SECP256K1 Actor BLS + Delegated ) ``` @@ -180,6 +182,43 @@ const ( base32[................................] ``` +#### Protocol 4: Delegated (f4) + + + +**Protocol 4** addresses represent delegated addresses where user-defined address management actors control address assignment. The payload field contains the address manager's actor ID (leb128 encoded) followed by an arbitrary sub-address (up to 54 bytes) chosen by the address manager. + +**Bytes** + +```text +|----------|----------------------------------------| +| protocol | payload | +|----------|----------------------------------------| +| 4 | leb128(actor-id) || sub-address | +``` + +**String** + +```text +|------------|----------|-----------------------------------------|----------| +| network | protocol | payload | checksum | +|------------|----------|-----------------------------------------|----------| +| 'f' or 't' | '4' | {decimal(actor-id)}f{base32(sub-addr)} | 4 bytes | +``` + +In the string format, f4 addresses are formatted as `f4{decimal(actor-id)}f{base32(sub-address || checksum)}` where: +- `{decimal(actor-id)}` is the decimal representation of the address manager's actor ID +- The sub-namespace is separated by an 'f' character +- `{base32(sub-address || checksum)}` is the base32 encoding of the sub-address concatenated with a 4-byte checksum + +For example, an address manager at actor ID 10 managing sub-address `[0x01, 0x02, 0x03]` would produce: `f410f0000001020304yzxehm7a` + ### Payload The payload represents the data specified by the protocol. All payloads except the payload of the ID protocol are [base32](https://tools.ietf.org/html/rfc4648#section-6) encoded using the lowercase alphabet when seralized to their human readable format. @@ -188,6 +227,30 @@ The payload represents the data specified by the protocol. All payloads except t Filecoin checksums are calculated over the address protocol and payload using blake2b-4. Checksums are base32 encoded and only added to an address when encoding to a string. Addresses following the ID Protocol do not have a checksum. +### Actor State and Delegated Addresses + + + +Since FIP-0048, the ActorState object includes a `delegated_address` field to store an actor's f4 address, if assigned: + +```rust +pub struct ActorState { + pub code: Cid, + pub state: Cid, + pub nonce: u64, + pub balance: TokenAmount, + pub delegated_address: Option
, // f4 address if assigned +} +``` + +The FVM provides a `lookup_delegated_address` syscall to retrieve an actor's f4 address. + ### Expected Methods All implementations in Filecoin must have methods for creating, encoding, and decoding addresses in addition to checksum creation and validation. The follwing is a golang version of the Address Interface: @@ -241,6 +304,11 @@ func Encode(network string, a Address) string { return network + string(a.Protocol) + base32.Encode(a.Payload+cksm) case ID: return network + string(a.Protocol) + base10.Encode(leb128.Decode(a.Payload)) + case Delegated: + // Extract actor ID and sub-address from payload + actorID, subAddr := decodeDelegatedPayload(a.Payload) + cksm := Checksum(a) + return network + string(a.Protocol) + base10.Encode(actorID) + "f" + base32.Encode(subAddr+cksm) default: Fatal("invalid address protocol") } @@ -276,6 +344,27 @@ func Decode(a string) Address { } } + if protocol == Delegated { + // Parse f4 address: f4{actor-id}f{sub-address} + splitIdx := strings.Index(raw, "f") + if splitIdx < 0 { + Fatal(ErrInvalidFormat) + } + actorID := base10.Decode(raw[:splitIdx]) + subAddrWithChecksum := base32.Decode(raw[splitIdx+1:]) + subAddr := subAddrWithChecksum[:len(subAddrWithChecksum)-CksmLen] + cksm := subAddrWithChecksum[len(subAddrWithChecksum)-CksmLen:] + + // Reconstruct payload + payload := append(leb128.Encode(actorID), subAddr...) + addr := Address{Protocol: protocol, Payload: payload} + + if !ValidateChecksum(addr, cksm) { + Fatal(ErrInvalidChecksum) + } + return addr + } + raw = base32.Decode(raw) payload = raw[:len(raw)-CksmLen] if protocol == SECP256K1 || protocol == Actor { @@ -431,3 +520,60 @@ xzg5tcaqwbyfabxetwtj4tsam3pbhnwghyhijr5mixa d28712965e5f26ecc40858382803724ed34f2720336 f09db631f074 ``` + +### Delegated (f4) Type Addresses + +To aid in readability, these addresses are line-wrapped. Address and hex pairs +are separated by `---`. + +```text +f410f2v5eqgbpbty26bmjdmv4xa +--- +040a01020304 + +f432f76poymyubypmiiywlqzeim +--- +04200eff924032365f51a36541efa24217bfc5b85bc6b + +f41111f574siazdmx2runsud35ciil37rnylpdl +--- +0487570eff924032365f51a36541efa24217bfc5b85bc6b +``` + +### Address Managers + + + +Address managers are actors that control f4 address assignment within their sub-namespace. An address manager at actor ID `N` controls all addresses starting with `f4{N}f`. For now, only specific "blessed" address managers are permitted, but this restriction will be relaxed when users can deploy custom WebAssembly actors. + +Address managers enable: +- Foreign addressing schemes (e.g., Ethereum addresses) +- Predictable address computation before actor deployment +- Sending funds to addresses before actors exist there + +#### Ethereum Address Manager (EAM) + +Since FIP-0055, the Ethereum Address Manager (EAM) is a singleton built-in actor at ID address `f010` that manages the `f410` address space. This enables native Ethereum address support in Filecoin: + +- **Address Format**: Ethereum addresses (20 bytes) are represented as `f410f{base32(eth_addr || checksum)}` +- **Bidirectional Mapping**: Ethereum addresses can be cast to f410 addresses and vice versa +- **Contract Deployment**: The EAM acts as an EVM contract factory supporting CREATE and CREATE2 patterns +- **Account Creation**: Automatically creates Ethereum Account actors for EOA addresses + +### Placeholder Actors + +When sending funds to an unassigned f4 address, the FVM creates a placeholder actor to hold the funds. The placeholder actor: +- Has minimal functionality (accepts all messages but does nothing) +- Stores the f4 address in its ActorState +- Can be replaced by deploying a real actor to that address + +This enables counterfactual interactions where addresses can receive funds before the intended actor is deployed. diff --git a/content/appendix/data_structures.md b/content/appendix/data_structures.md index adf271bc8..28ca347f0 100644 --- a/content/appendix/data_structures.md +++ b/content/appendix/data_structures.md @@ -63,9 +63,58 @@ a long block. For Filecoin, byte arrays representing RLE+ bitstreams are encoded using [LSB 0](https://en.wikipedia.org/wiki/Bit_numbering#LSB_0_bit_numbering) bit numbering. -## HAMT +## HAMT (Hash Array Mapped Trie) -See the draft [IPLD hash map spec](https://github.com/ipld/specs/blob/master/data-structures/hashmap.md) for details on implementing the HAMT used for the global state tree map and throughout the actor code. + + +Filecoin uses HAMT (Hash Array Mapped Trie) v3 as the primary data structure for the global state tree and throughout actor code. The HAMT provides an efficient key-value store with the following characteristics: + +### Key Features +- **Efficient lookups and updates**: O(log n) time complexity for get/set operations +- **Space-efficient**: Only allocates nodes as needed +- **Merkle proof compatible**: Each node has a CID for verification + +### Version 3 Optimizations +The current HAMT implementation includes several performance optimizations: + +1. **Dirty node tracking**: Only flushes modified nodes to the blockstore, reducing unnecessary writes +2. **Persistent caching**: Retains loaded nodes in memory after flush operations +3. **Deferred writes**: All blockstore writes occur during flush rather than immediately +4. **Efficient pointer serialization**: Uses CBOR type discrimination instead of keyed maps, saving 3 bytes per pointer + +For implementation details, see the [IPLD hash map spec](https://github.com/ipld/specs/blob/master/data-structures/hashmap.md) and the [go-hamt-ipld](https://github.com/filecoin-project/go-hamt-ipld) reference implementation. + +## AMT (Array Mapped Trie) + + + +The AMT (Array Mapped Trie) is a data structure used in Filecoin for storing sequential data with integer indices. It provides similar benefits to HAMT but optimized for array-like access patterns. + +### Key Features +- **Sparse array support**: Efficiently stores arrays with gaps +- **Efficient range queries**: Optimized for sequential access +- **Fixed height**: Predictable performance characteristics + +### Version 3 Optimizations +Similar to HAMT v3, the AMT implementation includes: + +1. **Dirty node tracking**: Only flushes modified nodes during updates +2. **Optimized traversals**: ForEach operations only load nodes containing keys within the traversal range +3. **Reduced blockstore operations**: Minimizes unnecessary reads and writes + +For implementation details, see the [go-amt-ipld](https://github.com/filecoin-project/go-amt-ipld) reference implementation. ## Other Considerations diff --git a/content/glossary/_index.md b/content/glossary/_index.md index ab7e7ef2f..430cc6f7a 100644 --- a/content/glossary/_index.md +++ b/content/glossary/_index.md @@ -40,7 +40,7 @@ The _height_ of a block corresponds to the number of epochs elapsed from genesis ## Block Reward -The reward in [FIL](glossary#fil) given to [storage miners](glossary#storage-miner-actor) for contributing to the network with storage and proving that they have stored the files they have committed to store. The _Block Reward_ is allocated to the storage miners that mine blocks and extend the blockchain. +The reward in [FIL](glossary#fil) given to [storage miners](glossary#storage-miner-actor) for contributing to the network with storage and proving that they have stored the files they have committed to store. The _Block Reward_ is allocated to the storage miners that mine blocks and extend the blockchain. As of FIP-0004, 25% of block rewards are immediately available for withdrawal, while 75% vest linearly over 180 days and serve as collateral. ## Blockchain @@ -52,7 +52,15 @@ Bootstrapping traditionally refers to the process of starting a network. In the ## Capacity commitment -If a storage miner doesn't find any available deal proposals appealing, they can alternatively make a _capacity commitment_, filling a sector with arbitrary data, rather than with client data. Maintaining this sector allows the storage miner to provably demonstrate that they are reserving space on behalf of the network. Also referred to as Committed Capacity (CC). + + +If a storage miner doesn't find any available deal proposals appealing, they can alternatively make a _capacity commitment_, filling a sector with arbitrary data, rather than with client data. Maintaining this sector allows the storage miner to provably demonstrate that they are reserving space on behalf of the network. Also referred to as Committed Capacity (CC). Since FIP-0019, CC sectors can be updated with real data through Snap Deals without requiring a full re-sealing process. ## Challenge Sampling @@ -84,17 +92,21 @@ Consensus Fault Slashing is the penalty that a miner incurs for committing conse The [_Cron Actor_](sysactors) is a scheduler actor that runs critical functions at every epoch. +## DataCap + +DataCap is a credit allocated by Notaries to Filecoin Plus clients. When a client makes a storage deal and identifies it as a Filecoin Plus verified deal, the DataCap is consumed and the miner receives a 10x deal quality multiplier for that deal, resulting in increased storage power and block rewards. As of FIP-0012, clients can receive multiple DataCap allocations to the same address, with new allocations adding to their existing balance. + ## Deal Two participants in the Filecoin network can enter into a [_deal_](storage_market#deal-flow) in which one party contracts the services of the other for a given price agreed between the two. The Filecoin specification currently details _storage deals_ (in which one party agrees to store data for the other for a specified length of time) and _retrieval deals_ (in which one party agrees to transmit specified data to the other). ## Deal Quality Multiplier -This factor is assigned to different deal types (committed capacity, regular deals, and verified client deals) to reward different content. +This factor is assigned to different deal types (committed capacity, regular deals, and Filecoin Plus verified deals) to reward different content. ## Deal Weight -This weight converts spacetime occupied by deals into consensus power. Deal weight of verified client deals in a sector is called Verified Deal Weight and will be greater than the regular deal weight. +This weight converts spacetime occupied by deals into consensus power. Deal weight of Filecoin Plus verified deals in a sector is called Verified Deal Weight and will be greater than the regular deal weight. ## DRAND @@ -112,6 +124,17 @@ Election Proof is used as a source of randomness in EC leader election. The elec Time in the Filecoin blockchain is discretized into _epochs_ that are currently set to thirty (30) seconds in duration. On every epoch, a subset of storage miners are elected to each add a new block to the Filecoin blockchain via [Winning Proof-of-Spacetime](glossary#winning-proof-of-spacetime-winningpost). Also referred to as [Round](glossary#round). +## F3 (Fast Finality in Filecoin) + +_F3_ is a Byzantine Fault Tolerant (BFT) consensus protocol that provides fast finality for the Filecoin network. F3 runs alongside [Expected Consensus](expected_consensus) and provides deterministic finality for tipsets in tens of seconds, compared to the 7.5 hours (900 epochs) required for soft finality in EC alone. When F3 finalizes a tipset, it becomes irreversible, and all nodes must respect this finality in their chain selection. + + + ## Fault A fault occurs when a proof is not posted in the Filecoin system within the proving period, denoting another malfunction such as loss of network connectivity, storage malfunction, or malicious behaviour. @@ -130,10 +153,23 @@ _FIL_ is the name of the Filecoin unit of currency; it is alternatively denoted The term _Filecoin_ is used generically to refer to the Filecoin project, protocol, and network. +## Filecoin Plus + +Filecoin Plus is a program (previously called Verified Clients) that aims to maximize the amount of useful storage on Filecoin by adding a layer of social trust. The program allows clients to make verified deals that carry a 10x deal quality multiplier, incentivizing miners to store real, valuable data. The program is governed by Root Key Holders who appoint Notaries, who in turn allocate DataCap to clients. + ## Finality [Finality](expected_consensus#finality-in-ec) is a well known concept in blockchain environments and refers to the amount of time needed until having a reasonable guarantee that a message cannot be reversed or cancelled. It is measured in terms of delay, normally in epochs or rounds from the point when a message has been included in a block published on-chain. +With the introduction of F3 (Fast Finality in Filecoin), the network now has two types of finality: the original soft finality provided by Expected Consensus (approximately 900 epochs or 7.5 hours) and the fast deterministic finality provided by F3 (tens of seconds). + + + ## `fr32` The term `fr32` is derived from the name of a struct that Filecoin uses to represent the elements of the arithmetic field of a pairing-friendly curve, specifically Bls12-381—which justifies use of 32 bytes. `F` stands for "Field", while `r` is simply a mathematic letter-as-variable substitution used to denote the modulus of this particular field. @@ -176,12 +212,20 @@ A message is a call to an actor in the Filecoin VM. The term _message_ is used t ## Miner -A miner is an actor in the Filecoin system performing a service in the network for a reward. + + +A miner is an actor in the Filecoin system performing a service in the network for a reward. Note: Following FIP-0018, the term "Storage Provider" is preferred in marketing and communications materials, though "miner" remains in technical contexts. There are three types of miners in Filecoin: -- [Storage miners](glossary#storage-miner-actor), who store files on behalf of clients. -- [Retrieval miners](glossary#retrieval-miner), who deliver stored files to clients. +- [Storage miners](glossary#storage-miner-actor) (Storage Providers), who store files on behalf of clients. +- [Retrieval miners](glossary#retrieval-miner) (Retrieval Providers), who deliver stored files to clients. - Repair miners, who replicate files to keep them available in the network, when a storage miner presents a fault. ## Multisig Actor @@ -258,7 +302,15 @@ This measurement is the size of a sector in bytes. ## Retrieval miner -A [_retrieval miner_](retrieval_market#retrieval_provider) is a Filecoin participant that enters in retrieval [deals](glossary#deal) with clients, agreeing to supply a client with a particular file in exchange for [FIL](glossary#fil). Note that unlike [storage miners](glossary#storage-miner-actor), retrieval miners are not additionally rewarded with the ability to add blocks to (i.e., extend) the Filecoin blockchain; their only reward is the fee they extract from the client. + + +A [_retrieval miner_](retrieval_market#retrieval_provider) is a Filecoin participant that enters in retrieval [deals](glossary#deal) with clients, agreeing to supply a client with a particular file in exchange for [FIL](glossary#fil). Note that unlike [storage miners](glossary#storage-miner-actor), retrieval miners are not additionally rewarded with the ability to add blocks to (i.e., extend) the Filecoin blockchain; their only reward is the fee they extract from the client. Following FIP-0018, retrieval miners are also referred to as "Retrieval Providers" in marketing and communications. ## Repair @@ -286,7 +338,7 @@ Sectors can contain data from multiple deals and multiple clients. Sectors are a ## Sector Quality Multiplier -Sector quality is assigned on Activation (the epoch when the miner starts proving theyʼre storing the file). The sector quality multiplier is computed as an average of deal quality multipliers (committed capacity, regular deals, and verified client deals), weighted by the amount of spacetime each type of deal occupies in the sector. +Sector quality is assigned on Activation (the epoch when the miner starts proving theyʼre storing the file). The sector quality multiplier is computed as an average of deal quality multipliers (committed capacity, regular deals, and Filecoin Plus verified deals), weighted by the amount of spacetime each type of deal occupies in the sector. ## Sector Spacetime @@ -296,6 +348,18 @@ This measurement is the sector size multiplied by its promised duration in byte- Filecoin implements two kinds of slashing: [**Storage Fault Slashing**](glossary#storage-fault-slashing) and [**Consensus Fault Slashing**](glossary#consensus-fault-slashing). +## Snap Deals + + + +Snap Deals is a protocol introduced in FIP-0019 that allows storage providers to update existing Committed Capacity (CC) sectors with real data without re-sealing. The provider embeds deal data into an existing sector replica through an encoding process using unpredictable randomness, then generates a single proof message (`ProveReplicaUpdates`) that demonstrates the sector was correctly updated. This significantly reduces the cost and time required to convert CC sectors to sectors containing real data, enabling providers to quickly onboard client data into their existing committed capacity. + ## Smart contracts In the Filecoin blockchain smart contracts are referred to as [actors](glossary#actor). @@ -310,12 +374,32 @@ The [_Storage Market Actor_](sysactors) is responsible for managing storage and ## Storage Miner Actor -The [_Storage Miner Actor_](sysactors) commits storage to the network, stores data on behalf of the network and is rewarded in [FIL](glossary#fil) for the storage service. The storage miner actor is responsible for collecting proofs and reaching consensus on the latest state of the storage network. When they create a block, storage miners are rewarded with newly minted FIL, as well as the message fees they can levy on other participants seeking to include messages in the block. + + +The [_Storage Miner Actor_](sysactors) commits storage to the network, stores data on behalf of the network and is rewarded in [FIL](glossary#fil) for the storage service. The storage miner actor is responsible for collecting proofs and reaching consensus on the latest state of the storage network. When they create a block, storage miners are rewarded with newly minted FIL, as well as the message fees they can levy on other participants seeking to include messages in the block. Note: Following FIP-0018, storage miners are also referred to as "Storage Providers" in marketing and communications. ## Storage Power Actor The [_Storage Power Actor_](sysactors) is responsible for keeping track of the storage power allocated at each storage miner. +## Storage Provider + + + +Storage Provider (SP) is the preferred terminology for [storage miners](glossary#storage-miner-actor) in marketing and communications materials as of FIP-0018. This terminology better represents the service-oriented nature of entities that provide storage infrastructure and services to the Filecoin network. The technical implementation continues to use the term "storage miner" in code and protocol specifications. + ## Storage Fault Slashing Storage Fault Slashing is a term that is used to encompass a broader set of penalties, including (but not limited to) Fault Fees, Sector Penalties, and Termination Fees. These penalties are to be paid by miners if they fail to provide sector reliability or decide to voluntarily exit the network. @@ -331,19 +415,35 @@ Tickets are generated as in [Election Proof](glossary#election-proof), but the i ## Tipset + + A [tipset](https://filecoin.io/blog/tipsets-family-based-approach-to-consensus/) is a set of [blocks](glossary#block) that each have the same [height](glossary#block-height) and parent tipset; the Filecoin [blockchain](glossary#blockchain) is a chain of tipsets, rather than a chain of blocks. -Each tipset is assigned a weight corresponding to the amount of storage the network is provided per the commitments encoded in the tipset's blocks. The consensus protocol of the network directs nodes to build on top of the heaviest chain. +Each tipset is assigned a weight corresponding to the amount of storage the network is provided per the commitments encoded in the tipset's blocks. The consensus protocol of the network directs nodes to build on top of the heaviest chain. When selecting between tipsets of equal weight, nodes choose the one with the smallest winning [ElectionProof](glossary#election-proof) ticket. By basing its blockchain on tipsets, Filecoin can allow multiple [storage miners](glossary#storage-miner-actor) to create blocks in the same [epoch](glossary#epoch), increasing network throughput. By construction, this also provides network security: a node that attempts to intentionally prevent the valid blocks of a second node from making it onto the canonical chain runs up against the consensus preference for heavier chains. -## Verified client +## Filecoin Plus Client + +To further incentivize the storage of "useful" data over simple [capacity commitments](glossary#capacity-commitment), [storage miners](glossary#storage-miner-actor) have the additional opportunity to compete for special [deals](glossary#deal) offered by Filecoin Plus clients. Such clients are certified by Notaries with respect to their intent to offer deals involving the storage of meaningful data, and the power a storage miner earns for these deals is augmented by a 10x multiplier. + +## Notary + +Notaries are selected to act as fiduciaries for the Filecoin network in the Filecoin Plus program. They are entrusted with DataCap to allocate to clients in order to subsidize reliable and useful storage on the network. Notaries verify that clients receive a DataCap allocation commensurate with the level of trust that is warranted based on information provided. + +## Root Key Holder -To further incentivize the storage of "useful" data over simple [capacity commitments](glossary#capacity-commitment), [storage miners](glossary#storage-miner-actor) have the additional opportunity to compete for special [deals](glossary#deal) offered by verified clients. Such clients are certified with respect to their intent to offer deals involving the storage of meaningful data, and the power a storage miner earns for these deals is augmented by a multiplier. +Root Key Holders are signers to a multisig on chain with the power to grant and remove Notaries in the Filecoin Plus program. They act as executors for decisions made by the community governance on-chain. The role of the Root Key Holder is not to make subjective decisions, but rather to execute community decisions transparently. ## Verified Registry Actor -The [_Verified Registry Actor_](sysactors) is responsible for managing [verified clients](glossary#verified-client). +The [_Verified Registry Actor_](sysactors) is responsible for managing [Filecoin Plus clients](glossary#filecoin-plus-client), Notaries, and DataCap allocations. ## VDF diff --git a/content/intro/filecoin_vm.md b/content/intro/filecoin_vm.md index 5b1febdf2..8bb423268 100644 --- a/content/intro/filecoin_vm.md +++ b/content/intro/filecoin_vm.md @@ -8,11 +8,19 @@ dashboardAudit: n/a # Filecoin VM + + The majority of Filecoin's user facing functionality (payments, storage market, power table, etc) is managed through the Filecoin Virtual Machine (Filecoin VM). The network generates a series of blocks, and agrees which 'chain' of blocks is the correct one. Each block contains a series of state transitions called `messages`, and a checkpoint of the current `global state` after the application of those `messages`. The `global state` here consists of a set of `actors`, each with their own private `state`. -An `actor` is the Filecoin equivalent of Ethereum's smart contracts, it is essentially an 'object' in the filecoin network with state and a set of methods that can be used to interact with it. Every actor has a Filecoin balance attributed to it, a `state` pointer, a `code` CID which tells the system what type of actor it is, and a `nonce` which tracks the number of messages sent by this actor. +An `actor` is the Filecoin equivalent of Ethereum's smart contracts, it is essentially an 'object' in the filecoin network with state and a set of methods that can be used to interact with it. Every actor has a Filecoin balance attributed to it, a `state` pointer, a `code` CID which tells the system what type of actor it is, and a `nonce` which tracks the number of messages sent by this actor. Since the introduction of the FVM in FIP-0030, actors can be either built-in system actors (like the storage market or miner actors) or user-deployed actors running custom WASM bytecode. There are two routes to calling a method on an `actor`. First, to call a method as an external participant of the system (aka, a normal user with Filecoin) you must send a signed `message` to the network, and pay a fee to the miner that includes your `message`. The signature on the message must match the key associated with an account with sufficient Filecoin to pay for the message's execution. The fee here is equivalent to transaction fees in Bitcoin and Ethereum, where it is proportional to the work that is done to process the message (Bitcoin prices messages per byte, Ethereum uses the concept of 'gas'. We also use 'gas'). diff --git a/content/libraries/drand/_index.md b/content/libraries/drand/_index.md index 2f3b6f33d..fd1a0f9c2 100644 --- a/content/libraries/drand/_index.md +++ b/content/libraries/drand/_index.md @@ -9,6 +9,14 @@ dashboardAuditURL: /#section-appendix.audit_reports.drand dashboardAuditDate: '2020-08-09' --- + + # DRAND DRand (Distributed Randomness) is a publicly verifiable random beacon protocol Filecoin relies on as a source of unbiasable entropy for leader election (see [Secret Leader Election](expected_consensus#secret-leader-election)). @@ -16,6 +24,14 @@ DRand (Distributed Randomness) is a publicly verifiable random beacon protocol F At a high-level, the drand protocol runs a series of MPCs (Multi-Party Computations) in order to produce a series of deterministic, verifiable random values. Specifically, after a trusted setup, a known (to each other) group of n drand nodes sign a given message using t-of-n threshold BLS signatures in a series of successive rounds occuring at regular intervals (the drand round time). Any node that has gathered t of the signatures can reconstruct the full BLS signature. This signature can then be hashed in order to produce a collective random value which can be verified against the collective public key generated during the trusted setup. Note that while this can be done by the drand node, the random value (i.e. hashed value) should be checked by the consumer of the beacon. In Filecoin, we hash it using blake2b in order to obtain a 256 bit output. +### Quicknet Network + +Since FIP-0063, Filecoin uses the drand **quicknet** network which features: +- **Unchained randomness**: Each beacon is independent and doesn't reference previous beacons +- **3-second beacon frequency**: Beacons are produced every 3 seconds (Filecoin uses every 10th beacon for its 30-second epochs) +- **G1/G2 swap**: Signatures are on G1 (48 bytes) and public keys on G2, resulting in smaller beacon signatures +- **Stateless verification**: No need to store previous beacons for verification + drand assumes that at least t of the n nodes are honest (and online -- for liveness). If this threshold is broken, the adversary can permanently halt randomness production but cannot otherwise bias the randomness. You can learn more about how drand works, by visiting its [repository](https://github.com/drand/drand), or reading its [specification](https://drand.love/docs/specification/). @@ -38,11 +54,11 @@ By polling the appropriate endpoint (see below for specifics on the drand networ Specifically, we have: - `Randomness` -- SHA256 hash of the signature -- `Signature` -- the threshold BLS signature on the previous signature value `Previous` and the current round number `round`. -- `PreviousSignature` -- the threshold BLS signature from the previous drand round. -- `Round` -- the index of Randomness in the sequence of all random values produced by this drand network. +- `Signature` -- the threshold BLS signature on the round number (for quicknet, no previous signature is included) +- `PreviousSignature` -- (only for legacy chained beacons, not present in quicknet) +- `Round` -- the index of Randomness in the sequence of all random values produced by this drand network -Specifically, the message signed is the concatenation of the round number treated as a uint64 and the previous signature. At the moment, drand uses BLS signatures on the BLS12-381 curve with the latest v7 RFC of hash-to-curve and the signature is made over G1 (for more see the [drand specification](https://drand.love/docs/specification/#cryptographic-specification). +For quicknet (unchained mode), the message signed is simply the round number treated as a uint64. The signature uses BLS12-381 with signatures on G1 and public keys on G2, following the latest v7 RFC of hash-to-curve. ## Polling the drand network @@ -68,6 +84,23 @@ Note that it is possible to simply store the hash of this chain info and to retrieve the contents from the drand distribution network as well on the `/info` endpoint. +#### Quicknet Chain Info + +The quicknet network used by Filecoin has the following parameters: +```json +{ + "public_key": "83cf0f2896adee7eb8b5f01fcad3912212c437e0073e911fb90022d3e760183c8c4b450b6a0a6c3ac6a5776a2d1064510d1fec758c921cc22b0e17e63aaf4bcb5ed66304de9cf809bd274ca73bab4af5a6e9c76a4bc09e76eae8991ef5ece45a", + "period": 3, + "genesis_time": 1692803367, + "hash": "52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971", + "groupHash": "f477d5c89f21a17c863a7f937c6a6d15859414d2be09cd448d4279af331c5d3e", + "schemeID": "bls-unchained-g1-rfc9380", + "metadata": { + "beaconID": "quicknet" + } +} +``` + Thereafter, the Filecoin client can call drand's endpoints: - `/public/latest` to get the latest randomness value produced by the beacon @@ -87,10 +120,17 @@ Filecoin. See [randomness](randomness) for more. ### Verifying an incoming drand value -Upon receiving a new drand randomness value from a beacon, a Filecoin node should immediately verify its validity. That is, it should verify: +Upon receiving a new drand randomness value from a beacon, a Filecoin node should immediately verify its validity: -- that the `Signature` field is verified by the beacon's `PublicKey` as the beacon's signature of `SHA256(PreviousSignature || Round)`. -- that the `Randomness` field is `SHA256(Signature)`. +#### Quicknet (Unchained) Verification +1. Instantiate BLS12-381 with signatures on G1 and public keys on G2 +2. Hash only the current beacon round number using SHA256 +3. Verify that the `Randomness` field equals `SHA256(Signature)` +4. Verify the signature over the round number is valid for the group public key + +#### Legacy (Chained) Verification +1. Verify that the `Signature` field is verified by the beacon's `PublicKey` as the beacon's signature of `SHA256(PreviousSignature || Round)` +2. Verify that the `Randomness` field is `SHA256(Signature)` See [drand](https://github.com/drand/drand/blob/0df91a710b4366d41e88ad487814a16cf88494f9/crypto/schemes.go#L68) for an example. @@ -124,6 +164,19 @@ MaxBeaconRoundForEpoch(filEpoch) { } ``` +### Beacon Sourcing for Quicknet + +Since quicknet produces beacons every 3 seconds but Filecoin epochs are 30 seconds, Filecoin only uses every 10th beacon. For a Filecoin epoch at time `T` seconds, the beacon round is calculated as: + +``` +beacon_round = (T - 30 - 1692803367) / 3 + 1 +``` + +Where: +- `1692803367` is the quicknet genesis timestamp +- `3` is the quicknet period (3 seconds) +- `30` accounts for the lookback (randomness from 30 seconds before the epoch) + ## Edge cases and dealing with a drand outage It is important to note that any drand beacon outage will effectively halt @@ -136,6 +189,8 @@ current round, as defined by wall clock time. In this way, the above time-to-round mapping in drand (see above) used by Filecoin remains an invariant after this catch-up following downtime. +With quicknet's 2-second catch-up time per beacon (compared to legacy's 15 seconds), the total catch-up time per Filecoin epoch is 20 seconds. Any monitoring, alerting, or automation relying on catch-up timing should account for this change. + So while Filecoin miners were not able to mine during the drand outage, they will quickly be able to run leader election thereafter, given a rapid production of drand values. We call this a "catch up" period. diff --git a/content/systems/filecoin_blockchain/storage_power_consensus/_index.md b/content/systems/filecoin_blockchain/storage_power_consensus/_index.md index 6f3ddbad7..c4f08b545 100644 --- a/content/systems/filecoin_blockchain/storage_power_consensus/_index.md +++ b/content/systems/filecoin_blockchain/storage_power_consensus/_index.md @@ -8,6 +8,14 @@ dashboardAudit: wip dashboardTests: 0 --- + + # Storage Power Consensus The Storage Power Consensus (SPC) subsystem is the main interface which enables Filecoin nodes to agree on the state of the system. Storage Power Consensus accounts for individual storage miners' effective power over consensus in given chains in its [Power Table](storage_power_actor#the-power-table). It also runs [Expected Consensus](expected_consensus) (the underlying consensus algorithm in use by Filecoin), enabling storage miners to run leader election and generate new blocks updating the state of the Filecoin system. @@ -35,11 +43,11 @@ However, given Filecoin's "useful Proof-of-Work" is achieved through file storag ## On Power -Quality-adjusted power is assigned to every sector as a static function of its **_Sector Quality_** which includes: i) the **Sector Spacetime**, which is the product of the sector size and the promised storage duration, ii) the **Deal Weight** that converts spacetime occupied by deals into consensus power, iii) the **Deal Quality Multiplier** that depends on the type of deal done over the sector (i.e., CC, Regular Deal or Verified Client Deal), and finally, iv) the **Sector Quality Multiplier**, which is an average of deal quality multipliers weighted by the amount of spacetime each type of deal occupies in the sector. +Quality-adjusted power is assigned to every sector as a static function of its **_Sector Quality_** which includes: i) the **Sector Spacetime**, which is the product of the sector size and the promised storage duration, ii) the **Deal Weight** that converts spacetime occupied by deals into consensus power, iii) the **Deal Quality Multiplier** that depends on the type of deal done over the sector (i.e., CC, Regular Deal or Filecoin Plus Deal), and finally, iv) the **Sector Quality Multiplier**, which is an average of deal quality multipliers weighted by the amount of spacetime each type of deal occupies in the sector. The **Sector Quality** is a measure that maps size, duration and the type of active deals in a sector during its lifetime to its impact on power and reward distribution. -The quality of a sector depends on the deals made over the data inside the sector. There are generally three types of deals: the _Committed Capacity (CC)_, where there is effectively no deal and the miner is storing arbitrary data inside the sector, the _Regular Deals_, where a miner and a client agree on a price in the market and the _Verified Client_ deals, which give more power to the sector. We refer the reader to the [Sector](sector) and [Sector Quality](sector#sector-quality) sections for details on Sector Types and Sector Quality, the [Verified Clients](verified_clients) section for more details on what a verified client is, and the [CryptoEconomics](cryptoecon) section for specific parameter values on the Deal Weights and Quality Multipliers. +The quality of a sector depends on the deals made over the data inside the sector. There are generally three types of deals: the _Committed Capacity (CC)_, where there is effectively no deal and the miner is storing arbitrary data inside the sector, the _Regular Deals_, where a miner and a client agree on a price in the market and the _Filecoin Plus verified deals_, which give more power to the sector (10x multiplier). We refer the reader to the [Sector](sector) and [Sector Quality](sector#sector-quality) sections for details on Sector Types and Sector Quality, the [Filecoin Plus](verified_clients) section for more details on the Filecoin Plus program, and the [CryptoEconomics](cryptoecon) section for specific parameter values on the Deal Weights and Quality Multipliers. **Quality-Adjusted Power** is the number of votes a miner has in the [Secret Leader Election](expected_consensus#secret-leader-election) and has been defined to increase linearly with the useful storage that a miner has committed to the network. @@ -62,20 +70,21 @@ This randomness may be drawn from various Filecoin chain epochs by the respectiv It is important to note that a given Filecoin network and a given drand network need not have the same round time, i.e. blocks may be generated faster or slower -by Filecoin than randomness is generated by drand. For instance, if the drand -beacon is producing randomness twice as fast as Filecoin produces blocks, we -might expect two random values to be produced in a Filecoin epoch, conversely if -the Filecoin network is twice as fast as drand, we might expect a random value -every other Filecoin epoch. Accordingly, depending on both networks' -configurations, certain Filecoin blocks could contain multiple or no drand -entries. +by Filecoin than randomness is generated by drand. Since FIP-0063, Filecoin uses +the quicknet drand network which produces randomness every 3 seconds, while +Filecoin epochs are 30 seconds. Therefore, Filecoin uses every 10th beacon +(specifically, beacons at rounds that correspond to epoch times minus 30 seconds). + Furthermore, it must be that any call to the drand network for a new randomness entry during an outage should be blocking, as noted with the `drand.Public()` calls below. -In all cases, Filecoin blocks must include all drand beacon outputs generated -since the last epoch in the `BeaconEntries` field of the block header. Any use -of randomness from a given Filecoin epoch should use the last valid drand entry -included in a Filecoin block. This is shown below. + +Blocks must include beacon entries for the epoch corresponding to their own +height, as well as those corresponding to any parent epochs that were null. +This guarantees that a unique beacon entry can be found for any Filecoin epoch +to serve as a source of external randomness. Note that not every beacon entry +is included in the blockchain - only those corresponding to Filecoin epochs +(every 10th entry for quicknet). ### Get drand randomness for VM @@ -100,9 +109,9 @@ the new block. ### Validating Beacon Entries on block reception -A Filecoin chain will contain the entirety of the beacon's output from the Filecoin genesis to the current block. +A Filecoin chain will contain beacon entries corresponding to Filecoin epochs from genesis to the current block. -Given their role in leader election and other critical protocols in Filecoin, a block's beacon entries must be validated for every block. See [drand](drand) for details. This can be done by ensuring every beacon entry is a valid signature over the prior one in the chain, using drand's [`Verify`](https://github.com/drand/drand/blob/763e9a252cf59060c675ced0562e8eba506971c1/chain/beacon.go#L76) endpoint as follows: +Given their role in leader election and other critical protocols in Filecoin, a block's beacon entries must be validated for every block. See [drand](drand) for details. Since FIP-0063 and the switch to quicknet, validation uses unchained randomness where each beacon is validated independently (not requiring the previous beacon). The validation verifies that each beacon entry is a valid signature over its round number: {{}} diff --git a/content/systems/filecoin_markets/onchain_storage_market/storage_market_actor.md b/content/systems/filecoin_markets/onchain_storage_market/storage_market_actor.md index ad1fe9c4b..2ace0f5b7 100644 --- a/content/systems/filecoin_markets/onchain_storage_market/storage_market_actor.md +++ b/content/systems/filecoin_markets/onchain_storage_market/storage_market_actor.md @@ -10,6 +10,26 @@ dashboardTests: 0 math-mode: true --- + + # Storage Market Actor The `StorageMarketActor` is responsible for processing and managing on-chain deals. This is also the entry point of all storage deals and data into the system. It maintains a mapping of `StorageDealID` to `StorageDeal` and keeps track of locked balances of `StorageClient` and `StorageProvider`. When a deal is posted on chain through the `StorageMarketActor`, it will first check if both transacting parties have sufficient balances locked up and include the deal on chain. @@ -40,3 +60,139 @@ This collateral is returned to the storage provider when all deals in the sector ```text $$MinimumProviderDealCollateral = 1\% \times FILCirculatingSupply \times \frac{DealRawByte}{max(NetworkBaseline, NetworkRawBytePower)}$$ ``` + +## Deal Publishing + +The `PublishStorageDeals` method is used to publish storage deals on-chain. As of FIP-0022, this method has improved error handling that prevents a single invalid deal from causing the entire batch to fail. Instead: + +- Valid deals in the batch are successfully published +- Invalid deals (due to validation errors, insufficient balance, or other issues) are dropped +- The return value includes both the deal IDs for successful deals and a bitfield indicating which deals from the input were valid + +This change significantly improves the user experience for storage providers by making deal publishing more resilient to individual deal failures. The method only returns an error if all deals fail validation or if an internal error occurs. + +## Balance Withdrawals + +The Storage Market Actor maintains escrow balances for both clients and providers. These balances can be withdrawn using the `WithdrawBalance` method. As of FIP-0020, this method returns the actual amount withdrawn, which may be less than the requested amount if the available balance is insufficient. This improvement provides better visibility and traceability of FIL flow, particularly important for financial reporting. + +## Deal Maintenance and Settlement + +### Automatic Settlement (Legacy) + +Prior to FIP-0074, the Storage Market Actor performed automatic maintenance on all active deals through Filecoin's cron mechanism every 30 days (FIP-0060). This maintenance included: +- Processing incremental payments from clients to providers +- Handling deal state updates +- Cleaning up expired deals + +Since FIP-0074, automatic settlement only applies to deals activated before the upgrade. New deals require manual settlement. + +### Manual Deal Settlement + +FIP-0074 introduced the `SettleDealPayments` method to allow storage providers to manually settle deal payments: + +```rust +struct SettleDealPaymentsParams { + Deals: Bitfield, // Deal IDs to settle +} + +struct SettleDealPaymentsReturn { + Results: { + SuccessCount: u32, + FailCodes: []{ Index: u32, ExitCode: ExitCode }, + }, + Settlements: []DealSettlementSummary, +} + +struct DealSettlementSummary { + Payment: TokenAmount, // Incremental amount paid to provider + Completed: bool, // Whether deal has settled for final time +} +``` + +#### Settlement Rules +- **Non-existent deals**: Fail with `USR_NOT_FOUND` +- **Unactivated/unexpired deals**: Succeed with no effect +- **Expired or completed deals**: Fail with `EX_DEAL_EXPIRED` +- **Terminated deals**: Abort with `USR_ILLEGAL_ARGUMENT` + +### Termination Processing + +Since FIP-0074, the `OnMinerSectorsTerminate` method immediately: +1. Makes final payment settlement +2. Charges applicable penalties +3. Cleans up deal state + +This replaces the previous deferred cleanup via cron, ensuring immediate state consistency. + +### Impact on Gas Costs + +The shift from automatic to manual settlement: +- **Removes risk**: Cron operations no longer threaten to exceed chain processing capacity +- **Aligns costs**: Storage providers pay gas for settlement, incentivizing efficient batching +- **Enables scaling**: Deal volume can grow without impacting cron execution +- **Levels playing field**: User-programmed markets aren't disadvantaged by subsidized settlement + +Storage providers can optimize costs by: +- Settling multiple deals in a single transaction +- Choosing periods of low gas demand +- Settling only payment-bearing deals (zero-fee deals can remain unsettled) + +## Direct Data Onboarding Support + +### Provider-Sector Mapping + +The market actor maintains a mapping of provider addresses to sector numbers and the deal IDs stored in those sectors. This enables tracking which deals are in which sectors without relying on the miner actor state. + +State structure additions: +```go +// HAMT[ActorID]HAMT[SectorNumber]SectorDealIDs +ProviderSectors: Cid + +// Deal state now includes sector number +struct DealState { + SectorNumber: SectorNumber, + // ... other fields +} +``` + +### SectorContentChanged + +The market actor implements the `SectorContentChanged` method (FRC-0042 method 2034386435) to support direct data onboarding. When storage providers use `ProveCommitSectors3`, they can notify the market actor of deals being activated without going through traditional deal activation flow. + +Method behavior: +- Receives notifications from miner actor when sectors are activated +- Validates that nominated deal IDs match the committed piece CID and size +- Activates deals independently (failures don't affect other deals) +- Returns acceptance status for each piece + +```go +struct SectorContentChangedParams { + Sectors: []SectorChanges, +} + +struct SectorChanges { + Sector: SectorNumber, + MinimumCommitmentEpoch: ChainEpoch, + Added: []PieceChange, +} + +struct PieceChange { + Data: Cid, + Size: PaddedPieceSize, + Payload: []byte, // CBOR-encoded deal ID +} +``` + +### BatchActivateDeals Updates + +The `BatchActivateDeals` method (used by traditional onboarding) now includes sector numbers: +- Records sector-deal associations in the `ProviderSectors` mapping +- Enables reverse lookup from deal ID to sector number +- Maintains compatibility with existing workflows + +### GetDealSector + +New exported method `GetDealSector` (method 2611213344) returns the sector number for an active deal: +- Aborts with `EX_DEAL_NOT_ACTIVATED` (33) if deal not yet activated +- Provides visibility into deal-sector relationships +- Supports monitoring and verification workflows diff --git a/content/systems/filecoin_markets/storage_market/_index.md b/content/systems/filecoin_markets/storage_market/_index.md index 44e70ac82..14097a76d 100644 --- a/content/systems/filecoin_markets/storage_market/_index.md +++ b/content/systems/filecoin_markets/storage_market/_index.md @@ -82,7 +82,7 @@ Data is now transferred, both parties have agreed, and it's time to publish the 12. First, the `StorageProvider` adds collateral for the deal as needed to the `StorageMarketActor` (using `AddBalance`). 13. Then, the `StorageProvider` prepares and signs the on-chain `StorageDeal` message with the `StorageDealProposal` signed by the client and its own signature. It can now either send this message back to the client or call `PublishStorageDeals` on the `StorageMarketActor` to publish the deal. It is recommended for `StorageProvider` to send back the signed message before `PublishStorageDeals` is called. 14. After calling `PublishStorageDeals`, the `StorageProvider` sends a message to the `StorageClient` on the `Storage Deal Protocol` with the CID of the message that it is putting on chain for convenience. -15. If all goes well, the `StorageMarketActor` responds with an on-chain `DealID` for the published deal. +15. If all goes well, the `StorageMarketActor` responds with on-chain `DealID`s for the published deals. As of FIP-0022, the `PublishStorageDeals` method will publish all valid deals even if some deals in the batch are invalid, returning both the deal IDs and a bitfield indicating which input deals were successfully published. Finally, the `StorageClient` verifies the deal. diff --git a/content/systems/filecoin_mining/miner_collaterals.md b/content/systems/filecoin_mining/miner_collaterals.md index 4f55fab47..64c8e7ae0 100644 --- a/content/systems/filecoin_mining/miner_collaterals.md +++ b/content/systems/filecoin_mining/miner_collaterals.md @@ -10,12 +10,38 @@ dashboardTests: 0 # Miner Collaterals + + Most permissionless blockchain networks require upfront investment in resources in order to participate in the consensus. The more power an entity has on the network, the greater the share of total resources it needs to own, both in terms of physical resources and/or staked tokens (collateral). Filecoin must achieve security via the dedication of resources. By design, Filecoin mining requires commercial hardware only (as opposed to ASIC hardware) that is cheap in amortized cost and easy to repurpose, which means the protocol cannot solely rely on the hardware as the capital investment at stake for attackers. Filecoin also uses upfront token collaterals, as in proof-of-stake protocols, proportional to the storage hardware committed. This gets the best of both worlds: attacking the network requires both acquiring and running the hardware, but it also requires acquiring large quantities of the token. To satisfy the multiple needs for collateral in a way that is minimally burdensome to miners, Filecoin includes three different collateral mechanisms: _initial pledge collateral, block reward as collateral, and storage deal provider collateral_. The first is an initial commitment of filecoin that a miner must provide with each sector. The second is a mechanism to reduce the initial token commitment by vesting block rewards over time. The third aligns incentives between miner and client, and can allow miners to differentiate themselves in the market. The remainder of this subsection describes each in more detail. +## Pre-Commit Deposit + +Before a sector can be proven and activated, storage providers must submit a pre-commit deposit (PCD) that serves as an early commitment to the sector. Since FIP-0034, this deposit is set to a fixed value regardless of sector content, calculated as the 20-day projection of expected reward for a sector with quality 10 (i.e., completely filled with verified deals). + +This fixed pre-commit deposit: +- Simplifies the onboarding process by removing the dependency on deal content +- Provides adequate security against proof-of-replication cheating attempts +- Enables future programmable storage markets by decoupling sector onboarding from the built-in market actor +- Ensures the deposit is always less than the initial pledge, minimizing additional capital requirements + +The pre-commit deposit is forfeited if the sector fails to be proven within the required timeframe, incentivizing providers to complete the sector onboarding process. + ## Initial Pledge Collateral Filecoin Miners must commit resources in order to participate in the economy; the protocol can use the minersʼ stake in the network to ensure that rational behavior benefits the network, rewarding the creation of value and penalizing malicious behavior via slashing. The pledge size is meant to adequately incentivize the fulfillment of a sectorʼs promised lifetime and provide sufficient consensus security. @@ -36,21 +62,78 @@ $SectorInitialStoragePledge = Estimated20DaysSectorBlockReward$ {{}} -Since the storage pledge per sector is based on the expected block reward that sector will win, the storage pledge is independent of the networkʼs total storage. As a result, the total network storage pledge depends solely on future block reward. Thus, while the storage pledge provides a clean way to reason about the rationality of adding a sector, it does not provide sufficient long-term security guarantees to the network, making consensus takeovers less costly as the block reward decreases. As such, the second half of the initial pledge function, the consensus pledge, depends on both the amount of quality-adjusted power (QAP) added by the sector and the network circulating supply. The network targets approximately 30% of the network's circulating supply locked up in initial consensus pledge when it is at or above the baseline. This is achieved with a small pledge share allocated to sectors based on their share of the networkʼs quality-adjusted power. Given an exponentially growing baseline, initial pledge per unit QAP should decrease over time, as should other mining costs. +Since the storage pledge per sector is based on the expected block reward that sector will win, the storage pledge is independent of the networkʼs total storage. As a result, the total network storage pledge depends solely on future block reward. Thus, while the storage pledge provides a clean way to reason about the rationality of adding a sector, it does not provide sufficient long-term security guarantees to the network, making consensus takeovers less costly as the block reward decreases. As such, the second half of the initial pledge function, the consensus pledge, depends on both the amount of quality-adjusted power (QAP) added by the sector and the network circulating supply. The network targets approximately 30% of the network's circulating supply locked up in initial consensus pledge when it is at or above the baseline. This is achieved with a small pledge share allocated to sectors based on their share of the networkʼs quality-adjusted power. + +### Consensus Pledge Components + +Since FIP-0081, the consensus pledge is split into two components to prevent pledge requirements from falling to zero as the baseline function grows exponentially: + +{{}} + +$SectorInitialConsensusPledge = (1 - \gamma) \times SimpleConsensusPledge + \gamma \times BaselineConsensusPledge$ + +{{}} + +where: {{}} -$SectorInitialConsensusPledge = 30\% \times FILCirculatingSupply \times \frac{SectorQAP}{max(NetworkBaseline, NetworkQAP)}$ +$SimpleConsensusPledge = 30\% \times FILCirculatingSupply \times \frac{SectorQAP}{NetworkQAP}$ + +$BaselineConsensusPledge = 30\% \times FILCirculatingSupply \times \frac{SectorQAP}{max(NetworkBaseline, NetworkQAP)}$ {{}} +The parameter γ (gamma) determines the contribution of each component: +- γ = 1.0: All consensus pledge comes from the baseline component (pre-FIP-0081 behavior) +- γ = 0.7: 70% from baseline component, 30% from simple component (target value) + +This is implemented with a 1-year linear ramp from γ = 1.0 to γ = 0.7 after activation. + +The simple component provides a floor that prevents pledge requirements from falling to zero, maintaining network security even when the baseline function significantly exceeds network QAP. The baseline component preserves the incentive for growth by reducing pledge requirements when the network lags behind the baseline target. + +### Network Circulating Supply + +The network circulating supply (FILCirculatingSupply) is a critical parameter in calculating the consensus pledge. It represents the total amount of FIL tokens that are actively circulating in the network economy. + +Since FIP-0065, the circulating supply is calculated as: + +{{}} +$CirculatingSupply = Vested + Mined - Burnt - Locked$ +{{}} + +where: +- **Vested**: Tokens that have been released from vesting schedules +- **Mined**: All tokens that have been minted as mining rewards +- **Burnt**: Tokens permanently removed from circulation (e.g., gas fees, penalties) +- **Locked**: Only pledge collateral (no longer includes built-in market balances) + +Prior to FIP-0065, the Locked component included provider deal collateral, client deal collateral, and pending deal payments from the built-in storage market actor. These have been removed from the calculation to simplify the protocol and prepare for direct data commitments that bypass the built-in market actor. + ## Block Reward Collateral + + Clients need reliable storage. Under certain circumstances, miners might agree to a storage deal, then want to abandon it later as a result of increased costs or other market dynamics. A system where storage miners can freely or cheaply abandon files would drive clients away from Filecoin as a result of serious data loss and low quality of service. To make sure all the incentives are correctly aligned, Filecoin penalizes miners that fail to store files for the promised duration. As such, high collateral could be used to incentivize good behavior and improve the networkʼs quality of service. On the other hand, however, high collateral creates barriers to miners joining the network. Filecoin's constructions have been designed such that they hit the right balance. In order to reduce the upfront collateral that a miner needs to provide, the block reward is used as collateral. This allows the protocol to require a smaller but still meaningful initial pledge. Block rewards earned by a sector are subject to slashing if a sector is terminated before its expiration. However, due to chain state limitations, the protocol is unable to do accounting on a per sector level, which would be the most fair and accurate. Instead, the chain performs a per-miner level approximation. Sublinear vesting provides a strong guarantee that miners will always have the incentive to keep data stored until the deal expires and not earlier. An extreme vesting schedule would release all tokens that a sector earns only when the sector promise is fulfilled. -However, the protocol should provide liquidity for miners to support their mining operations, and releasing rewards all at once creates supply impulses to the network. Moreover, there should not be a disincentive for longer sector lifetime if the vesting duration also depends on the lifetime of the sector. As a result, a fixed duration linear vesting for the rewards that a miner earns after a short delay creates the necessary sub-linearity. This sub-linearity has been introduced by the Initial Pledge. +However, the protocol should provide liquidity for miners to support their mining operations, and releasing rewards all at once creates supply impulses to the network. Moreover, there should not be a disincentive for longer sector lifetime if the vesting duration also depends on the lifetime of the sector. As a result, the protocol implements a balanced approach: +- 25% of block rewards are immediately available for withdrawal, providing liquidity for mining operations +- 75% of block rewards vest linearly over 180 days and serve as collateral + +This structure creates the necessary sub-linearity while ensuring miners have access to funds for operational needs. The vested portion acts as collateral and is added to pledgeDeltaTotal, aligning long-term incentives. + +Vesting is processed through the miner's deadline cron handler every 30 minutes and when WithdrawBalance is called. The vesting table is quantized to 12-hour increments. Miners can manually trigger vesting processing by calling WithdrawBalance with an amount of zero using the miner's Owner address. In general, fault fees are slashed first from the soonest-to-vest unvested block rewards followed by the minerʼs account balance. When a minerʼs balance is insufficient to cover their minimum requirements, their ability to participate in consensus, win block rewards, and grow storage power will be restricted until their balance is restored. Overall, this reduces the initial pledge requirement and creates a sufficient economic deterrent for faults without slashing the miner's balance for every penalty. diff --git a/content/systems/filecoin_mining/sector/_index.md b/content/systems/filecoin_mining/sector/_index.md index eb496cf51..a6cae9a30 100644 --- a/content/systems/filecoin_mining/sector/_index.md +++ b/content/systems/filecoin_mining/sector/_index.md @@ -18,9 +18,9 @@ Individual deals are formed when a storage miner and client are matched on Filec If a sector is only partially full of deals, the network considers the remainder to be _committed capacity_. Similarly, sectors with no deals are called committed capacity sectors; miners are rewarded for proving to the network that they are pledging storage capacity and are encouraged to find clients who need storage. When a miner finds storage demand, they can upgrade their committed capacity sectors to earn additional revenue in the form of a deal fee from paying clients. More details on how to add storage and upgrade sectors in [Adding Storage](adding_storage). -Committed capacity sectors improve minersʼ incentives to store client data, but they donʼt solve the problem entirely. Storing real client files adds some operational overhead for storage miners. In certain circumstances – for example, if a miner values block rewards far more than deal fees – miners might still choose to ignore client data entirely and simply store committed capacity to increase their storage power as rapidly as possible in pursuit of block rewards. This would make Filecoin less useful and limit clientsʼ ability to store data on the network. Filecoin addresses this issue by introducing the concept of verified clients. Verified clients are certified by a decentralized network of verifiers. Once verified, they can post a predetermined amount of verified client deal data to the storage market, set by the size of their DataCap. Sectors with verified client deals are awarded more storage power – and therefore more block rewards – than sectors without. This provides storage miners with an additional incentive to store client data. +Committed capacity sectors improve minersʼ incentives to store client data, but they donʼt solve the problem entirely. Storing real client files adds some operational overhead for storage miners. In certain circumstances – for example, if a miner values block rewards far more than deal fees – miners might still choose to ignore client data entirely and simply store committed capacity to increase their storage power as rapidly as possible in pursuit of block rewards. This would make Filecoin less useful and limit clientsʼ ability to store data on the network. Filecoin addresses this issue through the Filecoin Plus program. Filecoin Plus clients are verified by a decentralized network of Notaries. Once verified, they receive DataCap which allows them to make deals that carry a 10x quality multiplier. Sectors with Filecoin Plus deals are awarded more storage power – and therefore more block rewards – than sectors without. This provides storage miners with an additional incentive to store client data. -Verification is not intended to be scarce – it will be very easy to acquire for anyone with real data to store on Filecoin. Even though verifiers may allocate verified client DataCaps liberally (yet responsibly and transparently) to make onboarding easier, the overall effect should be a dramatic increase in the proportion of useful data stored on Filecoin. +Verification is not intended to be scarce – it will be very easy to acquire for anyone with real data to store on Filecoin. Even though Notaries may allocate DataCap liberally (yet responsibly and transparently) to make onboarding easier, the overall effect should be a dramatic increase in the proportion of useful data stored on Filecoin. Once a sector is full (either with client data or as committed capacity), the unsealed sector is combined by a proving tree into a single root `UnsealedSectorCID`. The sealing process then encodes (using CBOR) an unsealed sector into a sealed sector, with the root `SealedSectorCID`. diff --git a/content/systems/filecoin_mining/sector/adding_storage.md b/content/systems/filecoin_mining/sector/adding_storage.md index 25c70be68..7e58486a1 100644 --- a/content/systems/filecoin_mining/sector/adding_storage.md +++ b/content/systems/filecoin_mining/sector/adding_storage.md @@ -7,12 +7,27 @@ dashboardAudit: wip dashboardTests: 0 --- + + # Adding Storage A Miner adds more storage in the form of Sectors. Adding more storage is a two-step process: -1. **PreCommitting a Sector**: A Miner publishes a Sector's SealedCID, through `miner.PreCommitSector` of `miner.PreCommitSectorBatch`, and makes a deposit. The Sector is now registered to the Miner, and the Miner must ProveCommit the Sector or lose their deposit. -2. **ProveCommitting a Sector**: The Miner provides a Proof of Replication (PoRep) for the Sector through miner.ProveCommitSector or miner.ProveCommitAggregate. This proof must be submitted AFTER a delay (the InteractiveEpoch), and BEFORE PreCommit expiration. +1. **PreCommitting a Sector**: A Miner publishes a Sector's SealedCID and data commitment (unsealed CID), through `miner.PreCommitSectorBatch2`, and makes a deposit. The Sector is now registered to the Miner, and the Miner must ProveCommit the Sector or lose their deposit. +2. **ProveCommitting a Sector**: The Miner provides a Proof of Replication (PoRep) for the Sector through one of several methods: + - `miner.ProveCommitAggregate` - For batch proving multiple sectors with aggregated proofs + - `miner.ProveCommitSectors3` - For both single and batch sector proving, with optional direct data onboarding + + This proof must be submitted AFTER a delay (the InteractiveEpoch), and BEFORE PreCommit expiration. This two-step process provides assurance that the Miner's PoRep _actually proves_ that the Miner has replicated the Sector data and is generating proofs from it: @@ -36,6 +51,58 @@ Miners are free to choose which types of Sectors to store. CC sectors, in partic To incentivize Miners to hoard storage space and dedicate it to Filecoin, CC Sectors have a unique capability: **they can be "upgraded" to Regular Sectors** (also called "replacing a CC Sector"). -Miners upgrade their ProveCommitted CC Sectors by PreCommitting a Regular Sector, and specifying that it should replace an existing CC Sector. Once the Regular Sector is successfully ProveCommitted, it will replace the existing CC Sector. If the newly ProveCommitted Regular sector contains a Verified Client deal, i.e., a deal with higher Sector Quality, then the miner's storage power will increase accordingly. +Miners upgrade their ProveCommitted CC Sectors by PreCommitting a Regular Sector, and specifying that it should replace an existing CC Sector. Once the Regular Sector is successfully ProveCommitted, it will replace the existing CC Sector. If the newly ProveCommitted Regular sector contains a Filecoin Plus deal, i.e., a deal with higher Sector Quality, then the miner's storage power will increase accordingly. Upgrading capacity currently involves resealing, that is, creating a unique representation of the new data included in the Sector through a computationally intensive process. Looking ahead, committed capacity upgrades should eventually be possible without a reseal. A succinct and publicly verifiable proof that the committed capacity has been correctly replaced with replicated data should achieve this goal. However, this mechanism must be fully specified to preserve the security and incentives of the network before it can be implemented and is, therefore, left as a future improvement. + +## Direct Data Onboarding + +Direct data onboarding allows storage providers to commit data to sectors without requiring built-in market deals. This significantly reduces gas costs for common use cases like verified deals with no on-chain payments. + +### ProveCommitSectors3 + +The `ProveCommitSectors3` method (method 34) enables direct sector activation with the following features: + +- **Piece Manifests**: Explicitly declare all pieces of data in each sector +- **Verified Allocations**: Claim DataCap allocations directly from the verified registry +- **Actor Notifications**: Notify actors (currently only built-in market) when sectors are activated +- **Batch Support**: Process multiple sectors with either individual or aggregate proofs + +Key parameters: +- `SectorActivations`: Manifests describing data in each sector +- `SectorProofs` or `AggregateProof`: Proof(s) of replication +- `RequireActivationSuccess`: Whether to abort if any sector fails +- `RequireNotificationSuccess`: Whether to abort if any notification fails + +### ProveReplicaUpdates3 + +The `ProveReplicaUpdates3` method (method 35) provides similar functionality for updating existing sectors: + +- Updates sectors with new data while maintaining the same sector number +- Supports the same piece manifest and notification features as `ProveCommitSectors3` +- Enables capacity sectors to be updated with real data + +### Direct Onboarding Workflow + +1. **For verified data**: Client allocates DataCap directly with verified registry +2. **PreCommit**: Storage provider specifies unsealed CID (CommD) but no deal IDs +3. **ProveCommit**: Storage provider uses `ProveCommitSectors3` with: + - Piece manifests declaring sector contents + - Verified allocation IDs to claim (if applicable) + - Actor addresses to notify (if applicable) + +### Benefits + +- **Reduced Gas Costs**: Bypass built-in market actor when deals aren't needed +- **Flexibility**: Support for future user-programmed storage applications +- **Efficiency**: Batch operations and optimized gas usage +- **Simplicity**: Direct path for common Filecoin Plus deals + +### Deprecated Methods + +The following methods are removed as of FIP-0076: +- `PreCommitSector` (method 6) +- `PreCommitSectorBatch` (method 25) +- `ProveReplicaUpdates2` (method 29) + +Storage providers should use `PreCommitSectorBatch2` for pre-commitment and the new `ProveCommitSectors3` or `ProveReplicaUpdates3` for direct onboarding. diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index f1e346019..b8e0256e4 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -9,25 +9,173 @@ dashboardTests: 0 # Sector Lifecycle + + Once the sector has been generated and the deal has been incorporated into the Filecoin blockchain, the storage miner begins generating Proofs-of-Spacetime (PoSt) on the sector, starting to potentially win block rewards and also earn storage fees. Parameters are set so that miners generate and capture more value if they guarantee that their sectors will be around for the duration of the original contract. However, some bounds are placed on a sectorʼs lifetime to improve the network performance. In particular, as sectors of shorter lifetime are added, the networkʼs capacity can be bottlenecked. The reason is that the chainʼs bandwidth is consumed with new sectors only replacing expiring ones. As a result, a minimum sector lifetime of six months was introduced to more effectively utilize chain bandwidth and miners have the incentive to commit to sectors of longer lifetime. The maximum sector lifetime is limited by the security of the present proofs construction. For a given set of proofs and parameters, the security of Filecoinʼs Proof-of-Replication (PoRep) is expected to decrease as sector lifetimes increase. -It is reasonable to assume that miners enter the network by adding Committed Capacity sectors, that is, sectors that do not contain user data. Once miners agree storage deals with clients, they upgrade their sectors to Regular Sectors. Alternatively, if they find Verified Clients and agree a storage deal with them, they upgrade their sector accordingly. Depending on whether or not a sector includes a (verified) deal, the miner acquires the corresponding storage power in the network. +It is reasonable to assume that miners enter the network by adding Committed Capacity sectors, that is, sectors that do not contain user data. Once miners agree storage deals with clients, they upgrade their sectors to Regular Sectors. Since FIP-0019, miners can use Snap Deals to update CC sectors with real data without re-sealing, significantly reducing the cost and time of the upgrade process. Alternatively, if they find Filecoin Plus clients and agree a storage deal with them, they upgrade their sector accordingly. Depending on whether or not a sector includes a Filecoin Plus deal, the miner acquires the corresponding storage power in the network. All sectors are expected to remain live until the end of their sector lifetime and early dropping of sectors will result in slashing. This is done to provide clients a certain level of guarantee on the reliability of their hosted data. Sector termination comes with a corresponding _termination fee_. As with every system it is expected that sectors will present faults. Although this might degrade the quality offered by the network, the reaction of the miner to the fault drives system decisions on whether or not the miner should be penalized. A miner can recover the faulty sector, let the system terminate the sector automatically after 42 days of faults, or proactively terminate the sector immediately in the case of unrecoverable data loss. In case of a faulty sector, a small penalty fee approximately equal to the block reward that the sector would win per day is applied. The fee is calculated per day of the sector being unavailable to the network, i.e. until the sector is recovered or terminated. -Miners can extend the lifetime of a sector at any time, though the sector will be expected to remain live until it has reached the end of the new sector lifetime. This can be done by submitting a `ExtendedSectorExpiration` message to the chain. +Miners can extend the lifetime of a sector at any time, though the sector will be expected to remain live until it has reached the end of the new sector lifetime. This can be done by submitting a `ExtendedSectorExpiration` message to the chain. As of FIP-0021, when sectors are extended, their deal weights are adjusted to account for the portion of deal spacetime already consumed, preventing quality calculation issues. + +## Sector Commitment Duration + +### Maximum Commitment Duration +Since FIP-0052, storage providers can commit sectors for up to 1278 days (3.5 years). This increased from the previous maximum of 540 days (1.5 years), enabling: +- Longer-term storage deals that meet client demands for archival storage +- Improved network stability through longer commitment periods +- Reduced operational overhead from less frequent sector renewals + +The maximum commitment duration applies to: +- Initial sector commitments when sectors are first proven +- Sector extensions at any point during a sector's lifetime +- Storage deals, which can now be made for up to 1278 days + +All sectors, including those committed before FIP-0052, are eligible for extension up to 1278 days, subject to the overall 5-year maximum sector lifetime limit imposed by proof security constraints. + +## Sector Extension Limitations + +### V1 Proof Sectors +Sectors sealed using V1 proof before network version 7 (November 27, 2020) have a special limitation on their maximum lifetime. These sectors can only be extended up to a maximum total lifetime of 540 days, including the days they have already been active. This restriction was introduced to address potential long-term security concerns with the V1 proof construction while still allowing miners who sealed these sectors to benefit from extensions. A sector can be in one of the following states. | State | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Precommitted` | Miner seals sector and submits `miner.PreCommitSector` or `miner.PreCommitSectorBatch` | -| `Committed` | Miner generates a Seal proof and submits `miner.ProveCommitSector` or `miner.ProveCommitAggregate` | +| `Precommitted` | Miner seals sector and submits `miner.PreCommitSector` or `miner.PreCommitSectorBatch` (up to 256 sectors per batch) | +| `Committed` | Miner generates a Seal proof and submits `miner.ProveCommitSector` or `miner.ProveCommitSectorAggregated` | | `Active` | Miner generate valid PoSt proofs and timely submits `miner.SubmitWindowedPoSt` | | `Faulty` | Miner fails to generate a proof (see Fault section) | | `Recovering` | Miner declared a faulty sector via `miner.DeclareFaultRecovered` | | `Terminated` | Either sector is expired, or early terminated by a miner via `miner.TerminateSectors`, or was failed to be proven for 42 consecutive proving periods. | + +## Batch Operations + +To improve gas efficiency and reduce chain congestion, miners can use batch methods for sector operations: + +### PreCommitSectorBatch +The `PreCommitSectorBatch` method allows miners to pre-commit up to 256 sectors in a single transaction. This method provides significant gas savings by: +- Fetching reward and power statistics only once for the entire batch +- Allocating sector numbers in batch rather than individually +- Loading and storing state structures (HAMT, AMT) only once +- Invoking market actor verification once for all sectors + +High-growth miners benefit most from batching, as it amortizes per-sector costs across multiple sectors. The 256 sector limit per batch supports up to 8 EiB of 32 GiB sectors per year for a single miner. + +Since FIP-0041, a new `PreCommitSectorBatch2` method (method number 28) is available that includes an `unsealed_sector_cid` field for forward compatibility with future market mechanisms. This method removes deprecated CC upgrade fields and prepares for user-deployable storage markets. + +### ProveCommitSectorAggregated +The `ProveCommitSectorAggregated` method allows miners to prove-commit multiple sectors at once using aggregated proofs. This method provides significant gas savings by: +- Using aggregated proof verification that scales logarithmically with the number of sectors +- Amortizing state access costs across multiple prove commits +- Batching market actor `ComputeDataCommitment` calls +- Eliminating the need for temporary storage and cron-batching used in individual prove commits + +The method supports a minimum of 4 and a maximum of 819 sectors per aggregation. The aggregated proof uses novel cryptographic techniques to drastically reduce per-sector proof size and verification times. The maximum delay between pre-commit and prove-commit is extended to 30 days plus PreCommitChallengeDelay to allow miners of all sizes to accumulate enough sectors for efficient aggregation. + +## Sector Updates + +### Snap Deals (ProveReplicaUpdates) +Snap Deals, introduced in FIP-0019, allow storage providers to update existing Committed Capacity (CC) sectors with real data without performing a full re-sealing operation. This one-message protocol significantly reduces the cost and time required to convert empty sectors into sectors containing client data. + +The process works by: +- Encoding deal data into the existing CC sector replica using unpredictable randomness +- Generating a SNARK proof that demonstrates the sector was correctly updated +- Submitting a single `ProveReplicaUpdates` message to the chain + +This mechanism unlocks the large amount of CC capacity already committed to the network, allowing it to be quickly utilized for storing real client data. The protocol is limited to CC sectors as it requires access to the sector key commitment that is only available for sectors without existing deals. + +Since FIP-0041, a new `ProveReplicaUpdates2` method (method number 29) is available that includes a `new_unsealed_cid` field. This forward-compatible version prepares for future changes in storage market mechanisms where unsealed CIDs will serve as primary data identifiers. + +### Aggregated Replica Updates (ProveReplicaUpdates3) + +FIP-0082 introduces support for aggregated proof verification in the `ProveReplicaUpdates3` method (method number 35, originally from FIP-0076). This allows storage providers to update multiple sectors efficiently in a single transaction by submitting an aggregated Groth16 proof. + +Key features: +- **Batch Size**: Minimum 3 sectors, maximum 512 sectors per aggregation +- **Gas Efficiency**: Verification time and gas costs scale logarithmically with the number of proofs +- **Proof Format**: Uses SnarkPack V2 aggregation (same as ProveCommitAggregate) +- **Gas Pricing**: Linear component (80,000 gas per sector) plus step-wise costs based on proof count + +Gas cost breakdown: +- **32 GiB sectors**: 80,000 gas per sector plus step-wise costs ranging from 86.5M to 99M gas +- **64 GiB sectors**: 80,000 gas per sector plus step-wise costs ranging from 86.5M to 99.5M gas + +The aggregated proof mechanism significantly reduces the per-sector cost of replica updates, making Snap Deals more economically viable for storage providers updating many sectors. Like ProveCommitAggregate, it includes an additional batch gas charge to align incentives. + +## PoRep Security Policy and Replacement Sealing + +FIP-0067 establishes a comprehensive policy to address potential vulnerabilities in Proof-of-Replication (PoRep) theory or implementation. While no PoRep issues are currently known, this policy ensures the network can respond effectively if a flaw is discovered. + +### Replacement Sealing Mechanism + +The replacement sealing mechanism introduces enforcement for sectors with commitments longer than 1.5 years (the DeactivationTarget). Key components include: + +**Miner State Properties:** +- `InitialOldSectors`: Number of sectors sealed with vulnerable PoRep that must be deactivated +- `DeactivatedOldSectors`: Count of old sectors that have been successfully deactivated + +**Timeline Parameters:** +- `GracePeriod`: 60 days during which no enforcement actions are taken +- `DeactivationTarget`: 1.5 years - the deadline for all vulnerable sectors to be deactivated +- `StartEpoch`: Network upgrade epoch when replacement sealing begins + +**Deactivation Progress:** +The `DeactivationProgress` metric tracks each miner's replacement progress: +``` +DeactivationProgress = GracePeriod + (DeactivationTarget - GracePeriod) * DeactivatedOldSectors / InitialOldSectors +``` + +### Enforcement Actions + +If a storage provider falls behind their deactivation schedule: + +1. **Block Production Eligibility**: Miners cannot produce blocks if their deactivation progress lags behind the current epoch +2. **Deadline Faults**: If progress is >24 hours behind, the deadline is marked faulty (recoverable) +3. **Deadline Termination**: If progress is >7 days behind, the deadline is terminated (non-recoverable) + +### Policy Response to PoRep Vulnerabilities + +In case a PoRep flaw is discovered: +1. A new, secure PoRep algorithm is implemented +2. The vulnerable algorithm is disabled for new sectors +3. The deactivation timeline begins for existing vulnerable sectors +4. Sector extensions are prohibited for vulnerable sectors +5. A `ReplaceSector(OldSector, NewSector)` method allows providers to replace vulnerable sectors without termination fees + +This policy ensures network security can be maintained even with longer sector commitments (up to 3.5 years), as vulnerable sectors can be systematically replaced rather than waiting for natural expiration. diff --git a/content/systems/filecoin_mining/sector/sector-faults.md b/content/systems/filecoin_mining/sector/sector-faults.md index 9372b735e..93e23e9ce 100644 --- a/content/systems/filecoin_mining/sector/sector-faults.md +++ b/content/systems/filecoin_mining/sector/sector-faults.md @@ -9,6 +9,14 @@ dashboardTests: 0 # Sector Faults + + It is very important for storage providers to have a strong incentive to both report the failure to the chain and attempt recovery from the fault in order to uphold the storage guarantee for the networkʼs clients. Without this incentive, it is impossible to distinguish an honest minerʼs hardware failure from malicious behavior, which is necessary to treat miners fairly. The size of the fault fees depend on the severity of the failure and the rewards that the miner is expected to earn from the sector to make sure incentives are aligned. The two types of sector storage fault fees are: - **Sector fault fee:** This fee is paid per sector per day while the sector is in a faulty state. This fee is not paid the first day the system detects the fault allowing a one day grace period for recovery without fee. The size of the sector fault fee is slightly more than the amount the sector is expected to earn per day in block rewards. If a sector remains faulty for more than 42 consecutive days, the sector will pay a termination fee and be _removed from the chain state_. As storage miner reliability increases above a reasonable threshold, the risk posed by these fees decreases rapidly. diff --git a/content/systems/filecoin_mining/sector/sector-quality/_index.md b/content/systems/filecoin_mining/sector/sector-quality/_index.md index f1be2c0fc..da16f252c 100644 --- a/content/systems/filecoin_mining/sector/sector-quality/_index.md +++ b/content/systems/filecoin_mining/sector/sector-quality/_index.md @@ -8,15 +8,23 @@ dashboardTests: 0 math-mode: true --- + + # Sector Quality Given different sector contents, not all sectors have the same usefulness to the network. The notion of Sector Quality distinguishes between sectors with heuristics indicating the presence of valuable data. That distinction is used to allocate more subsidies to higher-quality sectors. To quantify the contribution of a sector to the consensus power of the network, some relevant parameters are described here. - **Sector Spacetime:** This measurement is the sector size multiplied by its promised duration in byte-epochs. -- **Deal Weight:** This weight converts spacetime occupied by deals into consensus power. Deal weight of verified client deals in a sector is called Verified Deal Weight and will be greater than the regular deal weight. +- **Deal Weight:** This weight converts spacetime occupied by deals into consensus power. Deal weight of Filecoin Plus deals in a sector is called Verified Deal Weight and will be greater than the regular deal weight. - **Deal Quality Multiplier:** This factor is assigned to different deal types (committed - capacity, regular deals, and verified client deals) to reward different content. -- **Sector Quality Multiplier:** Sector quality is assigned on Activation (the epoch when the miner starts proving theyʼre storing the file). The sector quality multiplier is computed as an average of deal quality multipliers (committed capacity, regular deals, and verified client deals), weighted by the amount of spacetime each type of deal occupies in the sector. + capacity, regular deals, and Filecoin Plus deals) to reward different content. +- **Sector Quality Multiplier:** Sector quality is assigned on Activation (the epoch when the miner starts proving theyʼre storing the file). The sector quality multiplier is computed as an average of deal quality multipliers (committed capacity, regular deals, and Filecoin Plus deals), weighted by the amount of spacetime each type of deal occupies in the sector. {{}} $SectorQualityMultiplier = \frac{\sum\nolimits_{deals} DealWeight * DealQualityMultiplier}{SectorSpaceTime}$ @@ -27,7 +35,7 @@ $SectorQualityMultiplier = \frac{\sum\nolimits_{deals} DealWeight * DealQualityM The multipliers for committed capacity and regular deals are equal to make self dealing irrational in the current configuration of the protocol. In the future, it may make sense to pick different values, depending on other ways of preventing attacks becoming available. -The high quality multiplier and easy verification process for verified client deals facilitates decentralization of miner power. Unlike other proof-of-work-based protocols, like Bitcoin, central control of the network is not simply decided based on the resources that a new participant can bring. In Filecoin, accumulating control either requires significantly more resources or some amount of consent from verified clients, who must make deals with the centralized miners for them to increase their influence. Verified client mechanisms add a layer of social trust to a purely resource driven network. As long as the process is fair and transparent with accountability and bounded trust, abuse can be contained and minimized. A high sector quality multiplier is a very powerful leverage for clients to push storage providers to build features that will be useful to the network as a whole and increase the networkʼs long-term value. The verification process and DataCap allocation are meant to evolve over time as the community learns to automate and improve this process. An illustration of sectors with various contents and their respective sector qualities are shown in the following Figure. +The high quality multiplier and verification process for Filecoin Plus deals facilitates decentralization of miner power. Unlike other proof-of-work-based protocols, like Bitcoin, central control of the network is not simply decided based on the resources that a new participant can bring. In Filecoin, accumulating control either requires significantly more resources or some amount of consent from Filecoin Plus clients, who must make deals with the centralized miners for them to increase their influence. The Filecoin Plus mechanism adds a layer of social trust to a purely resource driven network. As long as the process is fair and transparent with accountability and bounded trust, abuse can be contained and minimized. A high sector quality multiplier is a very powerful leverage for clients to push storage providers to build features that will be useful to the network as a whole and increase the networkʼs long-term value. The verification process and DataCap allocation are meant to evolve over time as the community learns to automate and improve this process. An illustration of sectors with various contents and their respective sector qualities are shown in the following Figure. ![Sector Quality](sector-quality.jpg) @@ -37,7 +45,7 @@ The high quality multiplier and easy verification process for verified client de | ----------------------------------- | ----------------------------------------------------- | | QualityBaseMultiplier (QBM) | Multiplier for power for storage without deals. | | DealWeightMultiplier (DWM) | Multiplier for power for storage with deals. | -| VerifiedDealWeightMultiplier (VDWM) | Multiplier for power for storage with verified deals. | +| VerifiedDealWeightMultiplier (VDWM) | Multiplier for power for storage with Filecoin Plus deals. | The formula for calculating Sector Quality Adjusted Power (or QAp, often referred to as power) makes use of the following factors: @@ -58,3 +66,23 @@ $sectorQuality = avgQuality*size$ {{}} During `miner.PreCommitSector` and `miner.PreCommitSectorBatch`, the sector quality is calculated and stored in the sector information. + +## Sector Extension Quality Calculation + +When a sector is extended, the quality calculation must account for the fact that some of the original deal spacetime has already been "spent" during the sector's past lifetime. As of FIP-0021, the protocol corrects for this by adjusting the DealWeight and VerifiedDealWeight during extension. + +The adjustment is performed by multiplying the deal weights by the fraction of the sector's lifetime that remains: + +{{}} +$remainingFraction = \frac{currentExpiration - currentEpoch}{currentExpiration - activationEpoch}$ +{{}} + +{{}} +$adjustedDealWeight = DealWeight * remainingFraction$ +{{}} + +{{}} +$adjustedVerifiedDealWeight = VerifiedDealWeight * remainingFraction$ +{{}} + +This correction prevents the overcounting of deal spacetime that would otherwise occur when sectors with expired deals are extended, ensuring that verified deal weight maintains its designed relative power compared to committed capacity sectors. diff --git a/content/systems/filecoin_mining/storage_mining/storage_miner_actor.md b/content/systems/filecoin_mining/storage_mining/storage_miner_actor.md index 45b47682a..69f1c490d 100644 --- a/content/systems/filecoin_mining/storage_mining/storage_miner_actor.md +++ b/content/systems/filecoin_mining/storage_mining/storage_miner_actor.md @@ -9,8 +9,44 @@ dashboardAuditDate: '2020-10-19' dashboardTests: 0 --- + + # Storage Miner Actor {{}} {{}} + +## Balance Management + +Storage miners maintain balances for various purposes including collateral and rewards. The `WithdrawBalance` method allows authorized parties to withdraw available funds from the miner actor. + +### Beneficiary Address + +Since FIP-0029, storage miners can designate a beneficiary address that takes over financial control from the owner. This separation enables more flexible financial arrangements such as lending markets and improved security. Key features include: + +- **Beneficiary Role**: The beneficiary address receives all withdrawn funds, even when withdrawals are initiated by the owner +- **Quota and Expiration**: Beneficiaries have a quota (maximum withdrawal amount) and expiration date defined in the BeneficiaryTerm +- **Change Process**: Changing the beneficiary requires approval from the owner, current beneficiary, and proposed beneficiary (with auto-approval in certain cases) +- **Default Behavior**: New miners without a specified beneficiary have their beneficiary set to the owner address for backward compatibility + +### Withdrawal Process + +The `WithdrawBalance` method can be called by either the owner or beneficiary address, but funds are always sent to the beneficiary. Following FIP-0020, this method returns the actual amount withdrawn, providing transparency when the available balance is less than the requested withdrawal amount. + +If the beneficiary term has expired or the quota is exhausted, withdrawal attempts will fail with a USR_FORBIDDEN error until the beneficiary is updated. This differs from owner-to-self withdrawals, which succeed with zero withdrawal when no funds are available. + +### Methods + +- **WithdrawBalance**: Withdraws available funds to the beneficiary address +- **ChangeBeneficiary**: Proposes or confirms a change to the beneficiary address and/or terms +- **GetBeneficiary**: Retrieves current and proposed beneficiary information diff --git a/content/systems/filecoin_token/multisig.md b/content/systems/filecoin_token/multisig.md index b17cf12b2..f4b5a2981 100644 --- a/content/systems/filecoin_token/multisig.md +++ b/content/systems/filecoin_token/multisig.md @@ -10,6 +10,14 @@ dashboardAuditDate: '2020-10-19' dashboardTests: 0 --- + + # Multisig Wallet & Actor The Multisig actor is a single actor representing a group of Signers. Signers may be external users, other Multisigs, or even the Multisig itself. There should be a maximum of 256 signers in a multisig wallet. In case more signers are needed, then the multisigs should be combined into a tree. @@ -17,3 +25,13 @@ The Multisig actor is a single actor representing a group of Signers. Signers ma The implementation of the Multisig Actor can be found [here](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/multisig/multisig_actor.go). The Multisig Actor statuses can be found [here](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/multisig/multisig_state.go). + +## Method Handling + +Since FIP-0062, the multisig actor includes a fallback method handler for method numbers greater than or equal to 2^24 (the first exported method as per FRC-0042). This enables the multisig actor to: + +- Receive value transfers from EVM runtime actors (smart contracts), Ethereum accounts, and placeholders +- Accept calls with method numbers ≥ 2^24, which are handled as no-ops returning success +- Maintain compatibility with the Filecoin EVM ecosystem where actors use `MethodNum = FRC-42("InvokeEVM")` for outbound calls + +This behavior brings multisig actors in line with account actors, which received similar functionality in FIP-0050. Prior to this change, multisigs would reject such calls, causing value transfers to fail when originating from EVM-based actors. diff --git a/content/systems/filecoin_token/payment_channels.md b/content/systems/filecoin_token/payment_channels.md index 736bdf042..3a4a2484d 100644 --- a/content/systems/filecoin_token/payment_channels.md +++ b/content/systems/filecoin_token/payment_channels.md @@ -8,6 +8,14 @@ dashboardAudit: wip dashboardTests: 0 --- + + # Payment Channels Payment channels are generally used as a mechanism to increase the scalability of blockchains and enable users to transact without involving (i.e., publishing their transactions on) the blockchain, which: i) increases the load of the system, and ii) incurs gas costs for the user. Payment channels generally use a smart contract as an agreement between the two participants. In the Filecoin blockchain Payment Channels are realised by the `paychActor`. @@ -124,6 +132,22 @@ Summarising, we have the following sequence: 9. Either the channel sender or the channel recipient calls `Collect`. 10. Funds are transferred to the channel recipient's account and any unclaimed balance goes back to channel sender. +## Channel Destruction + +Payment channels can be destroyed using the `self_destruct` syscall. Since FIP-0073, this syscall has been simplified: + +### Previous Behavior +- `self_destruct(beneficiary)` would transfer remaining funds to a beneficiary address before deleting the actor +- This transfer was implicit and didn't appear in traces or create the beneficiary if needed + +### Current Behavior +- `self_destruct(burn: bool)` takes a boolean parameter instead of a beneficiary address +- If `burn` is `false` and there are remaining funds, the syscall fails with `IllegalOperation` +- If `burn` is `true`, any remaining funds are transferred to the burnt funds account +- To transfer funds before destruction, actors must explicitly use the `send` syscall first + +This change ensures all fund transfers follow standard message semantics and appear properly in execution traces. + ## Payment Channels as part of the Filecoin Retrieval Payment Channels are used in the Filecoin [Retrieval Market](retrieval_market) to enable efficient off-chain payments and accounting between parties for what is expected to be a series of microtransactions, as these occur during data retrieval. diff --git a/content/systems/filecoin_token/token_allocation/_index.md b/content/systems/filecoin_token/token_allocation/_index.md index cad9585c3..63c7e2463 100644 --- a/content/systems/filecoin_token/token_allocation/_index.md +++ b/content/systems/filecoin_token/token_allocation/_index.md @@ -8,6 +8,14 @@ dashboardAudit: n/a dashboardTests: 0 --- + + # Token Allocation Filecoinʼs token distribution is broken down as follows. A maximum of 2,000,000,000 FIL will ever be created, referred to as `FIL_BASE`. Of the Filecoin genesis block allocation, 10% of `FIL_BASE` were allocated for fundraising, of which 7.5% were sold in the 2017 token sale, and the 2.5% remaining were allocated for ecosystem development and potential future fundraising. 15% of `FIL_BASE` were allocated to Protocol Labs (including 4.5% for the PL team & contributors), and 5% were allocated to the Filecoin Foundation. The other 70% of all tokens were allocated to miners, as mining rewards, "for providing data storage service, maintaining the blockchain, distributing data, running contracts, and more." There are multiple types of mining that these rewards will support over time; therefore, this allocation has been subdivided to cover different mining activities. A pie chart reflecting the FIL token allocation is shown in the following Figure. @@ -16,7 +24,9 @@ Filecoinʼs token distribution is broken down as follows. A maximum of 2,000,000 **Storage Mining Allocation.** At network launch, the only mining group with allocated incentives will be storage miners. This is the earliest group of miners, and the one responsible for maintaining the core functionality of the protocol. Therefore, this group has been allocated the largest amount of mining rewards. 55% of `FIL_BASE` (78.6% of mining rewards) is allocated to storage mining. This will cover primarily block rewards, which reward maintaining the blockchain, running actor code, and subsidizing reliable and useful storage. This amount will also cover early storage mining rewards, such as rewards in the SpaceRace competition and other potential types of storage miner initialization, such as faucets. -**Mining Reserve.** The Filecoin ecosystem must ensure incentives exist for all types of miners (e.g. retrieval miners, repair miners, and including future unknown types of miners) to support a robust economy. In order to ensure the network can provide incentives for these other types of miners, 15% of `FIL_BASE` (21.4% of mining rewards) have been set aside as a Mining Reserve. It will be up to the community to determine in the future how to distribute those tokens, through Filecoin improvement proposals (FIPs) or similar decentralized decision making processes. For example, the community might decide to create rewards for retrieval mining or other types of mining-related activities. The Filecoin Network, like all blockchain networks and open source projects, will continue to evolve, adapt, and overcome challenges for many years. Reserving these tokens provides future flexibility for miners and the ecosystem as a whole. Other types of mining, like retrieval mining, are not yet subsidized and yet are very important to the Filecoin Economy; Arguably, those uses may need a larger percentage of mining rewards. As years pass and the network evolves, it will be up to the community to decide whether this reserve is enough, or whether to make adjustments with unmined tokens. +**Mining Reserve.** The Filecoin ecosystem must ensure incentives exist for all types of miners (e.g. retrieval miners, repair miners, and including future unknown types of miners) to support a robust economy. In order to ensure the network can provide incentives for these other types of miners, 15% of `FIL_BASE` (21.4% of mining rewards) have been set aside as a Mining Reserve. It will be up to the community to determine in the future how to distribute those tokens, through Filecoin improvement proposals (FIPs) or similar decentralized decision making processes. + +The Mining Reserve is held in actor f090, which is a keyless account actor that ensures all changes must go through network governance. This means that any use of the Mining Reserve funds requires a FIP and network upgrade, ensuring transparent and decentralized control over these funds. For example, the community might decide to create rewards for retrieval mining or other types of mining-related activities. The Filecoin Network, like all blockchain networks and open source projects, will continue to evolve, adapt, and overcome challenges for many years. Reserving these tokens provides future flexibility for miners and the ecosystem as a whole. Other types of mining, like retrieval mining, are not yet subsidized and yet are very important to the Filecoin Economy; Arguably, those uses may need a larger percentage of mining rewards. As years pass and the network evolves, it will be up to the community to decide whether this reserve is enough, or whether to make adjustments with unmined tokens. **Market Cap.** Various communities estimate the size of cryptocurrency and token networks using different analogous measures of market capitalization. The most sensible token supply for such calculations is `FIL_CirculatingSupply`, because unmined, unvested, locked, and burnt funds are not circulating or tradeable in the economy. Any calculations using larger measures such as `FIL_BASE` are likely to be erroneously inflated and not to be believed. diff --git a/content/systems/filecoin_vm/_index.md b/content/systems/filecoin_vm/_index.md index cb10d9060..314fabd8f 100644 --- a/content/systems/filecoin_vm/_index.md +++ b/content/systems/filecoin_vm/_index.md @@ -11,8 +11,205 @@ dashboardTests: 0 # Virtual Machine + + An Actor in the Filecoin Blockchain is the equivalent of the smart contract in the Ethereum Virtual Machine. -The Filecoin Virtual Machine (VM) is the system component that is in charge of execution of all actors code. Execution of actors on the Filecoin VM (i.e., on-chain executions) incur a gas cost. +The Filecoin Virtual Machine (VM) is the system component that is in charge of execution of all actors code. Since FIP-0030, the FVM is a WASM-based execution environment that supports both built-in actors and user-programmable actors, enabling general smart contract functionality on Filecoin. Execution of actors on the Filecoin VM (i.e., on-chain executions) incur a gas cost. + +## Overview + +The FVM provides: +- **WASM Execution**: A WebAssembly-based runtime for executing actor code +- **User Programmability**: Support for deploying and running arbitrary user-defined actors +- **Built-in Actors**: Continued support for Filecoin's system actors (storage market, miner, etc.) +- **IPLD Integration**: Native support for IPLD data structures and content-addressed storage +- **Syscall Interface**: A comprehensive set of system calls for actor-to-system interactions + +## Actor Code CIDs + +Every actor in the state tree specifies a Code CID that identifies its executable code and serves as its type designator. Since FIP-0031, these are content-addressed CIDs computed over the actor's WASM bytecode: + +``` +CodeCid = Cid(IPLD_RAW_CODEC, Mh(BLAKE2B-256, wasm_bytecode)) +``` + +Prior to FIP-0031, the network used synthetic CIDs of the form `fil/$actor_version/$actor_type`. The transition to content-addressed CIDs improved security and enabled proper content verification. + +### Built-in Actors + +The canonical implementation of Filecoin's built-in actors is maintained at [`filecoin-project/builtin-actors`](https://github.com/filecoin-project/builtin-actors). The build process produces a CARv1 archive containing all actor WASM bytecode, which clients import on startup. + +Since FIP-0031, the system actor (f00) maintains a registry of built-in actor Code CIDs in its state, enabling dynamic actor version management. + +## Method Invocation and Access Control + +Since FIP-0050, the FVM enforces strict access control on built-in actor methods to maintain stability for user-programmed actors: + +### Method Number Conventions + +Following FRC-0042, method numbers are organized as: +- **0 to 2^24-1**: Internal methods restricted to built-in actors +- **2^24 and above**: Public exported methods callable by any actor + +### Access Restrictions + +When invoking a method on a built-in actor: +1. If the method number is ≥ 2^24, it is considered "exported" and callable by any actor +2. If the method number is < 2^24, the FVM checks the caller's code CID: + - Built-in actors can invoke these internal methods + - User-programmed actors (including EVM actors) receive an error + +This separation ensures that: +- Internal implementation details of built-in actors can evolve without breaking user actors +- User actors have access to a stable, well-defined API that won't change +- The protocol can be upgraded while maintaining backward compatibility + +### Public APIs + +Each built-in actor exports specific methods for public use: +- **Account Actor**: AuthenticateMessage, UniversalReceiverHook +- **Storage Market Actor**: AddBalance, WithdrawBalance, PublishStorageDeals, GetBalance, GetDealDataCommitment, etc. +- **Miner Actor**: ChangeWorkerAddress, WithdrawBalance, GetOwner, GetSectorSize, GetAvailableBalance, etc. +- **Storage Power Actor**: CreateMiner, NetworkRawPower, MinerRawPower, MinerCount +- **Datacap Actor**: Full token interface (Transfer, Balance, Allowance, etc.) +- **Verified Registry Actor**: AddVerifiedClient, GetClaims, ExtendClaimTerms, etc. + +## Filecoin EVM (FEVM) + + + +Since FIP-0054, Filecoin supports the execution of Ethereum smart contracts through the Filecoin EVM (FEVM) runtime actor. This built-in actor enables Ethereum compatibility while maintaining integration with Filecoin's unique features. + +### EVM Runtime Actor + +The FEVM runtime actor: +- **Runs EVM bytecode**: Compatible with Ethereum Paris fork plus EIP-3855 (PUSH0 opcode) +- **Embeds an EVM interpreter**: Executes smart contracts within the FVM environment +- **Translates opcodes**: Maps Ethereum operations to Filecoin primitives +- **Manages state**: Maps EVM storage model to Filecoin's IPLD-based state + +### Key Features + +1. **Address Mapping**: + - Ethereum addresses are mapped to Filecoin f4 addresses (via Ethereum Address Manager) + - Maintains compatibility with existing Ethereum tooling + - Supports CREATE and CREATE2 deployment patterns + +2. **Precompiles Support**: + - All standard Ethereum precompiles (ecrecover, SHA256, etc.) + - Filecoin-specific precompiles for native actor interaction + - Call actor methods, resolve addresses, and access Filecoin state + +3. **State Management**: + - EVM storage is persisted as IPLD blocks + - Efficient storage through deduplication and content addressing + - Compatible with Ethereum's storage slot model + +### Differences from Ethereum + +While striving for maximum compatibility, some differences exist: +- **Block Time**: ~30 seconds vs Ethereum's ~12 seconds +- **Chain ID**: Filecoin mainnet uses 314, Calibration testnet uses 314159 +- **Gas Model**: Different pricing due to FVM's execution model +- **No Pending Pool**: Transactions execute in the epoch they're included + +### Actor Interface + +The EVM runtime actor exposes these main methods: +- **Constructor**: Deploys new EVM contracts +- **InvokeContract**: Executes contract methods +- **GetBytecode**: Retrieves deployed bytecode +- **GetStorageAt**: Reads contract storage + +## State Tree Any operation applied (i.e., executed) on the Filecoin VM produces an output in the form of a _State Tree_ (discussed below). The latest _State Tree_ is the current source of truth in the Filecoin Blockchain. The _State Tree_ is identified by a CID, which is stored in the IPLD store. + +## Deterministic State Access + +Since FIP-0071, the FVM enforces deterministic rules for state access to ensure network consensus and prepare for user-defined WebAssembly actors. These rules guarantee that actors can only access state that is explicitly "reachable" from their execution context. + +### Reachable Set + +The FVM maintains a "reachable set" of IPLD blocks (identified by CIDs) that an actor instance can access. This set is per-actor-invocation and starts with: + +1. **Actor's state root**: The CID of the actor's state tree +2. **Message parameters**: Any IPLD blocks passed as parameters from other actors +3. **Return values**: Blocks returned from calls to other actors + +State is considered "reachable" if it can be accessed by traversing IPLD links (CIDs) from these roots. + +### IPLD State Access Rules + +Actors interact with state through IPLD syscalls, which enforce the following rules: + +#### Reading State (`ipld::block_open`) +- Actors can only open blocks whose CIDs are in the reachable set +- When a block is opened, all CIDs it references are added to the reachable set +- Gas is charged for tracking reachable CIDs (`ipld_link_tracked`: 550 gas per CID) + +#### Writing State (`ipld::block_create`) +- New blocks can only reference CIDs currently in the reachable set +- The FVM performs link analysis to extract all CIDs from the block +- Gas is charged for checking CID reachability (`ipld_link_checked`: 500 gas per CID) + +#### State Root Updates (`self::set_root`) +- Actors can only set their state root to a CID in the reachable set +- The root must be a blake2b-256 CID, not an identity-hashed inline block + +### Link Analysis + +The FVM performs IPLD link analysis to determine which blocks a given block references: + +**Supported Codecs**: +- Raw (0x55): Contains no links +- CBOR (0x51): Contains no links +- DagCBOR (0x71): Can contain links to other IPLD blocks + +**Allowed CIDs**: +- Blake2b-256 hashes (32 bytes) +- Identity hashes (up to 64 bytes, inlining the block) +- Codecs must be in the supported set + +**Gas Charges**: +- `ipld_cbor_scan_per_field`: 85 gas per CBOR field parsed +- `ipld_cbor_scan_per_cid`: 950 gas per CID encountered + +### Cross-Actor Communication + +When actors communicate via `send::send`: +1. IPLD blocks are passed by handle, not by CID +2. The receiving actor gets a copy of the block in its block table +3. All CIDs reachable from the transferred block are added to the receiver's reachable set +4. This ensures actors can share state while maintaining isolation + +### Security Benefits + +These rules prevent several potential issues: +- **Consensus forks**: Actors cannot read arbitrary blocks that might exist in some nodes but not others +- **State pollution**: Actors cannot reference garbage or leftover state from previous tipsets +- **Deterministic execution**: All state access is predictable and reproducible across the network + +This deterministic state access model is essential for supporting arbitrary user-defined actors while maintaining network security and consensus. diff --git a/content/systems/filecoin_vm/gas_fee.md b/content/systems/filecoin_vm/gas_fee.md index 0f33a85bc..b42f5963a 100644 --- a/content/systems/filecoin_vm/gas_fee.md +++ b/content/systems/filecoin_vm/gas_fee.md @@ -44,3 +44,136 @@ Finally, `GasPremium` is the priority fee included by senders to incentivize min - A message that runs out of gas fails with an "out of gas" exit code. `GasUsed * BaseFee` will still be burned (in this case `GasUsed = GasLimit`), and the miner will still be rewarded `GasLimit * GasPremium`. This assumes that `GasFeeCap > BaseFee + GasPremium`. - A low value for the `GasFeeCap` will likely cause the message to be stuck in the message pool, as it will not be attractive-enough in terms of profit for any miner to pick it and include it in a block. When this happens, there is a procedure to update the `GasFeeCap` so that the message becomes more attractive to miners. The sender can push a new message into the message pool (which, by default, will propagate to other miners' message pool) where: i) the identifier of the old and new messages is the same (e.g., same `Nonce`) and ii) the `GasPremium` is updated and increased by at least 25% of the previous value. + +## Message-Specific Gas Treatment + + + +All messages in the Filecoin network, including `SubmitWindowedPoSt`, are subject to the same gas fee mechanism described above. Specifically, all messages burn `BaseFee * GasUsed` as a network fee. This uniform treatment ensures fair gas market dynamics and prevents distortion of incentives for message batching and chain bandwidth optimization. + +### Batch Operations Gas Charges + +Certain batch operations (`PreCommitSectorBatch` and `ProveCommitSectorAggregated`) incur additional gas charges to align network incentives with long-term health. These charges encourage aggregation while ensuring the protocol captures value from network growth: + +- **BatchBalancer**: 5 nanoFIL - Sets the minimum fee per batch operation +- **BatchDiscount**: 1/20 (5%) - Discount factor applied to batch operations +- **SinglePreCommitGasUsage**: 16,433,324.1825 gas units +- **SingleProveCommitGasUsage**: 49,299,972.5475 gas units + +The batch gas charge is calculated as: +``` +BatchGasFee = Max(BatchBalancer, BaseFee) +BatchGasCharge = BatchGasFee * SingleGasUsage * numBatched * BatchDiscount +``` + +This charge is paid to the network (sent to f99, the burnt funds address) in addition to the regular gas fees for message execution. The mechanism incentivizes miners to aggregate operations when network `BaseFee` is below the crossover point of approximately 0.32 nanoFIL, while capturing additional protocol revenue when the network is less congested. + +## FVM Gas Accounting Model + +Since FIP-0032, the Filecoin Virtual Machine uses a comprehensive gas accounting model that accurately meters the computational resources consumed during actor execution. This model consists of three components: + +### Execution Gas + +Execution gas is charged per WASM instruction executed: +- **Rate**: 1 execution unit per WASM instruction (except structural instructions: `nop`, `drop`, `block`, `loop`, `unreachable`, `return`, `else`, `end`) +- **Pricing**: 4 gas units per execution unit +- **Purpose**: Meters the actual computational work performed by actor code + +### Syscall Gas + +Syscall gas covers the overhead of context switching when actors call system functions: +- **Fixed cost**: 14,000 gas units per syscall invocation +- **Purpose**: Accounts for the overhead of switching between WASM and native execution contexts +- **Note**: The actual work performed by the syscall is charged separately + +### Extern Gas + +Extern gas covers operations performed outside the WASM runtime, including: +- IPLD state management (gets and puts) +- Cryptographic operations +- Actor creation and deletion +- Message inclusion and return value costs + +This comprehensive gas model ensures accurate resource accounting for both built-in and user-defined actors, providing the foundation for secure execution of arbitrary code on the Filecoin network. + +## FEVM Gas Schedule Updates + +Since FIP-0057, the gas charging schedule has been updated to accurately reflect the costs of operations in the presence of user-programmable smart contracts: + +### Storage Costs + +- **State storage cost**: Increased from 1,300 to 3,440 gas/byte +- **Purpose**: Reflects the true cost of persistent storage in the state tree +- **Impact**: Applies to all newly created state, particularly relevant for FEVM contracts + +### Memory Operations + +- **Memory copy**: 0.4 gas/byte (reduced from 0.5) +- **Memory retention**: 10 gas/byte for returned data +- **Memory initialization**: Variable charges based on memory size +- **Purpose**: Accurately charge for memory operations that can be arbitrarily large in FEVM + +### Syscall Gas Adjustments + +Key syscall costs updated for FEVM: + +1. **IPLD Operations**: + - `block_open`: 187,440 + 10 × block_size gas + - `block_create`: Variable based on block size and codec + - `block_link`: 3,340 × block_size gas (storage cost) + +2. **State Tree Operations**: + - State tree reads: Additional charges for traversing the state tree + - Actor address resolution: New charges for resolving addresses + +3. **Hashing and Cryptography**: + - Updated costs for Blake2b, SHA256, and Keccak operations + - Signature verification costs adjusted based on benchmarks + +### System Limits + +FIP-0057 introduced system-wide limits to prevent resource exhaustion: + +- **Maximum IPLD block size**: 1 MiB for all newly created blocks +- **Memory limits**: Overall limits on Wasm memory and table elements +- **Call depth limit**: Reduced from 1025 to 1024 to align with other blockchain VMs + +These updates ensure that gas costs accurately reflect resource consumption, preventing potential DoS attacks and maintaining network stability as FEVM enables arbitrary smart contract execution. + +### Randomness and Tipset CID Lookback Costs + +Operations that require looking back through the chain history have gas costs proportional to the lookback distance: + +- **`get_chain_randomness`**: Returns randomness from the ticket chain +- **`get_beacon_randomness`**: Returns randomness from the beacon +- **`get_tipset_cid`**: Returns the CID of a tipset at a given epoch + +**Gas cost formula**: `75 * lookback + 146,200` + +Where: +- `lookback` = current epoch - requested epoch +- 75 gas per epoch accounts for skiplist traversal +- 146,200 gas covers base overhead (serialization, hashing, syscall costs) + +This proportional pricing ensures that operations requiring deep chain traversal are appropriately charged, preventing potential DoS attacks through excessive lookback requests. diff --git a/content/systems/filecoin_vm/runtime/_index.md b/content/systems/filecoin_vm/runtime/_index.md index 7b3dae31e..c35aa6d33 100644 --- a/content/systems/filecoin_vm/runtime/_index.md +++ b/content/systems/filecoin_vm/runtime/_index.md @@ -12,19 +12,35 @@ dashboardTests: 0 ## Receipts + + A `MessageReceipt` contains the result of a top-level message execution. Every syntactically valid and correctly signed message can be included in a block and will produce a receipt from execution. A syntactically valid receipt has: - a non-negative `ExitCode`, -- a non empty `Return` value only if the exit code is zero, and -- a non-negative `GasUsed`. +- a non empty `Return` value only if the exit code is zero, +- a non-negative `GasUsed`, and +- an optional `EventsRoot` containing the root CID of an AMT of events emitted during execution (since FIP-0049). ```go type MessageReceipt struct { ExitCode exitcode.ExitCode Return []byte GasUsed int64 + EventsRoot *cid.Cid // Root of AMT (optional, since FIP-0049) } ``` @@ -39,3 +55,137 @@ The Lotus implementation of the Filecoin Virtual Machine runtime can be found [h ## Exit Codes There are some common runtime exit codes that are shared by different actors. Their definition can be found [here](https://github.com/filecoin-project/go-state-types/blob/master/exitcode/common.go). + +## Actor Events + + + +Since FIP-0049, actors can emit externally observable events during execution. Events are fire-and-forget signals that indicate some relevant circumstance, action, or transition has occurred. They enable external agents to observe on-chain activity without needing to parse state trees or replay messages. + +### Event Structure + +Events consist of ordered key-value entries with metadata flags: + +```rust +/// An event emitted by an actor, stamped with additional metadata by the FVM +struct StampedEvent { + emitter: u64, // Actor ID of the emitting actor + event: ActorEvent, // The actual event payload +} + +/// Event payload as emitted by the actor +type ActorEvent = Vec; + +struct Entry { + flags: u64, // Metadata/hints (e.g., indexing flags) + key: String, // UTF-8 key (max 32 bytes) + codec: u64, // IPLD codec for the value (currently only IPLD_RAW = 0x55) + value: Vec, // Raw value bytes +} +``` + +### Emitting Events + +Actors emit events using the `vm::emit_event` syscall: + +```rust +/// Emits an actor event from CBOR-encoded ActorEvent in Wasm memory +fn emit_event(event_off: u32, event_len: u32) -> Result<()>; +``` + +### Event Accumulation + +- Events are accumulated during message execution +- When an actor exits normally (exit code 0), its events are retained +- When an actor exits abnormally (exit code > 0), its events are discarded +- Out of gas or fatal errors discard all events from the call stack + +### Event Limits + +Since FIP-0072, event limits have been refined: +- Maximum 31 bytes per key (reduced from 32 for compact CBOR encoding) +- Maximum 8 KiB total value size per event +- Maximum 255 entries per event (reduced from 256 for single-byte CBOR length) +- Only IPLD_RAW (0x55) codec currently supported + +### Improved Event Syscall API + +FIP-0072 introduced an optimized `emit_event` syscall that eliminates CBOR encoding overhead: + +**Previous API** (single CBOR-encoded buffer): +```rust +pub fn emit_event(event_off: *const u8, event_len: u32) -> Result<()> +``` + +**Current API** (three separate buffers): +```rust +pub fn emit_event( + event_off: *const EventEntry, + event_len: u32, + key_off: *const u8, + key_len: u32, + value_off: *const u8, + value_len: u32, +) -> Result<()> +``` + +Where `EventEntry` is a packed struct: +```rust +#[repr(C, packed)] +pub struct EventEntry { + pub flags: u64, // Event flags (indexing hints) + pub codec: u64, // Value codec (currently only IPLD_RAW) + pub key_size: u32, // Size of key in bytes + pub value_size: u32, // Size of value in bytes +} +``` + +This design enables: +- Precise gas charging based on actual data sizes +- Concurrent validation during deserialization +- Elimination of CBOR parsing overhead +- More accurate gas model for non-EVM actors + +### Indexing Flags + +Events support indexing hints through flags: +- `0x01`: Index by key +- `0x02`: Index by value +- `0x03`: Index by both key and value + +Note: Since FIP-0072, indexing costs have been removed from gas calculations as this feature was not being used. + +## Built-in Actor Events + +Since FIP-0083, built-in actors emit events to provide external observability of state transitions. Events use CBOR encoding (codec 0x51) for values. + +### Verified Registry Actor Events + +- **Verifier Balance Updated**: Emitted when a verifier's balance changes +- **Datacap Allocated**: Emitted when a client allocates datacap to a provider +- **Datacap Allocation Removed**: Emitted when an expired allocation is removed +- **Datacap Allocation Claimed**: Emitted when a provider claims an allocation +- **Datacap Claim Updated**: Emitted when a claim's term is extended +- **Datacap Claim Removed**: Emitted when an expired claim is removed + +### Market Actor Events + +- **Deal Published**: Emitted for each new deal published by a provider +- **Deal Activated**: Emitted when a deal is successfully activated +- **Deal Terminated**: Emitted when a deal is terminated early +- **Deal Completed**: Emitted when a deal completes successfully + +### Miner Actor Events + +- **Sector Pre-committed**: Emitted when a sector is pre-committed +- **Sector Activated**: Emitted when a sector is prove-committed +- **Sector Updated**: Emitted when a CC sector is updated with real data (Snap Deals) +- **Sector Terminated**: Emitted when a sector is terminated + +Each event includes relevant metadata (IDs, addresses, CIDs) to enable filtering and tracking by external tools. Event payloads are kept minimal to reduce gas costs while providing sufficient information for observability. diff --git a/content/systems/filecoin_vm/state_tree/_index.md b/content/systems/filecoin_vm/state_tree/_index.md index e3475824a..b93d66710 100644 --- a/content/systems/filecoin_vm/state_tree/_index.md +++ b/content/systems/filecoin_vm/state_tree/_index.md @@ -9,6 +9,8 @@ dashboardTests: 0 # State Tree -The State Tree is the output of the execution of any operation applied on the Filecoin Blockchain. The on-chain (i.e., VM) state data structure is a map (in the form of a Hash Array Mapped Trie - HAMT) that binds addresses to actor states. The current State Tree function is called by the VM upon every actor method invocation. +The State Tree is the output of the execution of any operation applied on the Filecoin Blockchain. The on-chain (i.e., VM) state data structure is a map (in the form of a Hash Array Mapped Trie - HAMT v3) that binds addresses to actor states. The current State Tree function is called by the VM upon every actor method invocation. + +The State Tree uses the optimized HAMT v3 data structure which provides efficient lookups and updates while minimizing gas costs through dirty node tracking and deferred writes. See the [Data Structures appendix](appendix#hamt-hash-array-mapped-trie) for details on HAMT v3 optimizations. {{}} diff --git a/content/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index c4e4162dc..f33283b30 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -12,27 +12,47 @@ dashboardTests: 0 # System Actors -There are eleven (11) builtin System Actors in total, but not all of them interact with the VM. Each actor is identified by a _Code ID_ (or CID). + + +There are fourteen (14) builtin System Actors in total, but not all of them interact with the VM. Each actor is identified by a _Code ID_ (or CID). There are four (4) system actors required for VM processing: - the [InitActor](sysactors#initactor), which initializes new actors and records the network name, and - the [CronActor](sysactors#cronactor), a scheduler actor that runs critical functions at every epoch. -There are another two actors that interact with the VM: +There are another three actors that interact with the VM: - the [AccountActor](sysactors#accountactor) responsible for user accounts (non-singleton), and - the [RewardActor](sysactors#rewardactor) for block reward and token vesting (singleton). +- the `EthereumAccountActor` responsible for Ethereum EOA accounts, supporting native Ethereum transactions (non-singleton). -The remaining seven (7) builtin System Actors that do not interact directly with the VM are the following: +The remaining nine (9) builtin System Actors that do not interact directly with the VM are the following: - `StorageMarketActor`: responsible for managing storage and retrieval deals [[Market Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/market_actor.go)] - `StorageMinerActor`: actor responsible to deal with storage mining operations and collect proofs [[Storage Miner Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/miner/miner_actor.go)] -- `MultisigActor` (or Multi-Signature Wallet Actor): responsible for dealing with operations involving the Filecoin wallet [[Multisig Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/multisig/multisig_actor.go)] +- `MultisigActor` (or Multi-Signature Wallet Actor): responsible for dealing with operations involving the Filecoin wallet. Since FIP-0062, includes a fallback handler for method numbers ≥ 2^24 to accept value transfers from EVM actors [[Multisig Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/multisig/multisig_actor.go)] - `PaymentChannelActor`: responsible for setting up and settling funds related to payment channels [[Paych Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/paych/paych_actor.go)] - `StoragePowerActor`: responsible for keeping track of the storage power allocated at each storage miner [[Storage Power Actor](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/power/power_actor.go)] -- `VerifiedRegistryActor`: responsible for managing verified clients [[Verifreg Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/verifreg/verified_registry_actor.go)] -- `SystemActor`: general system actor [[System Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/system/system_actor.go)] +- `VerifiedRegistryActor`: responsible for managing the Filecoin Plus program, including Root Key Holders (via multisig), Notaries, Filecoin Plus clients, and DataCap allocations. This actor enables the social trust layer that allows verified data to receive a 10x quality multiplier. Since FIP-0028, it also supports removing DataCap from client addresses through the `RemoveVerifiedClientDatacap` method [[Verifreg Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/verifreg/verified_registry_actor.go)] +- `SystemActor`: general system actor that, since FIP-0031, maintains a registry of built-in actor Code CIDs [[System Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/system/system_actor.go)] +- `EVMRuntimeActor`: responsible for executing Ethereum smart contracts within the Filecoin Virtual Machine. Since FIP-0054, this actor enables EVM compatibility by running EVM bytecode and managing contract state [[EVM Actor Repo](https://github.com/filecoin-project/builtin-actors/tree/master/actors/evm)] +- `EthereumAddressManagerActor` (EAM): singleton actor at f010 that manages the f410 address space for Ethereum addresses. Since FIP-0055, it acts as a factory for creating EVM contracts and Ethereum accounts [[EAM Actor Repo](https://github.com/filecoin-project/builtin-actors/tree/master/actors/eam)] ## CronActor @@ -42,8 +62,22 @@ Built in to the genesis state, the `CronActor`'s dispatch table invokes the `Sto ## InitActor + + The `InitActor` has the power to create new actors, e.g., those that enter the system. It maintains a table resolving a public key and temporary actor addresses to their canonical ID-addresses. Invalid CIDs should not get committed to the state tree. +Since FIP-0048, the InitActor also supports the `Exec4` method, which allows address managers to create new actors with specific f4 addresses. The Exec4 method: +- Computes the f4 address as `4{leb128(caller-actor-id)}{subaddress}` +- Creates a new actor with both an f2 (stable) address and the specified f4 address +- Stores both address mappings in the InitActor's address map +- Is currently restricted to "blessed" address managers + Note that the canonical ID address does not persist in case of chain re-organization. The actor address or public key survives chain re-organization. {{}} @@ -58,4 +92,34 @@ The `RewardActor` is where unminted Filecoin tokens are kept. The actor distribu The `AccountActor` is responsible for user accounts. Account actors are not created by the `InitActor`, but their constructor is called by the system. Account actors are created by sending a message to a public-key style address. The address must be `BLS` or `SECP`, or otherwise there should be an exit error. The account actor is updating the state tree with the new actor address. +Since FIP-0044, the AccountActor implements the `AuthenticateMessage` method, which provides a standard way for actors to authenticate data. This method validates that a given message has been properly authorized by the account through signature verification. This standard authentication interface enables: +- Other actors to verify account authorization without directly handling signatures +- A template for other actors (built-in and user-defined) to implement authentication +- Storage Market and Payment Channel actors to authenticate participants uniformly + +The AuthenticateMessage method accepts authorization data (typically a signature) and a message, returning true if the authentication is valid. + {{}} + +## EthereumAccountActor + +Since FIP-0055, the `EthereumAccountActor` represents Ethereum Externally-Owned Accounts (EOAs) backed by secp256k1 keys. This actor enables native Ethereum transaction support in Filecoin: + +- **Ethereum Compatibility**: Accepts native EIP-1559 Ethereum transactions with secp256k1 ECDSA signatures +- **Delegated Signatures**: Uses a new Delegated signature type that carries signatures verified by actor code +- **Address Management**: Associated with f410 addresses managed by the Ethereum Address Manager +- **Universal Methods**: Accepts all methods ≥ 2^24 (FRC-0042 minimum), preparing for future Account Abstraction + +The Ethereum Account actor serves as a bridge between Ethereum wallets and the Filecoin network, allowing existing Ethereum tools to interact seamlessly with Filecoin. + +## Special System Actors + +Some system actors have special properties or serve specific governance purposes: + +### Keyless Account Actors + +Keyless account actors are special actors that have no associated private keys and can only be modified through network upgrades. These actors ensure that certain critical network functions remain under decentralized governance control: + +- **f090 (Mining Reserve)**: Holds the 300,000,000 FIL mining reserve allocation. This actor is a keyless account that ensures the mining reserve can only be distributed through FIP proposals and network upgrades, preventing any individual or group from unilaterally accessing these funds. + +- **f099 (Burnt Funds Actor)**: A keyless account that accumulates all burnt FIL from network fees and penalties. These funds are permanently removed from circulation and cannot be accessed by any entity. diff --git a/spec/.gitignore b/spec/.gitignore new file mode 100644 index 000000000..531d76263 --- /dev/null +++ b/spec/.gitignore @@ -0,0 +1,5 @@ +# Claude settings +.claude/ + +# Agstruc workspace files +CLAUDE.MD \ No newline at end of file diff --git a/spec/content/algorithms/crypto/signatures.md b/spec/content/algorithms/crypto/signatures.md new file mode 100644 index 000000000..33b701fb4 --- /dev/null +++ b/spec/content/algorithms/crypto/signatures.md @@ -0,0 +1,229 @@ +--- +title: 'Signatures' +weight: 1 +dashboardWeight: 2 +dashboardState: wip +dashboardAudit: coming +dashboardTests: 0 +--- + + + +# Signatures + +Signatures are cryptographic functions that attest to the origin of a particular +message. In the context of Filecoin, signatures are used to send and receive +messages with the assurance that each message was generated by a specific +entity. In other words, it is infeasible for an entity i to +generate a signed message that appears to have been generated by j, with j != i. + +Filecoin uses signatures to associate an action to a given party. For +example, Filecoin uses signatures in order to validate deal messages which represent an +action like a storage deal. +Filecoin uses signatures to verify the authenticity of the following objects (non +exhaustive list): + +- Messages: Users authenticate their messages to the blockchain. +- Tickets: Miner authenticates its ticket (see [Storage Miner](filecoin_mining)). +- Blocks: Block leader signs over all data in the block. + +## Messages + +To generate a signature for the [Message](message) type, compute the signature over the message's CID (taken as a byte array). + +**Note**: for each specific use of a signature scheme, it is recommended to use a domain separation tag to treat the hash function as an independent random oracle. These tags are indicated in the relevant places throughout the specs. +Read more about this in [Randomness](randomness). + +## Signature Types + +Filecoin currently uses two types of signatures: + +- ECDSA signatures over the Secp256k1 elliptic curve to authenticate user + messages, mainly for compatibility with external blockchain systems. +- BLS signatures over the BLS12-381 group of curves + +Both signature types fulfill the `Signature` interface +and each type have additional functionality as explained below. + +{{}} + +### ECDSA Signatures + +Filecoin uses the ECDSA signature algorithm over the secp256k1 curve to +authenticate the blockchain messages. The main reason is to be able to +validate messages from other blockchain systems that uses secp256k1 (such as +Bitcoin or exchanges in general). ECDSA signatures offer an additional +useful functionality as well: to recover the public key from a given signature. +This feature can allow space to be saved on the blockchain by extracting the public +key locally from the signature rather than specifying an ID of the public key. + +{{}} + +**Wire Format**: Filecoin uses the standard secp256k1 signature serialization, +as described below. For more details on how the Filecoin `Signature` type is +serialized, see [Signature](signatures). + +```text +SignatureBytes = [0x30][len][0x02][r][indicator][s][indicator][recovery] +``` + +`s` = Scalar of size 32 bytes + +`r` = Compressed elliptic curve point (x-coordinate) of size 32 bytes + +`recovery` = Information needed to recover a public key from `sig`. + +- LSB(0) = parity of y-coordinate of r +- LSB(1) = overflow indicator + +`indicator` = a 2 byte formatting indicator + +**External References**: [Elliptic Curve Cryptography Paper](http://www.secg.org/sec1-v2.pdf) + +### BLS Signatures + +Filecoin uses the [BLS signature scheme](https://datatracker.ietf.org/doc/draft-boneh-bls-signature/) over the [BLS12-381](https://electriccoin.co/blog/new-snark-curve/) group of elliptic curves. You can find the default Rust implementation in [Filecoin's repo](https://github.com/filecoin-project/bls-signatures/). + +### Delegated Signatures (Ethereum Transactions) + + + +Filecoin supports Ethereum transactions through a delegated signature type. This allows Ethereum accounts (with f410f addresses) to send transactions on the Filecoin network. The delegated signature encapsulates the original Ethereum transaction signature and supports multiple Ethereum transaction types: + +1. **EIP-1559 Transactions**: Modern Ethereum transactions with separate base fee and priority fee (65-byte signatures) +2. **Homestead Transactions**: Legacy transactions without chain ID (66-byte signatures with 0x01 marker) +3. **EIP-155 Transactions**: Legacy transactions with chain ID replay protection (variable length signatures with 0x02 marker) + +The transaction type is determined by examining the signature length and marker byte: +- 65 bytes: EIP-1559 transaction +- 66 bytes starting with 0x01: Homestead transaction +- Variable length starting with 0x02: EIP-155 transaction + +For legacy transactions (Homestead and EIP-155), the `GasPrice` parameter is used for both `GasFeeCap` and `GasPremium` in the Filecoin message. + +{{}} +{{}} + +**Choice of group**: The BLS signature requires the use of a pairing-equipped +curve which generally yield three groups: G_1, G_2 and G_T. In the BLS signature +scheme, there is a choice on which group to define the public key and the +signature: + +- Public key is on G_1 and signature on G_2 +- Public key is on G_2 and signature on G_1 + +The group G_1 is "smaller" and hence offer faster arithmetic operations and +smaller byte representation of its elements. Filecoin currently uses the group +**G_1 for representing public keys** and the group **G_2 for representing +signatures**. + +**Wire Format**: Filecoin uses the standard way to serialize BLS signatures as +explained in the [RFC Section +2.6.1](https://tools.ietf.org/html/draft-boneh-bls-signature-00#section-2.6.1). + +**Rationale**: +BLS signatures have two main characteristics that are making them ideal +candidates in recent blockchain systems: + +- BLS signatures are deterministic: for a given message and a given secret key, + the signature is always the same. That feature removes an important security + weakness of most randomized signature schemes: signer must never re-use the + same randomness twice otherwise this reveals its private key. As well, + deterministic signatures are an ideal candidate to reduce the attack surface in + terms of grinding, which is a real concern in recent proof of stake systems. +- BLS signatures are aggregatable: one can aggregate signatures from different + signers into one single signature. This feature enables drastically saving + space on the blockchain, especially when aggregating user messages. + +**Aggregation Functionality**: The aggregation functionality is commutative and +associative, enabling _partial_ aggregation. For example, given +`(PK1, sig1), (PK2, sig2), (PK3, sig3)`, one can first aggregate `(PK12 = PK1 + PK2, sig12 = sig1 + sig2)` then aggregate with the third tuple to produce +`(PK123 = PK12 + PK3, sig123 = sig12 + sig3)`. + +**Aggregation Security**: The naive BLS signature aggregation scheme is +vulnerable to rogue-key attacks where the attacker can freely choose its public +key. To prevent against this class of attacks there exists three different kind +of measures, as explained [here](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html): + +- Enforce distinct messages +- Prove knowledge of the secret key +- Use a modified scheme (such as [BLS Multi Sig](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html)) + +Fortunately, Filecoin can enforce the first condition to safely use the +aggregation property: +Filecoin uses aggregation only for aggregating message signatures within a +single block. Since Filecoin uses the account model to represent the state of +the chain, each message for a given signer is used in combination with a nonce +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; +``` + +**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 diff --git a/spec/content/glossary/_index.md b/spec/content/glossary/_index.md new file mode 100644 index 000000000..f13d0440c --- /dev/null +++ b/spec/content/glossary/_index.md @@ -0,0 +1,504 @@ +--- +title: 'Glossary' +weight: 6 +dashboardWeight: 0.2 +dashboardState: reliable +dashboardAudit: n/a +--- + +# Glossary + +## Account Actor + +The [_Account Actor_](sysactors) is responsible for user accounts. + +## Actor + +The Actor is the Filecoin equivalent of the smart contract in Ethereum. + +An actor is an on-chain object with its own state and set of methods. An actor's state is persisted in the on-chain state tree, keyed by its address. All actors (miner actors, the storage market actor, account actors) have an address. Actor's methods are invoked by crafting messages and getting miners to include them in blocks. + +There eleven (11) builtin [System Actors](sysactors) in total in the Filecoin System. + +## Address + +An address is an identifier that refers to an actor in the Filecoin state. + +In the Filecoin network, an _address_ is a unique cryptographic value that serves to publicly identify a user. This value, which is a public key, is paired with a corresponding private key. The mathematical relationship between the two keys is such that access to the private key allows the creation of a signature that can be verified with the public key. Filecoin employs the Boneh–Lynn–Shacham (BLS) signature scheme for this purpose. + +## Ask + +An _ask_ contains the terms on which a miner is willing to provide services. Storage asks, for example, contain price and other terms under which a given storage miner is willing to lease its storage. The word comes from stock market usage, shortened from asking price. + +## Block + +In a blockchain, a [_block_](block) is the fundamental unit of record. Each block is cryptographically linked to one or more previous blocks. Blocks typically contain messages that apply changes to the previous state (for example, financial records) tracked by the blockchain. A block represents the state of the network at a given point in time. + +## Block Height + +The _height_ of a block corresponds to the number of epochs elapsed from genesis before the block was added to the blockchain. That said, `height` and `epoch` are synonymous. The height of the Filecoin blockchain is defined to be the maximum height of any block in the blockchain. + +## Block Reward + +The reward in [FIL](glossary#fil) given to [storage miners](glossary#storage-miner-actor) for contributing to the network with storage and proving that they have stored the files they have committed to store. The _Block Reward_ is allocated to the storage miners that mine blocks and extend the blockchain. As of FIP-0004, 25% of block rewards are immediately available for withdrawal, while 75% vest linearly over 180 days and serve as collateral. + +## Blockchain + +A [_blockchain_](filecoin_blockchain) is a system of record in which new records, or blocks are cryptographically linked to preceding records. This construction is a foundational component of secure, verifiable, and distributed transaction ledgers. + +## Bootstrapping + +Bootstrapping traditionally refers to the process of starting a network. In the context of the Filecoin network _bootstrapping_ refers to the process of onboarding a new Filecoin node in the Filecoin network and relates to connecting the new node to other peers, synchronizing the blockchain and "catching up" with the current state. + +## Capacity commitment + + + +If a storage miner doesn't find any available deal proposals appealing, they can alternatively make a _capacity commitment_, filling a sector with arbitrary data, rather than with client data. Maintaining this sector allows the storage miner to provably demonstrate that they are reserving space on behalf of the network. Also referred to as Committed Capacity (CC). Since FIP-0019, CC sectors can be updated with real data through Snap Deals without requiring a full re-sealing process. + +## Challenge Sampling + +An algorithm for challenge derivation used in [Proof of Replication](glossary#proof-of-replication-porep) or [Proof of SpaceTime](glossary#proof-of-spacetime-post). + +## CID + +[CID](multiformats#cids) is short for Content Identifier, a self describing content address used throughout the IPFS ecosystem. CIDs are used in Filecoin to identify files submitted to the decentralized storage network. For more detailed information, see [the github documentation for it](https://github.com/ipld/cid). + +## Client + +There are two types of [clients](filecoin_nodes#node_types) in Filecoin, the storage client and the retrieval client, both of which can be implemented as part of the same physical host. All clients have an account, which is used to pay for the storage or retrieval of data. + +## Collateral + +[Collateral](filecoin_mining#miner_collaterals) is Filecoin tokens pledged by an actor as a commitment to a promise. If the promise is respected, the collateral is returned. If the promise is broken, the collateral is not returned in full. + +In order to enter into a [storage deal](glossary#deal), a [storage miner](glossary#storage-miner-actor) is required to provide [FIL](glossary#fil) as _collateral_, to be paid out as compensation to a client in the event that the miner fails to uphold their storage commitment. + +## Consensus + +The algorithm(s) and logic needed so that the state of the blockchain is agreed across all nodes in the network. + +## Consensus Fault Slashing + +Consensus Fault Slashing is the penalty that a miner incurs for committing consensus faults. This penalty is applied to miners that have acted maliciously against the network's consensus functionality. + +## Cron Actor + +The [_Cron Actor_](sysactors) is a scheduler actor that runs critical functions at every epoch. + +## DataCap + +DataCap is a credit allocated by Notaries to Filecoin Plus clients. When a client makes a storage deal and identifies it as a Filecoin Plus verified deal, the DataCap is consumed and the miner receives a 10x deal quality multiplier for that deal, resulting in increased storage power and block rewards. As of FIP-0012, clients can receive multiple DataCap allocations to the same address, with new allocations adding to their existing balance. + +## Deal + +Two participants in the Filecoin network can enter into a [_deal_](storage_market#deal-flow) in which one party contracts the services of the other for a given price agreed between the two. The Filecoin specification currently details _storage deals_ (in which one party agrees to store data for the other for a specified length of time) and _retrieval deals_ (in which one party agrees to transmit specified data to the other). + +## Deal Quality Multiplier + +This factor is assigned to different deal types (committed capacity, regular deals, and Filecoin Plus verified deals) to reward different content. + +## Deal Weight + +This weight converts spacetime occupied by deals into consensus power. Deal weight of Filecoin Plus verified deals in a sector is called Verified Deal Weight and will be greater than the regular deal weight. + +## DRAND + +[DRAND](drand), short for Distributed Randomness, is a publicly verifiable random beacon protocol that Filecoin uses as a source of unbiasable entropy for [leader election](glossary#leader-election). See the [DRAND website](https://drand.love/) for more details. + +## Election + +On every [epoch](glossary#epoch), a small subset of Filecoin [storage miners](glossary#storage-miner-actor) are _elected_ to mine a new, or a few new [block(s)](glossary#block) for the Filecoin blockchain. A miner's probability of being elected is roughly proportional to the share of the Filecoin network's total storage capacity they contribute. Election in Filecoin is realized through [Expected Consensus](expected_consensus). + +## Election Proof + +Election Proof is used as a source of randomness in EC leader election. The election proof is created by calling [VRF](glossary#vrf) and giving the secret key of the miner's worker and the DRAND value of the current epoch as input. + +## EIP-155 Transaction + +An EIP-155 transaction is a legacy Ethereum transaction type that includes chain ID replay protection by encoding the chain ID in the V parameter of the signature. This prevents transactions from being replayed on different chains. In Filecoin, EIP-155 transactions are identified by a variable-length signature starting with a 0x02 marker byte. + + + +## Epoch + +Time in the Filecoin blockchain is discretized into _epochs_ that are currently set to thirty (30) seconds in duration. On every epoch, a subset of storage miners are elected to each add a new block to the Filecoin blockchain via [Winning Proof-of-Spacetime](glossary#winning-proof-of-spacetime-winningpost). Also referred to as [Round](glossary#round). + +## Fault + +A fault occurs when a proof is not posted in the Filecoin system within the proving period, denoting another malfunction such as loss of network connectivity, storage malfunction, or malicious behaviour. + +When a [storage miner](glossary#storage-miner-actor) fails to complete [Window Proof-of-Spacetime](glossary#window-proof-of-spacetime-windowpost) for a given sector, the Filecoin network registers a _fault_ for that sector, and the miner is [_slashed_](glossary#slashing). If a storage miner does not resolve the fault quickly, the network assumes they have abandoned their commitment. + +## FIL + +_FIL_ is the name of the Filecoin unit of currency; it is alternatively denoted by the Unicode symbol for an integral with a double stroke (⨎). + +## File + +[Files](file) are what clients bring to the filecoin system to store. A file is converted to a UnixFS DAG and is placed in a [piece](glossary#piece). A piece is the basic unit of account in the storage network and is what is actually stored by the Filecoin network. + +## Filecoin + +The term _Filecoin_ is used generically to refer to the Filecoin project, protocol, and network. + +## Filecoin Plus + +Filecoin Plus is a program (previously called Verified Clients) that aims to maximize the amount of useful storage on Filecoin by adding a layer of social trust. The program allows clients to make verified deals that carry a 10x deal quality multiplier, incentivizing miners to store real, valuable data. The program is governed by Root Key Holders who appoint Notaries, who in turn allocate DataCap to clients. + +## Finality + +[Finality](expected_consensus#finality-in-ec) is a well known concept in blockchain environments and refers to the amount of time needed until having a reasonable guarantee that a message cannot be reversed or cancelled. It is measured in terms of delay, normally in epochs or rounds from the point when a message has been included in a block published on-chain. + +## `fr32` + +The term `fr32` is derived from the name of a struct that Filecoin uses to represent the elements of the arithmetic field of a pairing-friendly curve, specifically Bls12-381—which justifies use of 32 bytes. `F` stands for "Field", while `r` is simply a mathematic letter-as-variable substitution used to denote the modulus of this particular field. + +## Gas, Gas Fees + +_Gas_ is a property of a [message](glossary#message), corresponding to the resources involved in including that message in a given [block](glossary#block). For each message included in a block, the block's creator (i.e., miner) charges a fee to the message's sender. + +## Genesis Block + +The _genesis block_ is the first block of the Filecoin blockchain. As is the case with every blockchain, the genesis block is the foundation of the blockchain. The tree of any block mined in the future should link back to the genesis block. + +## GHOST + +[GHOST](https://eprint.iacr.org/2013/881.pdf) is an acronym for `Greedy Heaviest Observable SubTree`, a class of blockchain structures in which multiple blocks can validly be included in the chain at any given height or round. GHOSTy protocols produce blockDAGs rather than blockchains and use a weighting function for fork selection, rather than simply picking the longest chain. + +## Height + +Same as Block Height. + +## Homestead Transaction + +A Homestead transaction is a legacy Ethereum transaction type that does not include a chain ID parameter. These transactions can be replayed across different chains, making them useful for deploying contracts at the same address on multiple networks. In Filecoin, Homestead transactions are identified by a 66-byte signature with a 0x01 marker byte. + + + +## Init Actor + +The [_Init Actor_](sysactors) initializes new actors and records the network name. + +## Lane + +[_Lanes_](payment_channels#lanes) are used to split Filecoin Payment Channels as a way to update the channel state (e.g., for different services exchanged between the same end-points/users). The channel state is updated using [vouchers](glossary#voucher) with every lane marked with an associated `nonce` and amount of tokens it can be redeemed for. + +## Leader + +A leader, in the context of Filecoin consensus, is a node that is chosen to propose the next block in the blockchain during [Leader Electioni](glossary#leader-election). + +## Leader election + +Same as [Election](glossary#election). + +## Message + +A message is a call to an actor in the Filecoin VM. The term _message_ is used to refer to data stored as part of a [block](glossary#block). A block can contain several messages. + +## Miner + + + +A miner is an actor in the Filecoin system performing a service in the network for a reward. Note: Following FIP-0018, the term "Storage Provider" is preferred in marketing and communications materials, though "miner" remains in technical contexts. + +There are three types of miners in Filecoin: + +- [Storage miners](glossary#storage-miner-actor) (Storage Providers), who store files on behalf of clients. +- [Retrieval miners](glossary#retrieval-miner) (Retrieval Providers), who deliver stored files to clients. +- Repair miners, who replicate files to keep them available in the network, when a storage miner presents a fault. + +## Multisig Actor + +The [_Multisig Actor_](sysactors) (or Multi-Signature Wallet Actor) is responsible for dealing with operations involving the Filecoin wallet. + +## Node + +A [node](filecoin_nodes) is a communication endpoint that implements the Filecoin protocol. + +## On-chain/off-chain + +On-chain actions are those that change the state of the tree and the blockchain and interact with the Filecoin VM. Off-chain actions are those that do not interact with the Filecoin VM. + +## Payment Channel + +A [_payment channel_](filecoin_token#payment_channels) is set up between actors in the Filecoin system to enable off-chain payments with on-chain guarantees, making settlement more efficient. Payment channels are managed by the Payment Channel Actor, who is responsible for setting up and settling funds related to payment channels. + +## Piece + +The [Piece](piece) is the main unit of account and negotiation for the data that a user wants to store on Filecoin. In the Lotus implementation, a piece is a [CAR file](https://github.com/ipld/specs/blob/master/block-layer/content-addressable-archives.md#summary) produced by an IPLD DAG with its own _payload CID_ and _piece CID_. However, a piece can be produced in different ways as long as the outcome matches the _piece CID_. A piece is not a unit of storage and therefore, it can be of any size up to the size of a [sector](glossary#sector). If a piece is larger than a sector (currently set to 32GB or 64GB and chosen by the miner), then it has to be split in two (or more) pieces. For more details on the exact sizing of a Filecoin Piece as well as how it can be produced, see the [Piece section](piece). + +## Pledged Storage + +Storage capacity (in terms of [sectors](glossary#sector))that a miner has promised to reserve for the Filecoin network via [Proof-of-Replication](glossary#proof-of-replication-porep) is termed _pledged storage_. + +## Power + +See [Power Fraction](glossary#power-fraction). + +## Power Fraction + +A storage miner's `Power Fraction` or `Power` is the ratio of their committed storage, as of their last PoSt submission, over Filecoin's total committed storage as of the current block. It is used in [Leader Election](glossary#leader-election). It is the proportion of power that a storage miner has in the system as a fraction of the overall power of all miners. + +## Power Table + +The Power Table is an abstraction provided by the Filecoin storage market that lists the `power` of every [storage miner](glossary#storage-miner-actor) in the system. + +## Protocol + +Commonly refers to the "Filecoin Protocol". + +## Proving Period + +Commonly referred to as the "duration of a PoSt", the _proving period_ is the period of time during which storage miners must compute Proofs of Spacetime. By the end of the period they must have submitted their PoSt. + +## Proving Set + +The elements used as input by a proof of Spacetime to enable a proof to be generated. + +## Proof of Replication (PoRep) + +[_Proof-of-Replication_](pos#porep) is a procedure by which a [storage miner](glossary#storage-miner-actor) can prove to the Filecoin network that they have created a unique copy of some piece of data on the network's behalf. PoRep is used in the Filecoin system to generate sealed sectors through which storage miners prove they hold client data. + +## Proof of Spacetime (PoSt) + +[_Proof-of-Spacetime_](pos#post) is a procedure by which a [storage-miner](glossary#storage-miner-actor) can prove to the Filecoin network they have stored and continue to store a unique copy of some data on behalf of the network for a period of time. Proof-of-Spacetime manifests in two distinct varieties in the present Filecoin specification: [Window Proof-of-Spacetime](glossary#window-proof-of-spacetime-windowpost) and [Winning Proof-of-Spacetime](glossary#winning-proof-of-spacetime-winningpost). + +## Quality-Adjusted Power + +This parameter measures the consensus power of stored data on the network, and is equal to [Raw Byte Power](glossary#raw-byte-power) multiplied by [Sector Quality Multiplier](glossary#sector-quality-multiplier). + +## Randomness + +Randomness is used in Filecoin in order to generate random values for electing the next leader and prevent malicious actors from predicting future and gaining advantage over the system. Random values are drawn from a [DRAND](glossary#drand) beacon and appropriately formatted for usage. + +## Randomness Ticket + +See Ticket. + +## Raw Byte Power + +This measurement is the size of a sector in bytes. + +## Retrieval miner + + + +A [_retrieval miner_](retrieval_market#retrieval_provider) is a Filecoin participant that enters in retrieval [deals](glossary#deal) with clients, agreeing to supply a client with a particular file in exchange for [FIL](glossary#fil). Note that unlike [storage miners](glossary#storage-miner-actor), retrieval miners are not additionally rewarded with the ability to add blocks to (i.e., extend) the Filecoin blockchain; their only reward is the fee they extract from the client. Following FIP-0018, retrieval miners are also referred to as "Retrieval Providers" in marketing and communications. + +## Repair + +Repair refers to the processes and protocols by which the Filecoin network ensures that data that is partially lost (by, for example, a miner disappearing) can be re-constructed and re-added to the network. Repairing is done by [Repair Miners](glossary#miner). + +## Reward Actor + +The [_Reward Actor_](sysactors) is responsible for distributing block rewards to [storage miners](glossary#storage-miner-actor) and token vesting. + +## Round + +A Round is synonymous to the [epoch](glossary#epoch) and is the time period during which new blocks are mined to extend the blockchain. The duration is of a round is set to 30 sec. + +## Seal + +Sealing is a cryptographic operation that transforms a sector packed with deals into a certified replica associated with: i) a particular miner’s cryptographic identity, ii) the sector's own identity. + +_Sealing_ is one of the fundamental building blocks of the Filecoin protocol. It is a computation-intensive process performed over a [sector](glossary#sector) that results in a unique representation of the sector as it is produced by a specific miner. The properties of this new representation are essential to the [Proof-of-Replication](glossary#proof-of-replication-porep) and the [Proof-of-Spacetime](glossary#proof-of-spacetime-post) procedures. + +## Sector + +The [sector](sector) is the default unit of storage that miners put in the network (currently 32GBs or 64GBs). A sector is a contiguous array of bytes that a [storage miner](glossary#storage-miner-actor) puts together, seals, and performs Proofs of Spacetime on. Storage miners store data on behalf of the Filecoin network in fixed-size sectors. + +Sectors can contain data from multiple deals and multiple clients. Sectors are also split in “Regular Sectors”, i.e., those that contain deals and “Committed Capacity” (CC), i.e., the sectors/storage that have been made available to the system, but for which a deal has not been agreed yet. + +## Sector Quality Multiplier + +Sector quality is assigned on Activation (the epoch when the miner starts proving theyʼre storing the file). The sector quality multiplier is computed as an average of deal quality multipliers (committed capacity, regular deals, and Filecoin Plus verified deals), weighted by the amount of spacetime each type of deal occupies in the sector. + +## Sector Spacetime + +This measurement is the sector size multiplied by its promised duration in byte-epochs. + +## Slashing + +Filecoin implements two kinds of slashing: [**Storage Fault Slashing**](glossary#storage-fault-slashing) and [**Consensus Fault Slashing**](glossary#consensus-fault-slashing). + +## Snap Deals + + + +Snap Deals is a protocol introduced in FIP-0019 that allows storage providers to update existing Committed Capacity (CC) sectors with real data without re-sealing. The provider embeds deal data into an existing sector replica through an encoding process using unpredictable randomness, then generates a single proof message (`ProveReplicaUpdates`) that demonstrates the sector was correctly updated. This significantly reduces the cost and time required to convert CC sectors to sectors containing real data, enabling providers to quickly onboard client data into their existing committed capacity. + +## Smart contracts + +In the Filecoin blockchain smart contracts are referred to as [actors](glossary#actor). + +## State + +The _State_ or [_State Tree_](state_tree) refers to the shared history of the Filecoin system which contains actors and their storage power. The _State_ is deterministically generated from the initial state and the set of messages generated by the system. + +## Storage Market Actor + +The [_Storage Market Actor_](sysactors) is responsible for managing storage and retrieval deals. + +## Storage Miner Actor + + + +The [_Storage Miner Actor_](sysactors) commits storage to the network, stores data on behalf of the network and is rewarded in [FIL](glossary#fil) for the storage service. The storage miner actor is responsible for collecting proofs and reaching consensus on the latest state of the storage network. When they create a block, storage miners are rewarded with newly minted FIL, as well as the message fees they can levy on other participants seeking to include messages in the block. Note: Following FIP-0018, storage miners are also referred to as "Storage Providers" in marketing and communications. + +## Storage Power Actor + +The [_Storage Power Actor_](sysactors) is responsible for keeping track of the storage power allocated at each storage miner. + +## Storage Provider + + + +Storage Provider (SP) is the preferred terminology for [storage miners](glossary#storage-miner-actor) in marketing and communications materials as of FIP-0018. This terminology better represents the service-oriented nature of entities that provide storage infrastructure and services to the Filecoin network. The technical implementation continues to use the term "storage miner" in code and protocol specifications. + +## Storage Fault Slashing + +Storage Fault Slashing is a term that is used to encompass a broader set of penalties, including (but not limited to) Fault Fees, Sector Penalties, and Termination Fees. These penalties are to be paid by miners if they fail to provide sector reliability or decide to voluntarily exit the network. + +- **Fault Fee (FF):** A penalty that a miner incurs for each day a miner's sector is offline. +- **Sector Penalty (SP):** A penalty that a miner incurs for a faulted sector that was not declared faulted before a WindowPoSt check occurs. + - The sector will pay FF after incurring an SP when the fault is detected. +- **Termination Penalty (TP):** A penalty that a miner incurs when a sector is voluntarily or involuntarily terminated and is removed from the network. + +## Ticket or VRF Chain + +Tickets are generated as in [Election Proof](glossary#election-proof), but the input of every ticket includes the concatenation of the previous ticket, hence the term chain. This means that the new ticket is generated by running the VRF on the old ticket concatenated with the new DRAND value (and the key as with the Election Proof). + +## Tipset + + + +A [tipset](https://filecoin.io/blog/tipsets-family-based-approach-to-consensus/) is a set of [blocks](glossary#block) that each have the same [height](glossary#block-height) and parent tipset; the Filecoin [blockchain](glossary#blockchain) is a chain of tipsets, rather than a chain of blocks. + +Each tipset is assigned a weight corresponding to the amount of storage the network is provided per the commitments encoded in the tipset's blocks. The consensus protocol of the network directs nodes to build on top of the heaviest chain. When selecting between tipsets of equal weight, nodes choose the one with the smallest winning [ElectionProof](glossary#election-proof) ticket. + +By basing its blockchain on tipsets, Filecoin can allow multiple [storage miners](glossary#storage-miner-actor) to create blocks in the same [epoch](glossary#epoch), increasing network throughput. By construction, this also provides network security: a node that attempts to intentionally prevent the valid blocks of a second node from making it onto the canonical chain runs up against the consensus preference for heavier chains. + +## Filecoin Plus Client + +To further incentivize the storage of "useful" data over simple [capacity commitments](glossary#capacity-commitment), [storage miners](glossary#storage-miner-actor) have the additional opportunity to compete for special [deals](glossary#deal) offered by Filecoin Plus clients. Such clients are certified by Notaries with respect to their intent to offer deals involving the storage of meaningful data, and the power a storage miner earns for these deals is augmented by a 10x multiplier. + +## Notary + +Notaries are selected to act as fiduciaries for the Filecoin network in the Filecoin Plus program. They are entrusted with DataCap to allocate to clients in order to subsidize reliable and useful storage on the network. Notaries verify that clients receive a DataCap allocation commensurate with the level of trust that is warranted based on information provided. + +## Root Key Holder + +Root Key Holders are signers to a multisig on chain with the power to grant and remove Notaries in the Filecoin Plus program. They act as executors for decisions made by the community governance on-chain. The role of the Root Key Holder is not to make subjective decisions, but rather to execute community decisions transparently. + +## Verified Registry Actor + +The [_Verified Registry Actor_](sysactors) is responsible for managing [Filecoin Plus clients](glossary#filecoin-plus-client), Notaries, and DataCap allocations. + +## VDF + +A Verifiable Delay Function that guarantees a random delay given some hardware assumptions and a small set of requirements. These requirements are efficient proof verification, random output, and strong sequentiality. Verifiable delay functions are formally defined by [BBBF](https://eprint.iacr.org/2018/601). + +```text +{proof, value} <-- VDF(public parameters, seed) +``` + +## (Filecoin) Virtual Machine (VM) + +The [Filecoin VM](actor) refers to the system by which changes are applied to the Filecoin system's state. The VM takes messages as input, and outputs updated state. The four main Actors interact with the Filecoin VM to update the state. These are: the `InitActor`, the `CronActor`, the `AccountActor` and the `RewardActor`. + +## Voucher + +[Vouchers](payment_channels#vouchers) are used as part of the Payment Channel Actor. Vouchers are signed messages exchanged between the channel creator and the channel recipient to acknowledge that a part of the service has been completed. Vouchers are the realisation of micropayments or checkpoints ini a payment channel. Vouchers are submitted to the blockchain and when `Collected`, funds are moved from the channel creator's account to the channel recipient's account. + +## VRF + +A Verifiable Random Function (VRF) that receives {Secret Key (SK), seed} and outputs {proof of correctness, output value}. VRFs must yield a proof of correctness and a unique & efficiently verifiable output. + +```text +{proof, value} <-- VRF(SK, seed) +``` + +## Weight + +Every mined block has a computed `weight`, also called its `WinCount`. Together, the `weights` of all the blocks in a branch of the chain determines the cumulative `weight` of that branch. Filecoin's Expected Consensus is a GHOSTy or heaviest-chain protocol, where chain selection is done on the basis of an explicit weighting function. Filecoin’s `weight` function currently seeks to incentivize collaboration amongst miners as well as the addition of storage to the network. The specific weighting function is defined in [Chain Weighting](expected_consensus#chain-weighting). + +## Window Proof-of-Spacetime (WindowPoSt) + +[_Window Proof-of-Spacetime_ (WindowPoSt)](post#windowpost) is the mechanism by which the commitments made by [storage miners](glossary#storage-miner-actor) are audited. It sees each 24-hour period broken down into a series of windows. Correspondingly, each storage miner's set of pledged [sectors](glossary#sector) is partitioned into subsets, one subset for each window. Within a given window, each storage miner must submit a [Proof-of-Spacetime](glossary#proof-of-spacetime-post) for each sector in their respective subset. This requires ready access to each of the challenged sectors, and will result in a [zk-SNARK-compressed](glossary#zksnark) proof published to the Filecoin [blockchain](glossary#blockchain) as a [message](glossary#message) in a [block](glossary#block). In this way, every sector of [pledged storage](glossary#pledged-storage) is audited at least once in any 24-hour period, and a permanent, verifiable, and public record attesting to each storage miner's continued commitment is kept. + +The Filecoin network expects constant availability of stored data. Failing to submit WindowPoSt for a sector will result in a [fault](glossary#fault), and the storage miner supplying the sector will be [slashed](glossary#slashing). + +## Winning Proof-of-Spacetime (WinningPoSt) + +[_Winning Proof-of-Spacetime_ (WinningPoSt)](post#winningpost) is the mechanism by which [storage miners](glossary#storage-miner-actor) are rewarded for their contributions to the Filecoin network. At the beginning of each [epoch](glossary#epoch), a small number of storage miners are [elected](glossary#election) to each mine a new [block](glossary#block). As a requirement for doing so, each miner is tasked with submitting a compressed [Proof-of-Spacetime](glossary#proof-of-spacetime-post) for a specified [sector](glossary#sector). Each elected miner who successfully creates a block is granted [FIL](glossary#fil), as well as the opportunity to charge other Filecoin participants fees to include [messages](glossary#message) in the block. + +Storage miners who fail to do this in the necessary window will forfeit their opportunity to mine a block, but will not otherwise incur penalties for their failure to do so. + +## zk-SNARK + +zk-SNARK stands for Zero-Knowledge Succinct Non-Interactive Argument of Knowledge. + +An _argument of knowledge_ is a construction by which one party, called the _prover_, can convince another, the _verifier_, that the prover has access to some piece of information. There are several possible constraints on such constructions: + +- A _non-interactive_ argument of knowledge has the requirement that just a single message, sent from the prover to the verifier, should serve as a sufficient argument. + +A _zero-knowledge_ argument of knowledge has the requirement that the verifier should not need access to the knowledge the prover has access to in order to verify the prover's claim. + +A _succinct_ argument of knowledge is one that can be "quickly" verified, and which is "small", for appropriate definitions of both of those terms. + +A Zero-Knowledge Succinct Non-Interactive Argument of Knowledge (zk-SNARK) embodies all of these properties. Filecoin utilizes these constructions to enable its distributed network to efficiently verify that [storage miners](glossary#storage-miner-actor) are storing files they pledged to store, without requiring the verifiers to maintain copies of these files themselves. + +In summary, Filecoin uses zk-SNARKs to produce a small 'proof' that convinces a 'verifier' that some computation on a stored file was done correctly, without the verifier needing to have access to the stored file itself.