Optimism is Ethereum, scaled.

OP Stack Specification

This repository contains the Specs Book.

Please chat with us on the discussion board.

Contributing

We welcome your contributions. Read through CONTRIBUTING.md for a general overview of the contributing process for this repository.

Dependencies

Using mise

We use mise as a dependency manager for these tools. Once properly installed, mise will provide the correct versions for each tool. mise does not replace any other installations of these binaries and will only serve these binaries when you are working inside of the optimism directory.

Install mise

Install mise by following the instructions provided on the Getting Started page.

Install dependencies

mise install

Manual installation

Rust Toolchain

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

mdbook + plugins

cargo install mdbook mdbook-katex mdbook-linkcheck mdbook-mermaid

just installation

brew install just

Serving the book locally

just serve

Linting

Please see the relevant commands in the justfile for more information.

doctoc is used to automatically add a table of contents.

To check the table of contents:

just lint-specs-toc-check

To fix the table of contents:

just lint-specs-toc

markdownlint-cli2 is used to check markdown linting errors.

To check markdown linting errors:

just lint-specs-md-check

To fix markdown linting errors:

just lint-specs-md

cspell is used to check spelling.

To check spelling:

just lint-specs-spelling-check

To fix spelling:

just lint-specs-spelling

lychee is used to check hyperlinks.

To check all hyperlinks respond with status 200:

just lint-links-check

find is used to check filenames do not contain underscores.

To check filenames do not contain underscores:

just lint-filenames-check

To check all linting:

just lint-check

To fix all linting that can be automatically fixed:

just lint

See the markdownlint rule reference and an example config file.

Justification for linting rules in .markdownlint.json:

• line_length (!strict && stern): don't trip up on url lines
• no-blanks-blockquote: enable multiple consecutive blockquotes separated by white lines
• single-title: enable reusing <h1> for content
• no-emphasis-as-heading: enable emphasized paragraphs

Precommit hook

There is a precommit hook in the repo which you can enable (optionally) to fix linting issues and perform a spellcheck on each commit. Enable like so:

git config core.hooksPath .githooks

This makes committing a little slow, but does mean you will know about problems without having to wait for CI. You may disable like so

git config --unset core.hooksPath

or temporarily commit without the hook like so

git commit --no-verify