chore: add markdown linter

.github/workflows/link-check-config.json

@@ -0,0 +1,20 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "(localhost)"
+    }
+  ],
+  "replacementPatterns": [
+    {
+      "pattern": "(^\\/(architecture|event)[^#]*)(#.*|$)",
+      "replacement": "$1.md$3"
+    },
+    {
+      "pattern": "^(\\/|@site\\/)",
+      "replacement": "{{BASEURL}}/docs/"
+    }
+  ],
+  "retryOn429": true,
+  "retryCount": 3,
+  "fallbackRetryDelay": "10s"
+}

.github/workflows/markdown-lint.yml

@@ -0,0 +1,25 @@
+name: Markdown Lint
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "**.md"
+      - "!.github/**"
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: tj-actions/changed-files@v39
+      id: changed-files
+      with:
+        files: '**/*.md'
+        separator: ","
+    - uses: DavidAnson/markdownlint-cli2-action@v13
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-files.outputs.all_changed_files }}
+        separator: ","

.markdownlint-cli2.jsonc

@@ -0,0 +1,8 @@
+// This file is used by markdownlint-cli2 to configure the linting process
+// in conjunction with .markdownlint.jsonc.
+{
+  "ignores": [
+    ".github",
+    "**/CHANGELOG.md"
+  ]
+}

.markdownlint.jsonc

