cardano-keys

The cardano-keys package holds the key types, their serialisation and the credential file readers. It is released on CHaP.

This repository hosts cardano-keys, the Haskell library of Cardano key types together with the serialisation layers for them. That code was extracted from cardano-api, which still carries its own copies of it; see What lives here and what stays in cardano-api.

What is in this repository

Package	What it is
cardano-keys	The library: key types for every Cardano key role, their raw-bytes, CBOR, bech32 and text-envelope serialisation, operational certificates, and the credential file readers a block-forging node needs.

What lives here and what stays in cardano-api

What lives here is the key types, the serialisation classes and instances that give those types their on-disk and on-the-wire forms — raw bytes, CBOR, bech32 and text envelopes — and the credential file readers that answer "given a path, give me the key" (issue #2). The bech32 layer travels with the types on purpose: the bech32-backed JSON instances would be orphan instances anywhere else.

What stays in cardano-api is address bech32, canonical CBOR, cardano-api's own text-envelope IO, everything era-dependent, and all credential assembly: which files a node should read, which combinations of them are valid, and the command-line parsing that produces the paths. Assembly is the consumer's job, not this package's — the readers here take a FilePath and nothing else.

The overlap with cardano-api is the transition, not the destination: when cardano-api adopts this package it deletes its own copies in the same release train, after which key serialisation lives in exactly one place. This is the boundary first proposed in cardano-config PR #13, with the file readers added to it.

Requirements

You can build with Nix (easiest: it provides everything) or with your own Haskell toolchain.

With Nix:

• Nix with flakes enabled.
• Answer "yes" when Nix asks to accept the flake settings. That enables the IOG binary cache (cache.iog.io). Without it, you will compile GHC and every dependency from source.
• Works on x86_64-linux, aarch64-linux and aarch64-darwin.

Without Nix:

The Developer Portal's Installing cardano-node guide covers this exact setup step by step. Follow it up to the point where it starts building the node itself. In short, you need:

• GHC 9.6, 9.10, 9.12 or 9.14, and Cabal 3.16 (for example via GHCup). Development mostly happens on GHC 9.12.
• Cardano's C libraries: libsodium (the IOG fork, with VRF support), libsecp256k1 and libblst. Prebuilt packages are on the iohk-nix releases page; this GitHub action shows how CI installs them.

Quick start

git clone https://github.com/IntersectMBO/cardano-keys
cd cardano-keys
nix develop          # skip this line if you are not using Nix
cabal update         # needed at least once, see note below
cabal build all --enable-tests

Run the tests:

cabal test all --enable-tests --test-show-details=direct

Build notes:

• cabal update downloads the package lists of two repositories: Hackage and CHaP (Cardano Haskell Packages, where the Cardano-specific dependencies live). CHaP is already configured in this repo's cabal.project.
• The project builds with -Werror, so every warning is an error. Stick to the GHC versions listed above.
• The flake provides further development shells: nix develop .#profiling, nix develop .#wasm, and, on x86_64-linux only, nix develop .#ghc967 and nix develop .#ghc914 (the haddock compiler).

Using the library in your project

Cardano libraries are released on CHaP, not on Hackage, so your project needs CHaP configured.

cabal.project points at your package and registers CHaP:

packages: .

repository cardano-haskell-packages
  url: https://chap.intersectmbo.org/
  secure: True
  root-keys:
    3e0cce471cf09815f930210f7827266fd09045445d65923e6d0238a6cd15126f
    443abb7fb497a134c343faf52f0b659bd7999bc06b7f63fa76dc99d631f9bea1
    a86a1f6ce86c449c46666bda44268677abf29b5b2d2eb5ec7af903ec2f117a82
    bcec67e8e99cabfa7764d75ad9b158d72bfacf70ca1d0ec8bc6b4406d1bf8413
    c00aae8461a256275598500ea0e187588c35a5d5d7454fb57eac18d9edb86a56
    d4a35cd3121aa00d18544bb0ac01c3e1691d618f462c46129271bccf39f7e8ee

(Tip: also pin an index-state to make your builds reproducible; see the CHaP README.)

With CHaP configured, depending on it looks like this:

cabal-version: 3.0
name:          example
version:       0.1.0.0
build-type:    Simple

executable example
  main-is:          Main.hs
  default-language: Haskell2010
  build-depends:
    , base
    , cardano-keys ^>=11.0
    , text

Expect the first build to take a while: it compiles a good part of the Cardano stack. Without Nix, you also need the C libraries from Requirements.

Documentation

• Haddock documentation: the full API reference, rebuilt from master.
• Cardano Node Wiki: development documentation.
• Cardano Developer Portal: if you are new to Cardano itself.

Contributing

See the Contributing guide for how to contribute to this project.