input-output-hk / cardano-ledger

The ledger implementation and specifications of the Cardano blockchain.

Cardano Ledger

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, PDF
Shelley	Design	Spec	CDDL
Allegra	Same as Mary era below	Same as Mary era below	CDDL
Mary	Multi-Currency, UTXOma	Spec	CDDL
Alonzo	eUTXO	Spec	CDDL
Babbage	batch-verification, CIP-31, CIP-32, CIP-33	Spec	CDDL
Conway	CIP-1694	Spec (WIP)	CDDL

Other Documents:

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

Some user documentation is published on Read the Docs

Haddock code documentation of the latest master branch is available here.

Repository structure

The directory structure of this repository is as follows:

• Byron
  • ledger
    • formal-spec
    • executable-spec
    • implementation
  • chain
    • formal-spec
    • executable-spec
  • cddl
• Shelley
  • design-spec
  • formal-spec
  • implementation
  • tests
  • cddl
• Allegra - Timelocks
  • formal-spec
  • implementation
  • tests
• Mary - Multi-Assets
  • formal-spec
  • implementation
  • tests
• Alonzo - Smart Contracts
  • formal-spec
  • implementation
  • cddl
  • tests
• Babbage
  • formal-spec
  • implementation
  • cddl
  • tests
• Conway - Governance
  • formal-spec
  • implementation
  • cddl
  • tests
• Libraries

Building

It is recommended to use nix for building everything in this repository. Haskell files can be built with cabal inside of a nix shell.

Make sure you have a recent version of nix by following this guide

Nix Cache

When using 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 /etc/nixos/configuration.nix:

