IntersectMBO · gromakovsky · Jan 23, 2024 · Jan 23, 2024
@@ -108,3 +108,14 @@ jobs:
 
     - name: Diff plans
       run: GH=1 ./scripts/release/cabal-plan-diff.sh
+
+  xrefcheck:
+
+    name: Check references
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: serokell/xrefcheck-action@v1
+      with:
+        xrefcheck-version: 0.3.0
@@ -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
@@ -2,13 +2,18 @@
 
 The following artifacts influence and/or describe the Consensus implementation.
 
+<!-- xrefcheck: ignore link -->
 * [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:
+    <!-- xrefcheck: ignore link -->
+    [Agda style](/pdfs/consensus-spec-agda.pdf),
+    <!-- xrefcheck: ignore link -->
+    [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:

@@ -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.
 
+<!-- xrefcheck: ignore link -->
 The Consensus Layer defines the core Consensus components and logic, notably the
 Ouroboros protocol. See [References](References).
 

@@ -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)
+[^glossary]: See the [Glossary](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/Glossary/)
@@ -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

@@ -1,3 +1,4 @@
+<!-- xrefcheck: ignore all -->
 # Glossary
 
 Notes on the use and maintenance of this glossary:

@@ -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/)
@@ -1,5 +1,6 @@
 # Overview of the tasks of a caught-up node
 
+<!-- xrefcheck: ignore link -->
 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.
+<!-- xrefcheck: ignore link -->
+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.

@@ -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/

@@ -4,12 +4,15 @@ The following artifacts influence and/or describe the Consensus implementation.
 
 ## Consensus and networking
 
+<!-- xrefcheck: ignore link -->
 * [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
 
+<!-- xrefcheck: ignore link -->
 * [Storing the Cardano ledger state on disk: analysis and design options (An IOHK technical report)](/pdfs/utxo-db.pdf)
+<!-- xrefcheck: ignore link -->
 * [Storing the Cardano ledger state on disk: API design concepts (An IOHK technical report)](/pdfs/utxo-db-api.pdf)
 
 

@@ -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.

@@ -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
 

@@ -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