Merge remote-tracking branch 'origin/beta' into feat/color-scheme-toggle

.github/workflows/main.yml

@@ -21,7 +21,7 @@ jobs:
 
       # Pin the built site to ipfs-cluster, output the cid as `steps.ipfs.outputs.cid`
       # see: https://github.com/ipfs-shipyard/ipfs-github-action
-      - uses: ipfs-shipyard/ipfs-github-action@v1.0.0
+      - uses: ipfs-shipyard/ipfs-github-action@v2.0.0
         id: ipfs
         with:
           path_to_add: public

README.md

@@ -45,7 +45,19 @@ You can find examples in the `config.toml`
     source = "actors"
     target = "content/modules/actors"
 ```
-This makes files from external repos available for Hugo rendering.  
+This makes files from external repos available for Hugo rendering and allows for linking to up-to-date files that are directly pulled from other repositories.
+
+The configuration above gives the following information:
+
+- `path`: gives the repository you want to mount content from.
+- `source`: the folder from the repository referenced in the `path` that we want to mount into  our local Hugo filesystem. This is the "root" seen from your Hugo site where you pull content from. In the above case, this means that the source that will be mounted is `https://github.com/filecoin-project/specs-actors/actors/`.
+- `target`: the folder in your local Hugo site where the mounted content appears. In our case folder `content` is where we include all Hugo content.
+
+Putting everything together in an example: if you want to link to the file `xyz.go` from `https://github.com/filecoin-project/specs-actors/actors/xyz-folder/xyz.go`, from any file within the local folder `content` (or any of its subfolders), then with the above configuration you have to include:
+
+```
+{{<embed src="/modules/actors/xyz-folder/xyz.go"  lang="go">}}
+```
 
 These modules can be updated with 
 
@@ -126,15 +138,28 @@ Some text
 ```
 
 ## Frontmatter
+
+Description for all the available frontmatter properties
+
 ```md
-title: Libraries
+<!-- Page Title to be used in the navigation -->
+title: Libraries 
+<!-- Small description for html metadata, if not present the first couple of paragraphs will be used instead -->
 description: Libraries used from Filecoin
+<!-- This will be used to order the navigation and any other listing of pages -->
 weight: 3
+<!-- This will make a page section collapse in the navigation -->
 bookCollapseSection: true
+<!-- This will hidden the page from the navigation -->
 bookhidden: true
+<!-- This is used in the dashboard to describe the importance of the page content -->
+dashboardWeight: 2
+<!-- This is used in the dashboard to describe the state of the page content options are "incorrect", "wip", "incomplete" and "stable" -->
+dashboardState: stable
+<!-- This is used in the dashboard to describe if the theory of the page has been audited, options are 1 or 0 -->
 dashboardAudit: 1
