diff --git a/README.md b/README.md index 8dd26086c32..af35d61cfc3 100644 --- a/README.md +++ b/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. + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000000..1eb05aaae14 --- /dev/null +++ b/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 + diff --git a/docs/README.md b/docs/README.md index a7a802007b9..3892a429e7b 100644 --- a/docs/README.md +++ b/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= yarn deploy +$ GIT_USER= npx docusaurus deploy ``` If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index e9bf3ebf591..cbb42e83b56 100644 --- a/docs/docusaurus.config.js +++ b/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', }, ], diff --git a/docs/root/getting-started/bootstrap-cardano-node.md b/docs/root/getting-started/bootstrap-cardano-node.md deleted file mode 100644 index 7088b3f24d2..00000000000 --- a/docs/root/getting-started/bootstrap-cardano-node.md +++ /dev/null @@ -1,10 +0,0 @@ -# Bootstrap a Cardano Node - -**This is a work in progress** :hammer_and_wrench: - -## Features breakdown - -The following graph represents the various features that our system would need to provide in order to be able to _ -Spin-up a wallet quickly_. - -![Features dependency graph](./images/feature-graph.png) diff --git a/docs/root/getting-started/install.md b/docs/root/getting-started/install.md new file mode 100644 index 00000000000..e69439591be --- /dev/null +++ b/docs/root/getting-started/install.md @@ -0,0 +1,11 @@ +--- +sidebar_position: 1 +--- + +# Installation + +## Mithril Aggregator + +## Mithril Signer + +## Mithril Client \ No newline at end of file diff --git a/docs/root/glossary.md b/docs/root/glossary.md new file mode 100644 index 00000000000..13ea863eda0 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/root/intro.md b/docs/root/intro.md index 94c94c4d004..3d7de9384f1 100644 --- a/docs/root/intro.md +++ b/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.) \ No newline at end of file diff --git a/docs/root/topologies/aggregator.md b/docs/root/topologies/aggregator.md new file mode 100644 index 00000000000..97a0b53385e --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/root/topologies/client.md b/docs/root/topologies/client.md new file mode 100644 index 00000000000..c07f78cea8d --- /dev/null +++ b/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) diff --git a/docs/root/topologies/images/aggregator.png b/docs/root/topologies/images/aggregator.png new file mode 100644 index 00000000000..6a0d5e901d6 Binary files /dev/null and b/docs/root/topologies/images/aggregator.png differ diff --git a/docs/root/topologies/images/client.png b/docs/root/topologies/images/client.png new file mode 100644 index 00000000000..9557734bd0b Binary files /dev/null and b/docs/root/topologies/images/client.png differ diff --git a/docs/root/topologies/images/mithril-arch-components.jpg b/docs/root/topologies/images/mithril-arch-components.jpg deleted file mode 100644 index d5dbbc98e3c..00000000000 Binary files a/docs/root/topologies/images/mithril-arch-components.jpg and /dev/null differ diff --git a/docs/root/topologies/images/mithril-arch-containers.jpg b/docs/root/topologies/images/mithril-arch-containers.jpg deleted file mode 100644 index 73cf211fbb5..00000000000 Binary files a/docs/root/topologies/images/mithril-arch-containers.jpg and /dev/null differ diff --git a/docs/root/topologies/images/signer.png b/docs/root/topologies/images/signer.png new file mode 100644 index 00000000000..f1ce146cd81 Binary files /dev/null and b/docs/root/topologies/images/signer.png differ diff --git a/docs/root/topologies/mithril-architecture.md b/docs/root/topologies/mithril-architecture.md deleted file mode 100644 index 4178b6025a9..00000000000 --- a/docs/root/topologies/mithril-architecture.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Mithril Architecture - -The following figure sketches of our current understanding of the Mithril network architecture, following initial PoC -phase ending in 2021 Q4. - -## Containers View - -This diagram represents the [Containers view](https://c4model.com/#ContainerDiagram) of the system, where rounded boxes -are expected to be separate "Containers" (eg. processes, servers, programs, nodes...) - -![](./images/mithril-arch-containers.jpg) - -This architecture is defined in the context of _Bootstrapping nodes_ as primary use case for early development of -Mithril. - -* The Mithril containers are more directly linked to the Cardano node, both for querying current state of the chain, - initialising the node with some UTXO snapshot, and reusing communication network for Mithril protocol purpose, -* There's a clear separation between the _Snapshotter_ container that's responsible for deciding when and what to sign, - and the _Certifier_ that's responsible for producing valid signatures and certificates, -* Similarly, the stores for signatures/certificates and the store for snapshots are separated. The latter could be - distributed or remote, -* Alternative messaging layers could be used instead of or beside the Cardano network. - -## Components View - -This diagram represents the [Components view](https://c4model.com/#ComponentDiagram) of the system, which provides more -details on the inner workings of each of the involved containers. - -![](./images/mithril-arch-components.jpg) diff --git a/docs/root/topologies/signer.md b/docs/root/topologies/signer.md new file mode 100644 index 00000000000..f37139ce42d --- /dev/null +++ b/docs/root/topologies/signer.md @@ -0,0 +1,7 @@ + # Signer + + A Signer is a participant to a Mithril Multisignature. As such, a signer contributes to signing an expected genuine message. To do so, the signer computes the digest from the information stored on a Cardano node and signs it with his secret key. This signed message is sent to the Aggregator, along with the corresponding won lottery numbers. This way, the Aggregator can assess that the Signer is identified and has signed the same message. + + ## Topology + +![](images/signer.png) diff --git a/docs/src/components/HomepageFeatures/index.js b/docs/src/components/HomepageFeatures/index.js index 674cb822c86..2d1702fe275 100644 --- a/docs/src/components/HomepageFeatures/index.js +++ b/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'll do the chores. Go - ahead and move your docs into the docs 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 (
- +

{title}

diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index c149687c0b9..7eb18eec982 100644 --- a/docs/src/css/custom.css +++ b/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; +} \ No newline at end of file diff --git a/docs/static/img/GitHub-Mark-32px.png b/docs/static/img/GitHub-Mark-32px.png new file mode 100644 index 00000000000..8b25551a979 Binary files /dev/null and b/docs/static/img/GitHub-Mark-32px.png differ diff --git a/docs/static/img/card-get-started.svg b/docs/static/img/card-get-started.svg new file mode 100644 index 00000000000..a408aaebcc5 --- /dev/null +++ b/docs/static/img/card-get-started.svg @@ -0,0 +1,102 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/card-native-tokens.svg b/docs/static/img/card-native-tokens.svg new file mode 100644 index 00000000000..c767c267241 --- /dev/null +++ b/docs/static/img/card-native-tokens.svg @@ -0,0 +1,114 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/card-operate-a-stake-pool.svg b/docs/static/img/card-operate-a-stake-pool.svg new file mode 100644 index 00000000000..28137c38c69 --- /dev/null +++ b/docs/static/img/card-operate-a-stake-pool.svg @@ -0,0 +1,76 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +