fix(content): on-chain storage market update (#1179)

Co-authored-by: zixuanzh <[email protected]>
Co-authored-by: Hugo Dias <[email protected]>

content/systems/filecoin_markets/onchain_storage_market/_index.md

@@ -3,7 +3,7 @@ title: Storage Market On-Chain Components
 weight: 2
 bookCollapseSection: true
 dashboardWeight: 2
-dashboardState: wip
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---
@@ -12,12 +12,12 @@ dashboardTests: 0
 
 ## Storage Deals
 
-There are two types of deals in Filecoin markets, storage deals and retrieval deals. Storage deals are recorded on the blockchain and enforced by the protocol. Retrieval deals are off chain and enabled by micropayment channel by transacting parties (see [Retrieval Market](retrieval_market) for more information). 
+There are two types of deals in Filecoin markets, storage deals and retrieval deals. Storage deals are recorded on the blockchain and enforced by the protocol. Retrieval deals are off chain and enabled by a micropayment channel between transacting parties (see [Retrieval Market](retrieval_market) for more information).
 
 The lifecycle of a Storage Deal touches several major subsystems, components, and protocols in Filecoin.
 
-This section describes the storage deal data type and a technical outline for deal flow in terms of how all the components involved and the functions they call on each other. For more detail and prose explanations, see [Storage Market](storage_market) and [Storage Mining](storage_mining).
+This section describes the storage deal data type and provides a technical outline of the deal flow in terms of how all the components interact with each other, as well as the functions they call. For more detail on the off-chain parts of the storage market see the [Storage Market section](storage_market).
 
 ## Data Types
 
-{{< embed src="https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/deal.go" lang="go" >}}
+{{<embed src="https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/deal.go" lang="go">}}

content/systems/filecoin_markets/onchain_storage_market/faults.md

@@ -2,26 +2,18 @@
 title: "Faults"
 weight: 4
 dashboardWeight: 2
-dashboardState: wip
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---
 
 # Faults
 
-There are two main categories of faults in the Filecoin network. 
+There are two main categories of faults in the Filecoin network:
 
-- ConsensusFaults
-- StorageDealFaults
+1. [Storage or Sector Faults](sector#sector-faults) that relate with the failure to store files agreed in a deal previously due to a hardware error or malicious behaviour, and
+2. [Consensus Faults](expected_consensus#consensus-faults) that relate to a miner trying deviate from the protocol in order to gain more power than their storage deserves.
 
-ConsensusFaults are faults that impact network consensus and StorageDealFaults are faults where data in a `StorageDeal` is not maintained by the providers pursuant to deal terms.
+Please refer to the corresponding sections for more details.
 
-[Pledge Collateral](storage_power_actor#pledge-collateral) is slashed for ConsensusFaults and Storage Deal Collateral for StorageDealFaults.
-
-Any misbehavior may result in more than one fault thus lead to slashing on both collaterals. For example, missing a `PoStProof` will incur a penalty on both `PledgeCollateral` and `StorageDealCollateral` given it impacts both a given `StorageDeal` and power derived from the sector commitments in [Storage Power Consensus](storage_power_consensus).
-
-## Storage Faults
-
-{{<hint warning>}}
-TODO: complete this.
-{{</hint>}}
+Both Storage and Consensus Faults come with penalties that slash the miner's collateral. See more details on the different types of collaterals in the [Miner Collaterals](filecoin_mining#miner_collaterals).

content/systems/filecoin_markets/onchain_storage_market/storage_deal_flow.md

@@ -2,7 +2,7 @@
 title: Deal Flow
 weight: 2
 dashboardWeight: 2
-dashboardState: wip
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---
@@ -16,7 +16,11 @@ dashboardTests: 0
 1. `StorageClient` and `StorageProvider` call `StorageMarketActor.AddBalance` to deposit funds into Storage Market.
    - `StorageClient` and `StorageProvider` can call `WithdrawBalance` before any deal is made.
 2. `StorageClient` and `StorageProvider` negotiate a deal off chain. `StorageClient` sends a `StorageDealProposal` to a `StorageProvider`.
-   - `StorageProvider` verifies the `StorageDeal` by checking address and signature of `StorageClient`, checking the proposal's `StartEpoch` is after the current Epoch, checking `StorageClient` did not call withdraw in the last X Epoch (`WithdrawBalance` should take at least X Epoch), checking both `StorageProvider` and `StorageClient` have sufficient available balances in `StorageMarketActor`.
+   - `StorageProvider` verifies the `StorageDeal` by checking:
+   		- the address and signature of the `StorageClient`,
+   		- the proposal's `StartEpoch` is after the current Epoch,
+   		- (tentative) the `StorageClient` did not call withdraw in the last *X* epochs (`WithdrawBalance` should take at least *X* epochs) - *X* is currently set to 0, but the setting will be re-considered in the near future.
+   		- both `StorageProvider` and `StorageClient` have sufficient available balances in `StorageMarketActor`.
 3. `StorageProvider` signs the `StorageDealProposal`  by constructing an on-chain message.
    - `StorageProvider` calls `PublishStorageDeals` in `StorageMarketActor` to publish this on-chain message which will generate a `DealID` for each `StorageDeal` and store a mapping from `DealID` to `StorageDeal`. However, the deals are not active at this point.
      - As a backup, `StorageClient` may call `PublishStorageDeals` with the `StorageDeal`, to activate the deal if they can obtain the signed on-chain message from `StorageProvider`.
@@ -25,30 +29,32 @@ dashboardTests: 0
 
 ## Sealing sectors
 
-4. Once the miner finishes packing a `Sector`, it generates a SectorPreCommitInfo and calls PreCommitSector with a PreCommitDeposit. It must call ProveCommitSector with SectorProveCommitInfo within some bound to recover the deposit. An expired PreCommit message will result in PreCommitDeposit being burned. There are two types of sectors, Regular Sector and Committed Capacity Sector but all sectors have an explicit expiration epoch declared during PreCommit. For a Regular Sector with storage deals in it, all deals must expire before sector expiration. Miner gains power for this particular sector upon successful ProveCommit.
+4. Once a miner finishes packing a `Sector`, it generates a `SectorPreCommitInfo` and calls `PreCommitSector` with a `PreCommitDeposit`. It must call `ProveCommitSector` with `SectorProveCommitInfo` within some bound to recover the deposit. Initial pledge will then be required at `ProveCommit`. Initial Pledge is usually higher than `PreCommitDeposit`. Recovered `PreCommitDeposit` will count towards Initial Pledge and miners only need to top up additional funds at `ProveCommit`. Excess `PreCommitDeposit`, when it is greater than Initial Pledge, will be returned to the miner. An expired `PreCommit` message will result in `PreCommitDeposit` being burned. All Sectors have an explicit expiration epoch declared during `PreCommit`. For sectors with deals, all deals must expire before sector expiration. The Miner gains power for this particular sector upon successful `ProveCommit`. For more details on the Sectors and the different types of deals that can be included in a Sector refer to the [Sector section](filecoin_mining#sector).
 
-## Receive Challenge
+## Prove Storage
 
-5. Miners enter the `Challenged` status when receiving a SurprisePoSt challenge from the chain. Miners will then have X Epoch as the ProvingPeriod to submit a successful PoSt before the chain checks for SurprisePoSt expiry. Miners can only get out the challenge with `SubmitSurprisePoStResponse`.
-6. Miners are allowed to DeclareTemporaryFault when they are in the `Challenged` state but this will not change the list of sectors challenged as `Challenged` state specifies a list of sectors to be challenged which is a snapshot of all Active sectors at the time of challenge. Miners are also allowed to call ProveCommit which will add to their ClaimedPower but their Nominal and Consensus Power are still zero whe  they are in either Challenged or DetectedFault state.
+5. Miners have to prove that they hold unique copies of Sectors by submitting proofs according to the [Proof of SpaceTime](post) algorithm. Miners have to prove all their Sectors in regular time intervals in order for the system to guarantee that they indeed store the data they committed to store in the deal phase.
 
 ## Declare and Recover Faults
 
-7. Declared faults are penalized to a smaller degree than DetectedFault. Miners declare failing sectors by invoking `DeclareTemporaryFaults` with a specified fault duration and associated `TemporaryFaultFee`. Miner will lose power associated with the sector when the TemporaryFault period begins.
-8. The loss of power associated with TemporaryFault will be restored when the TemporaryFault period has ended and the miner is now expected to prove over that sector. Failure to do so will result in unsuccessful ElectionPoSt or unsuccessful SurprisePoSt that leads to detected faults.
+6. Miners can call `DeclareFaults` to mark certain Sectors as faulty to avoid paying Sector Fault Detection Fee. Power associated with the sector will be removed at fault declaration.
+7. Miners can call `DeclareFaultsRecovered` to mark previously faulty sector as recovered. Power will be restored when recovered sectors pass WindowPoSt checks successfully.
+8. A sector pays a Sector Fault Fee for every proving period during which it is marked as faulty.
 
+## Skipped Faults
+9. After a WindowPoSt deadline opens, a miner can mark one of their sectors as faulty and exempted by WindowPoSt checks, hence Skipped Faults. This could avoid paying a Sector Fault Detection Fee on the whole partition.
 
-## Detect Faults
+## Detected Faults
 
-9. `CronActor` triggers `StorageMinerActor._rtCheckSurprisePoStExpiry` through `StoragePowerActor` and checks if SurprisePoSt challenge has expired for a particular miner.
-   - If no PoSt is submitted by the end of the `ProvingPeriod`, miner enters `DetectedFault` state, some `PledgeCollateral` is slashed, and all power is lost.
-   - Miners will now have to wait for the next SurprisePoSt challenge.
-   - If the faults persist for `MAX_CONSECUTIVE_FAULTS` then sectors are terminated and provider deal collateral is slashed. 
+10. If a partition misses a WindowPoSt submission deadline, all previously non-faulty sectors in the partition are detected as faulty and a Fault Detection Fee is charged. 
 
 ## Sector Expiration
 
-10. Sector expiration is done via a scheduled Cron event `_rtCheckSectorExpiry`. Sector expires when its Expiration epoch is reached and sector expiration epoch must be greater than the expiration epoch of all its deals.
+11. Sector expires when its expiration epoch is reached and sector expiration epoch must be greater than the expiration epoch of all its deals.
+
+## Sector Termination
+12. Termination of a sector can be triggered in two ways. One when sector remains faulty for 14 consecutive days and the other when a miner initiates a termination by calling `TerminateSectors`. In both cases, a `TerminationFee` is penalized, which is in principle equivalent to how much the sector has earned so far. Miners are also penalized for the `DealCollateral` that the sector contains and remaining `DealPayement` will be returned to clients.
 
 ## Deal Payment and slashing
 
-11.  Deal payment and slashing are evaluated lazily through `_updatePendingDealState` at WithdrawBalance and PublishStorageDeals events. The method is also called at `OnEpochTickEnd` on StorageMarketActor as a clean up mechanism.
+13.  Deal payment and slashing are evaluated lazily through `updatePendingDealState` called at `CronTick`.

content/systems/filecoin_markets/onchain_storage_market/storage_deal_states.md

@@ -2,14 +2,14 @@
 title: Deal States
 weight: 3
 dashboardWeight: 2
-dashboardState: wip
+dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
 ---
 
 # Storage Deal States
 
-All on-chain economic activities in Filecoin start with the deal. This section aims to explain different states of a deal and their relationship with other concepts in the protocol such as Power, Payment, and Collaterals.
+All on-chain economic activities in Filecoin start with the storage deal. This section aims to explain different states of a storage deal and their relationship with other concepts in the protocol such as Power, Payment, and Collaterals.
 
 A deal has the following states:
 

content/systems/filecoin_markets/onchain_storage_market/storage_market_actor.md

@@ -5,17 +5,26 @@ dashboardWeight: 2
 dashboardState: reliable
 dashboardAudit: missing
 dashboardTests: 0
+math-mode: true
 ---
 
 # Storage Market Actor
 
-`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. 
+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. 
 
-{{<embed src="https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/market_state.go" lang="go" symbol="State" title="Storage Market Actor State">}}
+## `StorageMarketActor` implementation
 
-{{<embed src="https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/market_actor.go" lang="go" title="Storage Market Actor" >}}
+{{<embed src="https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/market_actor.go" lang="go">}}
+
+## `StorageMarketActorState` implementation
+
+**Storage Market Actor Statuses**
+{{<embed src="https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/market_state.go" lang="go">}}
+
+**Storage Market Actor Balance states and mutations**
+
+{{<embed src="https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/market_balances.go" lang="go">}}
 
-The Storage Market Actor Balance states and mutations can be found [here](https://github.com/filecoin-project/specs-actors/blob/master/actors/builtin/market/market_balances.go).
 
 ## Storage Deal Collateral
 
@@ -27,7 +36,6 @@ Provider deal collateral is only slashed when a sector is terminated before the
 
 This collateral is returned to the storage provider when all deals in the sector successfully conclude. Upon graceful deal expiration, storage providers must wait for finality number of epochs (as defined in [Finality](expected_consensus#finality-in-ec)) before being able to withdraw their `StorageDealCollateral` from the `StorageMarketActor`.
 
-
-{{<katex>}}
-$MinimumProviderDealCollateral = \\[0.2cm] \ \ \ \ \ \ \ \ 5\% \times FILCirculatingSupply \times \frac{DealRawByte}{max(NetworkBaseline, NetworkRawBytePower)}$
-{{</katex>}}
+```text
+$$MinimumProviderDealCollateral = 1\% \times FILCirculatingSupply \times \frac{DealRawByte}{max(NetworkBaseline, NetworkRawBytePower)}$$
+```