From a22feb3f8be8270d83f639501bc2adbd6db675d0 Mon Sep 17 00:00:00 2001 From: Ivan Gromakovskii Date: Tue, 23 Jan 2024 18:25:12 +0100 Subject: [PATCH] Ignore/fix broken links Problem: several links in Markdown files are broken. Solution: 1. Links in References.md, index.md and TechnicalReports.md are invalid in the sense of Markdown and this repo, but they work on the website, so they are explicitly ignored. 2. Glossary.md contains many links to anchors in the same file. These anchors work differently in Markdown and Docusarus as can be seen here: https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/ Ideally, they should be fixed to work on the resulting website, in which case all of them would be broken in the sense of Markdown. Fixing them for Docusaurus is out of scope of this commit, but we force xrefcheck to ignore all links in that file in preparation for that fix. 3. There is also an anchor link in VersioningSchemeDecision.md, but this file is not used in the resulting website, so we fix it according to Markdown rules. --- CONTRIBUTING.md | 8 ++++---- docs/website/contents/about-ouroboros/References.md | 7 ++++++- docs/website/contents/about-ouroboros/index.md | 1 + docs/website/contents/for-developers/ChainSync.md | 2 +- docs/website/contents/for-developers/GitProcess.md | 4 ++-- docs/website/contents/for-developers/Glossary.md | 1 + .../for-developers/HandlingBlocksFromTheFuture.md | 2 +- docs/website/contents/for-developers/NodeTasks.md | 4 +++- docs/website/contents/for-developers/PreflightGuide.md | 10 +++++----- .../contents/for-developers/TechnicalReports.md | 3 +++ .../for-developers/VersioningSchemeDecision.md | 2 +- ouroboros-consensus-cardano/README.md | 2 +- ouroboros-consensus-diffusion/CHANGELOG.md | 2 +- 13 files changed, 30 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 23a77559d9..7fbdef98f8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,8 +28,8 @@ We have two types of documentation: When starting to work on Consensus, we recommend to take a look at the following resources: - - [Preflight guide](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/PreflightGuide) - - [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary) + - [Preflight guide](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/PreflightGuide/) + - [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/) When adding or improving documentation about the implementation, it is preferable to add haddock comments since they are closer to the code. However @@ -53,7 +53,7 @@ live in this repository. ## Using Nix -Consensus can be built using [Nix](https://nixos.org/download.html). The +Consensus can be built using [Nix](https://nixos.org/download/). The installation and configuration instructions are taken from [cardano-node](https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/getting-started/building-the-node-using-nix.md), and detailed below. To install `nix` run: @@ -378,5 +378,5 @@ See [Cardano engineering handbook](https://github.com/input-output-hk/cardano-engineering-handbook/blob/main/CODE-OF-CONDUCT.md)'s code of conduct. -[haddock-site]: https://haskell-haddock.readthedocs.io/en/latest/ +[haddock-site]: https://haskell-haddock.readthedocs.io/latest/ [chap]: https://github.com/IntersectMBO/cardano-haskell-packages diff --git a/docs/website/contents/about-ouroboros/References.md b/docs/website/contents/about-ouroboros/References.md index 437d6ed704..1b3a6d11d2 100644 --- a/docs/website/contents/about-ouroboros/References.md +++ b/docs/website/contents/about-ouroboros/References.md @@ -2,13 +2,18 @@ The following artifacts influence and/or describe the Consensus implementation. + * [Technical reports](../for-developers/TechnicalReports) * From the IOG researchers: * [Ouroboros BFT][ouroboros-bft] * [Ouroboros Praos][ouroboros-praos] * [Ouroboros Genesis][ouroboros-genesis] * [Ledger specifications][cardano-ledger]. -* Consensus (Praos) specification: [Agda style](/pdfs/consensus-spec-agda.pdf), [LaTeX style](/pdfs/consensus-spec.pdf) +* Consensus (Praos) specification: + + [Agda style](/pdfs/consensus-spec-agda.pdf), + + [LaTeX style](/pdfs/consensus-spec.pdf) * [Quick reference table for all Cardano features](https://github.com/cardano-foundation/CIPs/blob/master/CIP-0059/feature-table.md). This includes the dates and first slot numbers of all eras and hard forks. * IOG media: diff --git a/docs/website/contents/about-ouroboros/index.md b/docs/website/contents/about-ouroboros/index.md index 3e4489b4bb..7cb7628db8 100644 --- a/docs/website/contents/about-ouroboros/index.md +++ b/docs/website/contents/about-ouroboros/index.md @@ -40,6 +40,7 @@ The Ouroboros research papers that formalize the different protocols (such as Pr - the honest nodes will all continually and eventually agree on what the best chain is (unless an adversary controls more than half of the network's stake). - the best chain grows over time. + The Consensus Layer defines the core Consensus components and logic, notably the Ouroboros protocol. See [References](References). diff --git a/docs/website/contents/for-developers/ChainSync.md b/docs/website/contents/for-developers/ChainSync.md index 7338d7746a..90a1557611 100644 --- a/docs/website/contents/for-developers/ChainSync.md +++ b/docs/website/contents/for-developers/ChainSync.md @@ -158,4 +158,4 @@ trim their fragment so that it is anchored at our anchor point. sufficient number of headers to determine if their chain is preferred over ours (this needs careful consideration when adopting genesis). -[^glossary]: See the [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary) \ No newline at end of file +[^glossary]: See the [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/) \ No newline at end of file diff --git a/docs/website/contents/for-developers/GitProcess.md b/docs/website/contents/for-developers/GitProcess.md index 2950cc878b..00490414c6 100644 --- a/docs/website/contents/for-developers/GitProcess.md +++ b/docs/website/contents/for-developers/GitProcess.md @@ -66,7 +66,7 @@ If you'd like to opt-in to that or similar, add a `cabal.project.local` file. #NNNN`. See the [GitHub documentation][gh-auto-link-issue] for similar keywords and syntax that will trigger useful automatic behaviors. - [gh-auto-link-issue]: https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword + [gh-auto-link-issue]: https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword * Your PR should be a [Draft PR][github-draft-pr] until you think it is ready for final review and merging. I often open my PR as Draft PR in order to get @@ -76,7 +76,7 @@ If you'd like to opt-in to that or similar, add a `cabal.project.local` file. This is far superior to including "WIP" or "DO NOT MERGE" in the PR title, or a WIP label, etc. - [github-draft-pr]: https://github.blog/2019-02-14-introducing-draft-pull-requests/ + [github-draft-pr]: https://github.blog/news-insights/product-news/introducing-draft-pull-requests/ * Your branch name is impermanent, so it's less important than the above. However, we prefer the format `username/issue-NNNN-short-description` or diff --git a/docs/website/contents/for-developers/Glossary.md b/docs/website/contents/for-developers/Glossary.md index 9d172d2e40..54942ad5c4 100644 --- a/docs/website/contents/for-developers/Glossary.md +++ b/docs/website/contents/for-developers/Glossary.md @@ -1,3 +1,4 @@ + # Glossary Notes on the use and maintenance of this glossary: diff --git a/docs/website/contents/for-developers/HandlingBlocksFromTheFuture.md b/docs/website/contents/for-developers/HandlingBlocksFromTheFuture.md index 3a4cbb769f..48094675b9 100644 --- a/docs/website/contents/for-developers/HandlingBlocksFromTheFuture.md +++ b/docs/website/contents/for-developers/HandlingBlocksFromTheFuture.md @@ -41,4 +41,4 @@ In the future we might delete blocks from the future from the `VolatileDB` to im # References - [Original issue that prompted the fix](https://github.com/IntersectMBO/ouroboros-network/issues/4251) -- [Blocks from the future (Incident report)](https://updates.cardano.intersectmbo.org/2024-09-07-incident) +- [Blocks from the future (Incident report)](https://updates.cardano.intersectmbo.org/2024-09-07-incident/) diff --git a/docs/website/contents/for-developers/NodeTasks.md b/docs/website/contents/for-developers/NodeTasks.md index 43a0f56488..1d3da9818f 100644 --- a/docs/website/contents/for-developers/NodeTasks.md +++ b/docs/website/contents/for-developers/NodeTasks.md @@ -1,5 +1,6 @@ # Overview of the tasks of a caught-up node + This document gives an overview of the tasks of a [caught-up](./Glossary.md#honest-caught-up-parties) node, both as a relay and as a block producer. ## In a single node @@ -22,7 +23,8 @@ The selection is made up of an immutable and a volatile part: - The volatile part of the selection are the newest $k$ blocks. They are stored in the VolatileDB, together with other blocks that could be on a fork we might switch to in the future. -Additionally, the LedgerDB contains the ledger state corresponding to all [points](./Glossary/#point) on the volatile part of the chain as well as the tip of the immutable chain, in order to validate new blocks and potential forks. + +Additionally, the LedgerDB contains the ledger state corresponding to all [points](./Glossary.md#point) on the volatile part of the chain as well as the tip of the immutable chain, in order to validate new blocks and potential forks. The flow of information is depicted in the following diagram. Rectangular boxes stand for logical components, and hexagons correspond to Haskell RTS threads. diff --git a/docs/website/contents/for-developers/PreflightGuide.md b/docs/website/contents/for-developers/PreflightGuide.md index 127f221d4e..7e259f55be 100644 --- a/docs/website/contents/for-developers/PreflightGuide.md +++ b/docs/website/contents/for-developers/PreflightGuide.md @@ -259,7 +259,7 @@ Finally, we shall note that there are various ideas of how to eliminate grinding [^utxo-hd]: The main reason for this is that the ledger state, ie the aggregated information necessary to validate blocks, is currently fully stored in memory. The Consensus team is currently working on *UTxO HD*, a solution to move the ledger state to disk. -[^resource-relative]: Cardano is not a huge outlier in either direction, there are many examples for blockchains that are either much less resource-intensive (due to very low activity or new age, or due to very fancy cryptography, like Mina) or much more resource-intensive (due to very old age and large accumulated history, like Bitcoin, or a hyperfocus on performance, like [Solana](https://docs.solana.com/running-validator/validator-reqs#hardware-recommendations)). +[^resource-relative]: Cardano is not a huge outlier in either direction, there are many examples for blockchains that are either much less resource-intensive (due to very low activity or new age, or due to very fancy cryptography, like Mina) or much more resource-intensive (due to very old age and large accumulated history, like Bitcoin, or a hyperfocus on performance, like [Solana](https://docs.anza.xyz/operations/requirements#hardware-recommendations)). [^genesis-syncing]: As of early 2024, syncing is a fully trusted process; if any node you are syncing from is adversarial, you might end up on an adversarial chain. There is an ongoing effort to implement *Ouroboros Genesis* in order to reduce this strong trust assumption; in particular, it will involve reaching out to lots of nodes while syncing. @@ -293,17 +293,17 @@ for Ungrindable Blockchains" by Kiayias et al](https://eprint.iacr.org/2021/1698 [cardano-cli]: https://github.com/IntersectMBO/cardano-cli [cardano-db-sync]: https://github.com/IntersectMBO/cardano-db-sync [kupo]: https://github.com/cardanosolutions/kupo -[hydra]: https://github.com/input-output-hk/hydra +[hydra]: https://github.com/cardano-scaling/hydra [ogmios]: https://github.com/CardanoSolutions/ogmios [node release page]: https://github.com/IntersectMBO/cardano-node/releases [cardano mainnet conf]: https://github.com/IntersectMBO/cardano-node/blob/master/configuration/cardano/mainnet-config.yaml [cardano mainnet topo]: https://github.com/IntersectMBO/cardano-node/blob/master/configuration/cardano/mainnet-topology.json -[Mithril client]: https://mithril.network/doc -[Mithril instructions]: https://mithril.network/doc/manual/getting-started/bootstrap-cardano-node +[Mithril client]: https://mithril.network/doc/ +[Mithril instructions]: https://mithril.network/doc/manual/getting-started/bootstrap-cardano-node/ [Magic Wormhole]: https://github.com/magic-wormhole/magic-wormhole [db-analyser]: https://github.com/IntersectMBO/ouroboros-consensus/blob/main/ouroboros-consensus-cardano/README.md#db-analyser [Cardano ledger]: https://github.com/IntersectMBO/cardano-ledger -[Glossary]: https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary +[Glossary]: https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/ [db-analyser snapshot]: https://github.com/IntersectMBO/ouroboros-consensus/blob/main/ouroboros-consensus-cardano/README.md#saving-a-snapshot [preflight epic]: https://github.com/IntersectMBO/ouroboros-consensus/issues/887 [Ouroboros Praos paper]: https://iohk.io/en/research/library/papers/ouroboros-praos-an-adaptively-secure-semi-synchronous-proof-of-stake-protocol/ diff --git a/docs/website/contents/for-developers/TechnicalReports.md b/docs/website/contents/for-developers/TechnicalReports.md index 0b0df7e220..2d428292cd 100644 --- a/docs/website/contents/for-developers/TechnicalReports.md +++ b/docs/website/contents/for-developers/TechnicalReports.md @@ -4,12 +4,15 @@ The following artifacts influence and/or describe the Consensus implementation. ## Consensus and networking + * [The Cardano Consensus and Storage Layer](/pdfs/report.pdf). * [Introduction to the design of Data Diffusion and Networking of Cardano Shelley][network-report]. ## UTxO-HD + * [Storing the Cardano ledger state on disk: analysis and design options (An IOHK technical report)](/pdfs/utxo-db.pdf) + * [Storing the Cardano ledger state on disk: API design concepts (An IOHK technical report)](/pdfs/utxo-db-api.pdf) diff --git a/docs/website/contents/for-developers/VersioningSchemeDecision.md b/docs/website/contents/for-developers/VersioningSchemeDecision.md index d4d138eed1..c5fb807863 100644 --- a/docs/website/contents/for-developers/VersioningSchemeDecision.md +++ b/docs/website/contents/for-developers/VersioningSchemeDecision.md @@ -495,7 +495,7 @@ This rule is so simple that the ✗ for EasyPR is somewhat surpising. The hidden problem is that this scheme causes spurious merge conflicts among all your PRs. It would only be possible to merge PRs sequentially and merging one PR requires rebasing every other PR and updating its version number diff (assuming a single target branch). That usually implies a very poor contributor experience. -(If you're wondering about variations on this, such as "only bump the version if it hasn't already been bumped", see [below](#RisingEdgeCompromises).) +(If you're wondering about variations on this, such as "only bump the version if it hasn't already been bumped", see [below](#possible-risingedge-compromises).) We assign ✓ for EasyRelease because each release doesn't require any additional work; merely announce the result of the latest PR. Relatedly, though, we assign ✗ for TypicalReleases because it's unrealistic to release after every PR. diff --git a/ouroboros-consensus-cardano/README.md b/ouroboros-consensus-cardano/README.md index e91ff4dafc..36fdbfab14 100644 --- a/ouroboros-consensus-cardano/README.md +++ b/ouroboros-consensus-cardano/README.md @@ -196,7 +196,7 @@ See this file for usage information. If no analysis flag is provided, then the ChainDB will be opened, all the chunks in the immutable and volatile databases will be validated (see -[validation](#database-validation)), and the tool will exit. +[validation](#database-validation-via---db-validation)), and the tool will exit. ### Examples diff --git a/ouroboros-consensus-diffusion/CHANGELOG.md b/ouroboros-consensus-diffusion/CHANGELOG.md index ae57dde8f7..882b938796 100644 --- a/ouroboros-consensus-diffusion/CHANGELOG.md +++ b/ouroboros-consensus-diffusion/CHANGELOG.md @@ -143,7 +143,7 @@ NOTE: version jumps from `0.11.0.0` to `0.13.0.0` because `0.12.0.0` was created - Added the Genesis State Machine (GSM), though for now it is merely the simpler [Bootstrap Peers State - Machine](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/BootstrapPeersIER). + Machine](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/BootstrapPeersIER/). - Added `rnGetUseBootstrapPeers` to `RunNodeArgs`, for dynamically enabling/disabling the GSM. The proper GSM must always be running, despite