-dashboardState: wip
-dashboardInterface: stable
+<!-- This is used in the dashboard to describe if the page content has compliance tests, options are 0 or numbers of tests -->
+dashboardTests: 0
 ```
 
 ## Code fences
@@ -245,4 +270,4 @@ $\line{9}{\bi}{\return \BinTreeProof_c \thin \{\ \leaf, \thin \root, \thin \path
   - [editor](https://mermaid-js.github.io/mermaid-live-editor)
 - [Pan/Zoom for SVG](https://github.com/anvaka/panzoom)
 - [Icons](https://css.gg/)
-- [Working with submodules](https://github.blog/2016-02-01-working-with-submodules/)
+- [Working with submodules](https://github.blog/2016-02-01-working-with-submodules/)

assets/_colors.scss

@@ -0,0 +1,15 @@
+// Colors
+.text-incorrect {color: #ff0010;}
+.text-wip {color: #ff6f00;}
+.text-incomplete {color: #ffef00;}
+.text-stable {color: #90ff00;}
+.text-transparent { color: transparent;}
+.text-black { color: black;}
+
+.bg-na { background-color: #6c8293;}
+.bg-incorrect {background-color: #ff0010;}
+.bg-wip {background-color: #ff6f00;}
+.bg-incomplete {background-color: #ffef00;}
+.bg-stable {background-color: #90ff00;}
+.bg-transparent { background-color: transparent;}
+.bg-black { background-color: black;}

assets/_custom.scss

@@ -5,6 +5,9 @@
 // @import "plugins/numbered";
 @import "plugins/scrollbars";
 @import "plugins/toggles";
+@import "table-sort";
+@import "colors";
+@import "dashboard";
 
 // SVG Diagrams
 .diagrams-container {

assets/_dashboard.scss

@@ -0,0 +1,17 @@
+.Dashboard tr th,
+.Dashboard tr td {
+    padding: 0 1rem !important;
+    font-size: 12px;
+    text-align: center;
+}
+.Dashboard tr td:first-child {
+    text-align: left;
+}
+
+.Dashboard-section {
+    // max-width:250px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+

assets/_table-sort.scss

@@ -0,0 +1,37 @@
+th[role=columnheader]:not(.no-sort) {
+    cursor: pointer;
+    position: relative;
+    min-width: 110px;
+}
+
+th[role=columnheader]:not(.no-sort):after {
+	content: '';
+	position: absolute;
+    top: -3px;
+    right: 10px;
+	margin-top: 10px;
+	border-width: 0 4px 4px;
+	border-style: solid;
+	border-color: #404040 transparent;
+	visibility: hidden;
+	opacity: 0;
+	-ms-user-select: none;
+	-webkit-user-select: none;
+	-moz-user-select: none;
+	user-select: none;
+}
+
+th[aria-sort=ascending]:not(.no-sort):after {
+	border-bottom: none;
+	border-width: 4px 4px 0;
+}
+
+th[aria-sort]:not(.no-sort):after {
+	visibility: visible;
+	opacity: 0.4;
+}
+
+th[role=columnheader]:not(.no-sort):hover:after {
+	visibility: visible;
+	opacity: 1;
+}

config.toml

@@ -70,7 +70,7 @@ enableGitInfo = true
   # Enable "Edit this page" links for 'doc' page type.
   # Disabled by default. Uncomment to enable. Requires 'BookRepo' param.
   # Edit path must point to root directory of repo.
-  BookEditPath = 'edit/master'
+  BookEditPath = 'edit/beta'
 
   # Configure the date format used on the pages
   # - In git information

content/algorithms/_index.md

@@ -1,7 +1,9 @@
 ---
 title: Algorithms
-bookCollapseSection: true
-dashboardState: incorrect
-type: docs
 weight: 4
+
+dashboardWeight: 2
+dashboardState: wip
+dashboardAudit: 0
+dashboardTests: 0
 ---

content/algorithms/block_sync.md

@@ -1,6 +1,10 @@
 ---
 title: "BlockSync"
 weight: 5
+dashboardWeight: 1
+dashboardState: wip
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # BlockSync

content/algorithms/crypto/_index.md

@@ -2,10 +2,10 @@
 title: "Cryptographic Primitives"
 bookCollapseSection: true
 weight: 7
-entries:
-  - signatures
-  - vrf
-  - randomness
+dashboardWeight: 2
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Cryptographic Primitives

content/algorithms/crypto/randomness.md

@@ -1,6 +1,10 @@
 ---
 title: "Randomness"
 weight: 3
+dashboardWeight: 2
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Randomness
@@ -85,11 +89,7 @@ GetRandomness(dst, l, s):
     return H(buffer)
 ```
 
-{{< hint danger >}}
-Issue with readfile
-{{< /hint >}}
-
-{{<embed src="/docs/actors/actors/crypto/randomness.go"  lang="go">}}
+{{<embed src="/modules/actors/crypto/randomness.go"  lang="go">}}
 {{<embed src="/systems/filecoin_blockchain/struct/chain/chain.go" lang="go">}}
 
 ## Entropy to be used with randomness

content/algorithms/crypto/signatures.md

@@ -1,6 +1,10 @@
 ---
 title: "Signatures"
 weight: 1