nix.settings = {
  experimental-features = [ "nix-command" "flakes" ];
  substituters = [
    "https://cache.nixos.org"
    "https://cache.iog.io"
  ];
  trusted-public-keys = [
    "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:

experimental-features = nix-command flakes
substituters        = https://cache.iog.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

When using nix the documents and Haskell code can be readily built by running:

nix build .#specs

The LaTeX documents will be placed inside a directory named result, e.g.:

result/byron-ledger.pdf
result/shelley-delegation.pdf
result/non-integer-calculations.pdf
result/small-step-semantics.pdf
result/shelley-ledger.pdf
result/byron-blockchain.pdf

Building individual LaTeX documents

Change to the latex directory where the latex document is (e.g. eras/shelley/formal-spec 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:

cd <myLaTexDir>
nix develop --command make

For a continuous compilation of the LaTeX file run:

cd <myLaTexDir>
nix develop --command make watch

Testing

Run cabal test all to run all tests or cabal test <package> to run the tests for a specific package.

Note: The CARDANO_MAINNET_MIRROR environment variable can be overriden in flake.nix if one desires to run the Byron tests with a different version of the mainnet epochs.

Submitting an issue

Issues can be filed in the GitHub Issue tracker.

However, note that this is pre-release software, so we will not usually be providing support.

Contributing

See CONTRIBUTING.

cardano-ledger's Issues

Explicit Fees (executable model)

The executable model currently uses implicit fees. Make them explicit and validate a minimum fee.

Property Tests for Value Transactions

part of #20

Build instance of STS semantics for executable spec / generators

Deposits and Refunds (executable model)

Add certificate deposits and refunds to the Haskell executable model. This requires adding the protocol constants to the ledger state as well. It may make sense to not model refunding pool certificates until some kind of epoch boundary rules are in place.

min fee as ax+b

In the LaTeX spec, instead of keeping the minfee calculation abstract, define it as ax+b, where a and b are in the protocol constants and x is the number of bytes in an encoding of the transaction.

state properties for the delegation model

We will be writing property tests for our executable haskell model of the ledger with delegation. The first step is to think of all the properties that we can test. Add these to the LaTeX (or lhs) document.

Property Test for conservation of 45B ADA

Write a property test that checks that for any valid ledger state:

45B ADA == balance utxo + balance rewards + deposits + treasury + reserves + rewardPool + fees

Global Accounting Tracking (executable model)

In the Haskell executable model, add tracking to the ledger state for: treasury, reward pool, fee pool, reserves. This will involve adding some epoch boundary transitions.

Discuss the accounting model

Accounting model in progress, more discussion to come with model updates

Resolve double-depositing in the LaTeX spec rules

Reward Payout (executable model)

Implement the epoch boundary mechanism for paying out rewards in the Haskell executable model.

Write generators / mutators for `DelegationData`

After finishing this issue it

• MUST be possible to generate delegation transactions from a valid ledger state
• MUST be possible to mutate valid delegation transactions

add stale stake

add stale stake mechanism, as described in the delegation design doc, to the ledger rules.

Implement Property 7.1 once deposit / rewards are modelled in the executable spec

This property uses rewards and deposits and therefore can only be modelled / tested once this is included in the executable spec.

add LaTeX spec to CI

There is a makefile inside fm-ledger-rules/latex which builds a pdf using Nix. It would be nice to check this build as a part of CI. It would also be great if there was a way to publish the pdf as an artifact.

combine delegation rules with cardano-chain ledger rules

Combine the cardano-chain ledger rules with the delegation rules in this repo. We can probably use iohk.sty and ledger-spec.tex without modification. We can consider making a git submodule or nix package.

Property Tests for Stake Delegation

part of #20

Investigate Property Coverage Analysis

in particular http://hackage.haskell.org/package/tasty-hedgehog-coverage-0.1.0.0/docs/Test-Tasty-Hedgehog-Coverage.html

Adapt mutators for use with Goblins framework

After finishing this issue it

• MUST be possible to instantiate the Goblins framework with the mutators as toys

• MUST be possible to instantiate the ledger value transactions using the STS framework

• SHOULD be possible to run the Goblins to create invalid data using the GA approach

• SHOULD be possible to see labeled test results from the GA run

pool reg cert refunds

Currently, the spec refunds both stake key registration and pool registration deposits at any slot in the UTxO rule. The pool registration, however, should not be done this way since we allow retirement certificates to override each other. These refunds can only be returned when the pool is reaped.

ledger rule for combining delegation with utxo

there needs to be a main/top-level ledger rule which combines the delegation with witnesses rule with the UTxO with witnesses rule.

Delegation Design: Review Section on Displaying Pools in the Wallet

The section "Display of Stake Pools in the Wallet" (currently 5.2) was written before the incentives part of the document was finished. We should review this section, to make sure everything covered therein is covered in the section on incentives, and then just reference that section instead of duplicating information.

preservation of total ada & deposits

we need to write rules that ensure that the total amount of ada is preserved when deposits values are changed by voting.

add address types to the ledger rules

In the latex spec, we need to model pointer addresses.

Property Tests for Ledger with Delegation

Turn the properties from #18 and the generators from #19 into property tests.

ledger_spec_delegation

LaTeX and executable specification of new ledger rules including delegation.

Implement replay protection for transactions

To ensure replay protection, each transaction must consume at least one input. This is in particular important for delegation transactions, but currently not implemented in the executable spec.

After resolving this issue it

• MUST be ensured that a validated transaction consumes at least one input
• MUST be ensured that 'DelegationData' transactions spend at least one input
• SHOULD be one combined LedgerEntry data type
• there SHOULD be at least one test for checking that a transaction with empty input set is not validated

Generators for invalid data

The current generators can supply valid data to the state transition function. It should also be possible to generate invalid data, to test the correct behaviour of the state transition functions in those case.

This should then collect all reasons of why a transaction is rejected.
It is necessary to choose an efficient approach to generate invalid data, likely doesn't generate "interesting" cases that test the important edge cases.

Add "no double-spend" to Properties and implement property based test for it

after completing this issue:

• a property MUST exist in the latex spec which formalizes that double-spend is not possible using the defined transition rules
• this property MUST be implemented as a hedgehog property in the executable spec and validate the property for valid generated transactions

Fill out delegation spec with more explanations and context

The LaTeX delegation spec has very minimal explanations right now, it is mostly tables and rules. Fill out this document with more explanations and context.

add deposits to the ledger rules

In the latex spec, we need to model the deposit mechanisms as described in the delegation design document.

Generators for the Haskell model

Write the generators for property testing the Haskell model. We may want to break this ticket into several tickets.

add fees to the ledger rules

In the latex spec, we need to model transaction fees.

We can then state the preservation of value property as an equality instead of an inequality. For example, with implicit fees, we state this validation rule as balance (txouts tx) \leq balance (txins tx domRestr utxo). When fees and minted coins are explicit, we get an equality: fees + balance (txouts tx) = minted + balance (txins tx domRestr utxo).

Write introduction and outline UTxO updates

Discuss witnessing and complete ledger state transitions

Investigate use of Liquid Haskell in spec

Liquid Haskell provides means for automatic checking of certain properties

• refinement types
• theorem proving for equational reasoning
• termination checks (automatic for subset, manual in more complex cases)

There may be some properties that could be proven directly in Haskell using Liquid Haskell. Nevertheless, there are challenges, for example:

• expressiveness
• integration into Project, CI ...
• Results depend on choice of SMT solver (Z3, CVC4, MathSAT)

Delegation Design: Change section on refundable fees

We should change this section, to state that the refundable part of the fee is tracked separately from the rewards pool.

address replay attacks - spend one txin

Non UTxO actions that a transaction may take do not always afford the same replay protection as the UTxO. so, for this reason, we can piggyback replay prevention by signing the transaction body, assuming the transaction spends at least one input. We should make this a conditional requirement in the appropriate rules.

Reward Withdrawals (executable model)

Implement the mechanism for reward account withdrawals in the Haskell executable model.

Write mutators for signatures / hashes

After finishing this issue it

• MUST be possible to mutate Signatures
• MUST be possible to mutate hashes

Update Haskell ledger state to correspond to LaTeX spec

literate haskell?

Try combining our latex spec and haskell model with literate haskell. Decide if this is the approach that we should take. See this report for an example of multiple .lhs modules.

add rewards to the ledger rules

In the latex spec, we need to model the rewards mechanism from the leader election.

Discuss updated accounting model

DELEW rule does not conform to small step semantics

The current rule DELEGW has two rules in its antecedent. It is intended that this rule succeeds if either DELEG or POOL succeeds. As all the conditions in the antecedent are conjoined, however, as currently written, this rule can never succeed.

We need to either split this rule into multiple rules, or find a way to express the disjunction.

add reward withdrawls to the ledger rules

Discuss epoch boundary ledger state updates

Extend HSpec test in executable model to stake delegation

In addition to test basic functionality of transaction validation, the hspec
tests should also cover stake delegation functionality.

Discuss delegation

replace hspec with tasty-hunit

and write the tests in such a way that they can be individually loaded into ghci