# intersectmbo/cardano-ledger architecture

> Architecture diagram of the GitHub repository intersectmbo/cardano-ledger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/intersectmbo/cardano-ledger
- Repository: https://github.com/intersectmbo/cardano-ledger

## Overview

##### Major Modules and Components
- At the highest level, the repository is organized by blockchain eras. Create separate major blocks for each era:
– Byron (with its ledger, chain components, and separate CDDL for binary encoding)
– Shelley (with its design, formal specification, implementation, tests, and CDDL files)
– Allegra (and Mary – note that the README explains that these eras share similar structures as they both implement multi-currency or timelocks)
– Alonzo (with formal spec, implementation, tests and integration of Plutus Smart Contracts)
– Babbage (focusing on batch-verification and new CIP proposals)
– Conway (governance-focused, with work in-progress formal spec and tests)
- Support “Libraries” component – this deals with cardano-data, ledger API, ledger binary, ledger core, and other auxiliary libraries (such as constrained-generators, small-steps, set-algebra, etc.) that provide common functionality.

##### Within each Era Block
- Break each era module into three (or more) sub-components:
– Formal Specification: Documents and LaTeX builds (referenced in the README as PDFs).
– Executable/Implementation Layer: The Haskell source (often inside “impl” directories) that embodies the ledger rules, state transitions, and other behaviors.
– Tests: Test suites and executable specifications that validate the implementation against the formal model.
– CDDL Files: Representing the schema for binary serialization for that era.
- For Byron in particular, note the further breakdown into the “ledger”, “chain”, and “cddl” directories – so you might want to show a slightly different substructure for Byron versus later eras.