+dashboardWeight: 2
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Signatures

content/algorithms/crypto/vrf.md

@@ -1,6 +1,10 @@
 ---
 title: "Verifiable Random Function"
 weight: 2
+dashboardWeight: 2
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Verifiable Random Function

content/algorithms/cryptoecon/_index.md

@@ -1,6 +1,10 @@
 ---
 title: Cryptoecon
 weight: 8
+dashboardWeight: 2
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Cryptoecon

content/algorithms/expected_consensus/_index.md

@@ -1,6 +1,10 @@
 ---
 title: "Expected Consensus"
 weight: 1
+dashboardWeight: 2
+dashboardState: incomplete
+dashboardAudit: 1
+dashboardTests: 0
 ---
 
 # Expected Consensus
@@ -201,23 +205,28 @@ This is detectable when a given miner submits two blocks that satisfy any of the
 - both blocks have valid signatures
 - first block's epoch is smaller or equal than second block
 
-Thereafter, the faults are:
+### Types of faults
 
-- 1. **double-fork mining fault**: two blocks mined at the same epoch.
+1. **Double-Fork Mining Fault**: two blocks mined at the same epoch (even if they have the same tipset).
    - `B4.Epoch == B5.Epoch` 
 {{< svg src="diagrams/double_fork.dot.svg" title="Double-Fork Mining Fault" >}}
 
-- 2. **time-offset mining fault**: two blocks mined off of the same Tipset at different epochs (i.e. with different `ChallengeTickets` generated from the same input ticket).
+2. **Time-Offset Mining Fault**: two blocks mined off of the same Tipset at different epochs.
    - `B3.Parents == B4.Parents && B3.Epoch != B4.Epoch`
 {{< svg src="diagrams/time_offset.dot.svg" title="Time-Offset Mining Fault" >}}
 
-- 3. **parent-grinding fault**: one block's parent is a Tipset that provably should have included a given block but does not. While it cannot be proven that a missing block was willfully omitted in general (i.e. network latency could simply mean the miner did not receive a particular block), it can when a miner has successfully mined a block two epochs in a row and omitted one. That is, this condition should be evoked when a miner omits their own prior block.
+3. **Parent-Grinding Fault**: one block's parent is a Tipset that provably should have included a given block but does not. While it cannot be proven that a missing block was willfully omitted in general (i.e. network latency could simply mean the miner did not receive a particular block), it can when a miner has successfully mined a block two epochs in a row and omitted one. That is, this condition should be evoked when a miner omits their own prior block.
 Specifically, this can be proven with a "witness" block, that is by submitting blocks B2, B3, B4 where B2 is B4's parent and B3's sibling but B3 is not B4's parent.
     - `!B4.Parents.Include(B3) && B4.Parents.Include(B2) && B3.Parents == B2.Parents && B3.Epoch == B2.Epoch`
 {{< svg src="diagrams/parent_grinding.dot.svg" title="Parent-Grinding fault" >}}
 
