mining: fsm diagrams

hugo/layouts/shortcodes/diagram.html

@@ -1,8 +1,37 @@
+{{/* Get the filepath */}}
+{{/* If the first character is "/", the path is from the site's `baseURL`. */}}
+{{ if eq (.Get "src" | printf "%.1s") "/" }}
+
+{{/* Use Hugo `readfile` behavior of path from site's `baseURL`. */}}
+{{ $.Scratch.Set "filepath" ( .Get "src" ) }}
+
+{{ else }}
+
+{{/* Make relative: Fetch the current directory and then append it to the specified `file=""` value */}}
+{{ $.Scratch.Set "filepath" $.Page.Dir }}
+{{ $.Scratch.Add "filepath" ( .Get "src" ) }}
+
+{{ end }}
+
+
 
 <div class="diagram">
+
 <span class="diagram-title">{{ .Get "title" }}</span>
-(<a href="{{ .Get "src" }}" target="_blank">open in new tab</a>)
+
+{{/* Check if the specified file exists */}}
+{{ if fileExists ($.Scratch.Get "filepath") }}
+
+(<a href="{{ $.Scratch.Get "filepath" }}" target="_blank">open in new tab</a>)
+<br />
+<img src="{{ $.Scratch.Get "filepath" }}" />
+
+{{/* Say something if the file is not found and display the path that was specified in the shortcode (`file=" "`). */}}
+{{ else }}
+
 <br />
+<p style="color: #D74848"><b><i>Something's not right. The <code>{{ .Get "src" }}</code> file was not found.</i></b></p>
+
+{{ end }}
 
-<img src="{{ .Get "src" }}" />
 </div>

src/intro/arch.md

@@ -18,20 +18,20 @@ TODO:
 - reflect addition of Token system
   - move data_transfers into Token
 
-{{< diagram src="./docs/diagrams/overview1/overview.dot.svg" title="Protocol Overview Diagram" >}}
+{{< diagram src="../diagrams/overview1/overview.dot.svg" title="Protocol Overview Diagram" >}}
 
 
 # Protocol Flow Diagram -- deals off chain
 
-{{< diagram src="./docs/diagrams/sequence/full-deals-off-chain.mmd.svg" title="Protocol Sequence Diagram - Deals off Chain" >}}
+{{< diagram src="../diagrams/sequence/full-deals-off-chain.mmd.svg" title="Protocol Sequence Diagram - Deals off Chain" >}}
 
 # Protocol Flow Diagram -- deals on chain
 
