diff --git a/docs/website/blog/2022-10-11-keys-certification-badge/index.md b/docs/website/blog/2022-10-11-keys-certification-badge/index.md index 6ba6691b7a2..22ed01f1be0 100644 --- a/docs/website/blog/2022-10-11-keys-certification-badge/index.md +++ b/docs/website/blog/2022-10-11-keys-certification-badge/index.md @@ -50,6 +50,7 @@ sqlite3 ${DATA_STORES_DIRECTORY}/signer.sqlite3 "UPDATE protocol_initializer SET From now, SPOs can either run their node by: - **Declaring their Cardano `PoolId`**: + - This is the mode that all nodes were running prior to this release - This mode is still the **stable** mode - We intend to deprecate this mode in the near future diff --git a/docs/website/blog/2024-12-17-era-switch-pythagoras.md b/docs/website/blog/2024-12-17-era-switch-pythagoras.md index c3211bfd610..eac8592e0b2 100644 --- a/docs/website/blog/2024-12-17-era-switch-pythagoras.md +++ b/docs/website/blog/2024-12-17-era-switch-pythagoras.md @@ -47,10 +47,12 @@ curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/input-out #### Era switch plan for `Pythagoras` - **pre-release-preview** network: + - [x] Create the era switch transaction (done at epoch `757`) - [x] Complete the era switch to `Pythagoras` at the transition to epoch `759` - **release-preprod** network: + - [x] Create the era switch transaction (done at epoch `184`) - [x] Complete the era switch to `Pythagoras` at the transition to epoch `186` diff --git a/docs/website/blog/2025-06-17-client-cli-cardano-database-backends.md b/docs/website/blog/2025-06-17-client-cli-cardano-database-backends.md index 04f9605cd4e..704829d8a56 100644 --- a/docs/website/blog/2025-06-17-client-cli-cardano-database-backends.md +++ b/docs/website/blog/2025-06-17-client-cli-cardano-database-backends.md @@ -35,22 +35,27 @@ In particular, the `cardano-db` command in the Mithril client CLI has been updat To support this transition, both certification versions will remain available during the migration period, allowing users to adapt at their own pace. - [x] **Distribution [2524](https://github.com/input-output-hk/mithril/releases/tag/2524.0)**: + - Introduced the `--backend` parameter in the `cardano-db` command - The default backend is `v1`; the `v2` backend is still considered **unstable** - No breaking changes in the client CLI - The `v2` backend is accessible via the `cardano_database_v2` function in the client library. - [x] **Distribution [2537](https://github.com/input-output-hk/mithril/releases/tag/2537.0)**: + - The `v2` backend is promoted to **stable** status but will remain optional - The `v1` backend is still the default. - [x] **Distribution [2543](https://github.com/input-output-hk/mithril/releases/tag/2543.0)**: + - The `v2` backend is the default - [x] **Distribution [2603](https://github.com/input-output-hk/mithril/releases/tag/2603.1)**: + - The `v1` backend is deprecated. - [x] **Distribution [2617](https://github.com/input-output-hk/mithril/releases/tag/2617.0)**: + - The `v1` backend is decommissioned and removed from the client CLI and library. - [ ] **Distribution +5**: diff --git a/docs/website/blog/2025-11-03-distribution-2543.md b/docs/website/blog/2025-11-03-distribution-2543.md index a06dac038b0..6b2c167b65d 100644 --- a/docs/website/blog/2025-11-03-distribution-2543.md +++ b/docs/website/blog/2025-11-03-distribution-2543.md @@ -7,7 +7,7 @@ tags: [release, distribution, 2543] ### Distribution `2543` is now available -:::info Update 2025/11/10 +:::info[Update 2025/11/10] The team released the hotfix `2543.1-hotfix` to address a bug in the `2543.0` distribution that could prevent the Mithril signer from signing when (re)started. diff --git a/docs/website/blog/2026-01-06-dmq-testing-program.md b/docs/website/blog/2026-01-06-dmq-testing-program.md index ccd9c67ae6f..caf34612a9e 100644 --- a/docs/website/blog/2026-01-06-dmq-testing-program.md +++ b/docs/website/blog/2026-01-06-dmq-testing-program.md @@ -7,7 +7,7 @@ tags: [DMQ, decentralization, testing program] ### DMQ testing program with SPOs -:::info Update 2026/04/28 +:::info[Update 2026/04/28] With the release of the [`2617.0`](https://github.com/input-output-hk/mithril/releases/tag/2617.0) distribution, the DMQ node has been upgraded to version `0.4.2.0` on the `pre-release-preview` network. The testing program with SPOs is extended to keep gathering feedback before the stable release on `release-preprod` and `release-mainnet` networks. diff --git a/docs/website/blog/2026-01-06-multiple-aggregators-testing-program.md b/docs/website/blog/2026-01-06-multiple-aggregators-testing-program.md index 3df3e19bc2f..42fb0c327a4 100644 --- a/docs/website/blog/2026-01-06-multiple-aggregators-testing-program.md +++ b/docs/website/blog/2026-01-06-multiple-aggregators-testing-program.md @@ -7,7 +7,7 @@ tags: [DMQ, decentralization, testing program, aggregator, follower] ### Multiple aggregators testing program -:::info Update 2026/04/28 +:::info[Update 2026/04/28] With the release of the [`2617.0`](https://github.com/input-output-hk/mithril/releases/tag/2617.0) distribution, the testing program for running multiple aggregators is extended on the `pre-release-preview` network to keep gathering feedback before the stable release on `release-preprod` and `release-mainnet` networks. diff --git a/docs/website/docusaurus.config.js b/docs/website/docusaurus.config.js index ecf4a66bfb2..6d40b0c0115 100644 --- a/docs/website/docusaurus.config.js +++ b/docs/website/docusaurus.config.js @@ -15,11 +15,21 @@ const config = { url: "https://mithril.network", baseUrl: "/doc/", onBrokenLinks: "throw", - onBrokenMarkdownLinks: "warn", + favicon: "img/mithril-logo.svg", organizationName: "Input Output Global", projectName: "Mithril", + future: { + v4: { + removeLegacyPostBuildHeadAttribute: true, + useCssCascadeLayers: true, + siteStorageNamespacing: true, + fasterByDefault: false, + mdx1CompatDisabledByDefault: true, + }, + }, + scripts: [ { src: "https://plausible.io/js/script.js", @@ -372,6 +382,9 @@ const config = { }), markdown: { mermaid: true, + hooks: { + onBrokenMarkdownLinks: "warn", + }, }, themes: ["@docusaurus/theme-mermaid"], stylesheets: [ diff --git a/docs/website/root/manual/operate/run-aggregator-node.md b/docs/website/root/manual/operate/run-aggregator-node.md index 749f429329a..06e66af2711 100644 --- a/docs/website/root/manual/operate/run-aggregator-node.md +++ b/docs/website/root/manual/operate/run-aggregator-node.md @@ -60,6 +60,7 @@ Note that this guide works only on a Linux machine. - Operate a **Cardano full node** - To access the file system of the **Cardano full node**, you will need the following permissions: + - Read rights on the `Database` folder (specified by the `--database-path` setting of the **Cardano node**) - Read and write rights on the `Inter Process Communication` file (typically defined by the `CARDANO_NODE_SOCKET_PATH` environment variable used to launch the **Cardano node**) @@ -273,10 +274,12 @@ The configuration values for the `/opt/mithril/mithril-aggregator.env` file are - `CUSTOM_ORIGIN_TAG_WHITE_LIST`: Comma-separated list of custom origin tags to whitelist for client requests (default: `EXPLORER,BENCHMARK,CI,NA`). - **Base configuration** **optional** values are: + - `BLOCKFROST_PARAMETERS`: Parameters to connect to the Blockfrost API. Used to fetch the ticker and name of the registered stake pools. Example: `{"project_id":"preprodWuV1ICdtOWfZYfdcxpZ0tsS1N9rVZomQ"}` - `SIGNER_IMPORTER_RUN_INTERVAL`: Time interval at which the pools names and ticker in blockfrost will be imported (in minutes, default: `720`). - The **Cardano database** configuration values are (only needed if supporting Cardano database certification): + - `DB_DIRECTORY`: Directory of the Cardano node database stores (same as the `--database-path` setting of the Cardano node) - `DATA_STORES_DIRECTORY`: Directory where the aggregator will store its databases (eg, `/opt/mithril/stores`) - `GOOGLE_APPLICATION_CREDENTIALS_JSON`: JSON content of the GCP service account credentials (required if using GCP for snapshot storage) @@ -300,6 +303,7 @@ The configuration values for the `/opt/mithril/mithril-aggregator.env` file are Here is an **example** set of values for **release-preprod** that will be used in this guide in the **tip** boxes to illustrate some commands: - **Base configuration**: + - **SIGNED_ENTITY_TYPES**: `MithrilStakeDistribution,CardanoStakeDistribution,CardanoTransactions` (only supporting stake distributions and transactions, excluding database snapshots) - **SERVER_PORT**: `8080` - **PUBLIC_SERVER_URL**: `https://aggregator.example.com/aggregator` @@ -319,10 +323,12 @@ Here is an **example** set of values for **release-preprod** that will be used i - **CUSTOM_ORIGIN_TAG_WHITE_LIST**: `EXPLORER,BENCHMARK,CI,NA` - **Optional configuration**: + - **BLOCKFROST_PARAMETERS**: `{"project_id":"preprodWuV1ICdtOWfZYfdcxpZ0tsS1N9rVZomQ"}` - **SIGNER_IMPORTER_RUN_INTERVAL**: 720 - **Cardano database configuration**: + - **DB_DIRECTORY**: `/cardano/db` - **DATA_STORES_DIRECTORY**: `/opt/mithril/stores` - **GOOGLE_APPLICATION_CREDENTIALS_JSON**: `**YOUR_SECRET**` @@ -1299,6 +1305,7 @@ If you want to make your follower aggregator publicly discoverable, you should: 1. **Ensure your aggregator is accessible via HTTPS** by setting up Traefik or another reverse proxy with a valid SSL certificate (as described in the [Set up the SSL certificate](#setup-the-ssl-certificate-traefik) section). 2. **Register your aggregator in the networks configuration**. You can do this by: + - Opening an issue in the [Mithril GitHub repository](https://github.com/input-output-hk/mithril/issues) - Or by creating a pull request that modifies the [`networks.json`](https://github.com/input-output-hk/mithril/blob/main/networks.json) file and updates the `aggregators` field in the Cardano network you are targeting. diff --git a/docs/website/root/manual/operate/run-signer-node.md b/docs/website/root/manual/operate/run-signer-node.md index f42e3712dd7..dfd53d931bb 100644 --- a/docs/website/root/manual/operate/run-signer-node.md +++ b/docs/website/root/manual/operate/run-signer-node.md @@ -99,10 +99,12 @@ Note that this guide works only on a Linux machine. ::: - To operate a **Cardano node** as a **stake pool**, you need: + - The pool's `operational certificate` - The pool's `KES secret key` - To access the file system of the **Cardano block-producing** node for **production** deployment (or of the **Cardano relay** node for **naive** deployment), you will need the following permissions: + - Read rights on the `Database` folder (specified by the `--database-path` setting of the **Cardano node**) - Read and write rights on the `Inter Process Communication` file (typically defined by the `CARDANO_NODE_SOCKET_PATH` environment variable used to launch the **Cardano node**) @@ -546,6 +548,7 @@ sudo systemctl restart mithril-signer :::info - If you have already installed `Squid` via the `apt` package manager, we recommend that you delete it before manually building it from source by running the following commands: + - `sudo systemctl stop squid` - `sudo apt remove squid` - `sudo apt autoremove` diff --git a/docs/website/root/mithril/advanced/mithril-protocol/protocol.md b/docs/website/root/mithril/advanced/mithril-protocol/protocol.md index c92d90d7167..d8f9fb587d0 100644 --- a/docs/website/root/mithril/advanced/mithril-protocol/protocol.md +++ b/docs/website/root/mithril/advanced/mithril-protocol/protocol.md @@ -44,7 +44,7 @@ The protocol has three phases: 2. **Initialization phase** during which Mithril nodes generate and exchange keys 3. **Operations phase** during which nodes sign and aggregate signatures of messages to produce certificates. -:::note Note +:::note[Note] Note that all three phases require a set of parties (`P` in the paper) to be fixed. During the protocol establishment phase three important parameters are generated: @@ -103,6 +103,7 @@ a quorum of `k` valid signatures must be submitted. - For every valid signature, the party creates a proof (`π`) containing a signature of the message, verification key, stake, and paths of the party in the Merkle tree. - Then, multiple signatures can be aggregated together to form a certificate (`τ`) by: + - Verifying signatures from each party: - Checking the party is authorized to sign for the given index (using the same procedure as signing) - Checking the proof is valid which means: @@ -117,7 +118,7 @@ a quorum of `k` valid signatures must be submitted. - Each certificate `τ` can be verified as valid for some message, using the known setup parameters to verify the certificate’s proof and then verifying the aggregate signatures and verification keys. -:::note Note +:::note Note that if the individual signatures are broadcast to all parties, then each party can independently produce the certificates. In particular, the party that performs aggregation is not required to have any specific knowledge, nor it is assumed to be honest. This means that _any_ third party that has access to the individual signatures can perform the signature aggregation. diff --git a/docs/website/root/mithril/advanced/threat-model.md b/docs/website/root/mithril/advanced/threat-model.md index 8878b1a7173..663eba203ac 100644 --- a/docs/website/root/mithril/advanced/threat-model.md +++ b/docs/website/root/mithril/advanced/threat-model.md @@ -22,7 +22,7 @@ The threat model is a living document, updated to reflect the [latest Mithril ve ### System description -:::info To do +:::info[To do] - Consider reducing these details and moving them into the [architecture page](https://mithril.network/doc/mithril/mithril-network/architecture). - Also consider updating the [protocol page](https://mithril.network/doc/mithril/mithril-protocol/protocol). @@ -35,7 +35,7 @@ The system consists of three main components: signers, aggregators, and clients. - **Mithril signing keys** are rotated every epoch and require certification by the Cardano KES key. Therefore, Mithril signers must have access to the KES key to register a signing key for each epoch. - **Cardano KES keys** are also used by the block-producing `cardano-node` and are typically located on the same machine that produces blocks. These keys must be evolved every 36 hours, although they can be rotated from a root key when needed. For more details, see [KES period documentation](https://github.com/IntersectMBO/cardano-node-wiki/blob/main/docs/stake-pool-operations/7_KES_period.md). -:::info To do +:::info[To do] Is there a Cardano threat model available for this? @@ -55,7 +55,7 @@ Mithril clients do connect to an aggregator using HTTP over TLS to query Mithril A Mithril client can verify the received Mithril certificate is linked to other certificates up to the genesis certificate and can be verified using the Mithril genesis verification key (see [details](https://mithril.network/doc/mithril/mithril-protocol/certificates/)). -:::info To do +:::info[To do] Missing: the currently recommended relay (reverse proxy) @@ -114,6 +114,7 @@ For each asset, we first identify which part of the **CIA triad** (Confidentiali - The KES key is present only on the block-producing (BP) node but needs to be shared with both the `cardano-node` process and the `mithril-signer` process. - KES keys are needed by `mithril-signer` to sign a verification key along with an operational certificate that authenticates the key for this stake pool ID. - This signing happens at every epoch. + - **Confidentiality**: Yes Capturing KES private keys allows an attacker to impersonate a registered SPO on-chain and produce blocks on its behalf until the keys are rotated. @@ -324,6 +325,7 @@ A DoS on the `mithril-aggregator`. Data integrity of the Cardano block producer’s on-disk database could be compromised either by the action of the Mithril signer or by an attacker with access to the signer. - **Assets at risk**: + - [Block production](#block-production) - [Cardano chain database](#cardano-chain-database). diff --git a/docs/website/src/css/custom.css b/docs/website/src/css/custom.css index 35fc73eafd9..045e13e96e1 100644 --- a/docs/website/src/css/custom.css +++ b/docs/website/src/css/custom.css @@ -158,11 +158,20 @@ h3 { line-height: 2rem; } +.navbar__item:hover { + color: var(--ifm-color-primary); +} + .navbar__items { display: flex !important; font-family: "Lexend"; } +.footer__item:hover { + color: var(--ifm-color-primary-darkest); + text-decoration: underline; +} + .docusaurus-highlight-code-line { background-color: rgba(0, 0, 0, 0.1); display: block; @@ -180,10 +189,6 @@ h3 { } } -a.menu__link:hover { - text-decoration: underline; -} - /* "hack" to makes the announcement bar bigger since it doesn't have "public" css classes */ div[role="banner"] { height: 2.3em; @@ -228,10 +233,201 @@ div[role="banner"] div { margin-bottom: -8px !important; } +/* + There is a Tailwind Preflight-vs-infima layer conflict when moving to Docusaurus v4, + so I have to manually override styling here in custom.css (which was done before so + not a big deal). +*/ +.menu__link { + color: var(--ifm-menu-color); +} + .menu__link--active { + color: var(--ifm-menu-color-active); font-weight: 700; } +.menu__list .menu__list { + padding-left: var(--ifm-menu-link-padding-horizontal); +} + +/* Same Preflight-vs-infima fix stated above */ +[class*="yearGroupHeading"] { + font-size: 1rem; +} + +/* Same Preflight-vs-infima fix stated above */ +.hash-link:hover { + color: var(--ifm-link-color); +} + +.markdown a:hover { + color: var(--ifm-link-hover-color); +} + +/* Same Preflight-vs-infima fix stated above */ +.alert { + border-color: var(--ifm-alert-border-color); + border-style: solid; + border-width: var(--ifm-alert-border-width); + border-left-width: var(--ifm-alert-border-left-width); +} + +/* Same Preflight-vs-infima fix stated above */ +.alert a:hover { + text-decoration-thickness: 2px; +} + +/* Same Preflight-vs-infima fix stated above */ +.pagination-nav__link { + border-color: var(--ifm-color-emphasis-300); + border-style: solid; + border-width: 1px; +} + +.pagination-nav__link:hover { + border-color: var(--ifm-pagination-nav-color-hover); + color: var(--ifm-pagination-nav-color-hover); +} + +/* Same Preflight-vs-infima fix stated above */ +.table-of-contents__link { + color: var(--ifm-toc-link-color); +} + +.table-of-contents__link:hover, +.table-of-contents__link:hover code, +.table-of-contents__link--active, +.table-of-contents__link--active code { + color: var(--ifm-color-primary); +} + +/* Same Preflight-vs-infima fix stated above */ +table thead tr { + border-bottom: 2px solid var(--ifm-table-border-color); +} + +table tr { + border-top: var(--ifm-table-border-width) solid var(--ifm-table-border-color); +} + +table th, +table td { + border: var(--ifm-table-border-width) solid var(--ifm-table-border-color); +} + +/* Same Preflight-vs-infima fix stated above */ +.theme-doc-card-container { + border: 1px solid var(--ifm-color-emphasis-200); +} + +/* Same Preflight-vs-infima fix stated above */ +.theme-doc-sidebar-container { + border-right: 1px solid var(--ifm-toc-border-color); +} + +/* Same Preflight-vs-infima fix stated above */ +blockquote { + border-left: var(--ifm-blockquote-border-left-width) solid + var(--ifm-blockquote-border-color); +} + +/* Same Preflight-vs-infima fix stated above */ +.tabs__item { + border-bottom: 3px solid transparent; +} + +.tabs__item--active { + border-bottom-color: var(--ifm-tabs-color-active-border); +} + +/* Same Preflight-vs-infima fix stated above */ +code { + border: 0.1rem solid rgba(0, 0, 0, 0.1); +} + +/* Same Preflight-vs-infima fix stated above */ +a[rel="tag"] { + border: 1px solid + var(--docusaurus-tag-list-border, var(--ifm-color-emphasis-300)); +} + +a[rel="tag"]:hover { + border-color: var(--ifm-link-color); +} + +/* Same Preflight-vs-infima fix stated above */ +.theme-code-block [class*="codeBlockTitle"] { + border-bottom: 1px solid var(--ifm-color-emphasis-300); +} + +/* Same Preflight-vs-infima fix stated above */ +.theme-code-block [class*="buttonGroup"] button { + background: var(--prism-background-color); + color: var(--prism-color); + border: 1px solid var(--ifm-color-emphasis-300); + padding: 0.4rem; +} + +/* Same Preflight-vs-infima fix stated above */ +.theme-doc-toc-mobile [class*="tocCollapsibleContent"] > ul { + border-top: 1px solid var(--ifm-color-emphasis-300); +} + +/* Same Preflight-vs-infima fix stated above */ +.table-of-contents__left-border { + border-left: 1px solid var(--ifm-toc-border-color); +} + +/* Same Preflight-vs-infima fix stated above */ +.navbar__link:hover, +.navbar__link--active { + color: var(--ifm-navbar-link-hover-color); +} + +/* Same Preflight-vs-infima fix stated above */ +.navbar__logo img { + height: 100%; +} + +/* Same Preflight-vs-infima fix stated above */ +.container { + max-width: var(--ifm-container-width); +} + +@media (min-width: 1440px) { + .container { + max-width: var(--ifm-container-width-xl); + } +} + +.theme-doc-card-container:hover { + border-color: var(--ifm-color-primary); + color: var(--ifm-color-emphasis-700); +} + +/* Same Preflight-vs-infima fix stated above */ +.dropdown > .navbar__link:after { + border-color: currentColor transparent; + border-style: solid; + border-width: 0.4em 0.4em 0; +} + +/* Same Preflight-vs-infima fix stated above */ +.dropdown__link { + color: var(--ifm-dropdown-link-color); +} + +.dropdown__link:hover, +.dropdown__link--active { + color: var(--ifm-color-primary); +} + +.dropdown__link--active, +.dropdown__link--active:hover { + color: var(--ifm-link-color); +} + a.menu__link { text-decoration: none !important; -webkit-text-decoration: none !important; @@ -338,6 +534,13 @@ a.menu__link { .title_f1Hy { font-weight: 700; + font-size: 3rem; +} + +@media (max-width: 576px) { + .title_f1Hy { + font-size: 2rem; + } } .markdown h3 { @@ -362,6 +565,12 @@ a.menu__link { align-items: center; } +/* Same Preflight-vs-infima fix stated above */ +.theme-edit-this-page:hover { + text-decoration: underline; + color: var(--ifm-link-hover-color); +} + .stuck-grid { perspective: 500px; transform-style: preserve-3d; diff --git a/docs/website/versioned_docs/version-maintained/manual/operate/run-aggregator-node.md b/docs/website/versioned_docs/version-maintained/manual/operate/run-aggregator-node.md index f0ff317b9ad..f27284d3bac 100644 --- a/docs/website/versioned_docs/version-maintained/manual/operate/run-aggregator-node.md +++ b/docs/website/versioned_docs/version-maintained/manual/operate/run-aggregator-node.md @@ -60,6 +60,7 @@ Note that this guide works only on a Linux machine. - Operate a **Cardano full node** - To access the file system of the **Cardano full node**, you will need the following permissions: + - Read rights on the `Database` folder (specified by the `--database-path` setting of the **Cardano node**) - Read and write rights on the `Inter Process Communication` file (typically defined by the `CARDANO_NODE_SOCKET_PATH` environment variable used to launch the **Cardano node**) @@ -273,10 +274,12 @@ The configuration values for the `/opt/mithril/mithril-aggregator.env` file are - `CUSTOM_ORIGIN_TAG_WHITE_LIST`: Comma-separated list of custom origin tags to whitelist for client requests (default: `EXPLORER,BENCHMARK,CI,NA`). - **Base configuration** **optional** values are: + - `BLOCKFROST_PARAMETERS`: Parameters to connect to the Blockfrost API. Used to fetch the ticker and name of the registered stake pools. Example: `{"project_id":"preprodWuV1ICdtOWfZYfdcxpZ0tsS1N9rVZomQ"}` - `SIGNER_IMPORTER_RUN_INTERVAL`: Time interval at which the pools names and ticker in blockfrost will be imported (in minutes, default: `720`). - The **Cardano database** configuration values are (only needed if supporting Cardano database certification): + - `DB_DIRECTORY`: Directory of the Cardano node database stores (same as the `--database-path` setting of the Cardano node) - `DATA_STORES_DIRECTORY`: Directory where the aggregator will store its databases (eg, `/opt/mithril/stores`) - `GOOGLE_APPLICATION_CREDENTIALS_JSON`: JSON content of the GCP service account credentials (required if using GCP for snapshot storage) @@ -300,6 +303,7 @@ The configuration values for the `/opt/mithril/mithril-aggregator.env` file are Here is an **example** set of values for **release-preprod** that will be used in this guide in the **tip** boxes to illustrate some commands: - **Base configuration**: + - **SIGNED_ENTITY_TYPES**: `MithrilStakeDistribution,CardanoStakeDistribution,CardanoTransactions` (only supporting stake distributions and transactions, excluding database snapshots) - **SERVER_PORT**: `8080` - **PUBLIC_SERVER_URL**: `https://aggregator.example.com/aggregator` @@ -319,10 +323,12 @@ Here is an **example** set of values for **release-preprod** that will be used i - **CUSTOM_ORIGIN_TAG_WHITE_LIST**: `EXPLORER,BENCHMARK,CI,NA` - **Optional configuration**: + - **BLOCKFROST_PARAMETERS**: `{"project_id":"preprodWuV1ICdtOWfZYfdcxpZ0tsS1N9rVZomQ"}` - **SIGNER_IMPORTER_RUN_INTERVAL**: 720 - **Cardano database configuration**: + - **DB_DIRECTORY**: `/cardano/db` - **DATA_STORES_DIRECTORY**: `/opt/mithril/stores` - **GOOGLE_APPLICATION_CREDENTIALS_JSON**: `**YOUR_SECRET**` @@ -1300,6 +1306,7 @@ If you want to make your follower aggregator publicly discoverable, you should: 1. **Ensure your aggregator is accessible via HTTPS** by setting up Traefik or another reverse proxy with a valid SSL certificate (as described in the [Set up the SSL certificate](#setup-the-ssl-certificate-traefik) section). 2. **Register your aggregator in the networks configuration**. You can do this by: + - Opening an issue in the [Mithril GitHub repository](https://github.com/input-output-hk/mithril/issues) - Or by creating a pull request that modifies the [`networks.json`](https://github.com/input-output-hk/mithril/blob/main/networks.json) file and updates the `aggregators` field in the Cardano network you are targeting. diff --git a/docs/website/versioned_docs/version-maintained/manual/operate/run-signer-node.md b/docs/website/versioned_docs/version-maintained/manual/operate/run-signer-node.md index f61bad85951..8fc822683f4 100644 --- a/docs/website/versioned_docs/version-maintained/manual/operate/run-signer-node.md +++ b/docs/website/versioned_docs/version-maintained/manual/operate/run-signer-node.md @@ -99,10 +99,12 @@ Note that this guide works only on a Linux machine. ::: - To operate a **Cardano node** as a **stake pool**, you need: + - The pool's `operational certificate` - The pool's `KES secret key` - To access the file system of the **Cardano block-producing** node for **production** deployment (or of the **Cardano relay** node for **naive** deployment), you will need the following permissions: + - Read rights on the `Database` folder (specified by the `--database-path` setting of the **Cardano node**) - Read and write rights on the `Inter Process Communication` file (typically defined by the `CARDANO_NODE_SOCKET_PATH` environment variable used to launch the **Cardano node**) @@ -546,6 +548,7 @@ sudo systemctl restart mithril-signer :::info - If you have already installed `Squid` via the `apt` package manager, we recommend that you delete it before manually building it from source by running the following commands: + - `sudo systemctl stop squid` - `sudo apt remove squid` - `sudo apt autoremove` diff --git a/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/certificates.md b/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/certificates.md index 92bfe35d2ec..dfaa37340f3 100644 --- a/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/certificates.md +++ b/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/certificates.md @@ -57,7 +57,7 @@ Information embedded in the `METADATA(p,n)` field: The message `MSG(p,n)` is a map of multiple values associated with their respective keys. It provides a way to add more information to the certificates without breaking the chain itself. Added items can be any message that the signers can compute deterministically thanks to the Cardano consensus – an immutable files snapshot, the UTXO set, stake distribution, etc. -:::note +:::note[Note] The **trigger** represents the instant at which a certificate should be created. It is combined with at least the associated **epoch** to create a [**beacon**](../../../glossary.md#beacon) of the certificate. In the current implementation of the Cardano node database snapshot, this trigger is a new [**immutable file number**](../../../glossary.md#immutable-file-number). diff --git a/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/protocol.md b/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/protocol.md index c92d90d7167..2c1e5b892d3 100644 --- a/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/protocol.md +++ b/docs/website/versioned_docs/version-maintained/mithril/advanced/mithril-protocol/protocol.md @@ -44,7 +44,7 @@ The protocol has three phases: 2. **Initialization phase** during which Mithril nodes generate and exchange keys 3. **Operations phase** during which nodes sign and aggregate signatures of messages to produce certificates. -:::note Note +:::note[Note] Note that all three phases require a set of parties (`P` in the paper) to be fixed. During the protocol establishment phase three important parameters are generated: @@ -103,6 +103,7 @@ a quorum of `k` valid signatures must be submitted. - For every valid signature, the party creates a proof (`π`) containing a signature of the message, verification key, stake, and paths of the party in the Merkle tree. - Then, multiple signatures can be aggregated together to form a certificate (`τ`) by: + - Verifying signatures from each party: - Checking the party is authorized to sign for the given index (using the same procedure as signing) - Checking the proof is valid which means: @@ -117,7 +118,7 @@ a quorum of `k` valid signatures must be submitted. - Each certificate `τ` can be verified as valid for some message, using the known setup parameters to verify the certificate’s proof and then verifying the aggregate signatures and verification keys. -:::note Note +:::note[Note] Note that if the individual signatures are broadcast to all parties, then each party can independently produce the certificates. In particular, the party that performs aggregation is not required to have any specific knowledge, nor it is assumed to be honest. This means that _any_ third party that has access to the individual signatures can perform the signature aggregation. diff --git a/docs/website/versioned_docs/version-maintained/mithril/advanced/threat-model.md b/docs/website/versioned_docs/version-maintained/mithril/advanced/threat-model.md index 2fa3166fef6..82731bdca80 100644 --- a/docs/website/versioned_docs/version-maintained/mithril/advanced/threat-model.md +++ b/docs/website/versioned_docs/version-maintained/mithril/advanced/threat-model.md @@ -22,7 +22,7 @@ The threat model is a living document, updated to reflect the [latest Mithril ve ### System description -:::info To do +:::info[To do] - Consider reducing these details and moving them into the [architecture page](https://mithril.network/doc/mithril/mithril-network/architecture). - Also consider updating the [protocol page](https://mithril.network/doc/mithril/mithril-protocol/protocol). @@ -35,7 +35,7 @@ The system consists of three main components: signers, aggregators, and clients. - **Mithril signing keys** are rotated every epoch and require certification by the Cardano KES key. Therefore, Mithril signers must have access to the KES key to register a signing key for each epoch. - **Cardano KES keys** are also used by the block-producing `cardano-node` and are typically located on the same machine that produces blocks. These keys must be evolved every 36 hours, although they can be rotated from a root key when needed. For more details, see [KES period documentation](https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/stake-pool-operations/7_KES_period.md). -:::info To do +:::info[To do] Is there a Cardano threat model available for this? @@ -55,7 +55,7 @@ Mithril clients do connect to an aggregator using HTTP over TLS to query Mithril A Mithril client can verify the received Mithril certificate is linked to other certificates up to the genesis certificate and can be verified using the Mithril genesis verification key (see [details](https://mithril.network/doc/mithril/mithril-protocol/certificates/)). -:::info To do +:::info[To do] Missing: the currently recommended relay (reverse proxy) @@ -114,6 +114,7 @@ For each asset, we first identify which part of the **CIA triad** (Confidentiali - The KES key is present only on the block-producing (BP) node but needs to be shared with both the `cardano-node` process and the `mithril-signer` process. - KES keys are needed by `mithril-signer` to sign a verification key along with an operational certificate that authenticates the key for this stake pool ID. - This signing happens at every epoch. + - **Confidentiality**: Yes Capturing KES private keys allows an attacker to impersonate a registered SPO on-chain and produce blocks on its behalf until the keys are rotated. @@ -324,6 +325,7 @@ A DoS on the `mithril-aggregator`. Data integrity of the Cardano block producer’s on-disk database could be compromised either by the action of the Mithril signer or by an attacker with access to the signer. - **Assets at risk**: + - [Block production](#block-production) - [Cardano chain database](#cardano-chain-database).