-Any node that detects any of the above events should submit both block headers to the `StoragePowerActor`'s `ReportConsensusFault` method. The "slasher" will receive a portion of the offending miner's [Pledge Collateral](storage_power_actor#pledge-collateral) as a reward for notifying the network of the fault. Consensus faults (except for **uncommitted power fault** below which falls under storage faults with impact on consensus) will tentatively result in all pledge collateral being slashed and the miner removed from the power table. Some portion of the pledge collateral is given to the slasher as a function of some initial share (`SLASHER_INITIAL_SHARE`) and growth rate (`SLASHER_SHARE_GROWTH_RATE`). Slasher's share of the slashed collateral increases as block elapses since the block when the fault is committed. Default growth rate results in slasher's share reaches 1 after 250 blocks. However, only the first slasher gets its share of the pledge collateral and the remaining pledge collateral will be burned. The longer a slasher waits, the higher the likelihood that the slashed collateral will be claimed by another slasher.
+### Penalization for faults
+A single consensus fault results into:
+- miner termination and removal of power from the power table,
+- loss of all pledge collateral (which includes the initial pledge and blocks rewards yet to be vested)
 
-It is important to note that there exists a third type of consensus fault directly reported by the `CronActor` on `StorageDeal` failures via the `ReportUncommittedPowerFault` method:
+### Detection and Reporting
 
-- 4. **uncommitted power fault** which occurs when a miner fails to submit their `PostProof` and is thus participating in leader election with undue power (see [Storage Faults](faults#storage-faults)).
+A node that detects and report 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 offending miner's [Pledge Collateral](storage_power_actor#pledge-collateral) for notifying the network of the consensu fault.
+
+The reward give 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.

content/algorithms/gossip_sub.md

@@ -1,6 +1,10 @@
 ---
 title: "GossipSub"
 weight: 6
+dashboardWeight: 1.5
+dashboardState: incomplete
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # GossipSub

content/algorithms/payment_channels.md

@@ -1,6 +1,10 @@
 ---
 title: "Payment Channels"
 weight: 4
+dashboardWeight: 1
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Payment Channels

content/algorithms/porep/_index.md

@@ -7,4 +7,6 @@ weight: 2
 # Proof-of-Replication
 ---
 
-{{< pdf src="https://filecoin.io/filecoin.pdf" title="Filecoin Paper">}}
+_Proof-of-Replication(PoRep)_, is a new kind of _Proof-of-Storage_, that can be used to prove that some data _D_ has been replicated to its own uniquely dedicated physical storage.  Enforcing unique physical copies enables a verifier to check that a prover is not deduplicating multiple copies of _D_ into the same storage space.  This construction is particularly useful in Cloud Computing and Decentralized Storage Networks, which must be transparently verifiable, resistant to Sybil attacks, and unfriendly to outsourcing.
+
+Section 3.2 of the [Filecoin Paper](https://filecoin.io/filecoin.pdf) provides the original introduction to Proof-of-Replication.

content/algorithms/post/_index.md

@@ -2,8 +2,24 @@
 title: Proof-of-Spacetime
 bookCollapseSection: true
 weight: 3
+dashboardWeight: 2
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Proof-of-Spacetime
 ---
-{{< pdf src="https://filecoin.io/filecoin.pdf" title="Filecoin Paper">}}
+_Proof-of-Storage_ schemes allow a user to check if a storage provider is storing the outsourced data at the time
+of the challenge. How can we use **PoS** schemes to prove that some data was being stored throughout a period
+of time? A natural answer to this question is to require the user to repeatedly (e.g. every minute) send
+challenges to the storage provider. However, the communication complexity required in each interaction can
+be the bottleneck in systems such as Filecoin, where storage providers are required to submit their proofs to
+the blockchain network.
+
+To address this question, we introduce a new proof, _Proof-of-Spacetime_, where a verifier can check if a prover
+is storing her/his outsourced data for a range of time. The intuition is to require the prover to (1) generate
+sequential Proofs-of-Storage (in our case Proof-of-Replication), as a way to determine time (2) recursively
+compose the executions to generate a short proof.
+
+Section 3.3 of the [Filecoin Paper](https://filecoin.io/filecoin.pdf) provides the original introduction to Proof-of-Spacetime.

content/algorithms/post/election_post.md

@@ -1,5 +1,9 @@
 ---
 title: Election PoSt
+dashboardWeight: 2
+dashboardState: incorrect
+dashboardAudit: 0
+dashboardTests: 0
 ---
 
 # Election PoSt

content/algorithms/post/proof_of_spacetime_parameters.org

@@ -1,6 +1,10 @@
 #+TITLE: PoSt Parameters
 #+HUGO_SECTION: algorithms/post
 #+HUGO_BASE_DIR: ../../
+#+dashboardWeight: 2
+#+dashboardState: incorrect
+#+dashboardAudit: 0
+#+dashboardTests: 0
 
 * Proof of Spacetime Paramerters