Greg/docs/191

README.md

@@ -10,6 +10,20 @@ Mithril is an research project to provide [Stake-based Threshold Multisignatures
 
 This repository aims at hosting the various artefacts produced as part of the _prototyping phase_: Documentation, PoCs and prototype code...
 
+* Mithril Aggregator - the server runtime that creates certified blockchain snapshots using Mithril signatures.
+* Mithril Signer - the signer runtime that participates to Mithril signatures.
+* Mithril Client - a client runtime that checks and restores blockchain certified snapshots.
+* Mithril Common - shared library
+* Mithril Core - the Mithril cryptographic library
+
 * [Documentation](./docs)
 * [Wiki](https://github.com/input-output-hk/mithril/wiki)
 
+## Build
+
+In a shell with a Cargo toolkit in the PATH, just enter
+
+ `make`
+
+ It should build the whole project.
+

docs/Makefile

@@ -0,0 +1,15 @@
+.PHONY: clean install
+
+yarn.lock:
+	yarn install
+
+install: yarn.lock
+
+build: yarn.lock
+	yarn build
+
+clean:
+	rm -rf build
+	rm package-lock.json || true
+	rm yarn.lock || true
+

docs/README.md

@@ -5,7 +5,7 @@ This website is built using [Docusaurus 2](https://docusaurus.io/), a modern sta
 ### Installation
 
 ```
-$ yarn
+$ make install
 ```
 
 ### Local Development
@@ -20,7 +20,7 @@ having to restart the server.
 ### Build
 
 ```
-$ yarn build
+$ make build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting
@@ -31,13 +31,13 @@ service.
 Using SSH:
 
 ```
-$ USE_SSH=true yarn deploy
+$ USE_SSH=true npx docusaurus deploy
 ```
 
 Not using SSH:
 
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
+$ GIT_USER=<Your GitHub username> npx docusaurus deploy
 ```
 
 If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to

docs/docusaurus.config.js

@@ -57,7 +57,7 @@ const config = {
   ],
 
   themeConfig:
-  /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
       navbar: {
         title: 'Mithril',
@@ -91,14 +91,38 @@ const config = {
             position: 'left',
           },
           {
-            to: '/aggregator-api',
-            label: 'Aggregator Server Api Reference',
+            type: 'dropdown',
+            label: 'developer doc',
             position: 'left',
+            items: [
+              {
+                to: 'http://mithril.network/mithril-aggregator/doc/mithril_aggregator/index.html',
+                label: 'Aggregator Rust documentation'
+              },
+              {
+                to: 'http://mithril.network/mithril-signer/doc/mithril_signer/index.html',
+                label: 'Signer Rust documentation'
+              },
+              {
+                to: 'http://mithril.network/mithril-client/doc/mithril_client/index.html',
+                label: 'Client Rust documentation'
+              },
+              {
+                to: '/aggregator-api',
+                label: 'Aggegator HTTP API'
+              },
+            ]
+          },
+          {
+            to: '/glossary',
+            label: 'Glossary',
+            position: 'right',
           },
-          {to: '/adr', label: 'ADRs', position: 'right'},
+          { to: '/adr', label: 'ADRs', position: 'right' },
           {
+            className: 'header-github-link',
+            html: ':before',
             href: 'https://github.com/input-output-hk/mithril/',
-            label: 'GitHub',
             position: 'right',
           },
         ],

docs/root/getting-started/install.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+
+# Installation
+
+## Mithril Aggregator
+
+## Mithril Signer
+
+## Mithril Client

docs/root/glossary.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 1
+---
+
+# Glossary
+
+Here is a comprehensive list of terms' definition used in the project.
+
+## Aggregator
+
+An Aggregator is a software instance that computes, checks the [mithril multisignatures](#mithril-multisignature) and issues the [snapshots](#snapshot) along with their [digest](#snapshot-digest).
+
+## Beacon
+
+A beacon is a group of parameters tied by a temporal period. Each time a beacon ends, a new Mithril Certificate is issued.
+
+## Cardano Key Pair
+
+A Cardano key pair is a asymmetric key pair used to identify a stake holder on the Cardano Network.
+
+## Certificate
+
+A Certificate is a digital document that contains:
+
+ * the [Beacon](#beacon) when this information is relevant
+ * the snapshot digest
+ * the [Mithril multisignature](#mithril-multisignature) of the digest
+ * a list of mirrors where the snapshot can be downloaded
+
+## Client
+
+A client is a software ran by a Wallet owner or anyone who needs to compute the [ledger state](#ledger-state). Clients use Mithril to ensure the snapshot they download is certified by a randomly distributed population to be the official one.
+
+## Digest
+
+See [snapshot digest](#snapshot-digest).
+
+## Epoch
+
+Cardano uses Epochs to group blocks computed in a certain amount of time. Each epoch corresponds to certain security parameters. This makes harder to lead brut force attacks on the Blockchain. At the end of each Cardano's epoch, the stake distribution is computed.
+
+## Immutable File
+
+An Immutable File represents a fixed size chunk of the Blockchain state. It is immutable by essence since blocks computed in the past are immutables. Theses files are indexed by a sequential number in their filename.
+
+## Ledger State
+
+The Ledger State represents all the wallets' balances according to the transactions stored in the Blockchain. Ledger states are regulary computed every time an [immutable file](#immutable-file) is generated.
+
+## Mithril Multisignature
+
+A mithril multisignature is a unique signature computed by a random distributed population of [signers](#signer)'s signatures represening a minimal stake share and  based on a common message.
+
+## Mithril Single Signature
+
+A Mithril single signature is a signatures derived from the Signer's verification key based on Mithril parameters and can be used in the [Mithril eultisignature](#mithril-multisignature) if this party wins one or more lotteries. 
+
+## Party
+
+A party is an entity that owns stake and is identified by a key pair (WHAT NAME?). A party can be involved in a [mithril multisignature](#mithril-multisignature). The public key is used as party identifier in the Mithril signature process.
+
+## Signer
+
+A Signer is a software that acts as a party in [mithril multisignatures](#mithril-multisignature). It represents a single contributor in the Mithril internal lottery mechanism hence he is owner of a [signer key pair](#signer-key-pair). 
+
+## Signer Key Pair
+
+When interacting with the Mithril protocol, each party must generate a asymmetrical key pair: signing (or private) key and verification (or public) key based on his own [Cardano key pair](#cardano-key-pair) added with stake information. 
+
+## Snapshot
+
+A Mithril Snapshot is a signed archive of the Blockchain that can be used by [Clients](#client) to restore the [Ledger State](#ledger-state) quicker than computing it from scratch.
+
+## Snapshot Certificate
+
+The snapshot certificate is a [mithril multisignature](#mithril-multisignature) of the [snapshot digest](#snapshot-digest) that ensures its authenticity to all [clients](#clients) who want to use it.
+
+## Snapshot Digest
+
+A snapshot digest (or simply, Digest) is a unique control sum (hash) associated to a [Snapshot](#snapshot). It can be used to assert a [Snapshot](#snapshot) is valid or can be signed to certify the according [Snapshot](#snapshot)'s provenance.
+
+## Stake Distribution
+
+The Stake Distribution is the list of [signers](#signer) of a [mithril multisignature](#mithril-multisignature) with their stake.

docs/root/intro.md

@@ -4,9 +4,12 @@ sidebar_position: 1
 
 # Documentation
 
-## Technical Documentation
+Welcome to Mithril documentation.
 
-* [Mithril Core Concepts](./core-concepts/)
-* [Mithril Topologies](./topologies/)
-* [Mithril Test Lab](./test-lab)
-* [Mithril Core Library API](https://input-output-hk.github.io/mithril/mithril-core/doc/mithril/index.html)
+Mithril is the implementation of Mithril Stake-based Threshold Multisignature [research publication](https://eprint.iacr.org/2021/916.pdf). This project uses Mithril multisignature keys to create certified savepoints (aka snapshots) in the Cardano Blockchain in order to speed up Wallets synchronizations.
+
+ * [How does it work](./core-concepts/mithril-protocol.md)?
+
+
+    It might be interesting here to identify and place links to what user would
+    like the most to do (identify use cases? how it works? install software? etc.)

docs/root/topologies/aggregator.md

@@ -0,0 +1,11 @@
+# Aggregator
+
+The Aggregator is the central piece of the Mithril certificate creation.
+
+The first phase of the protocole is triggered when a new Epoch starts in the Cardano network. The aggregator node saves the current stake ditribution and starts performing the snapshot for this new epoch which is then stored in the cloud. A message is then created containing the current and the previous snapshots digests.
+
+### Certificate creation
+
+During this phase, the aggregator waits to reach a stake quorum of signers. They register to be part of the lotery process of the multisignature. During all this time, the certificate is in _pending_ state. Once the quorum is reached, the aggregator issues the multisignature certificate and stores it in the certificate chain.
+
+![](images/aggregator.png)

docs/root/topologies/client.md

@@ -0,0 +1,7 @@
+# Client
+
+A client is a Snapshot consumer. It is typically a Wallet that wants to synchronize with the Cardano blockchain. When performed from the begining of the chain, it can take several days to compute all the blocks and verify everything is consistent. Snapshots act as certified savepoints, the wallet can assume all the blocks in the snapshots are consistent hence only the newer blocks are to be verified. This dramatically reduces the synchronization times.
+
+## Topology
+
+![](images/client.png)

docs/root/topologies/signer.md

@@ -0,0 +1,7 @@
+ # Signer
+
+ A Signer is a participant to a Mithril Multisignature. As such, a signer assesses that the signed message is the expected genuine content. To do so, the signer computes the digest from the inormation stored on a Cardano node and signs it with his secret key. This signed message with the stake the Signer wants to invest in the signature process is sent to the Aggregator. This way, the Aggegator can assess that the Signer is identified and has the same message. With the Signer Key and the stake information, the Aggregator generates a Verification Key that is used to identify the Signer in the Mithril internal process.
+
+ ## Topology
+
+![](images/signer.png)

docs/src/components/HomepageFeatures/index.js

@@ -4,42 +4,41 @@ import styles from './styles.module.css';
 
 const FeatureList = [
   {
-    title: 'Easy to Use',
-    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
+    title: 'Modular',
+    Svg: require('@site/static/img/card-operate-a-stake-pool.svg').default,
     description: (
       <>
-        Docusaurus was designed from the ground up to be easily installed and
-        used to get your website up and running quickly.
+        Mithril is a modular set of tools to accelerate blockchain synchronization.
+        Find components description in Topologies.
       </>
     ),
   },
   {
-    title: 'Focus on What Matters',
-    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
+    title: 'How it works',
+    Svg: require('@site/static/img/card-native-tokens.svg').default,
     description: (
       <>
-        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
-        ahead and move your docs into the <code>docs</code> directory.
+        How does the heart of Mithril work?
+        Find how the Mithril multisignature works in Core Concepts.
       </>
     ),
   },
   {
-    title: 'Powered by React',
-    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+    title: 'Get started',
+    Svg: require('@site/static/img/card-get-started.svg').default,
     description: (
       <>
-        Extend or customize your website layout by reusing React. Docusaurus can
-        be extended while reusing the same header and footer.
+        Quick instructions to build it.
       </>
     ),
   },
 ];
 
-function Feature({Svg, title, description}) {
+function Feature({ Svg, title, description }) {
   return (
     <div className={clsx('col col--4')}>
       <div className="text--center">
-        <Svg className={styles.featureSvg} role="img"/>
+        <Svg className={styles.featureSvg} role="img" />
       </div>
       <div className="text--center padding-horiz--md">
         <h3>{title}</h3>

docs/src/css/custom.css

@@ -37,3 +37,12 @@
 [data-theme='dark'] .docusaurus-highlight-code-line {
     background-color: rgba(0, 0, 0, 0.3);
 }
+
+.header-github-link:before {
+    background: url("/static/img/GitHub-Mark-32px.png") no-repeat;
+    background-size: cover;
+    display: flex;
+    content: "";
+    height: 24px;
+    width: 24px;
+}