This repository contains the formal specifications, executable models, and implementations of the Cardano Ledger.
The documents are built in our CI and can be readily accessed using the following links:
|Era||Design Documents||Formal Specification||CDDL|
|Byron||Chain Spec, Ledger Spec||CDDL|
|Allegra & Mary||Multi-Currency, UTXOma||Spec||CDDL|
- Non-integer calculations specification: details on the parts of the Shelley specification that use real numbers.
- Stake pool ranking specification: details for a robust stake pool ranking mechanism.
- Explanation of the small-step-semantics framework: a guide to the notation and style used by our ledger rules.
In addition, there is a formalization of the Ledger Specification in Isabelle/HOL which can be found here.
The directory structure of this repository is as follows:
- Timelocks and Multi-Assets
- Smart Contracts
nix it is recommended that you setup the cache, so that it can
reuse built artifacts, reducing the compilation times dramatically:
If you are using NixOS add the snippet below to your
nix.binaryCaches = [ "https://cache.nixos.org" "https://hydra.iohk.io" ]; nix.binaryCachePublicKeys = [ "hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=" ];
If you are using the
nix package manager next to another operating system put
the following in
/etc/nix/nix.conf if you have a system-wide
installation , or in
~/.config/nix/nix.conf if you have a local installation:
substituters = https://hydra.iohk.io https://cache.nixos.org/ trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
Building the LaTeX documents and executable specifications
nix the documents and Haskell code can be readily
built by running:
The LaTeX documents will be places inside directories named
result-2/ledger-spec.pdf result-3/delegation_design_spec.pdf result-4/non-integer-calculations.pdf result-5/small-step-semantics.pdf result-6/ledger-spec.pdf result/blockchain-spec.pdf
Building individual LaTeX documents
Change to the latex directory where the latex document is (e.g.
for the ledger specification corresponding to the Shelley release, or
eras/byron/ledger/formal-spec for the ledger specification corresponding to
the Byron release). Then, build the latex document by running:
nix-shell --pure --run make
For a continuous compilation of the
LaTeX file run:
nix-shell --pure --run "make watch"
While building most compilation warnings will be turned into an error due to
-Werror flag. However during development it might be a bit inconvenient thus
can be disabled on per project basis:
cabal configure <package-name> --ghc-options="-Wwarn" cabal build <package-name>
Testing the Haskell programs
The tests can be run with cabal. For example the Shelley tests can be run with:
cabal test cardano-ledger-shelley-test
It can be helpful to use the
--test-show-details=streaming option for seeing
the output of the tests while they run:
cabal test cardano-ledger-shelley-test --test-show-details=streaming
Running Specific Tests
The test suites use Tasty,
which allows for running specific tests.
This is done by passing the
-p flag to the test program, followed by an
You can alternatively use the
TASTY_PATTERN environment variable with a pattern.
For example, the Shelley golden tests can be run with:
cabal test cardano-ledger-shelley-test --test-options="-p golden"
TASTY_PATTERN=golden cabal test cardano-ledger-shelley-test
Tasty allows for more
For instance, to run only the Byron update mechanism tests for the ledger
that classify traces, we can pass the
-p $1 ~ /Ledger/ && $2 ~ /Update/ && $3 ~ /classified/ option.
$i refers to a level in the tests names hierarchy.
tasty will list the available test names.
When testing using
cabal, pay special attention to escaping the right symbols, e.g.:
cabal test byron-spec-ledger:test:byron-spec-ledger-test --test-options "-p \"\$1 ~ /Ledger/ && \$2 ~ /Update/ && \$3 ~ /classified/\""
Replaying QuickCheck Failures
When a QuickCheck test fails, the seed which produced the failure is reported. The failure can be replayed with:
cabal test cardano-ledger-shelley-test --test-options "--quickcheck-replay=42"
(where 42 is an example seed).
Most of the test suites are grouped into test scenarios.
For example, the Shelley test suite contains
which can be run with the
--scenario flag. For example:
cabal test cardano-ledger-shelley-test --test-options --scenario=Fast
We have support for running
from inside of nix-shell.
Enter nix-shell from the base directory of the repository,
change directories to the cabal package that you wish to check,
nix-shell cd eras/shelley/impl/ ghcid
The artifacts in this repository can be built and tested using nix. This is additionally used by the Hydra CI to test building, including cross-compilation for other systems.
To add a new Haskell project
To add a new Haskell project, you should do the following:
- Create the project in the usual way. It should have an appropriate
- Add the project to the top-level stack.yaml, configuring dependencies etc as needed. If your project's configuration deviates too far from the snapshot in ``cardano-prelude`, then you may have to submit a PR there to update that snapshot.
- At this point, test that your new project builds using
stack build <project_name>.
- Run nix-shell ./nix -A iohkNix.stack-cabal-sync-shell --run scripts/stack-cabal_config_check.sh script to check and report your change from stack.yaml to cabal.project.
- Run the regenerate script to update sha256 checksums in cabal.project.
- Test that you can build your new project by running the following:
nix build -f default.nix libs.<project_name>. If you have executables, then you may also try building these using the
exes.<executable_name>attribute path. A good way to see what's available is to execute
nix repl. This will allow you to explore the potential attribute names.
- If you want your product to be tested by CI, add it to release.nix using the format specified in that file.
To add a new LaTeX specification
To add a new LaTeX specification, the easiest way is to copy from one of the
existing specifications. You will want the
from the Shelley ledger spec).
- Copy these files into the root of your new LaTeX specification.
- Modify the
- Make sure that the relative path in the first line is pointing to
(default.nix)[./default.nix]. This is used to pin the
nixpkgsversion used to build the LaTeX specifications.
- Update the
buildInputsto add in any LaTeX packages you need in your document, and remove any unneeded ones.
- Alter the
metadescription field to reflect the nature of this document.
- Make sure that the relative path in the first line is pointing to (default.nix)[./default.nix]. This is used to pin the
- Add a link to the package at the bottom of default.nix, following the existing examples.
- To require that your specification be built in CI, add it at the end of the list in default.nix following the existing examples.
You can find additional documentation on the nix infrastructure used in this repo in the following places:
Note that the user guide linked above is incomplete and does not correctly refer
to projects built using
iohk-nix, as this one is. A certain amount of trial
and error may be required to make substantive changes!
editorconfig to ensure consistency in the format of our
Haskell code. There are editorconfig plugins for several text editors, so make sure that your editor
honors the configuration in