##### Integration and Dependencies
- Strong interaction with the common libraries. For example:
– The “cardano-data” and “cardano-ledger-api” libraries provide data types and APIs that are used across eras.
– “cardano-ledger-core”, “cardano-ledger-binary” and similar libraries support the core types (states, transactions, cryptographic components) and serialization.
– Other libraries (like “small-steps” and “set-algebra”) provide analysis and testing frameworks for ledger rules.
- External tools and build infrastructure:
– Nix is used for development and build reproducibility.
– Cabal (within the nix shell) is used to build the Haskell files.
– The CI workflows in the “.github/workflows” directory are responsible for running tests and building documents.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Container
    subgraph "Cardano Ledger"
        
        %% Multi-Era Modules
        subgraph "Multi-Era Modules"
            %% Byron Era
            subgraph "Byron Era"
                %% Byron Ledger Subgraph
                subgraph "Ledger"
                    BLF["Byron – Ledger Formal"]:::formal
                    BLI["Byron – Ledger Impl"]:::implementation
                end
                BLF -->|"influences"| BLI
                %% Byron Chain Subgraph
                subgraph "Chain"
                    BCF["Byron – Chain Formal"]:::formal
                    BCI["Byron – Chain Exec"]:::implementation
                end
                BCF -->|"influences"| BCI
                %% Byron CDDL Node
                BCddl["Byron – CDDL"]:::cddl
                BLI -->|"uses-schema"| BCddl
                BCI -->|"uses-schema"| BCddl
            end

            %% Shelley Era
            subgraph "Shelley Era"
                SSFD["Shelley – Formal Spec & Design"]:::formal
                SImpl["Shelley – Implementation"]:::implementation
                STS["Shelley – Tests"]:::tests
                SSFD -->|"influences"| SImpl
                SImpl -->|"validated-by"| STS
            end

            %% Allegra Era
            subgraph "Allegra Era"
                AImpl["Allegra – Implementation"]:::implementation
                ACddl["Allegra – CDDL"]:::cddl
                ATS["Allegra – Tests"]:::tests
                AImpl -->|"validated-by"| ATS
                AImpl -->|"uses-schema"| ACddl
            end

            %% Mary Era
            subgraph "Mary Era"
                MImpl["Mary – Implementation"]:::implementation
                MCddl["Mary – CDDL"]:::cddl
                MTS["Mary – Tests"]:::tests
                MImpl -->|"validated-by"| MTS
                MImpl -->|"uses-schema"| MCddl
            end

            %% Alonzo Era
            subgraph "Alonzo Era"
                AFSP["Alonzo – Formal Spec (Plutus)"]:::formal
                AImpl2["Alonzo – Implementation"]:::implementation
                ACddl2["Alonzo – CDDL"]:::cddl
                ATS2["Alonzo – Tests"]:::tests
                AFSP -->|"influences"| AImpl2
                AImpl2 -->|"validated-by"| ATS2
                AImpl2 -->|"uses-schema"| ACddl2
            end

            %% Babbage Era
            subgraph "Babbage Era"
                BFSP["Babbage – Formal Spec"]:::formal
                BImpl["Babbage – Implementation"]:::implementation
                BCddl2["Babbage – CDDL"]:::cddl
                BTS["Babbage – Tests"]:::tests
                BFSP -->|"influences"| BImpl
                BImpl -->|"validated-by"| BTS
                BImpl -->|"uses-schema"| BCddl2
            end

            %% Conway Era
            subgraph "Conway Era"
                CImplSpec["Conway – Impl/Spec"]:::formal
                CCddl["Conway – CDDL"]:::cddl
                CTS["Conway – Tests"]:::tests
                CImplSpec -->|"validated-by"| CTS
                CImplSpec -->|"uses-schema"| CCddl
            end

            %% Evolution Flow between Eras (using representative nodes)
            BLF ---|"evolves"| SSFD
            SSFD ---|"evolves"| AImpl
            AImpl ---|"evolves"| MImpl
            MImpl ---|"evolves"| AFSP
            AFSP ---|"evolves"| BFSP
            BFSP ---|"evolves"| CImplSpec
        end

        %% Libraries Cluster
        subgraph "Libraries"
            LibData["cardano-data"]:::libraries
            LibAPI["cardano-ledger-api"]:::libraries
            LibBinary["cardano-ledger-binary"]:::libraries
            LibCore["cardano-ledger-core"]:::libraries
            LibConstr["constrained-generators"]:::libraries
            LibSmall["small-steps"]:::libraries
            LibSet["set-algebra"]:::libraries
            LibVector["vector-map"]:::libraries
            LibConform["cardano-ledger-conformance"]:::libraries
        end

        %% Infrastructure & Tools Cluster
        subgraph "Infrastructure & Tools"
            Nix["Nix Environment"]:::infrastructure
            CI["CI Workflows"]:::infrastructure
            Scripts["Supporting Scripts"]:::infrastructure
            Docs["Documentation Sources"]:::infrastructure
        end
    end

    %% Dotted dependency arrows from shared Libraries to Implementation nodes
    LibData ---|"dep"| BLI
    LibData ---|"dep"| BCI
    LibData ---|"dep"| SImpl
    LibData ---|"dep"| AImpl
    LibData ---|"dep"| MImpl
    LibData ---|"dep"| AImpl2
    LibData ---|"dep"| BImpl
    LibData ---|"dep"| CImplSpec

    LibAPI ---|"dep"| BLI
    LibAPI ---|"dep"| BCI
    LibAPI ---|"dep"| SImpl
    LibAPI ---|"dep"| AImpl
    LibAPI ---|"dep"| MImpl
    LibAPI ---|"dep"| AImpl2
    LibAPI ---|"dep"| BImpl
    LibAPI ---|"dep"| CImplSpec

    %% Click Events for Component Mappings
    %% Byron
    click BLF "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/byron/ledger/executable-spec"
    click BLI "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/byron/ledger/impl"
    click BCF "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/byron/chain/formal-spec"
    click BCI "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/byron/chain/executable-spec"
    click BCddl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/byron/cddl-spec"
    
    %% Shelley
    click SSFD "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/shelley/formal-spec"
    click SImpl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/shelley/impl"
    click STS "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/shelley/test-suite"

    %% Allegra
    click AImpl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/allegra/impl"
    click ACddl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/allegra/impl/cddl-files"
    click ATS "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/allegra/impl/test"

    %% Mary
    click MImpl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/mary/impl"
    click MCddl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/mary/impl/cddl-files"
    click MTS "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/mary/impl/test"

    %% Alonzo
    click AFSP "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/alonzo/formal-spec"
    click AImpl2 "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/alonzo/impl"
    click ACddl2 "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/alonzo/impl/cddl-files"
    click ATS2 "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/alonzo/test-suite"

    %% Babbage
    click BFSP "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/babbage/formal-spec"
    click BImpl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/babbage/impl"
    click BCddl2 "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/babbage/impl/cddl-files"
    click BTS "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/babbage/test-suite"

    %% Conway
    click CImplSpec "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/conway/impl"
    click CCddl "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/conway/impl/cddl-files"
    click CTS "https://github.com/intersectmbo/cardano-ledger/tree/master/eras/conway/test-suite"

    %% Libraries Click Events
    click LibData "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/cardano-data"
    click LibAPI "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/cardano-ledger-api"
    click LibBinary "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/cardano-ledger-binary"
    click LibCore "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/cardano-ledger-core"
    click LibConstr "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/constrained-generators"
    click LibSmall "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/small-steps"
    click LibSet "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/set-algebra"
    click LibVector "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/vector-map"
    click LibConform "https://github.com/intersectmbo/cardano-ledger/tree/master/libs/cardano-ledger-conformance"

    %% Infrastructure Click Events
    click Nix "https://github.com/intersectmbo/cardano-ledger/tree/master/nix/"
    click CI "https://github.com/intersectmbo/cardano-ledger/tree/master/.github/workflows"
    click Scripts "https://github.com/intersectmbo/cardano-ledger/tree/master/scripts"
    click Docs "https://github.com/intersectmbo/cardano-ledger/tree/master/doc"

    %% Style Definitions
    classDef formal fill:#a7c7e7,stroke:#1f4e79,stroke-width:2px;
    classDef implementation fill:#b9e2af,stroke:#3d7d33,stroke-width:2px;
    classDef tests fill:#fdd692,stroke:#b26d00,stroke-width:2px;
    classDef cddl fill:#d1a3d4,stroke:#7d3c98,stroke-width:2px;
    classDef libraries fill:#e2e2e2,stroke:#6e6e6e,stroke-width:2px;
    classDef infrastructure fill:#f4c2c2,stroke:#b22222,stroke-width:2px;
```
