## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

- Auto
- Light
- Dark

# Algorand Specifications

The source of the Algorand Specification is released on the official GitHub Algorand Foundation [repository](https://github.com/algorandfoundation/specs).

If you would like to contribute, please consider submitting an [issue](https://github.com/algorandfoundation/specs/issues/new/choose) or opening a [pull request](https://github.com/algorandfoundation/specs/pulls).

To fix typos, consider opening a pull request labeled _“typo”_. By clicking on the _“Suggest an edit”_ icon in the top-right corner of the page containing the typo, you will be redirected to the relevant source code file to be edited in the pull request.

To report major issues, such as unclear contents, errors in mathematical formulas, broken rendering of the Web version or PDF version, broken rendering of diagrams, broken links, etc. please consider submitting a [templated issue](https://github.com/algorandfoundation/specs/issues/new/choose).

The Algorand Specifications book is built with [mdBook](https://rust-lang.github.io/mdBook/index.html).

The source code is structured as follows:

```text
.github/                  -> GitHub actions and CI/CD workflows
_archive/                 -> Legacy specification archive
src/                      -> mdBook source code
└── _include/             -> Code snippets, templates, TeX-macros, and examples
└── _excalidraw/          -> Excalidraw diagrams source code
└── _images/              -> SVG files
└── Part_A/               -> Part A normative files
    └── non-normative/    -> Part A non-normative files
└── Part_B/               -> Part B files
└── Part.../              -> ...
└── SUMMARY.md, ...       -> mdBook SUMMARY.md, COVER.md, prefix/suffix-chapters, etc.
```

The book is written in [CommonMark](https://commonmark.org/).

The CI pipeline enforces Markdown linting, formatting, and style checking with [`markdownlint`](https://github.com/DavidAnson/markdownlint).

Numbered lists **MUST** be defined with `1`-only style.

> Important
> 
> **EXAMPLE:**
> 
> ```text
> 
> 1. First item
> 1. Second item
> 1. Third item
> ```
> 
> Result:
> 
> 1. First item
> 2. Second item
> 3. Third item

Table rows **MUST** use the same column widths.

> Important
> 
> **EXAMPLE:**
> 
> ✅ Correct table format
> 
> ```text
> 
> | Month    | Savings |
> |----------|---------|
> | January  | €250    |
> | February | €80     |
> | March    | €420    |
> ```
> 
> ❌ Wrong table format
> 
> ```text
> 
> | Month | Savings |
> |----------|---------|
> | January | €250 |
> | February | €80 |
> | March | €420 |
> ```
> 
> Result:
> 
> | Month | Savings |
> | --- | --- |
> | January | €250 |
> | February | €80 |
> | March | €420 |

Consider aligning text in the columns to the left, right, or center by adding a colon `:` to the left, right, or on both sides of the dashes `---` within the header row.

> Important
> 
> **EXAMPLE:**
> 
> ```text
> 
> | Name   | Quantity | Size |
> |:-------|:--------:|-----:|
> | Item A |    1     |    S |
> | Item B |    5     |    M |
> | Item C |    10    |   XL |
> ```
> 
> Result:
> 
> | Name | Quantity | Size |
> | --- | --- | --- |
> | Item A | 1 | S |
> | Item B | 5 | M |
> | Item C | 10 | XL |

Mathematical formulas are defined with [MathJax](https://www.mathjax.org/).

> mdBook MathJax [documentation](https://rust-lang.github.io/mdBook/format/mathjax.html).

Inline equations **MUST** include extra spaces in the MathJax delimiters.

> Important
> 
> **EXAMPLE:**
> 
> Equation: ∫xdx=x22+C∫xdx=x22+C
> 
> ✅ Correct inline delimiter
> 
> ```text
> 
> \( \\int x dx = \frac{x^2}{2} + C \)
> ```
> 
> ❌ Wrong inline delimiter
> 
> ```text
> 
> \(\int x dx = \frac{x^2}{2} + C\)
> ```

Block equations **MUST** use the `$$` delimiter (instead of `\[ ... \]`).

> Important
> 
> **EXAMPLE:**
> 
> Equation:
> 
> μ=1N∑i=0xiμ=1N∑i=0xi
> 
> ✅ Correct block delimiter
> 
> ```text
> 
> $$
> \mu = \frac{1}{N} \sum_{i=0} x_i
> $$
> ```
> 
> ❌ Wrong inline delimiter
> 
> ```text
> 
> \[\
> \mu = \frac{1}{N} \sum_{i=0} x_i\
> \]
> ```

TeX-macros are defined in the `./src/_include/tex-macros/` folder using the mdBook [include feature](https://rust-lang.github.io/mdBook/format/mdbook.html#including-files).

TeX-macros are divided into functional blocks (e.g., pseudocode, operators, constants, etc.).

TeX-macros **MUST** be imported at the top of the consumer files using the mdBook.

TeX macros can be imported entirely or partially (e.g., just a functional block).

> Important
> 
> **EXAMPLE:**
> 
> Import all TeX-macros:
> 
> ```text
> 
> {{#include ./_include/tex-macros.md:all}}
> ```
> 
> Import just a block of TeX-macros (e.g., pseudocode commands):
> 
> ```text
> 
> {{#include ./_include/tex-macros.md:pseudocode}}
> ```

Block styles are defined in the `./src/_include/styles.md` file using the mdBook [include feature](https://rust-lang.github.io/mdBook/format/mdbook.html#including-files).

Block styles (e.g., examples, implementation notes, etc.) are “styled quote” blocks included in the book.

> Important
> 
> **EXAMPLE:**
> 
> This example block has been included with the following syntax:
> 
> ```text
> 
> {{#include ./_include/styles.md:example}}
> > This example block has been included with the following syntax:
> ```

Links to the `go-algorand` reference implementation or other repositories **MUST** be [permalinks](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files).

Structured diagrams (e.g., flow charts, sequence diagrams, etc.) are defined with [Mermaid](https://mermaid.js.org/intro/) “text-to-diagram” tool.

Unstructured diagrams and images are drawn with [Excalidraw](https://excalidraw.com/).

Excalidraw images **MUST** be exported in `.svg` format without a background and saved in the `./src/_images/` folder.

Excalidraw images source code **MUST** be committed in the `./src/_excalidraw/` folder.

Clone the Algorand Specifications repository and install the git submodules:

**SSH** clone:

```shell

git clone --recurse-submodules git@github.com:algorandfoundation/specs.git
cd specs
```

or

**HTTPS** clone:

```shell

git clone --recurse-submodules https://github.com/algorandfoundation/specs.git
cd specs
```

If the Algorand Specifications repository is already cloned, sync the git submodules in the `specs` folder:

```shell

git submodule update --init --recursive
```

Use the `make` command to build and serve the Algorand Specifications book locally or in a Docker container.

> Use the `make doctor` command to check your environment for build dependencies.

To build and serve the book in a Docker container, the following dependencies are required:

- **Docker** and **Docker Compose**.

Build the Docker image:

```shell

make docker-setup
```

Build and serve (hot reload) the book on [localhost:3000](http://localhost:3000/):

```shell

make docker-serve
```

This section is for contributors who **cannot / do not want to** use Docker.

To build and serve the book locally, the following dependencies are required:

- **Rust toolchain** (`cargo`): install Rust with [rustup](https://rust-lang.org/tools/install/).

Install the mdBook tools:

```shell

make setup
```

> Ensure Cargo’s bin dir (usually `~/.cargo/bin`) is on your `PATH`.

Build and serve the book (HTML) locally (hot reload) on [localhost:3000](http://localhost:3000/):

```shell

make serve
```

Linting and formatting are enforced with [pre-commit](https://pre-commit.com/).

To run pre-commit hooks locally, the following dependencies are required:

- **Python** (`python3 + pip`): install [pip](https://pip.pypa.io/en/stable/installation/).

Install pre-commit hooks:

```shell

make lint-setup
```

Run pre-commit hooks:

```shell

make lint
```

> Link checker (`lychee`) requires Docker, it can be run optionally (outside `make lint`) with: `pre-commit run lychee --all-files --verbose`.

The CI/CD and Release pipeline is defined in the `.github/workflows/` files.

The CI runs on a Pull Request to:

- Enforce linting and formatting;
- Test the HTML book build;
- Provide warnings for broken links;
- Deploy the book preview to a temporary URL for review.

The CD pipeline deploys the book to [https://specs.algorand.co](https://specs.algorand.co/) on every push to the `master` branch.

The Release pipeline creates the release tag, builds the PDF Book, and publishes it as a release artifact.