From a8dea779ed446aa0015234eb33358ae42a3fe889 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 17:53:29 +1000 Subject: [PATCH 01/57] Update Filecoin specification to align with FIP-0003 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to reflect the rebranding and clarifications introduced by FIP-0003 (Filecoin Plus Principles). Changes include: - Updated terminology from "Verified Clients" to "Filecoin Plus" throughout - Added comprehensive documentation of Filecoin Plus roles (Root Key Holders, Notaries, and Filecoin Plus Clients) and their responsibilities - Updated all references to "verified client deals" to "Filecoin Plus deals" - Enhanced the VerifiedRegistryActor description to include its role in managing the Filecoin Plus program - Added governance structure documentation with the four layers: Principles, Mechanisms, Operations, and Markets These updates ensure the specification accurately reflects the current implementation of the Filecoin Plus program as defined in FIP-0003. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/cryptoecon/_index.md | 2 +- content/algorithms/verified_clients/_index.md | 33 ++++++++++++++++--- content/glossary/_index.md | 28 ++++++++++++---- .../storage_power_consensus/_index.md | 4 +-- .../systems/filecoin_mining/sector/_index.md | 4 +-- .../filecoin_mining/sector/adding_storage.md | 2 +- .../filecoin_mining/sector/lifecycle.md | 2 +- .../sector/sector-quality/_index.md | 10 +++--- .../systems/filecoin_vm/sysactors/_index.md | 2 +- 9 files changed, 63 insertions(+), 24 deletions(-) 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/verified_clients/_index.md b/content/algorithms/verified_clients/_index.md index 473ff7dbf..d2de8b984 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,33 @@ 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. Filecoin Plus clients can request increased DataCap once they have used their full allocation, with Notaries performing due diligence to ensure clients are not maliciously exploiting the system. + +### 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. + +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/glossary/_index.md b/content/glossary/_index.md index ab7e7ef2f..1ec5da9c7 100644 --- a/content/glossary/_index.md +++ b/content/glossary/_index.md @@ -84,17 +84,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 one-time 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. + ## 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 @@ -130,6 +134,10 @@ _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. @@ -286,7 +294,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 @@ -337,13 +345,21 @@ Each tipset is assigned a weight corresponding to the amount of storage the netw 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/systems/filecoin_blockchain/storage_power_consensus/_index.md b/content/systems/filecoin_blockchain/storage_power_consensus/_index.md index 6f3ddbad7..5cb48c4eb 100644 --- a/content/systems/filecoin_blockchain/storage_power_consensus/_index.md +++ b/content/systems/filecoin_blockchain/storage_power_consensus/_index.md @@ -35,11 +35,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. 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..8027a8ee9 100644 --- a/content/systems/filecoin_mining/sector/adding_storage.md +++ b/content/systems/filecoin_mining/sector/adding_storage.md @@ -36,6 +36,6 @@ 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. diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index f1e346019..6d7e33d87 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -13,7 +13,7 @@ Once the sector has been generated and the deal has been incorporated into the F 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. 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_. diff --git a/content/systems/filecoin_mining/sector/sector-quality/_index.md b/content/systems/filecoin_mining/sector/sector-quality/_index.md index f1be2c0fc..e0d9574b0 100644 --- a/content/systems/filecoin_mining/sector/sector-quality/_index.md +++ b/content/systems/filecoin_mining/sector/sector-quality/_index.md @@ -13,10 +13,10 @@ math-mode: true 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 +27,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 +37,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: diff --git a/content/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index c4e4162dc..d03b1e34e 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -31,7 +31,7 @@ The remaining seven (7) builtin System Actors that do not interact directly with - `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)] - `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)] +- `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 [[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)] ## CronActor From 18978dc1e93a968cadca21e1ee00f7e0b98a6d33 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 18:11:30 +1000 Subject: [PATCH 02/57] Update Filecoin specification to align with FIP-0004 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to reflect the liquidity improvements for storage miners introduced by FIP-0004. Changes include: - Updated Block Reward Collateral section to specify that 25% of block rewards are immediately available for withdrawal - Clarified that 75% of block rewards vest linearly over 180 days and serve as collateral - Added explanation that only the vested portion (75%) is added to pledgeDeltaTotal - Updated glossary definition of Block Reward to include the vesting split - Added YAML history metadata showing this change was introduced by FIP-0004 These updates ensure the specification accurately reflects the improved liquidity mechanism that helps miners with cash flow while maintaining alignment with long-term network incentives. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/glossary/_index.md | 2 +- .../systems/filecoin_mining/miner_collaterals.md | 14 +++++++++++++- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/content/glossary/_index.md b/content/glossary/_index.md index 1ec5da9c7..0d0cb01bc 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 diff --git a/content/systems/filecoin_mining/miner_collaterals.md b/content/systems/filecoin_mining/miner_collaterals.md index 4f55fab47..f0b128aad 100644 --- a/content/systems/filecoin_mining/miner_collaterals.md +++ b/content/systems/filecoin_mining/miner_collaterals.md @@ -46,11 +46,23 @@ $SectorInitialConsensusPledge = 30\% \times FILCirculatingSupply \times \frac{Se ## 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. 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. From 139a4ca5e11bdd2dfae8c367a98a2db0ce6de3f3 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 18:24:46 +1000 Subject: [PATCH 03/57] Update Filecoin specification to align with FIP-0005 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to reflect the gas optimization for reward vesting introduced by FIP-0005. Changes include: - Added explanation that vesting is processed only through the miner's deadline cron handler (every 30 minutes) and WithdrawBalance calls - Clarified that the vesting table is quantized to 12-hour increments - Added note that miners can manually trigger vesting by calling WithdrawBalance with zero amount using the Owner address - Updated YAML history metadata to document the removal of vesting processing from PreCommitSector and ConfirmSectorProofsValid These updates ensure the specification accurately reflects the gas-efficient vesting mechanism that reduces chain bandwidth consumption and costs. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_mining/miner_collaterals.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/content/systems/filecoin_mining/miner_collaterals.md b/content/systems/filecoin_mining/miner_collaterals.md index f0b128aad..79a06c60b 100644 --- a/content/systems/filecoin_mining/miner_collaterals.md +++ b/content/systems/filecoin_mining/miner_collaterals.md @@ -52,6 +52,9 @@ changes: - fip: FIP-0004 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0004.md description: Introduced 25% immediate liquidity for block rewards, with 75% vesting over 180 days. + - fip: FIP-0005 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0005.md + description: Removed vesting processing from PreCommitSector and ConfirmSectorProofsValid, leaving it to deadline cron and WithdrawBalance calls. --> 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. @@ -64,6 +67,8 @@ However, the protocol should provide liquidity for miners to support their minin 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. ## Storage Deal Collateral From 94d542b84ccf3fb67be9a0cd15002f59ca18f86a Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 18:32:26 +1000 Subject: [PATCH 04/57] Update Filecoin specification to align with FIP-0007 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to document the HAMT and AMT v3 improvements introduced by FIP-0007. Changes include: - Expanded HAMT section in data structures appendix to document v3 optimizations: dirty node tracking, persistent caching, deferred writes, and efficient pointer serialization - Added new AMT (Array Mapped Trie) section documenting the data structure and its v3 optimizations - Updated State Tree documentation to specify it uses HAMT v3 - Added YAML history metadata for both HAMT and AMT showing FIP-0007 introduced the v3 optimizations These updates ensure the specification accurately reflects the performance improvements that reduce gas costs and improve efficiency of state operations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/appendix/data_structures.md | 53 ++++++++++++++++++- .../systems/filecoin_vm/state_tree/_index.md | 4 +- 2 files changed, 54 insertions(+), 3 deletions(-) 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/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. {{}} From eb1c8b1bf7ee184b730dfcf21e69a843d71b0d8c Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:06:13 +1000 Subject: [PATCH 05/57] Update Filecoin specification to align with FIP-0008 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to document the batch pre-commit functionality introduced by FIP-0008. Changes include: - Added batch size limit (256 sectors) to the lifecycle state table - Created new "Batch Operations" section documenting PreCommitSectorBatch - Detailed the gas optimization benefits of batching: single state loads, batch sector number allocation, and unified market verification - Explained the economic benefits for high-growth miners - Added YAML history metadata showing FIP-0008 introduced this functionality These updates ensure the specification accurately reflects the batch pre-commit method that significantly reduces gas costs and chain congestion. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_mining/sector/lifecycle.md | 23 ++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index 6d7e33d87..6342a62cf 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -9,6 +9,14 @@ 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. @@ -25,9 +33,22 @@ A sector can be in one of the following states. | State | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Precommitted` | Miner seals sector and submits `miner.PreCommitSector` or `miner.PreCommitSectorBatch` | +| `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.ProveCommitAggregate` | | `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. From 878c3720736a2a66e82b8b1910f89ebfd441a8a6 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:16:09 +1000 Subject: [PATCH 06/57] Update Filecoin specification to align with FIP-0010 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to document the off-chain Window PoSt verification mechanism introduced by FIP-0010. Changes include: - Added YAML history metadata to WindowPoSt section documenting FIP-0010 - Created new "Off-chain Verification and Dispute Mechanism" section - Documented optimistic acceptance of proofs without on-chain verification - Detailed the dispute window (1800 epochs) and DisputeWindowedPoSt method - Explained penalties for invalid proofs (5.51x block reward + 20 FIL) - Documented dispute rewards (4 FIL) and restrictions during dispute window - Clarified that proofs recovering faulty sectors are still verified on-chain These updates ensure the specification accurately reflects the significant gas and bandwidth savings (~13%) achieved through off-chain verification. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/pos/post.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/content/algorithms/pos/post.md b/content/algorithms/pos/post.md index 6102f4c94..86f6ed25d 100644 --- a/content/algorithms/pos/post.md +++ b/content/algorithms/pos/post.md @@ -38,6 +38,14 @@ 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 +93,27 @@ 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. From e4895290dd05ba77e4dfbad155373ab09c26ab90 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:19:36 +1000 Subject: [PATCH 07/57] Update Filecoin specification to align with FIP-0011 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to reflect the removal of the Dutch auction mechanism for consensus fault reporting introduced by FIP-0011. Changes include: - Added YAML history metadata to Detection and Reporting section - Removed references to the Dutch auction mechanism with exponentially increasing rewards over time - Documented the fixed reward of BlockReward/4 for reporting consensus faults - Removed obsolete references to SLASHER_INITIAL_SHARE and SLASHER_SHARE_GROWTH_RATE parameters - Clarified that the fixed reward incentivizes immediate reporting These updates ensure the specification accurately reflects the simplified reward mechanism that encourages prompt reporting of consensus faults. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/expected_consensus/_index.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/content/algorithms/expected_consensus/_index.md b/content/algorithms/expected_consensus/_index.md index 78997d59f..24aa4a1c6 100644 --- a/content/algorithms/expected_consensus/_index.md +++ b/content/algorithms/expected_consensus/_index.md @@ -402,6 +402,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. + -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. +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. + +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. From 1fc6df1108928389a0d26283a1713ee3d9e93c2e Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:26:22 +1000 Subject: [PATCH 08/57] Update Filecoin specification to align with FIP-0012 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the Filecoin specification to reflect the DataCap top-up functionality introduced by FIP-0012. Changes include: - Updated Notaries section to document that clients can receive DataCap top-ups to the same address without full depletion - Clarified that new allocations are added to existing DataCap balance - Removed "one-time" designation from DataCap glossary entry - Added note that Notaries should check existing allocations before approving additional DataCap - Added YAML history metadata documenting FIP-0012's contribution These updates ensure the specification accurately reflects the improved user experience that allows clients to use static addresses and receive multiple DataCap allocations without address rotation. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/verified_clients/_index.md | 13 ++++++++++++- content/glossary/_index.md | 2 +- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/content/algorithms/verified_clients/_index.md b/content/algorithms/verified_clients/_index.md index d2de8b984..e2bd7b3c5 100644 --- a/content/algorithms/verified_clients/_index.md +++ b/content/algorithms/verified_clients/_index.md @@ -17,7 +17,18 @@ Filecoin Plus is a layer of social trust designed to maximize the amount of usef 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. Filecoin Plus clients can request increased DataCap once they have used their full allocation, with Notaries performing due diligence to ensure clients are not maliciously exploiting the system. + + + +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. ### 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. diff --git a/content/glossary/_index.md b/content/glossary/_index.md index 0d0cb01bc..fead029c3 100644 --- a/content/glossary/_index.md +++ b/content/glossary/_index.md @@ -86,7 +86,7 @@ The [_Cron Actor_](sysactors) is a scheduler actor that runs critical functions ## DataCap -DataCap is a one-time 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. +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 From 11b1913ac97d8676d994c5cd443e5d30e807627e Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:30:25 +1000 Subject: [PATCH 09/57] Update Filecoin specification to align with FIP-0013 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for ProveCommitSectorAggregated method introduced in FIP-0013: - Correct method name from ProveCommitAggregate to ProveCommitSectorAggregated - Add detailed description of the aggregated proof method and its benefits - Document minimum (4) and maximum (819) sectors per aggregation - Explain extended prove-commit delay of 30 days for better aggregation - Add FIP-0013 to the YAML changelog This aligns the specification with the actual implementation of aggregated sector prove-commit functionality. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../systems/filecoin_mining/sector/lifecycle.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index 6342a62cf..3c1a13616 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -15,6 +15,9 @@ changes: - fip: FIP-0008 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0008.md description: Added PreCommitSectorBatch method to enable batch pre-commitment of up to 256 sectors. + - fip: FIP-0013 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0013.md + description: Added ProveCommitSectorAggregated method to enable aggregated proof verification for multiple sectors. --> 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. @@ -34,7 +37,7 @@ A sector can be in one of the following states. | State | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `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.ProveCommitAggregate` | +| `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` | @@ -52,3 +55,12 @@ The `PreCommitSectorBatch` method allows miners to pre-commit up to 256 sectors - 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. + +### 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. From 3c59f4a5718611afe69540e10dd246f149655028 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:33:55 +1000 Subject: [PATCH 10/57] Update Filecoin specification to align with FIP-0014 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for V1 proof sector extension limitations: - Document that V1 proof sectors sealed before network v7 can only extend to 540 days total - Add new section on Sector Extension Limitations - Clarify that the 540-day limit includes days already active - Add FIP-0014 to the YAML changelog This ensures the specification accurately reflects the special handling of V1 proof sectors introduced to balance security concerns with miner fairness. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_mining/sector/lifecycle.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index 3c1a13616..0da78b136 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -18,6 +18,9 @@ changes: - fip: FIP-0013 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0013.md description: Added ProveCommitSectorAggregated method to enable aggregated proof verification for multiple sectors. + - fip: FIP-0014 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0014.md + description: Allowed V1 proof sectors to be extended up to a maximum of 540 days. --> 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. @@ -32,6 +35,11 @@ As with every system it is expected that sectors will present faults. Although t 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. +## 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 | From 8fdeefa5668524c932bf216ccbd892acab528e85 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:40:16 +1000 Subject: [PATCH 11/57] Update Filecoin specification to align with FIP-0015 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation clarifying gas fee treatment after FIP-0015: - Document that all messages including SubmitWindowedPoSt pay BaseFee burn - Add history showing FIP-0009 exemption and FIP-0015 reversal - Clarify uniform gas treatment ensures fair market dynamics - Add new Message-Specific Gas Treatment section This ensures the specification reflects the current state where Window PoSt messages are no longer exempt from BaseFee burn, maintaining gas market fairness. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/gas_fee.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/content/systems/filecoin_vm/gas_fee.md b/content/systems/filecoin_vm/gas_fee.md index 0f33a85bc..7be52986d 100644 --- a/content/systems/filecoin_vm/gas_fee.md +++ b/content/systems/filecoin_vm/gas_fee.md @@ -44,3 +44,18 @@ 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. From b5cee0ee37378ccfe189fb5c04fd812233361266 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:45:50 +1000 Subject: [PATCH 12/57] Update Filecoin specification to align with FIP-0018 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for Storage Provider terminology introduced in FIP-0018: - Update Miner glossary entry to note Storage Provider terminology - Update Storage Miner Actor entry with terminology note - Update Retrieval miner entry with Retrieval Provider terminology - Add new Storage Provider glossary entry explaining the terminology change - Add FIP-0018 YAML metadata to affected entries This acknowledges the organizational terminology shift from "miner" to "Storage Provider" in marketing/communications while maintaining technical accuracy in the specification. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/glossary/_index.md | 46 +++++++++++++++++++++++++++++++++----- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/content/glossary/_index.md b/content/glossary/_index.md index fead029c3..488f73716 100644 --- a/content/glossary/_index.md +++ b/content/glossary/_index.md @@ -184,12 +184,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 @@ -266,7 +274,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 @@ -318,12 +334,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. From 41914fc3e3331179981deb14a16f9f6d7cff47f7 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:49:45 +1000 Subject: [PATCH 13/57] Update Filecoin specification to align with FIP-0019 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for Snap Deals functionality introduced in FIP-0019: - Update Capacity commitment glossary to mention Snap Deals capability - Add new Snap Deals glossary entry explaining the protocol - Update sector lifecycle to describe CC sector upgrades via Snap Deals - Add new Sector Updates section with ProveReplicaUpdates details - Add FIP-0019 to the YAML changelog This documents how storage providers can update CC sectors with real data without re-sealing, significantly reducing onboarding costs and time. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/glossary/_index.md | 22 ++++++++++++++++++- .../filecoin_mining/sector/lifecycle.md | 17 +++++++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/content/glossary/_index.md b/content/glossary/_index.md index 488f73716..7a11f7bf4 100644 --- a/content/glossary/_index.md +++ b/content/glossary/_index.md @@ -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 @@ -320,6 +328,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). diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index 0da78b136..e2af41892 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -21,13 +21,16 @@ changes: - fip: FIP-0014 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0014.md description: Allowed V1 proof sectors to be extended up to a maximum of 540 days. + - fip: FIP-0019 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0019.md + description: Introduced Snap Deals for updating CC sectors with real data without re-sealing. --> 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 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. +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_. @@ -72,3 +75,15 @@ The `ProveCommitSectorAggregated` method allows miners to prove-commit multiple - 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. From 66254b0bcfaf842a187ba5f07a093895ea469b07 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 19:53:28 +1000 Subject: [PATCH 14/57] Update Filecoin specification to align with FIP-0020 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for WithdrawBalance return value enhancement: - Update Storage Market Actor with balance withdrawal section - Update Storage Miner Actor with balance management section - Document that WithdrawBalance now returns actual amount withdrawn - Add FIP-0020 to YAML changelog in both actor files This improvement provides better visibility and traceability of FIL flow, addressing the ambiguity when withdrawal amounts are less than requested. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../onchain_storage_market/storage_market_actor.md | 12 ++++++++++++ .../storage_mining/storage_miner_actor.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) 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..7908cad8a 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,14 @@ 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 +48,7 @@ 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)}$$ ``` + +## 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. 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..e9c595d33 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,20 @@ 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 (owner or beneficiary) to withdraw available funds from the miner actor. Following FIP-0020, this method returns the actual amount withdrawn, providing transparency when the available balance is less than the requested withdrawal amount. This enhancement improves financial tracking and reporting for mining operations. From eef2b8fdc521a2b10d35a67d022ec96e1b4d2cf1 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:02:47 +1000 Subject: [PATCH 15/57] Update Filecoin specification to align with FIP-0021 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for corrected sector quality calculation on extension: - Add Sector Extension Quality Calculation section with formulas - Document how deal weights are adjusted by remaining lifetime fraction - Update sector lifecycle to mention quality adjustment on extension - Add FIP-0021 to YAML changelog This correction prevents overcounting of deal spacetime when sectors are extended, ensuring verified deal weight maintains proper relative power. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_mining/sector/lifecycle.md | 2 +- .../sector/sector-quality/_index.md | 28 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index e2af41892..a2f705cfa 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -36,7 +36,7 @@ All sectors are expected to remain live until the end of their sector lifetime a 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 Extension Limitations diff --git a/content/systems/filecoin_mining/sector/sector-quality/_index.md b/content/systems/filecoin_mining/sector/sector-quality/_index.md index e0d9574b0..da16f252c 100644 --- a/content/systems/filecoin_mining/sector/sector-quality/_index.md +++ b/content/systems/filecoin_mining/sector/sector-quality/_index.md @@ -8,6 +8,14 @@ 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. @@ -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. From 7924ab04e25c884c740d4aabd047adda3b461362 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:06:29 +1000 Subject: [PATCH 16/57] Update Filecoin specification to align with FIP-0022 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for improved PublishStorageDeals error handling: - Add Deal Publishing section to Storage Market Actor - Document that invalid deals no longer fail entire batch - Explain return value includes deal IDs and validity bitfield - Update storage market flow to note FIP-0022 behavior - Add FIP-0022 to YAML changelog This improvement makes deal publishing more resilient by allowing valid deals to succeed even when some deals in the batch are invalid. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../onchain_storage_market/storage_market_actor.md | 13 +++++++++++++ .../filecoin_markets/storage_market/_index.md | 2 +- 2 files changed, 14 insertions(+), 1 deletion(-) 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 7908cad8a..47b523202 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 @@ -16,6 +16,9 @@ changes: - fip: FIP-0020 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0020.md description: WithdrawBalance now returns the actual amount withdrawn. + - fip: FIP-0022 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0022.md + description: PublishStorageDeals no longer fails entirely when individual deals are invalid. --> # Storage Market Actor @@ -49,6 +52,16 @@ This collateral is returned to the storage provider when all deals in the sector $$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. 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. From 444df57a27edfc6f1cee2ad22c96787f607b1785 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:17:27 +1000 Subject: [PATCH 17/57] Update Filecoin specification to align with FIP-0023 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adds the tie-breaking rule for tipsets of equal weight as formalized in FIP-0023. The rule specifies that when selecting between tipsets of equal weight, nodes should choose the one with the smallest winning ElectionProof ticket. Changes: - Added YAML changelog to Expected Consensus section documenting that the tie-breaking rule was formalized by FIP-0023 - Updated Tipset glossary entry to include the tie-breaking rule and added corresponding YAML changelog 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/expected_consensus/_index.md | 8 ++++++++ content/glossary/_index.md | 10 +++++++++- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/content/algorithms/expected_consensus/_index.md b/content/algorithms/expected_consensus/_index.md index 24aa4a1c6..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. diff --git a/content/glossary/_index.md b/content/glossary/_index.md index 7a11f7bf4..e8aa58427 100644 --- a/content/glossary/_index.md +++ b/content/glossary/_index.md @@ -395,9 +395,17 @@ 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. From cca3b2c8d23a32b46a9550ce6993ce9704dc691a Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:22:21 +1000 Subject: [PATCH 18/57] Update Filecoin specification to align with FIP-0024 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the BatchBalancer and BatchDiscount parameters introduced in FIP-0013 and adjusted in FIP-0024. These parameters govern additional gas charges for batch operations to align network incentives with long-term health. Changes: - Added new section "Batch Operations Gas Charges" to gas_fee.md - Documented BatchBalancer (5 nanoFIL) and BatchDiscount (1/20) - Included gas usage values for PreCommit and ProveCommit operations - Explained the batch gas charge calculation formula - Added FIP-0024 to the YAML changelog The documentation now accurately reflects the gas economics for PreCommitSectorBatch and ProveCommitSectorAggregated operations. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/gas_fee.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/content/systems/filecoin_vm/gas_fee.md b/content/systems/filecoin_vm/gas_fee.md index 7be52986d..4c714fb11 100644 --- a/content/systems/filecoin_vm/gas_fee.md +++ b/content/systems/filecoin_vm/gas_fee.md @@ -56,6 +56,26 @@ changes: - fip: FIP-0015 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0015.md description: Reverted FIP-0009; Window PoSt messages no longer exempt from BaseFee burn. + - fip: FIP-0024 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0024.md + description: Adjusted BatchBalancer to 5 nanoFIL and applied batch gas charges to PreCommitBatch. --> 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. From d195111452db4489cba738e62a173939271b2d81 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:26:54 +1000 Subject: [PATCH 19/57] Update Filecoin specification to align with FIP-0026 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adds YAML changelog entries documenting the sector fault cutoff period extension from 14 days (2 weeks) to 42 days (6 weeks) as specified in FIP-0026. The specification content already reflected the correct 42-day period, but lacked the proper FIP attribution. Changes: - Added FIP-0026 changelog to sector-faults.md - Added FIP-0026 changelog to lifecycle.md This change provides storage providers more time to recover from force majeure events such as natural disasters while maintaining strong incentives for reliable service through continued fault fees. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_mining/sector/lifecycle.md | 3 +++ content/systems/filecoin_mining/sector/sector-faults.md | 8 ++++++++ 2 files changed, 11 insertions(+) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index a2f705cfa..a43906d58 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -24,6 +24,9 @@ changes: - fip: FIP-0019 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0019.md description: Introduced Snap Deals for updating CC sectors with real data without re-sealing. + - fip: FIP-0026 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0026.md + description: Extended sector fault cutoff period from 14 days to 42 days. --> 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. 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. From 465586fbb86e4479537f395904a54b65c6aba944 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:33:35 +1000 Subject: [PATCH 20/57] Update Filecoin specification to align with FIP-0028 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the DataCap removal capability introduced in FIP-0028, which allows Notaries to remove DataCap from client addresses in cases of inactivity or abuse. Changes: - Added FIP-0028 to the Notaries section changelog - Documented the DataCap removal process requiring 2 Notaries and 2 Root Key Holders approval - Updated VerifiedRegistryActor description to mention the RemoveVerifiedClientDatacap method This feature strengthens the Filecoin Plus program's ability to maintain integrity and prevent abuse while ensuring appropriate checks and balances through multi-signature requirements. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/verified_clients/_index.md | 5 +++++ content/systems/filecoin_vm/sysactors/_index.md | 2 +- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/content/algorithms/verified_clients/_index.md b/content/algorithms/verified_clients/_index.md index e2bd7b3c5..80ac427bb 100644 --- a/content/algorithms/verified_clients/_index.md +++ b/content/algorithms/verified_clients/_index.md @@ -24,12 +24,17 @@ changes: - fip: FIP-0012 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0012.md description: Enabled DataCap top-ups to existing client addresses without requiring full depletion. + - fip: FIP-0028 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0028.md + description: Added ability to remove DataCap from client addresses. --> 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. diff --git a/content/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index d03b1e34e..ef7572ec9 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -31,7 +31,7 @@ The remaining seven (7) builtin System Actors that do not interact directly with - `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)] - `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 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 [[Verifreg Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/verifreg/verified_registry_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 [[System Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/system/system_actor.go)] ## CronActor From 745e21f43ea334804c2f444fb12ca5c0b4563783 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:37:43 +1000 Subject: [PATCH 21/57] Update Filecoin specification to align with FIP-0029 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the beneficiary address functionality introduced in FIP-0029, which separates financial control from owner control for storage providers. Changes: - Added FIP-0029 to the Storage Miner Actor changelog - Expanded Balance Management section with detailed beneficiary documentation - Added new subsections: Beneficiary Address, Withdrawal Process, and Methods - Documented quota and expiration features for beneficiaries - Explained the approval process for changing beneficiary - Clarified withdrawal behavior with beneficiary addresses The beneficiary feature enables lending markets, improves security, and provides more flexible financial arrangements for storage providers while maintaining backward compatibility. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../storage_mining/storage_miner_actor.md | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) 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 e9c595d33..69f1c490d 100644 --- a/content/systems/filecoin_mining/storage_mining/storage_miner_actor.md +++ b/content/systems/filecoin_mining/storage_mining/storage_miner_actor.md @@ -15,6 +15,9 @@ changes: - fip: FIP-0020 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0020.md description: WithdrawBalance now returns the actual amount withdrawn. + - fip: FIP-0029 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0029.md + description: Added beneficiary address for financial control separation from owner. --> # Storage Miner Actor @@ -25,4 +28,25 @@ changes: ## Balance Management -Storage miners maintain balances for various purposes including collateral and rewards. The `WithdrawBalance` method allows authorized parties (owner or beneficiary) to withdraw available funds from the miner actor. Following FIP-0020, this method returns the actual amount withdrawn, providing transparency when the available balance is less than the requested withdrawal amount. This enhancement improves financial tracking and reporting for mining operations. +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 From e901ba7ccd7a73429de1711d3605fa65a9bc397e Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:46:57 +1000 Subject: [PATCH 22/57] Update Filecoin specification to align with FIP-0030 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the introduction of the Filecoin Virtual Machine (FVM) as specified in FIP-0030. The FVM represents a major architectural change that enables user-programmable smart contracts on Filecoin. Changes: - Added FIP-0030 changelog to both VM documentation files - Updated VM overview to mention WASM-based execution environment - Added section describing FVM capabilities (WASM, user actors, IPLD, syscalls) - Updated actor description to distinguish built-in vs user-deployed actors - Clarified that actors can now run custom WASM bytecode The FVM transforms Filecoin from a network with only built-in actors to a fully programmable blockchain platform supporting arbitrary user-defined smart contracts. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/intro/filecoin_vm.md | 10 +++++++++- content/systems/filecoin_vm/_index.md | 19 ++++++++++++++++++- 2 files changed, 27 insertions(+), 2 deletions(-) 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/systems/filecoin_vm/_index.md b/content/systems/filecoin_vm/_index.md index cb10d9060..1ed659b1b 100644 --- a/content/systems/filecoin_vm/_index.md +++ b/content/systems/filecoin_vm/_index.md @@ -11,8 +11,25 @@ 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 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. From 80dc6a75e927870809c79bb698798ed47a5ac952 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:54:54 +1000 Subject: [PATCH 23/57] Update Filecoin specification to align with FIP-0031 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the atomic switch to non-programmable FVM and the transition from synthetic to content-addressed Code CIDs as implemented in FIP-0031. Changes: - Added FIP-0031 changelog to VM and System Actors documentation - Added new section "Actor Code CIDs" explaining the transition - Documented content-addressed CID format using BLAKE2B-256 - Explained the previous synthetic CID format for historical context - Added information about canonical builtin-actors implementation - Updated SystemActor description to mention Code CID registry - Added note about system actor state introduced in FIP-0031 This change represents a critical infrastructure upgrade that improved security through content verification and established the foundation for future programmability features. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/_index.md | 21 +++++++++++++++++++ .../systems/filecoin_vm/sysactors/_index.md | 10 ++++++++- 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/content/systems/filecoin_vm/_index.md b/content/systems/filecoin_vm/_index.md index 1ed659b1b..61d71e2fd 100644 --- a/content/systems/filecoin_vm/_index.md +++ b/content/systems/filecoin_vm/_index.md @@ -17,6 +17,9 @@ changes: - fip: FIP-0030 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0030.md description: Introduced the Filecoin Virtual Machine (FVM) with WASM-based execution and user-programmable actors. + - fip: FIP-0031 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0031.md + description: Switched to non-programmable FVM with content-addressed Code CIDs and introduced system actor state. --> An Actor in the Filecoin Blockchain is the equivalent of the smart contract in the Ethereum Virtual Machine. @@ -32,4 +35,22 @@ The FVM provides: - **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. + +## 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. diff --git a/content/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index ef7572ec9..cdb2bb5b5 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -12,6 +12,14 @@ 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 four (4) system actors required for VM processing: @@ -32,7 +40,7 @@ The remaining seven (7) builtin System Actors that do not interact directly with - `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 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 [[System Actor Repo](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/system/system_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)] ## CronActor From 03a353d8333d7efb4f7be79b1b22fa9d9a0cde10 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 20:57:42 +1000 Subject: [PATCH 24/57] Update Filecoin specification to align with FIP-0032 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the gas accounting model adjustments introduced in FIP-0032 for the non-programmable FVM. These changes enable accurate resource metering for WASM-based actor execution. Changes: - Added FIP-0032 to the gas fee changelog - Created new section "FVM Gas Accounting Model" documenting three components: - Execution Gas: 4 gas per WASM instruction (with exceptions) - Syscall Gas: 14,000 gas per syscall invocation - Extern Gas: Covers IPLD, crypto, and other external operations - Explained the purpose and pricing of each gas component This comprehensive gas model provides the foundation for secure execution of both built-in and future user-defined actors on the Filecoin network. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/gas_fee.md | 31 ++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/content/systems/filecoin_vm/gas_fee.md b/content/systems/filecoin_vm/gas_fee.md index 4c714fb11..d6b7e5aa9 100644 --- a/content/systems/filecoin_vm/gas_fee.md +++ b/content/systems/filecoin_vm/gas_fee.md @@ -59,6 +59,9 @@ changes: - fip: FIP-0024 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0024.md description: Adjusted BatchBalancer to 5 nanoFIL and applied batch gas charges to PreCommitBatch. + - fip: FIP-0032 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0032.md + description: Introduced execution gas, syscall gas, and extern gas for FVM. --> 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. @@ -79,3 +82,31 @@ 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. From cf3d76657b8a9441521d3d1dd9dcdfab28b8448d Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:04:15 +1000 Subject: [PATCH 25/57] Update Filecoin specification to align with FIP-0034 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the fixed pre-commit deposit (PCD) introduced in FIP-0034, which sets the deposit to a sector quality 10 value regardless of actual sector content. Changes: - Added FIP-0034 to the miner collaterals changelog - Created new "Pre-Commit Deposit" section explaining the fixed PCD - Documented benefits: simplified onboarding, security, market decoupling - Clarified that PCD is always less than initial pledge - Explained forfeiture conditions for incomplete sector onboarding This change enables future programmable storage markets by removing the dependency between sector onboarding and deal content verification. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_mining/miner_collaterals.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/content/systems/filecoin_mining/miner_collaterals.md b/content/systems/filecoin_mining/miner_collaterals.md index 79a06c60b..dc1c5513b 100644 --- a/content/systems/filecoin_mining/miner_collaterals.md +++ b/content/systems/filecoin_mining/miner_collaterals.md @@ -10,12 +10,32 @@ 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. From 99253536b74e97fe8878517f779fbb9d1fba54ce Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:07:18 +1000 Subject: [PATCH 26/57] Update Filecoin specification to align with FIP-0041 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the forward-compatible methods introduced in FIP-0041 for PreCommit and ReplicaUpdate operations. These new methods prepare for future storage market changes. Changes: - Added FIP-0041 to the sector lifecycle changelog - Documented PreCommitSectorBatch2 (method 28) with unsealed_sector_cid field - Documented ProveReplicaUpdates2 (method 29) with new_unsealed_cid field - Explained forward compatibility purpose for future market mechanisms These new methods enable a smoother transition to user-deployable storage markets by establishing the required method signatures before behavioral changes are implemented. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_mining/sector/lifecycle.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index a43906d58..21376f95a 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -27,6 +27,9 @@ changes: - fip: FIP-0026 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0026.md description: Extended sector fault cutoff period from 14 days to 42 days. + - fip: FIP-0041 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0041.md + description: Added PreCommitSectorBatch2 and ProveReplicaUpdates2 for forward compatibility. --> 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. @@ -70,6 +73,8 @@ The `PreCommitSectorBatch` method allows miners to pre-commit up to 256 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 @@ -90,3 +95,5 @@ The process works by: - 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. From cc02da793dfa80b17c2e4d8daeddb1a9bba3d434 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:10:03 +1000 Subject: [PATCH 27/57] Update Filecoin specification to align with FIP-0044 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the standard authentication method for actors introduced in FIP-0044. The AuthenticateMessage method provides a flexible way for any actor to verify authorization of data. Changes: - Added FIP-0044 to the system actors changelog - Expanded AccountActor section with AuthenticateMessage documentation - Explained the method's purpose and benefits: - Standard interface for authentication across all actors - Enables other actors to verify authorization without handling signatures - Template for both built-in and user-defined actors - Noted adoption by Storage Market and Payment Channel actors This standard authentication interface is essential for the FVM ecosystem, enabling user-defined actors to participate in authentication workflows previously limited to account actors. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/sysactors/_index.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/content/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index cdb2bb5b5..d97392329 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -18,6 +18,9 @@ changes: - fip: FIP-0031 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0031.md description: Added state to SystemActor to maintain registry of built-in actor Code CIDs. + - fip: FIP-0044 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0044.md + description: Added AuthenticateMessage method to AccountActor for standard authentication. --> 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). @@ -66,4 +69,11 @@ 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. + {{}} From b480f19594a504439ef26eff947e87c9bc49b516 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:12:47 +1000 Subject: [PATCH 28/57] Update Filecoin specification to align with FIP-0045 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit documents the decoupling of DataCap from the built-in market actor introduced in FIP-0045. This architectural change enables future user-programmed market actors and simplifies power calculations. Changes: - Added FIP-0045 to the Filecoin Plus changelog - Created new "DataCap Allocations and Claims" section explaining: - Two-stage process: allocations created by clients, claimed by providers - Allocation parameters (provider, CID, term limits, expiration) - Claims representing provider commitments - Listed benefits of decoupling: - Enables user-programmed market actors - Simplified quality-adjusted power calculations - Independent term extensions - DataCap as fungible tokens This change provides the foundation for a more flexible and extensible storage market ecosystem on Filecoin. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/verified_clients/_index.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/content/algorithms/verified_clients/_index.md b/content/algorithms/verified_clients/_index.md index 80ac427bb..c6710cc68 100644 --- a/content/algorithms/verified_clients/_index.md +++ b/content/algorithms/verified_clients/_index.md @@ -27,6 +27,9 @@ changes: - fip: FIP-0028 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0028.md description: Added ability to remove DataCap from client addresses. + - fip: FIP-0045 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0045.md + description: Decoupled DataCap from market deals, introduced allocations and claims. --> 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. @@ -42,6 +45,24 @@ Clients are active participants with DataCap allocation for their use cases. The 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 From afb618ea2b6755cd92a14c064ac0f4894354f0ee Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:21:27 +1000 Subject: [PATCH 29/57] Update Filecoin specification to align with FIP-0048 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0048 (f4 Address Class): - Added f4 address class (protocol 4) documentation to address.md - Documented the f4 address format: f4{actor-id}f{sub-address} - Added information about address managers and their role - Documented placeholder actors for unassigned f4 addresses - Added delegated_address field to ActorState documentation - Updated InitActor documentation to include Exec4 method - Added test vectors for f4 addresses - Included YAML change history tracking FIP-0048 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/appendix/address.md | 134 ++++++++++++++++++ .../systems/filecoin_vm/sysactors/_index.md | 14 ++ 2 files changed, 148 insertions(+) diff --git a/content/appendix/address.md b/content/appendix/address.md index 20575a2e6..3709b8d47 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,48 @@ 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 + +### 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/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index d97392329..933e17f30 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -53,8 +53,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. {{}} From 0fdb9c6eaaf7fdbb5c10256c3eb3a9becb2cf101 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:28:30 +1000 Subject: [PATCH 30/57] Update Filecoin specification to align with FIP-0049 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0049 (Actor events): - Updated MessageReceipt structure to include events_root field - Added comprehensive Actor Events section documenting: - Event structure (StampedEvent, ActorEvent, Entry) - emit_event syscall for emitting events - Event accumulation and retention rules - Event limits (32 bytes/key, 8 KiB total, 256 entries max) - Indexing flags for client hints - Added YAML change history tracking FIP-0049 Actor events enable external observability of on-chain activity without requiring state tree parsing or message replay. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/runtime/_index.md | 80 ++++++++++++++++++- 1 file changed, 78 insertions(+), 2 deletions(-) diff --git a/content/systems/filecoin_vm/runtime/_index.md b/content/systems/filecoin_vm/runtime/_index.md index 7b3dae31e..0a3149eb2 100644 --- a/content/systems/filecoin_vm/runtime/_index.md +++ b/content/systems/filecoin_vm/runtime/_index.md @@ -12,19 +12,29 @@ 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 +49,69 @@ 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 + +- Maximum 32 bytes per key +- Maximum 8 KiB total value size per event +- Maximum 256 entries per event +- Only IPLD_RAW (0x55) codec currently supported + +### Indexing Flags + +Events support indexing hints through flags: +- `0x01`: Index by key +- `0x02`: Index by value +- `0x03`: Index by both key and value + +These flags are hints to clients for constructing efficient indices for event queries. From 287ea9a1f0e0d7601659d53dde33514340a8c119 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:30:20 +1000 Subject: [PATCH 31/57] Update Filecoin specification to align with FIP-0050 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0050 (API between user-programmed actors and built-in actors): - Added comprehensive Method Invocation and Access Control section - Documented method number conventions (0 to 2^24-1 for internal, 2^24+ for public) - Explained access restrictions enforcing built-in actor only access to internal methods - Listed public APIs exported by each built-in actor: - Account Actor: AuthenticateMessage, UniversalReceiverHook - Storage Market Actor: Balance operations, deal information getters - Miner Actor: Configuration changes, balance queries - Storage Power Actor: Miner creation and network statistics - Datacap Actor: Full token interface - Verified Registry Actor: Client and claims management - Added YAML change history tracking FIP-0050 This separation ensures stability for user-programmed actors while allowing protocol evolution. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/_index.md | 36 +++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/content/systems/filecoin_vm/_index.md b/content/systems/filecoin_vm/_index.md index 61d71e2fd..a3d6f26d2 100644 --- a/content/systems/filecoin_vm/_index.md +++ b/content/systems/filecoin_vm/_index.md @@ -20,6 +20,9 @@ changes: - fip: FIP-0031 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0031.md description: Switched to non-programmable FVM with content-addressed Code CIDs and introduced system actor state. + - fip: FIP-0050 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0050.md + description: Restricted built-in actor method invocation and defined stable public APIs for user actors. --> An Actor in the Filecoin Blockchain is the equivalent of the smart contract in the Ethereum Virtual Machine. @@ -51,6 +54,39 @@ The canonical implementation of Filecoin's built-in actors is maintained at [`fi 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. + ## 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. From 3394fd1e1ba2c12ef9af27137341c977c151881c Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:33:07 +1000 Subject: [PATCH 32/57] Update Filecoin specification to align with FIP-0052 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0052 (Increase max sector commitment to 3.5 years): - Added new Sector Commitment Duration section documenting: - Maximum commitment duration increased to 1278 days (3.5 years) - Previous maximum was 540 days (1.5 years) - Benefits include longer-term storage deals, improved network stability - Applies to initial commitments, extensions, and storage deals - Clarified that all sectors can be extended up to 1278 days - Maintained existing V1 proof sector limitations (540 days max) - Added YAML change history tracking FIP-0052 This change enables storage providers to offer longer-term archival storage solutions while reducing operational overhead. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_mining/sector/lifecycle.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index 21376f95a..402d70ce6 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -30,6 +30,9 @@ changes: - fip: FIP-0041 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0041.md description: Added PreCommitSectorBatch2 and ProveReplicaUpdates2 for forward compatibility. + - fip: FIP-0052 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0052.md + description: Increased maximum sector commitment duration from 540 days to 1278 days (3.5 years). --> 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. @@ -44,6 +47,21 @@ As with every system it is expected that sectors will present faults. Although t 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 From 858a1c420640f0b1a14aab8a002cee542886eee4 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:38:31 +1000 Subject: [PATCH 33/57] Update Filecoin specification to align with FIP-0054 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0054 (Filecoin EVM runtime): - Added comprehensive Filecoin EVM (FEVM) section to FVM documentation: - EVM Runtime Actor capabilities and features - Address mapping between Ethereum and Filecoin (f4 addresses) - Precompile support (both Ethereum and Filecoin-specific) - State management using IPLD - Key differences from Ethereum (block time, chain ID, gas model) - Actor interface methods (Constructor, InvokeContract, etc.) - Updated system actors documentation: - Increased builtin actor count from 11 to 12 - Added EVMRuntimeActor to the list of system actors - Linked to EVM actor repository - Added YAML change history tracking FIP-0054 The FEVM enables Ethereum smart contract execution on Filecoin while maintaining compatibility with existing Ethereum tooling. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/_index.md | 53 +++++++++++++++++++ .../systems/filecoin_vm/sysactors/_index.md | 8 ++- 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/content/systems/filecoin_vm/_index.md b/content/systems/filecoin_vm/_index.md index a3d6f26d2..0ea870e6c 100644 --- a/content/systems/filecoin_vm/_index.md +++ b/content/systems/filecoin_vm/_index.md @@ -87,6 +87,59 @@ Each built-in actor exports specific methods for public use: - **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. diff --git a/content/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index 933e17f30..d64b55cac 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -21,9 +21,12 @@ changes: - fip: FIP-0044 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0044.md description: Added AuthenticateMessage method to AccountActor for standard authentication. + - fip: FIP-0054 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0054.md + description: Added EVM runtime actor for executing Ethereum smart contracts. --> -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 twelve (12) 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: @@ -35,7 +38,7 @@ There are another two 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 remaining seven (7) builtin System Actors that do not interact directly with the VM are the following: +The remaining eight (8) 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)] @@ -44,6 +47,7 @@ The remaining seven (7) builtin System Actors that do not interact directly with - `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 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)] ## CronActor From 8f48f247f663c0526653c698e17f009afcf4d589 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:45:05 +1000 Subject: [PATCH 34/57] Update Filecoin specification to align with FIP-0055 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0055 (Supporting Ethereum Accounts, Addresses, and Transactions): - Updated address documentation: - Added Ethereum Address Manager (EAM) section - Documented f410 address space for Ethereum addresses - Explained bidirectional mapping between Ethereum and Filecoin addresses - Noted EAM's role as EVM contract factory - Updated system actors documentation: - Increased builtin actor count from 12 to 14 - Added EthereumAccountActor for Ethereum EOA support - Added EthereumAddressManagerActor (EAM) at f010 - Documented Ethereum Account actor features (EIP-1559 transactions, delegated signatures) - Added YAML change history tracking FIP-0055 This enables native Ethereum wallet and tool compatibility with Filecoin. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/appendix/address.md | 12 ++++++++++ .../systems/filecoin_vm/sysactors/_index.md | 22 ++++++++++++++++--- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/content/appendix/address.md b/content/appendix/address.md index 3709b8d47..1fbe44588 100644 --- a/content/appendix/address.md +++ b/content/appendix/address.md @@ -548,6 +548,9 @@ changes: - fip: FIP-0048 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0048.md description: Introduced address managers for f4 address assignment. + - fip: FIP-0055 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0055.md + description: Added Ethereum Address Manager (EAM) at f010 for managing Ethereum addresses. --> 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. @@ -557,6 +560,15 @@ Address managers enable: - 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: diff --git a/content/systems/filecoin_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index d64b55cac..c2bca14b9 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -24,21 +24,25 @@ changes: - fip: FIP-0054 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0054.md description: Added EVM runtime actor for executing Ethereum smart contracts. + - fip: FIP-0055 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0055.md + description: Added Ethereum Address Manager and Ethereum Account actors. --> -There are twelve (12) 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 eight (8) 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)] @@ -48,6 +52,7 @@ The remaining eight (8) builtin System Actors that do not interact directly with - `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 @@ -95,3 +100,14 @@ Since FIP-0044, the AccountActor implements the `AuthenticateMessage` method, wh 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. From df39282247dd802a5518d4bd17f4d87dd0438f90 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:48:57 +1000 Subject: [PATCH 35/57] Update Filecoin specification to align with FIP-0057 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0057 (Update gas charging schedule and system limits for FEVM): - Added comprehensive FEVM Gas Schedule Updates section documenting: - Storage cost increase from 1,300 to 3,440 gas/byte - Memory operation costs (copy: 0.4 gas/byte, retention: 10 gas/byte) - Syscall gas adjustments for IPLD and state tree operations - Hashing and cryptography operation cost updates - Added System Limits section covering: - Maximum IPLD block size of 1 MiB - Memory limits for Wasm execution - Call depth limit reduction to 1024 - Added YAML change history tracking FIP-0057 These updates ensure accurate gas pricing for user-programmable smart contracts, preventing DoS attacks and maintaining network stability. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/gas_fee.md | 47 ++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/content/systems/filecoin_vm/gas_fee.md b/content/systems/filecoin_vm/gas_fee.md index d6b7e5aa9..d89daae0c 100644 --- a/content/systems/filecoin_vm/gas_fee.md +++ b/content/systems/filecoin_vm/gas_fee.md @@ -62,6 +62,9 @@ changes: - fip: FIP-0032 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0032.md description: Introduced execution gas, syscall gas, and extern gas for FVM. + - fip: FIP-0057 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0057.md + description: Updated gas charging schedule for FEVM, increased storage costs, and introduced memory limits. --> 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. @@ -110,3 +113,47 @@ Extern gas covers operations performed outside the WASM runtime, including: - 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. From 37fd3f91714202d916c9f20cc32be94684f26055 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:51:07 +1000 Subject: [PATCH 36/57] Update Filecoin specification to align with FIP-0059 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0059 (Synthetic PoRep): - Added comprehensive Synthetic PoRep section to PoRep documentation - Documented how Synthetic PoRep works: - N_syn = 2^18 synthetic challenges generated before PreCommit - Vanilla proofs precomputed for all challenges (~25GiB storage) - Layer data (~400GiB) can be deleted after precomputation - N_verified = 176 challenges selected using on-chain randomness - SNARK proofs generated only for selected challenges - Listed benefits: - >90% reduction in temporary storage (400GiB → 25GiB) - No security impact - Optional feature for storage providers - Same proving costs and on-chain flow - Added new proof types for 32GiB and 64GiB sectors - Added YAML change history tracking FIP-0059 This optimization significantly reduces storage requirements during sealing without compromising security or changing the on-chain protocol. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/pos/porep.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/content/algorithms/pos/porep.md b/content/algorithms/pos/porep.md index eaf4b0dec..5b839abaa 100644 --- a/content/algorithms/pos/porep.md +++ b/content/algorithms/pos/porep.md @@ -9,6 +9,14 @@ 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 +27,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) From d90b7ae3c0cac04514aefef808d9e715f5d66ab5 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:53:08 +1000 Subject: [PATCH 37/57] Update Filecoin specification to align with FIP-0060 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0060 (Set market deal maintenance interval to 30 days): - Added Deal Maintenance and Cron Operations section documenting: - The role of cron in processing deal maintenance - Activities performed during maintenance (payments, state updates, cleanup) - Added Maintenance Interval subsection covering: - Increase from 1 day (2,880 epochs) to 30 days (86,400 epochs) - DEAL_UPDATES_INTERVAL constant definition - Gas cost reduction from ~73B to ~2.4B units per epoch (97% reduction) - Deal scheduling mechanism based on deal ID modulo - Automatic rescheduling process requiring no migration - Added YAML change history tracking FIP-0060 This optimization significantly reduces cron execution costs and improves chain validation performance without affecting deal functionality. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../storage_market_actor.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) 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 47b523202..7b5a597d4 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 @@ -19,6 +19,9 @@ changes: - fip: FIP-0022 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0022.md description: PublishStorageDeals no longer fails entirely when individual deals are invalid. + - fip: FIP-0060 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0060.md + description: Increased deal maintenance interval from 1 day to 30 days to reduce cron execution costs. --> # Storage Market Actor @@ -65,3 +68,25 @@ This change significantly improves the user experience for storage providers by ## 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 Cron Operations + +The Storage Market Actor performs regular maintenance on active deals through Filecoin's cron mechanism. This maintenance includes: +- Processing incremental payments from clients to providers +- Handling deal state updates +- Cleaning up expired deals + +### Maintenance Interval + +Since FIP-0060, the deal maintenance interval has been increased from 1 day (2,880 epochs) to 30 days (86,400 epochs): + +```rust +const DEAL_UPDATES_INTERVAL = 30 * EPOCHS_IN_DAY +``` + +This change significantly reduces the computational burden on the network: +- **Previous cost**: ~73 billion gas units per epoch for market cron operations +- **Current cost**: ~2.4 billion gas units per epoch (97% reduction) +- **Impact**: Improved chain validation times and reduced resource requirements + +Each deal's maintenance is scheduled based on its deal ID modulo the maintenance interval, ensuring an even distribution of maintenance work across epochs. The rescheduling happens automatically when deals are first processed after the FIP activation, requiring no migration. From 87b0602f9c7634d63738414cf3d7b54cc71f89d0 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 21:56:12 +1000 Subject: [PATCH 38/57] Update Filecoin specification to align with FIP-0061 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the changes introduced in FIP-0061 (WindowPoSt Grindability Fix): - Added Challenge Generation section documenting: - The purpose of cryptographic challenges in WindowPoSt - How challenge generation determines which data chunks to prove - Added Grindability Fix subsection explaining: - The vulnerability where challenges depended on sector ordering - How malicious providers could manipulate challenges - The fix making challenge generation independent of sector order - Documented the updated algorithm: - challenge_index is now relative to each sector (0 to challenge_count_per_sector) - Previously was global across all sectors - Challenges derived only from: chain randomness, sector ID, and local index - Listed new proof types (V1_1) that signal the updated behavior - Added YAML change history tracking FIP-0061 This security fix prevents storage providers from gaming the proof system by manipulating sector ordering. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/pos/post.md | 41 ++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/content/algorithms/pos/post.md b/content/algorithms/pos/post.md index 86f6ed25d..a44768e8e 100644 --- a/content/algorithms/pos/post.md +++ b/content/algorithms/pos/post.md @@ -44,6 +44,9 @@ changes: - fip: FIP-0010 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0010.md description: Introduced off-chain Window PoSt verification with optimistic acceptance and dispute mechanism. + - fip: FIP-0061 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0061.md + description: Fixed WindowPoSt challenge generation to be independent of sector ordering. --> WindowPoSt is the mechanism by which the commitments made by storage miners are audited. In _WindowPoSt_ every 24-hour period is called a _"proving period"_ and is broken down into a series of 30min, non-overlapping _deadlines_, making a total of 48 deadlines within any given 24-hour proving period. Every miner must demonstrate availability of all claimed sectors on a 24hr basis. Constraints on individual proof computations limit a single proof to 2349 sectors (a partition), with 10 challenges each. @@ -117,3 +120,41 @@ Since FIP-0010, Window PoSt proofs are optimistically accepted on-chain without - `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. From 52c9beeab3a4824821fdad80453e0ced7ca465f3 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:00:02 +1000 Subject: [PATCH 39/57] Update Filecoin specification to align with FIP-0062 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIP-0062 introduces a fallback method handler for the multisig actor to enable interoperability with EVM actors. Key changes: - Multisig actors now accept method calls with numbers ≥ 2^24 - These calls are handled as no-ops returning success - Enables value transfers from EVM smart contracts, Eth accounts - Brings multisig actors in line with account actors (FIP-0050) This change allows multisig wallets to receive value from EVM-based actors which use FRC-42("InvokeEVM") method numbers by default. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_token/multisig.md | 18 ++++++++++++++++++ .../systems/filecoin_vm/sysactors/_index.md | 2 +- 2 files changed, 19 insertions(+), 1 deletion(-) 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_vm/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index c2bca14b9..ae06faec9 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -46,7 +46,7 @@ The remaining nine (9) builtin System Actors that do not interact directly with - `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 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)] From 77ea7a071906f7d53a13bfb07c42ee6bcf566909 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:04:42 +1000 Subject: [PATCH 40/57] Update Filecoin specification to align with FIP-0063 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIP-0063 switches Filecoin to the new drand quicknet network. Key changes: - Uses unchained randomness (each beacon independent, no previous signature) - 3-second beacon frequency (Filecoin uses every 10th beacon for 30s epochs) - G1/G2 swap: signatures on G1 (48 bytes), public keys on G2 - Stateless verification: no need to store previous beacons - Updated catch-up time from 15s to 20s per epoch Documentation updates include: - Quicknet chain info and parameters - New beacon verification algorithm for unchained mode - Beacon sourcing formula for epoch-to-round mapping - Block header beacon entry requirements This enables smaller beacon signatures, simpler verification, and future timelock encryption capabilities. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/libraries/drand/_index.md | 69 +++++++++++++++++-- .../storage_power_consensus/_index.md | 35 ++++++---- 2 files changed, 84 insertions(+), 20 deletions(-) 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 5cb48c4eb..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. @@ -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: {{}} From 4d23623c08e2794a0cb08f1c9946089c2aeeefea Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:08:47 +1000 Subject: [PATCH 41/57] Update Filecoin specification to align with FIP-0065 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIP-0065 simplifies the network circulating supply calculation by excluding built-in market actor locked balances. Key changes: - Circulating supply now only considers pledge collateral in "Locked" - Removed provider deal collateral from the calculation - Removed client deal collateral from the calculation - Removed pending deal payments from the calculation This change: - Simplifies the protocol as market balances are <0.1% of total locked - Prepares for direct data commitments bypassing the built-in market - Has negligible impact on consensus pledge calculations (~0.067%) The circulating supply formula is now: CirculatingSupply = Vested + Mined - Burnt - Locked where Locked = PledgeCollateral only 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_mining/miner_collaterals.md | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/content/systems/filecoin_mining/miner_collaterals.md b/content/systems/filecoin_mining/miner_collaterals.md index dc1c5513b..76519fae6 100644 --- a/content/systems/filecoin_mining/miner_collaterals.md +++ b/content/systems/filecoin_mining/miner_collaterals.md @@ -16,6 +16,9 @@ changes: - fip: FIP-0034 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0034.md description: Fixed pre-commit deposit to sector quality 10 value regardless of sector content. + - fip: FIP-0065 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0065.md + description: Simplified circulating supply calculation by excluding built-in market locked balances. --> 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). @@ -64,6 +67,24 @@ $SectorInitialConsensusPledge = 30\% \times FILCirculatingSupply \times \frac{Se {{}} +### 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 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. diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index 402d70ce6..abd72b271 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -33,6 +33,9 @@ changes: - fip: FIP-0052 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0052.md description: Increased maximum sector commitment duration from 540 days to 1278 days (3.5 years). + - fip: FIP-0067 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0067.md + description: Established PoRep security policy and replacement sealing enforcement mechanism. --> 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. @@ -115,3 +118,45 @@ The process works by: 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. + +## 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. From f3de65488fe117d305cda89f337cc699d20510cd Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:14:58 +1000 Subject: [PATCH 43/57] Update Filecoin specification to align with FIP-0071 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIP-0071 introduces deterministic state access rules to ensure actors can only read state reachable from their execution context. Key updates: - Added "reachable set" concept for tracking accessible IPLD blocks - Documented state access rules for reading, writing, and root updates - Specified IPLD link analysis for extracting CID references - Added gas charges for state access operations: * ipld_link_tracked: 550 gas per reachable CID tracked * ipld_link_checked: 500 gas per CID reachability check * ipld_cbor_scan_per_field: 85 gas per CBOR field * ipld_cbor_scan_per_cid: 950 gas per CID in CBOR These rules prevent consensus forks by ensuring actors cannot access arbitrary blocks that may exist in some nodes but not others. Essential for supporting user-defined WebAssembly actors securely. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/_index.md | 70 +++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/content/systems/filecoin_vm/_index.md b/content/systems/filecoin_vm/_index.md index 0ea870e6c..314fabd8f 100644 --- a/content/systems/filecoin_vm/_index.md +++ b/content/systems/filecoin_vm/_index.md @@ -23,6 +23,9 @@ changes: - fip: FIP-0050 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0050.md description: Restricted built-in actor method invocation and defined stable public APIs for user actors. + - fip: FIP-0071 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0071.md + description: Introduced deterministic state access rules to ensure actors can only read state reachable from their state-tree. --> An Actor in the Filecoin Blockchain is the equivalent of the smart contract in the Ethereum Virtual Machine. @@ -143,3 +146,70 @@ The EVM runtime actor exposes these main methods: ## 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. From a221643243ae133f27ab044c1c2ccf42ffa26200 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:17:33 +1000 Subject: [PATCH 44/57] Update Filecoin specification to align with FIP-0072 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIP-0072 improves the event syscall API to eliminate CBOR encoding overhead and enable precise gas charging. Key updates: - Changed emit_event syscall from single CBOR buffer to three buffers: * event_off/len: Array of EventEntry structs * key_off/len: Concatenated keys buffer * value_off/len: Concatenated values buffer - Reduced limits for compact CBOR encoding: * Max key size: 31 bytes (from 32) * Max entries: 255 (from 256) - Introduced EventEntry packed struct (flags, codec, key_size, value_size) - Removed indexing costs from gas model (feature unused) - Added new gas parameters for accurate charging: * p_gas_event: 2000 (base fee per event) * p_gas_event_per_entry: 1400 (per entry fee) * p_gas_utf8_validation: 500 + 16/byte This optimization enables non-EVM actors to safely emit events with predictable gas costs and concurrent validation during deserialization. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/runtime/_index.md | 48 +++++++++++++++++-- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/content/systems/filecoin_vm/runtime/_index.md b/content/systems/filecoin_vm/runtime/_index.md index 0a3149eb2..4d893fe85 100644 --- a/content/systems/filecoin_vm/runtime/_index.md +++ b/content/systems/filecoin_vm/runtime/_index.md @@ -18,6 +18,9 @@ changes: - fip: FIP-0049 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0049.md description: Added events_root field to support actor events. + - fip: FIP-0072 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0072.md + description: Improved event syscall API with separate buffers and refined limits. --> 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. @@ -102,11 +105,50 @@ fn emit_event(event_off: u32, event_len: u32) -> Result<()>; ### Event Limits -- Maximum 32 bytes per key +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 256 entries 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: @@ -114,4 +156,4 @@ Events support indexing hints through flags: - `0x02`: Index by value - `0x03`: Index by both key and value -These flags are hints to clients for constructing efficient indices for event queries. +Note: Since FIP-0072, indexing costs have been removed from gas calculations as this feature was not being used. From e65c59e69c0aa1452bb76b603fb748116d2ac139 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:21:44 +1000 Subject: [PATCH 45/57] Update Filecoin specification to align with FIP-0073 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIP-0073 simplifies the self_destruct syscall by removing the beneficiary parameter and requiring explicit fund transfers. Key changes: - Changed self_destruct(beneficiary) to self_destruct(burn: bool) - If burn=false and funds remain, syscall fails with IllegalOperation - If burn=true, remaining funds are burnt (sent to f099) - Actors must now explicitly transfer funds before destruction This change ensures: - All fund transfers use standard send messages - Transfers appear properly in execution traces - Consistent behavior with normal sends (auto-creates recipients) - Avoids potential reentrancy issues in future The payment channel actor is the only built-in actor using this syscall. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_token/payment_channels.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) 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. From c9897c8d907042a686a4b8f695281cd64c34dca4 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:23:56 +1000 Subject: [PATCH 46/57] Update Filecoin specification to align with FIP-0074 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit FIP-0074 removes automatic cron-based deal settlement for new deals to prevent cron from overtaking chain processing capacity. Key changes: - Added SettleDealPayments method for manual deal settlement - New deals no longer scheduled for automatic settlement - Existing deals continue automatic settlement until expiration - OnMinerSectorsTerminate now immediately settles and cleans up - GetDealActivation always fails for terminated deals Manual settlement: - Storage providers explicitly settle payment-bearing deals - Can batch multiple deals to optimize gas costs - Zero-fee deals can remain unsettled indefinitely - Aligns gas costs with the benefiting party This change prevents cron execution from threatening chain progress as deal volume grows, while enabling fair competition with future user-programmed storage markets. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../storage_market_actor.md | 63 ++++++++++++++++--- 1 file changed, 53 insertions(+), 10 deletions(-) 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 7b5a597d4..7604bb88d 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 @@ -22,6 +22,9 @@ changes: - fip: FIP-0060 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0060.md description: Increased deal maintenance interval from 1 day to 30 days to reduce cron execution costs. + - fip: FIP-0074 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0074.md + description: Removed automatic deal settlement for new deals, added manual SettleDealPayments method. --> # Storage Market Actor @@ -69,24 +72,64 @@ This change significantly improves the user experience for storage providers by 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 Cron Operations +## Deal Maintenance and Settlement -The Storage Market Actor performs regular maintenance on active deals through Filecoin's cron mechanism. This maintenance includes: +### 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 -### Maintenance Interval +Since FIP-0074, automatic settlement only applies to deals activated before the upgrade. New deals require manual settlement. + +### Manual Deal Settlement -Since FIP-0060, the deal maintenance interval has been increased from 1 day (2,880 epochs) to 30 days (86,400 epochs): +FIP-0074 introduced the `SettleDealPayments` method to allow storage providers to manually settle deal payments: ```rust -const DEAL_UPDATES_INTERVAL = 30 * EPOCHS_IN_DAY +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 +} ``` -This change significantly reduces the computational burden on the network: -- **Previous cost**: ~73 billion gas units per epoch for market cron operations -- **Current cost**: ~2.4 billion gas units per epoch (97% reduction) -- **Impact**: Improved chain validation times and reduced resource requirements +#### 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 -Each deal's maintenance is scheduled based on its deal ID modulo the maintenance interval, ensuring an even distribution of maintenance work across epochs. The rescheduling happens automatically when deals are first processed after the FIP activation, requiring no migration. +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) From d5e7819abe1f7df3631ba24bd4e213985819ec6d Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:29:10 +1000 Subject: [PATCH 47/57] Update Filecoin specification to align with FIP-0075 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the improvements to FVM randomness syscalls introduced in FIP-0075. Key changes: - Moved entropy mixing from FVM syscalls to actor code - syscalls now return raw randomness - Documented the draw_randomness algorithm that actors must use to mix entropy - Added proportional gas costs for randomness and tipset CID lookback operations (75 * lookback + 146,200) - Updated randomness.md with FVM syscall details and gas cost formula - Updated gas_fee.md with new randomness lookback cost section These changes ensure accurate gas charging for chain traversal operations and simplify the FVM by moving entropy mixing to userspace. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/crypto/randomness.md | 54 +++++++++++++++++++++++++ content/systems/filecoin_vm/gas_fee.md | 20 +++++++++ 2 files changed, 74 insertions(+) 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/systems/filecoin_vm/gas_fee.md b/content/systems/filecoin_vm/gas_fee.md index d89daae0c..b42f5963a 100644 --- a/content/systems/filecoin_vm/gas_fee.md +++ b/content/systems/filecoin_vm/gas_fee.md @@ -65,6 +65,9 @@ changes: - fip: FIP-0057 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0057.md description: Updated gas charging schedule for FEVM, increased storage costs, and introduced memory limits. + - fip: FIP-0075 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0075.md + description: Introduced proportional gas costs for randomness and tipset CID lookback operations. --> 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. @@ -157,3 +160,20 @@ FIP-0057 introduced system-wide limits to prevent resource exhaustion: - **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. From 050702ea741433bf0a7dda914fbfb2a4c7509b9a Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:32:57 +1000 Subject: [PATCH 48/57] Update Filecoin specification to align with FIP-0076 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect direct data onboarding introduced in FIP-0076. Key changes: - Updated adding_storage.md with ProveCommitSectors3 and ProveReplicaUpdates3 methods - Documented direct onboarding workflow that bypasses built-in market deals - Added provider-sector mapping and SectorContentChanged method to market actor - Documented piece manifests, verified allocations, and actor notifications - Listed deprecated methods (PreCommitSector, PreCommitSectorBatch, ProveReplicaUpdates2) - Added GetDealSector method for deal-sector lookups Direct data onboarding significantly reduces gas costs for common use cases like verified deals without on-chain payments, enabling more efficient data commitment to the Filecoin network. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../storage_market_actor.md | 63 +++++++++++++++++ .../filecoin_mining/sector/adding_storage.md | 68 ++++++++++++++++++- 2 files changed, 129 insertions(+), 2 deletions(-) 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 7604bb88d..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 @@ -25,6 +25,9 @@ changes: - fip: FIP-0074 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0074.md description: Removed automatic deal settlement for new deals, added manual SettleDealPayments method. + - fip: FIP-0076 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0076.md + description: Added provider-sector mapping, SectorContentChanged method, and support for direct data onboarding. --> # Storage Market Actor @@ -133,3 +136,63 @@ 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_mining/sector/adding_storage.md b/content/systems/filecoin_mining/sector/adding_storage.md index 8027a8ee9..e566722de 100644 --- a/content/systems/filecoin_mining/sector/adding_storage.md +++ b/content/systems/filecoin_mining/sector/adding_storage.md @@ -7,12 +7,24 @@ 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.ProveCommitSector` or `miner.ProveCommitAggregate` - Traditional methods requiring built-in market deals + - `miner.ProveCommitSectors3` - Direct data onboarding method that bypasses the built-in market actor + + 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: @@ -39,3 +51,55 @@ To incentivize Miners to hoard storage space and dedicate it to Filecoin, CC Sec 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. From 6b97d14cd9197c07e513675d35a6067900b34673 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:37:15 +1000 Subject: [PATCH 49/57] Update Filecoin specification to align with FIP-0079 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect BLS aggregate signature support in the FVM introduced in FIP-0079. Key changes: - Added FVM syscall verify_bls_aggregate for BLS aggregate signature verification - Documented removal of generic verify_signature syscall - Added gas pricing formula for aggregate signature verification - Documented SDK functions for signature verification - Explained that verify_signature SDK function now uses specialized syscalls The verify_bls_aggregate syscall supports both aggregate and non-aggregate BLS signatures, enforces plaintext uniqueness, and uses proportional gas pricing based on number of signatures and plaintext size. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/algorithms/crypto/signatures.md | 63 +++++++++++++++++++++++++ 1 file changed, 63 insertions(+) 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 From 138600d0ef82784d2b7129d74aa8807bc58e238e Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:39:45 +1000 Subject: [PATCH 50/57] Update Filecoin specification to align with FIP-0081 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect the lower bound for sector initial pledge introduced in FIP-0081. Key changes: - Split consensus pledge into simple (30%) and baseline (70%) components - Added formulas for SimpleConsensusPledge and BaselineConsensusPledge - Documented gamma parameter and 1-year linear ramp from 1.0 to 0.7 - Explained how the simple component provides a floor to prevent pledge from falling to zero The factored pledge calculation preserves network security by ensuring pledge requirements approach 30% of pre-baseline-crossing values rather than zero, even when the exponential baseline function exceeds network QAP. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_mining/miner_collaterals.md | 29 +++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/content/systems/filecoin_mining/miner_collaterals.md b/content/systems/filecoin_mining/miner_collaterals.md index 76519fae6..64c8e7ae0 100644 --- a/content/systems/filecoin_mining/miner_collaterals.md +++ b/content/systems/filecoin_mining/miner_collaterals.md @@ -19,6 +19,9 @@ changes: - fip: FIP-0065 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0065.md description: Simplified circulating supply calculation by excluding built-in market locked balances. + - fip: FIP-0081 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0081.md + description: Introduced lower bound for sector initial pledge by splitting consensus pledge into simple and baseline components. --> 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). @@ -59,14 +62,36 @@ $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 = 30\% \times FILCirculatingSupply \times \frac{SectorQAP}{max(NetworkBaseline, NetworkQAP)}$ +$SectorInitialConsensusPledge = (1 - \gamma) \times SimpleConsensusPledge + \gamma \times BaselineConsensusPledge$ {{}} +where: + +{{}} + +$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. From 716408bef0fe5596b4760fd5ff978eaf30b832cb Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:42:11 +1000 Subject: [PATCH 51/57] Update Filecoin specification to align with FIP-0082 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect aggregated replica update proofs introduced in FIP-0082. Key changes: - Added section on aggregated replica updates in ProveReplicaUpdates3 - Documented minimum (3) and maximum (512) sectors per aggregation - Listed gas cost structure: linear (80k/sector) plus step-wise components - Explained SnarkPack V2 usage and logarithmic scaling benefits - Added gas cost tables for 32 GiB and 64 GiB sectors Aggregated proofs significantly reduce per-sector costs for replica updates, making Snap Deals more economically viable when updating multiple sectors. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../filecoin_mining/sector/lifecycle.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/content/systems/filecoin_mining/sector/lifecycle.md b/content/systems/filecoin_mining/sector/lifecycle.md index abd72b271..b8e0256e4 100644 --- a/content/systems/filecoin_mining/sector/lifecycle.md +++ b/content/systems/filecoin_mining/sector/lifecycle.md @@ -36,6 +36,9 @@ changes: - fip: FIP-0067 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0067.md description: Established PoRep security policy and replacement sealing enforcement mechanism. + - fip: FIP-0082 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0082.md + description: Added support for aggregated replica update proofs in ProveReplicaUpdates3. --> 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. @@ -119,6 +122,22 @@ This mechanism unlocks the large amount of CC capacity already committed to the 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. From 971e30a23ba87e9e90c9ecb80db3395e0fb81216 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:44:07 +1000 Subject: [PATCH 52/57] Update Filecoin specification to align with FIP-0083 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit updates the specification to reflect built-in actor events introduced in FIP-0083. Key changes: - Added section on built-in actor events with CBOR encoding support - Listed verified registry events: balance updates, allocations, claims - Listed market actor events: deal published, activated, terminated, completed - Listed miner actor events: sector pre-committed, activated, updated, terminated - Noted that event payloads are minimal to reduce gas costs Built-in actor events enable external observability tools to track state transitions without relying on complex state tree diffs or message replays. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/systems/filecoin_vm/runtime/_index.md | 32 +++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/content/systems/filecoin_vm/runtime/_index.md b/content/systems/filecoin_vm/runtime/_index.md index 4d893fe85..c35aa6d33 100644 --- a/content/systems/filecoin_vm/runtime/_index.md +++ b/content/systems/filecoin_vm/runtime/_index.md @@ -21,6 +21,9 @@ changes: - fip: FIP-0072 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0072.md description: Improved event syscall API with separate buffers and refined limits. + - fip: FIP-0083 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0083.md + description: Added built-in actor events for verified registry, market, and miner actors. --> 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. @@ -157,3 +160,32 @@ Events support indexing hints through flags: - `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. From 62c9bd20cf2b6cadc071210b39da72a33e5ff268 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:46:37 +1000 Subject: [PATCH 53/57] Update Filecoin specification to align with FIP-0084 Remove references to ProveCommitSector method which has been deprecated to eliminate gas subsidy imbalance and reduce cron overhead. Storage providers must now use ProveCommitAggregate or ProveCommitSectors3 for sector activation. - Update ProveCommitting section to only mention available methods - Add YAML change history for FIP-0084 --- content/systems/filecoin_mining/sector/adding_storage.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/content/systems/filecoin_mining/sector/adding_storage.md b/content/systems/filecoin_mining/sector/adding_storage.md index e566722de..7e58486a1 100644 --- a/content/systems/filecoin_mining/sector/adding_storage.md +++ b/content/systems/filecoin_mining/sector/adding_storage.md @@ -13,6 +13,9 @@ changes: - fip: FIP-0076 pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0076.md description: Added direct data onboarding methods ProveCommitSectors3 and ProveReplicaUpdates3 that bypass built-in market deals. + - fip: FIP-0084 + pr-url: https://github.com/filecoin-project/FIPs/blob/master/FIPS/fip-0084.md + description: Removed ProveCommitSector method to eliminate gas subsidy imbalance and reduce cron overhead. --> # Adding Storage @@ -21,8 +24,8 @@ A Miner adds more storage in the form of Sectors. Adding more storage is a two-s 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.ProveCommitSector` or `miner.ProveCommitAggregate` - Traditional methods requiring built-in market deals - - `miner.ProveCommitSectors3` - Direct data onboarding method that bypasses the built-in market actor + - `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. From d3dfa1d3efb9b05c875f9e30829757bdb17c09bf Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Thu, 10 Jul 2025 22:49:38 +1000 Subject: [PATCH 54/57] Update Filecoin specification to align with FIP-0085 Convert f090 Mining Reserve actor from multisig to keyless account actor for decentralized governance. This ensures mining reserve funds can only be distributed through FIP proposals and network upgrades. - Update token allocation documentation to describe f090 as keyless account - Add special system actors section documenting keyless account actors - Add YAML change history for FIP-0085 --- .../filecoin_token/token_allocation/_index.md | 12 +++++++++++- content/systems/filecoin_vm/sysactors/_index.md | 12 ++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) 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/sysactors/_index.md b/content/systems/filecoin_vm/sysactors/_index.md index ae06faec9..f33283b30 100644 --- a/content/systems/filecoin_vm/sysactors/_index.md +++ b/content/systems/filecoin_vm/sysactors/_index.md @@ -111,3 +111,15 @@ Since FIP-0055, the `EthereumAccountActor` represents Ethereum Externally-Owned - **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. From ee44919e306482af29cd8c94139317dbd7fc7a15 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Fri, 11 Jul 2025 11:29:01 +1000 Subject: [PATCH 55/57] Update Filecoin specification to align with FIP-0086 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add Fast Finality in Filecoin (F3) documentation: - Add F3 definition to glossary - Update finality definition to include both EC soft finality and F3 fast finality 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- content/glossary/_index.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/content/glossary/_index.md b/content/glossary/_index.md index e8aa58427..430cc6f7a 100644 --- a/content/glossary/_index.md +++ b/content/glossary/_index.md @@ -124,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. @@ -150,6 +161,15 @@ Filecoin Plus is a program (previously called Verified Clients) that aims to max [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. From 960df6257a484bcab5ca3d203ddd2b975d1f9202 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Fri, 11 Jul 2025 12:48:15 +1000 Subject: [PATCH 56/57] Add .gitignore to exclude workspace metadata files --- spec/.gitignore | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 spec/.gitignore 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 From f234b8390473ed5c96fc991e3a992ce23f643395 Mon Sep 17 00:00:00 2001 From: Adrian Lanzafame Date: Fri, 11 Jul 2025 12:50:37 +1000 Subject: [PATCH 57/57] Update Filecoin specification to align with FIP-0091 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add support for Homestead and EIP-155 Ethereum Transactions: - Document delegated signature types for different Ethereum transaction formats - Add glossary entries for Homestead and EIP-155 transactions - Explain transaction identification by signature length and marker bytes 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- spec/content/algorithms/crypto/signatures.md | 229 +++++++++ spec/content/glossary/_index.md | 504 +++++++++++++++++++ 2 files changed, 733 insertions(+) create mode 100644 spec/content/algorithms/crypto/signatures.md create mode 100644 spec/content/glossary/_index.md 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.