-{{< diagram src="./docs/diagrams/sequence/full-deals-on-chain.mmd.svg" title="Protocol Sequence Diagram - Deals on Chain" >}}
+{{< diagram src="../diagrams/sequence/full-deals-on-chain.mmd.svg" title="Protocol Sequence Diagram - Deals on Chain" >}}
 
 # Parameter Calculation Dependency Graph
 
 This is a diagram of the model for parameter calculation. This is made with [orient](https://github.com/filecoin-project/orient), our tool for modeling and solving for constraints.
 
-{{< diagram src="./docs/diagrams/orient/filecoin.dot.svg" title="Parameter Calculation Dependency Graph" >}}
+{{< diagram src="../diagrams/orient/filecoin.dot.svg" title="Parameter Calculation Dependency Graph" >}}
 

src/systems/filecoin_markets/storage_market/storage_client.md

@@ -2,6 +2,12 @@
 title: "Storage Client"
 ---
 
-Both `StorageProvider` and `StorageClient` are `StorageMarketParticipant`. Any party can be a storage provider or client or both at the same time. Storage deal negotiation is expected to happen completely off chain and the request-response style storage deal protocol is to submit agreed-upon storage deal onto the network and gain storage power on chain. `StorageClient` will initiate the storage deal protocol by submitting a `StorageDealProposal` to the `StorageProvider` who will then add the deal data to a `Sector` and commit the sector onto the blockchain. 
+Both `StorageProvider` and `StorageClient` are `StorageMarketParticipant`. Any party can be a storage provider or client or both at the same time. Storage deal negotiation is expected to happen completely off chain and the request-response style storage deal protocol is to submit agreed-upon storage deal onto the network and gain storage power on chain. `StorageClient` will initiate the storage deal protocol by submitting a `StorageDealProposal` to the `StorageProvider` who will then add the deal data to a `Sector` and commit the sector onto the blockchain.
 
 {{< readfile file="storage_client.id" code="true" lang="go" >}}
+
+{{< readfile file="storage_client.go" code="true" lang="go" >}}
+
+# Storage Client State Machine
+
+{{< diagram src="diagrams/storage_client_fsm.dot.svg" title="Storage Client State Machine" >}}

src/systems/filecoin_markets/storage_market/storage_provider.md

@@ -2,6 +2,12 @@
 title: "Storage Provider"
 ---
 
-Both `StorageProvider` and `StorageClient` are `StorageMarketParticipant`. Any party can be a storage provider or client or both at the same time. Storage deal negotiation is expected to happen completely off chain and the request-response style storage deal protocol is to submit agreed-upon storage deal onto the network and gain storage power on chain. `StorageClient` will initiate the storage deal protocol by submitting a `StorageDealProposal` to the `StorageProvider` who will then add the deal data to a `Sector` and commit the sector onto the blockchain. 
+Both `StorageProvider` and `StorageClient` are `StorageMarketParticipant`. Any party can be a storage provider or client or both at the same time. Storage deal negotiation is expected to happen completely off chain and the request-response style storage deal protocol is to submit agreed-upon storage deal onto the network and gain storage power on chain. `StorageClient` will initiate the storage deal protocol by submitting a `StorageDealProposal` to the `StorageProvider` who will then add the deal data to a `Sector` and commit the sector onto the blockchain.
 
 {{< readfile file="storage_provider.id" code="true" lang="go" >}}
+
+{{< readfile file="storage_provider.go" code="true" lang="go" >}}
+
+# Storage Provider State Machine
+
+{{< diagram src="diagrams/storage_provider_fsm.dot.svg" title="Storage Provider State Machine" >}}

src/systems/filecoin_mining/storage_mining/_index.md

@@ -16,3 +16,15 @@ TODO:
 Filecoin Storage Mining Subsystem
 
 {{< readfile file="storage_mining_subsystem.id" code="true" lang="go" >}}
+
+# Sector in StorageMiner State Machine (on chain)
+
+{{< diagram src="diagrams/sector_chain_fsm.dot.svg" title="Sector State Machine (on chain)" >}}
+
+# Sector in StorageMiner State Machine (off chain)
+
+{{< diagram src="diagrams/sector_offchain_fsm.dot.svg" title="Sector State Machine (off chain)" >}}
+
+# Sector in StorageMiner State Machine (both)
+
+{{< diagram src="diagrams/sector_fsm.dot.svg" title="Sector State Machine (both)" >}}

src/systems/filecoin_mining/storage_mining/diagrams/mining_cycle.dot

@@ -0,0 +1,76 @@
+digraph mining_cycle {
+  compound=true;
+  ranksep=0.2;
+  edge [style=solid]
+
+
+  subgraph cluster_local {
+    label="Storage Miner\n(off chain)"
+
+    ActiveL -> ChallengedL [style=invis]
+
+    subgraph cluster_local_mining {
+      label="Mining"
+      style=filled
+      color=lightblue
+
+      ActiveL
+      ChallengedL
+
+      { // chain challenge
+        edge [color=red, fontcolor=red]
+        node [color=red, fontcolor=red, shape=none]
+        ActiveL -> ChallengedL [label="Chain issues challenge\n(implicit)"]
+      }
+
+      { // messages
+        edge [color=blue, fontcolor=blue]
+        node [color=blue, fontcolor=blue, shape=none]
+      }
+    }
+  }
+
+  subgraph cluster_chain {
+    label="Storage Miner Actor\n(on chain)"
+    color=blue
+
+    OwnerAccountC
+    ActiveC
+    // ChallengedC
+
+
+    OwnerAccountC -> ActiveC [style=invis]
+    // ActiveC -> ChallengedC [style=invis]
+
+    { // cron
+      edge [color=magenta, fontcolor=magenta]
+      node [color=magenta, fontcolor=magenta, shape=none]
+      // ActiveC -> ChallengedC [label="Chain issues challenge\n(implicit)"]
+    }
+
+    { // messages
+      edge [color=blue, fontcolor=blue]
+      node [color=blue, fontcolor=blue, shape=none]
+      OwnerAccountC -> ActiveC [label="Create Miner\n(spa.CreateMiner)"]
+    }
+  }
+
+
+  { // messages
+    edge [color=blue, fontcolor=blue]
+    node [color=blue, fontcolor=blue, shape=none]
+    OwnerAccL -> ActiveC [label="Create Miner\n(spa.CreateMiner)", constraint=false]
+    ActiveL -> ActiveC [label="Add Sectors\n(sm.CommitSector)", constraint=false]
+
+
+    ProducePost [label="Produce & submit PoSt\n(sm.SubmitPost)"]
+    ChallengedL -> ProducePost [arrowhead=none]
+    // ChallengedC -> ProducePost [arrowhead=none]
+    ProducePost -> ActiveL
+    ProducePost -> ActiveC
+
+  }
+
+  ActiveC -> ActiveL [label="Miner Created"]
+
+}

src/systems/filecoin_mining/storage_mining/diagrams/sector_chain_fsm.dot

@@ -0,0 +1,82 @@
+digraph sector {
+  compound=true;
+  ranksep=0.2;
+  splines=ortho;
+  edge [style=solid]
+
+  subgraph cluster_chain {
+    label="Sector States in StorageMinerActor\n(on chain)"
+    style=bold
+    color=gray
+
+    subgraph cluster_postproving {
+      label="must be proved in post"
+      style=filled
+      color=azure2
+
+      subgraph cluster_nopowerC1 {
+        label="Does not count for power"
+        style=filled
+        color=lightgray
+        CommittedC [label="Unproven"]
+      }
+
+      subgraph cluster_powerC {
+        label="Counts for power"
+        style=filled
+        color=seagreen3
+        ActiveC [label="Active"]
+      }
+
+    }
+
+    subgraph cluster_nopowerC2 {
+      label="Does not count for power"
+      style=filled
+      color=lightgray
+
+      FaultedC [label="Faulted"]
+      ExpiredC [label="Deleted"]
+      // DeletedC [label="Deleted"]
+
+      { // cron
+        edge [color=magenta, fontcolor=magenta]
+        // ExpiredC -> DeletedC [label="Sector Cleanup\n(sma.CronTick \n-> sm.SectorCleanup)"]
+        FaultedC -> ExpiredC [label="Expiry epoch reached\n(sma.CronTick \n-> sm.ExpireSectors)"]
+        FaultedC -> ExpiredC [label="Faulted 3+ times\n(sma.CronTick \n-> sm.SectorCleanup)", constraint=false]
+      }
+    }
+
+    { // messages
+      edge [color=blue, fontcolor=blue]
+      node [color=blue, fontcolor=blue, shape=box]
+
+      FaultsDeclared [label="Fault Declared\n(sm.DeclareFaults)"]
+
+      CommittedC -> ActiveC [label="1st PoSt\n(sm.SubmitPost \n->sm.ActivateSector)"]
+
+      CommittedC -> FaultsDeclared [arrowhead=none]
+      ActiveC -> FaultsDeclared [arrowhead=none]
+      FaultsDeclared -> FaultedC
+
+      FaultedC -> CommittedC [label="Recover\n(sm.SubmitPost)", constraint=false]
+      ActiveC -> ExpiredC [label="Expiry epoch reached\n(sm.SubmitPost \n-> sm.ExpireSectors)"]
+    }
+
+    { // cron
+      edge [color=magenta, fontcolor=magenta]
+      node [color=magenta, fontcolor=magenta, shape=box]
+      FaultSpotted [label="Fault Spotted\n(sma.CronTick \n-> sm.PostFailed)"]
+
+      // CommittedC -> ExpiredC [label="Expiry epoch reached\n(sma.CronTick \n-> sm.ExpireSectors)"]
+      CommittedC -> FaultSpotted [arrowhead=none]
+      ActiveC -> FaultSpotted [arrowhead=none]
+      FaultSpotted -> FaultedC
+
+      // ActiveC -> ExpiredC [label="Expiry epoch reached\n(sma.CronTick \n-> sm.ExpireSectors)"]
+    }
+
+    CommittedC -> ActiveC -> FaultsDeclared -> FaultedC -> ExpiredC [style=invis] // structure
+    CommittedC -> ActiveC -> FaultSpotted -> FaultedC -> ExpiredC [style=invis] // structure
+  }
+}