@@ -0,0 +1,18 @@
+{
+  "default": true,
+  "MD003": { "style": "atx" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md003---heading-style
+  "MD004": { "style": "dash" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md004---unordered-list-style
+  "MD007": { "indent": 2 }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md007---unordered-list-indentation
+  "MD009": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md009---trailing-spaces
+  "MD010": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md010---hard-tabs
+  "MD013": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md013---line-length
+  "MD024": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024---multiple-headings-with-the-same-content
+  "MD025": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md025---multiple-top-level-headings-in-the-same-document
+  "MD029": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix
+  "MD031": { "list_items": false }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md031---fenced-code-blocks-should-be-surrounded-by-blank-lines 
+  "MD033": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033---inline-html
+  "MD036": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md036---emphasis-used-instead-of-a-heading
+  "MD041": false, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041---first-line-in-a-file-should-be-a-top-level-heading
+  "MD049": { "style": "asterisk" }, // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md049---emphasis-style-should-be-consistent
+  "MD050": { "style": "asterisk" } // https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md050---strong-style-should-be-consistent
+}

Makefile

@@ -0,0 +1,13 @@
+#!/usr/bin/make -f
+
+###############################################################################
+###                                Linting                                  ###
+###############################################################################
+
+docs-lint:
+	markdownlint-cli2 "**.md"
+
+docs-lint-fix:
+	markdownlint-cli2-fix "**.md"
+
+.PHONY: docs-lint docs-lint-fix

archive/papers/2020-05/README.md

@@ -9,6 +9,6 @@ Submission options:
   - Remove author names from paper
   - Pre-prints OK
   - Prior work:
-    - https://assets.pubpub.org/asuzx3df/11581974880753.pdf
-    - https://assets.pubpub.org/a7tcrzro/31581340169699.pdf
-    - https://assets.pubpub.org/g84cchsz/11581340329396.pdf
+    - <https://assets.pubpub.org/asuzx3df/11581974880753.pdf>
+    - <https://assets.pubpub.org/a7tcrzro/31581340169699.pdf>
+    - <https://assets.pubpub.org/g84cchsz/11581340329396.pdf>

archive/papers/2020-05/src/fungible-token-transfer.md

@@ -39,7 +39,6 @@ interface FungibleTokenPacketData {
 
 The acknowledgement data type describes whether the transfer succeeded or failed, and the reason for failure (if any):
 
-
 ```typescript
 interface FungibleTokenPacketAcknowledgement {
   success: boolean

archive/papers/2020-05/src/paper.md

@@ -59,5 +59,3 @@
 \twocolumn
 
 # References
-
-

meta/CONTRIBUTING.md

@@ -35,6 +35,7 @@ If fixing an issue requires changes to multiple standards, create multiple PRs a
 All PRs require an approval from at least two members of the [standardisation committee](./STANDARDS_COMMITTEE.md) before merge. 
 The PRs submitted by one of the members of the standardisation committee require an approval from only one other member before merge. 
 When reviewing PRs please use the following review explanations:
+
 - `Approval` through the GH UI means that you understand all the changes proposed in the PR. In addition:
   - You must also think through anything which ought to be included but is not.
   - You must think through any potential security issues or incentive-compatibility flaws introduced by the changes.
@@ -58,4 +59,3 @@ Ensure that you base and target your PR on the `master` branch.
 
 - Ensure all github requirements pass.
 - Squash and merge pull request.
-

meta/PROCESS.md

@@ -2,23 +2,23 @@
 
 IBC standardisation will follow an adaptation of the [TC 39](https://tc39.github.io/process-document/) process used by the ECMAScript steering committee.
 
-#### Stage 1 - `Strawman`
+### Stage 1 - `Strawman`
 
-- _**Purpose**_: Start the specification process
-- _**Entrance Criteria**_: [Open an issue](https://github.com/cosmos/ibc/issues/new) on this repository with a short outline of your proposal and a specification name.
-- _**Acceptance Requirements**_: No acceptance required to move to the next stage. Keep the issue around to track the specification status, and close it when the final specification is merged or the proposal abandoned.
-- _**Spec Quality**_: Outline only. Link to any prior documentation, discussion, or reference materials.
-- _**Changes Expected Post-Acceptance**_: N/A
-- _**Implementation Types Expected**_: None required, but link to any existing
+- ***Purpose***: Start the specification process
+- ***Entrance Criteria***: [Open an issue](https://github.com/cosmos/ibc/issues/new) on this repository with a short outline of your proposal and a specification name.
+- ***Acceptance Requirements***: No acceptance required to move to the next stage. Keep the issue around to track the specification status, and close it when the final specification is merged or the proposal abandoned.
+- ***Spec Quality***: Outline only. Link to any prior documentation, discussion, or reference materials.
+- ***Changes Expected Post-Acceptance***: N/A
+- ***Implementation Types Expected***: None required, but link to any existing
 
-#### Stage 2 - `Draft`
+### Stage 2 - `Draft`
 
-- _**Purpose**_:
-  * Make the case for the addition of this specification to the IBC ecosystem
-  * Describe the shape of a potential solution
-  * Identify challenges to this proposal
-- _**Entrance Criteria**_:
-  * Prose outlining the problem or need and the general shape of a solution in a PR to a `./spec/{area}/ics-{{ .Spec.Number }}-{{ .Spec.Name }}/README.md` file in this repository.
+- ***Purpose***:
+  - Make the case for the addition of this specification to the IBC ecosystem
+  - Describe the shape of a potential solution
+  - Identify challenges to this proposal
+- ***Entrance Criteria***:
+  - Prose outlining the problem or need and the general shape of a solution in a PR to a `./spec/{area}/ics-{{ .Spec.Number }}-{{ .Spec.Name }}/README.md` file in this repository.
     This file should contain:
     - List of expected projects & users within the Cosmos ecosystem who might make use of the specification along with any particular requirements they have
     - Discussion of key algorithms, abstractions, and semantics
@@ -28,55 +28,55 @@ IBC standardisation will follow an adaptation of the [TC 39](https://tc39.github
     For a more detailed description of standard requirements, see [ICS 1](../spec/ics-001-ics-standard).
 
     For more details on submitting a PR, take a look at the [Pull Requests](./CONTRIBUTING.md#pull-requests) section in the contribution guidelines.
-  * Identified `author(s)` who will advance the proposal in the header of the standard file
-  * Any additional reference documentation or media in the `./spec/ics-{{ .Spec.Number }}-{{ .Spec.Name }}` directory
-  * The specification team expects that this proposal will be finalised and eventually included in the IBC standard set.
-- _**Spec Quality**_:
-  * Follows the structure laid out in ICS 1 and provides a reasonable overview of the proposed addition.
-- _**Acceptance Requirements**_:
-  * The PR has received two approvals from members of the [core specification committee](./STANDARDS_COMMITTEE.md), at which point it can be merged into the IBC repository.
-- _**Changes Expected Post-Acceptance**_:
-  * Changes to details but not to the key concepts are expected after a standard enters draft stage. Implementers should work with the spec authors as work continues on spec development.
-- _**Implementation Types Expected**_:
-  * Tightly bounded demos, example repositories showing reproduction steps for issues fixed by proposal
+  - Identified `author(s)` who will advance the proposal in the header of the standard file
+  - Any additional reference documentation or media in the `./spec/ics-{{ .Spec.Number }}-{{ .Spec.Name }}` directory
+  - The specification team expects that this proposal will be finalised and eventually included in the IBC standard set.
+- ***Spec Quality***:
+  - Follows the structure laid out in ICS 1 and provides a reasonable overview of the proposed addition.
+- ***Acceptance Requirements***:
+  - The PR has received two approvals from members of the [core specification committee](./STANDARDS_COMMITTEE.md), at which point it can be merged into the IBC repository.
+- ***Changes Expected Post-Acceptance***:
+  - Changes to details but not to the key concepts are expected after a standard enters draft stage. Implementers should work with the spec authors as work continues on spec development.
+- ***Implementation Types Expected***:
+  - Tightly bounded demos, example repositories showing reproduction steps for issues fixed by proposal
 
-#### Stage 3 - `Candidate`
+### Stage 3 - `Candidate`
 
-- _**Purpose**_:
-  * Indicate that further refinement will require feedback from implementations and users
-- _**Entrance Criteria**_:
-  * Everything from stages 1 & 2
-  * Complete specification text
-  * At least one specification-compatible implementation exists
-  * All relevant ecosystem stakeholders have been given a chance to review and provide feedback on the standard
-  * The solution is complete and no further work is possible without implementation experience, significant usage and external feedback.
-- _**Spec Quality**_:
-  * Complete: all semantics, syntax and API are completed as described
-- _**Acceptance Requirements**_:
-  * The PR changing the stage to "candidate" has been approved by two members of the core specification team.
-- _**Changes Expected Post-Acceptance**_:
-  * Limited: only those deemed critical based on implementation experiences.
-- _**Implementation Types Expected**_:
-  * Specification-compliant
+- ***Purpose***:
+  - Indicate that further refinement will require feedback from implementations and users
+- ***Entrance Criteria***:
+  - Everything from stages 1 & 2
+  - Complete specification text
+  - At least one specification-compatible implementation exists
+  - All relevant ecosystem stakeholders have been given a chance to review and provide feedback on the standard
+  - The solution is complete and no further work is possible without implementation experience, significant usage and external feedback.
+- ***Spec Quality***:
+  - Complete: all semantics, syntax and API are completed as described
+- ***Acceptance Requirements***:
+  - The PR changing the stage to "candidate" has been approved by two members of the core specification team.
+- ***Changes Expected Post-Acceptance***:
+  - Limited: only those deemed critical based on implementation experiences.
+- ***Implementation Types Expected***:
+  - Specification-compliant
 
-#### Stage 4 - `Finalised`
+### Stage 4 - `Finalised`
 
-- _**Purpose**_:
-  * Indicate that the addition is included in the formal ICS standard set
-- _**Entrance Criteria**_:
-  * Everything from stages 1,2,3
-  * At least two specification-compatible implementations exist, and they have been tested against each other
-  * All relevant ecosystem stakeholders approve the specification (any holdout can block this stage)
-  * Acceptance tests are written and merged into the relevant repositories
-  * All files in the `./spec/ics-{{ .Spec.Number }}-{{ .Spec.Name}}/` directory are up to date and merged into the `cosmos/ics` repository
-- _**Acceptance Requirements**_:
-  * The PR changing the stage to "finalised" has been approved by representatives from all relevant ecosystem stakeholders, and all members of the core specification team.
-- _**Spec Quality**_:
-  * Final: All changes as a result of implementation experience are integrated
-- _**Changes Expected Post-Acceptance**_:
-  * Backward-compatible fixes or breaking changes that are supported by a backwards-compatibility preserving upgrade protocol
-- _**Implementation Types Expected**_:
-  * Shipping/Production
+- ***Purpose***:
+  - Indicate that the addition is included in the formal ICS standard set
+- ***Entrance Criteria***:
+  - Everything from stages 1,2,3
+  - At least two specification-compatible implementations exist, and they have been tested against each other
+  - All relevant ecosystem stakeholders approve the specification (any holdout can block this stage)
+  - Acceptance tests are written and merged into the relevant repositories
+  - All files in the `./spec/ics-{{ .Spec.Number }}-{{ .Spec.Name}}/` directory are up to date and merged into the `cosmos/ics` repository
+- ***Acceptance Requirements***:
+  - The PR changing the stage to "finalised" has been approved by representatives from all relevant ecosystem stakeholders, and all members of the core specification team.
+- ***Spec Quality***:
+  - Final: All changes as a result of implementation experience are integrated
+- ***Changes Expected Post-Acceptance***:
+  - Backward-compatible fixes or breaking changes that are supported by a backwards-compatibility preserving upgrade protocol
+- ***Implementation Types Expected***:
+  - Shipping/Production
 
 ### Calls for implementation and feedback
 

meta/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap IBC specs
 
-_Lastest update: April 6th, 2022_
+*Lastest update: April 6th, 2022*
 
 This document endeavours to inform the wider IBC community about plans and priorities for the specification work of IBC. This roadmap should be read as a high-level guide, rather than a commitment to schedules and deliverables. The degree of specificity is inversely proportional to the timeline. We will update this document periodically to reflect the status and plans.
 
@@ -16,4 +16,4 @@ This roadmap reflects the major activities that the [standards committee](STANDA
 - Finish [ICS28](https://github.com/cosmos/ibc/pull/666) (Cross-chain validation) spec.
 - Review and possibly merge [ICS721](https://github.com/cosmos/ibc/pull/615) spec for NFT transfers.
 - Review and possibly merge the spec for [IBC queries](https://github.com/cosmos/ibc/pull/647).
-- Write and add to the repository a high level overview of what IBC is. This can be used as an entry point for newcomers to IBC to understand its general principles.
+- Write and add to the repository a high level overview of what IBC is. This can be used as an entry point for newcomers to IBC to understand its general principles.

meta/STANDARDS_COMMITTEE.md

@@ -1,6 +1,7 @@
 ## Standards Committee
 
 Currently, the core standardisation committee consists of:
+
 - Aditya Sripal (@adityasripal)
 - Christopher Goes (@cwgoes)
 - Marius Poke (@mpoke)

spec/app/ics-020-fungible-token-transfer/README.md

@@ -47,7 +47,6 @@ interface FungibleTokenPacketData {
 }
 ```
 
-
 As tokens are sent across chains using the ICS 20 protocol, they begin to accrue a record of channels for which they have been transferred across. This information is encoded into the `denom` field. 
 
 The ICS 20 token denominations are represented by the form `{ics20Port}/{ics20Channel}/{denom}`, where `ics20Port` and `ics20Channel` are an ICS 20 port and channel on the current chain for which the funds exist. The prefixed port and channel pair indicate which channel the funds were previously sent through. Implementations are responsible for correctly parsing the IBC trace information from the base denomination. The way the reference ICS 20 implementation in ibc-go handles this is by taking advantage of the fact that it automatically generates channel identifiers with the format `channel-{n}`, where `n` is a integer greater or equal than 0. It can then correctly parse out the IBC trace information from the base denom which may have slashes, but will not have a substring of the form `{transfer-port-name}/channel-{n}`. If this assumption is broken, the trace information will be parsed incorrectly (i.e. part of the base denom will be misinterpreted as trace information). Thus chains must make sure that base denominations do not have the ability to create arbitrary prefixes that can mock the ICS 20 logic.