Haskell Core Contributor
This guide covers contributing to the reference Cardano node implementation: cardano-ledger, ouroboros-consensus, cardano-node, and their companion libraries. This is the Haskell path.
Before reading further, make sure you have read the Cardano Blueprint: the implementation-independent guide to how the protocol works. It is the best orientation before navigating any of these repositories.
New to Haskell? Work through the IOG Haskell Course first. It is a beginner-friendly, 22-lesson curriculum built by IOG that takes you from zero Haskell knowledge to practical productivity, with video lessons and hands-on exercises. It assumes no prior Haskell experience and is specifically designed with Cardano development in mind.
The Repositories
The core of Cardano is implemented in Haskell across several tightly coupled repositories. Start with cardano-ledger for ledger rules or ouroboros-consensus for chain selection and block validation: these are the two deepest entry points.
| Repository | What it governs | Issues |
|---|---|---|
cardano-ledger | All ledger rules: how transactions are validated, how state transitions work using the STS framework | Issues |
ouroboros-consensus | The Ouroboros consensus algorithm, chain selection, and block validation | Issues |
ouroboros-network | The peer-to-peer networking layer: mini-protocols, connection management | Issues |
cardano-node | The node executable that ties ledger, consensus, and networking together | Issues |
cardano-api | High-level Haskell library over ledger/consensus; the interface used by CLI and tooling | Issues |
cardano-cli | The official command-line interface: good for contributor-friendly Haskell issues | Issues |
cardano-base | Shared cryptography, slotting, and binary serialization libraries used across the stack | Issues |
plutus | The Plutus Core language and execution engine: compiler, evaluator, cost models | Issues |
When browsing issues, filter by the good first issue label to find tasks suitable for new contributors, or by help wanted for issues where the team is actively looking for outside input. You can also filter by area (e.g. ledger, consensus, testing) to narrow down to your domain of interest.
Important distinction: The Plutus Pioneer Program teaches you to write on-chain validators. It does not prepare you to contribute to
cardano-ledgerorouroboros-consensus. These are different jobs. Completing the Plutus Pioneer Program is not a prerequisite here.
Step 0: The Dependency Wall
Every core Cardano Haskell repository has a complex dependency graph involving GHC version constraints, C library dependencies, cryptographic primitives, and cross-platform linker flags.
Attempting to resolve this manually will fail. Depending on your OS and distribution, it ranges from painful to impossible. On NixOS specifically, non-Nix builds do not work by design.
Nix is the standard working environment. A nix develop invocation drops you into an environment where all dependencies are pinned, present, and working.
Getting started with Nix:
nix-installerby Determinate Systems: the recommended installerdevenv: a developer-friendly layer on top of Nix- Each repo's
flake.nixorshell.nixdefines the development shell: runnix developfrom the repo root
The Formal Specifications
The Haskell implementation must match the formal specifications. These are the ground truth.
| Document | What it specifies |
|---|---|
| Shelley Ledger Formal Spec | The foundational ledger rules using small-step semantics (STS) |
| Conway Ledger Spec | CIP-1694 governance, DRep ratification, committee logic |
| Ouroboros papers | The family of consensus protocol proofs (Classic, BFT, Praos, Genesis) |
The STS (small-step semantics) framework that governs all ledger rules is the conceptual backbone of cardano-ledger. Understanding it is the difference between reading the code and understanding it.
Your Most Accessible Entry Point: Testing
You do not need to implement a new ledger rule to make a valuable core contribution. Writing tests is often where new contributors start, and it is high-value work.
cardano-ledger has substantial test infrastructure built on property-based testing:
- Hedgehog and QuickCheck are used throughout
- Conformance testing: verifying that alternative implementations (Rust, Go, etc.) match the Haskell ledger rules: is an ongoing effort and a legitimate core contribution
- The test suite documents expected behavior; writing a test for an existing rule is a concrete, reviewable contribution
Good first issues in the testing area:
- Search for
good first issueortestinglabels incardano-ledgerissues - Look at existing
Specmodules incardano-ledgerto understand the testing patterns
How to Contribute a CIP
A Cardano Improvement Proposal (CIP) is how many core contributions happen: especially changes to ledger rules, protocol parameters, or cryptographic primitives.
What becomes a CIP vs. a PR:
- Changes that affect the protocol specification → CIP
- Bug fixes, test additions, or implementation details that don't change the spec → normal PR/issue
The CIP stages:
- Proposed: draft submitted to the CIPs repository as a PR
- Candidate: reviewed and accepted by CIP editors, open for community comment
- Active: ratified and incorporated into a hard fork or ecosystem tooling
Key contacts and venues:
- CIP editors review submissions in the CIPs repo PRs
- Intersect's TSC working groups often discuss CIPs in progress: see Intersect Working Groups
- The
#cip-discussionchannel in the Intersect Discord is the informal venue for early feedback. Join Intersect first to get access: see the Intersect Membership Guide
The CIPs repository README has the authoritative process document. Reading a few merged CIPs (CIP-1694, CIP-0381) before writing your own will calibrate your expectations. You can browse all ratified and draft CIPs at cips.cardano.org.
Governance Protocol Work
Governance in Cardano operates at three distinct layers: don't conflate them:
| Layer | What it is | Example work |
|---|---|---|
| Governance participation | Being a DRep, voting, joining Intersect | Register as a DRep, join a working group |
| Governance tooling | Application development on governance infrastructure | GovTool, Agora, wallet integrations for voting |
| Governance protocol | Core ledger rules governing governance itself | CIP-1694 implementation in cardano-ledger, Conway era rules, DRep pulsing, ratification logic |
The Conway era modules in cardano-ledger are a good starting point for governance protocol work:
Cardano.Ledger.Conway.Rules: the STS rules for governance- The Conway formal spec (linked above)
- Governance model — how on-chain governance works end to end
- Governance actions — the types of actions the ledger can ratify
For governance participation and tooling, see the Intersect Membership Guide.
Back to Core Protocol Contributor: or continue to Rust or Go.