Fix documentation diagrams (base-org#129)

README.md

@@ -119,4 +119,4 @@ A bootstrap config file is used to define the initial state of the pessimism ser
 
 
 ## Spawning an invariant session
-To learn about the currently supported invariants and how to spawn them, please advise the [invariants' documentation](./docs/invariants.md).
+To learn about the currently supported invariants and how to spawn them, please advise the [invariants' documentation](./docs/invariants.markdown).

docs/Gemfile

@@ -16,7 +16,6 @@ gem "github-pages", "~> 228", group: :jekyll_plugins
 # If you have any plugins, put them here!
 group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.12"
-  gem 'jekyll-spaceship'
 end
 
 

docs/Gemfile.lock

@@ -13,7 +13,7 @@ GEM
       execjs
     coffee-script-source (1.11.1)
     colorator (1.1.0)
-    commonmarker (0.23.9)
+    commonmarker (0.23.10)
     concurrent-ruby (1.2.2)
     dnsruby (1.70.0)
       simpleidn (~> 0.2.1)
@@ -147,11 +147,6 @@ GEM
       jekyll (>= 3.8, < 5.0)
     jekyll-sitemap (1.4.0)
       jekyll (>= 3.7, < 5.0)
-    jekyll-spaceship (0.10.2)
-      gemoji (~> 3.0)
-      jekyll (>= 3.6, < 5.0)
-      nokogiri (~> 1.6)
-      rainbow (~> 3.0)
     jekyll-swiss (1.0.0)
     jekyll-theme-architect (0.2.0)
       jekyll (> 3.5, < 5.0)
@@ -224,7 +219,6 @@ GEM
       forwardable-extended (~> 2.6)
     public_suffix (4.0.7)
     racc (1.7.1)
-    rainbow (3.1.1)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
@@ -261,7 +255,6 @@ DEPENDENCIES
   github-pages (~> 228)
   http_parser.rb (~> 0.6.0)
   jekyll-feed (~> 0.12)
-  jekyll-spaceship
   minima (~> 2.5)
   tzinfo (>= 1, < 3)
   tzinfo-data

docs/_config.yml

@@ -28,7 +28,6 @@ url: "base-org.github.io" # the base hostname & protocol for your site, e.g. htt
 theme: minima
 plugins:
   - jekyll-feed
-  - jekyll-spaceship
 
 # Exclude from processing.
 # The following items will not be processed, by default.

docs/alerting.markdown → docs/architecture/alerting.markdown

@@ -4,11 +4,17 @@ title: Alerting
 permalink: /architecture/alerting
 ---
 
+{% raw %}
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10.3.0/dist/mermaid.min.js"></script>
+{% endraw %}
+
 ## Overview
 The alerting subsystem will receive alerts from the `EngineManager` and publish them to the appropriate alerting destinations. The alerting subsystem will also be responsible for managing the lifecycle of alerts. This includes creating, updating, and removing alerting entries for invariant sessions.
 
 ## Diagram
-```mermaid!
+
+{% raw %}
+<div class="mermaid">
 graph LR
 
 subgraph EM["Engine Manager"]
@@ -26,8 +32,8 @@ subgraph AM["Alerting Manager"]
 end
 CPH --> |"HTTP POST"|TPH["Third Party API"]
 SH --> |"HTTP POST"|SlackAPI("Slack Webhook API")
-
-```
+</div>
+{% endraw %}
 
 ### Alert
 An `Alert` type stores all necessary metadata for external consumption by a downstream entity. 

docs/architecture/architecture.markdown

@@ -8,7 +8,7 @@ permalink: /architecture
 There are *three subsystems* that drive Pessimism’s architecture:
 1. [ETL](etl.markdown) - Modularized data extraction system for retrieving and processing external chain data in the form of a DAG known as the Pipeline DAG
 2. [Risk Engine](engine.markdown) - Logical execution platform that runs a set of invariants on the data funneled from the Pipeline DAG
-3. [Alerting](../alerting.markdown) - Alerting system that is used to notify users of invariant failures
+3. [Alerting](alerting.markdown) - Alerting system that is used to notify users of invariant failures
 
 These systems will be accessible by a client through the use of a JSON-RPC API that has unilateral access to all three primary subsystems.
 

docs/architecture/engine.markdown

@@ -4,13 +4,20 @@ title: Risk Engine
 permalink: /architecture/risk-engine
 ---
 
+{% raw %}
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10.3.0/dist/mermaid.min.js"></script>
+{% endraw %}
+
+
 ## Overview
 The Risk Engine is responsible for handling and executing active invariants. It is the primary downstream consumer of ETL output. The Risk Engine will receive data from the ETL and execute the invariants associated with the data. If an invalidation occurs, the Risk Engine will return an `InvalidationOutcome` to the `EngineManager`. The `EngineManager` will then create an `Alert` using the `InvalidationOutcome` and publish it to the Alerting system.
 
 The Risk Engine will execute the invariants associated with some ingested input data and return an `InvalidationOutcome` to the `EngineManager`. The `EngineManager` will then create an `Alert` using the `InvalidationOutcome` and publish it to the Alerting system.
 
 The following diagram further exemplifies this key interaction:
-```mermaid!
+
+{% raw %}
+<div class="mermaid">
 graph LR;
     subgraph A["Engine Manager"]
         C(eventLoop) -.->  C;
@@ -29,7 +36,8 @@ graph LR;
     subgraph AAA["Alerting Manager"]
         G --> FF("eventLoop()")
     end
-```
+</div>
+{% endraw %}
 
 ## Inter-Connectivity
 The ETL publishes `Invariant Input` to the Risk Engine using a relay channel. The Risk Engine will subscribe to this channel to receive and process updates as they are published by the ETL. The Risk Engine will also publish events to the Alerting system using a separate downstream relay channel. The Alerting system will subscribe to this channel to receive and process updates as they are published by the Risk Engine.

docs/architecture/etl.markdown

@@ -4,6 +4,11 @@ title: ETL
 permalink: /architecture/etl
 ---
 
+{% raw %}
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10.3.0/dist/mermaid.min.js"></script>
+{% endraw %}
+
+
 The Pessimism ETL is a generalized abstraction for a DAG-based component system that continuously transforms chain data into inputs for consumption by a Risk Engine in the form of intertwined data “pipelines”. This DAG based representation of ETL operations is done to ensure that the application can optimally scale to support many active invariants. This design allows for the reuse of modularized ETL components and de-duplication of conflicting pipelines under certain key logical circumstances. 
 
 ## Component
@@ -16,7 +21,8 @@ Currently, there are three total component types:
 ### Inter-Connectivity 
 The diagram below showcases how interactivity between components occurs:
 
-```mermaid
+{% raw %}
+<div class="mermaid">
 graph LR;
     A((Component0)) -->|dataX| C[Ingress];
 
@@ -30,15 +36,21 @@ graph LR;
 
     G --> K((Component2));
     H --> J((Component3));
-```
+</div>
+{% endraw %}
+
 
 #### Egress Handler
 All component types use an `egressHandler` struct for routing transit data to actively subscribed downstream ETL components.
-```mermaid
+
+{% raw %}
+<div class="mermaid">
 flowchart TD;
     Component-->|Transit_Data|A[Egress0];
     Component-->|Transit_Data|B[Egress1];
-```
+</div>
+{% endraw %}
+
 
 #### Ingress Handler
 All component types also use an `ingressHandler` struct for ingesting active transit data from upstream ETL components.
@@ -84,15 +96,17 @@ The following key interface functions are supported/enforced:
 
 Unlike other components, `Oracles` actually employ _2 go routines_ to safely operate. This is because the definition routines are run as a separate go routine with a communication channel to the actual `Oracle` event loop. This is visualized below:
 
-```mermaid
+{% raw %}
+<div class="mermaid">
 graph LR;
     subgraph A[Oracle]
         B[eventLoop]-->|channel|ODefRoutine;
          B[eventLoop]-->|context|ODefRoutine;
         B-->B;
     end
+</div>
+{% endraw %}
 
-```
 
 #### Attributes
 * A communication channel with the pipeline manager
@@ -156,9 +170,10 @@ A registry submodule is used to store all ETL data register definitions that pro
 Some component's require knowledge of a specific address to properly function. For example, an oracle that polls a geth node for native ETH balance amounts would need knowledge of the address to poll. To support this, the ETL leverages a shared state store between the ETL and Risk Engine subsystems.
 
 Shown below is how the ETL and Risk Engine interact with the shared state store using a `BalanceOracle` component as an example:
-```mermaid
-graph LR;
 
+{% raw %}
+<div class="mermaid">
+graph LR;
     subgraph SB["State Store"]
         state
     end
@@ -182,7 +197,9 @@ graph LR;
 
         state --> |"{2} []address"|BO
     end
-```
+</div>
+{% endraw %}
+
 
 
 ### Geth Block Oracle Register
@@ -199,7 +216,8 @@ The ETL uses a `ComponentGraph` construct to represent and store critical compon
 
 A graph edge is represented as a binded communication path between two arbitrary component nodes (`c1`, `c2`). Adding an edge from some component (`c1`) to some downstream component (`c2`) results in `c1` having a path to the ingress of `c2` in its [egress handler](#egress-handler). This would look something like:
 
-```mermaid
+{% raw %}
+<div class="mermaid">
 graph TB;
 
     subgraph "\nEdge"
@@ -216,7 +234,8 @@ graph TB;
 
     classDef orange fill:#f96,stroke:#333,stroke-width:4px
     class A,D orange
-```
+</div>
+{% endraw %}
 
 **NOTE:** The component graph used in the ETL is represented as a _DAG_ (Directed Acyclic Graph), meaning that no bipartite edge relationships should exist between two components (`c1`, `c2`) where `c1-->c2` && `c2-->c1`. While there are no explicit checks for this in the code software, it should be impossible given that all components declare entrypoint register dependencies within their metadata, meaning that a component could only be susceptible to bipartite connectivity in the circumstance where a component registry definition declares inversal input->output of an existing component. 
 

docs/index.markdown

@@ -6,10 +6,13 @@ Detect real-time threats on Op-stack compatible chains
 
 ## Contents
 - [Architecture](../pessimism/architecture)
-- [JSON-RPC API](../pessimism/api)
-- [ETL Subsystem](../pessimism/etl)
-- [Engine Subsystem](../pessimism/risk-engine)
-- [Alerting Subsystem](../pessimism/alerting)
+  - [JSON-RPC API](../pessimism/api)
+  - [ETL Subsystem](../pessimism/architecture/etl)
+  - [Engine Subsystem](../pessimism/architecture/risk-engine)
+  - [Alerting Subsystem](../pessimism/architecture/alerting)
+- [API Swaggerdoc](swaggerdoc.html)
+- [Invariant Documentation](../pessimism/invariants)
+- [Telemetry Documentation](../pessimism/telemetry)
 
 ## Github Pages
 The Pessimism documentation is hosted on Github Pages. To view the documentation, please visit [https://base-org.github.io/pessimism/architecture](https://base-org.github.io/pessimism/architecture).