Cardano Addresses

Overview

This module provides mnemonic (backup phrase) creation, and conversion of a mnemonic to seed for wallet restoration, and address derivation functionalities.

Documentation

Haddock documentation

Haddock API documentation is available here.

Docusaurus-powered documentation

Powered by

CLI documentation is available here

Supported platforms

cardano-addresses is officially supported on the following operating systems:

• Linux - Ubuntu 20.04+, Debian 11+, Fedora 38+, and other major distributions
• macOS - version 11 (Big Sur) and later
• Windows - Windows 10 and Windows 11

cardano-addresses comes with CLI for Linux, MacOS and Windows. See releases to get respective pre-compiled binaries.

Building/testing from source using nix

Prerequisites: Install Nix with flakes enabled.

This project uses devx for the development shell.

Updating dependencies

Periodically update the flake lock file to get the latest versions of devx and nixpkgs:

nix flake update

This ensures you have recent GHC versions, security updates, and bug fixes.

Enter development shell

nix develop

To use a specific GHC version, append the variant:

# GHC 9.10
nix develop github:input-output-hk/devx#ghc910-iog

# GHC 9.12
nix develop github:input-output-hk/devx#ghc912-iog

Inside the development shell:

# building
cabal build all

# testing
cabal test cardano-addresses:unit

# installing executable locally
cabal install cardano-address

Using direnv

If you use direnv, add this to your .envrc:

use flake "github:input-output-hk/devx#ghc96-iog"

Docker image

Use the devx devcontainer image:

docker run -it ghcr.io/input-output-hk/devx-devcontainer:x86_64-linux.ghc96-iog

Available images:

• ghc96-iog - GHC 9.6 with IOG libraries
• ghc98-iog - GHC 9.8 with IOG libraries
• ghc910-iog - GHC 9.10 with IOG libraries
• ghc912-iog - GHC 9.12 with IOG libraries
• ghc96-js-iog - GHC 9.6 with JavaScript cross-compilation
• ghc98-js-iog - GHC 9.8 with JavaScript cross-compilation

To build the project inside the container:

cabal build all

Cross-compilation

Devx supports cross-compilation through variants:

# Windows cross-compilation (when available)
nix develop github:input-output-hk/devx#ghc96-windows-iog

# JavaScript cross-compilation
nix develop github:input-output-hk/devx#ghc96-js-iog

# Static binary build
nix develop github:input-output-hk/devx#ghc96-static-iog

You can combine variants:

# Static build with minimal IOG dependencies
nix develop github:input-output-hk/devx#ghc96-static-minimal-iog

Preparation steps before uploading to hackage

cabal build all
cabal haddock
cabal sdist

Note: Make sure proper version is set in cardano-addresses.cabal

Docker Image

Please make sure you have just installed as justfile is used for building Docker image.

Build

just clean-build-docker

Run

Use the auto-remove flag --rm when running commands.

docker run --rm cardano-address recovery-phrase generate --size 15

Use the interactive flag -i when piping stdin:

echo "addr1gqtnpvdhqrtpd4g424fcaq7k0ufuzyadt7djygf8qdyzevuph3wczvf2dwyx5u" | docker run --rm -i cardano-addresses address inspect

Javascript support

Javascript support was discontinued and dropped. One could look at the following now:

1. MeshJS
2. blaze-cardano

Alternatively one could lean back on release 3.9.0 where Javascript was still present.

Docs generation

The README.md is generated from this file using:

just generate-readme

Contributing

Pull requests are welcome.

When creating a pull request, please make sure that your code adheres to our coding standards.

WebAssembly

The library compiles to WebAssembly via GHC's WASM backend, producing a single cardano-addresses.wasm binary that runs in the browser or any WASI runtime.

Build

nix build github:IntersectMBO/cardano-addresses#wasm
ls result/cardano-addresses.wasm   # 7.0MB

Commands

The binary reads JSON from stdin and writes JSON to stdout. A cmd field selects the operation:

# Address inspection
echo '{"cmd":"inspect","address":"addr1..."}' | wasmtime result/cardano-addresses.wasm

# Key derivation (CIP-1852 Shelley)
echo '{"cmd":"derive","mnemonic":"word1 word2 ...","path":"1852H/1815H/0H/0/0"}' | wasmtime result/cardano-addresses.wasm

# Address construction
echo '{"cmd":"make-address","type":"enterprise","network":"testnet","payment_key":"hex..."}' | wasmtime result/cardano-addresses.wasm

# Ed25519 signing and verification
echo '{"cmd":"sign","key":"hex...","message":"hex..."}' | wasmtime result/cardano-addresses.wasm
echo '{"cmd":"verify","key":"hex...","message":"hex...","signature":"hex..."}' | wasmtime result/cardano-addresses.wasm

# Legacy bootstrap addresses (Byron/Icarus)
echo '{"cmd":"bootstrap-address","style":"icarus-from-mnemonic","protocol_magic":764824073,...}' | wasmtime result/cardano-addresses.wasm

Browser integration

Use @bjorn3/browser_wasi_shim to run the WASM binary client-side:

import { WASI, File, OpenFile, ConsoleStdout } from "@bjorn3/browser_wasi_shim";

const mod = await WebAssembly.compile(await (await fetch("cardano-addresses.wasm")).arrayBuffer());

async function call(input) {
  let out = "";
  const fds = [
    new OpenFile(new File(new TextEncoder().encode(input))),
    ConsoleStdout.lineBuffered(l => out += l + "\n"),
    ConsoleStdout.lineBuffered(() => {}),
  ];
  const wasi = new WASI([], [], fds, { debug: false });
  wasi.start(await WebAssembly.instantiate(mod, { wasi_snapshot_preview1: wasi.wasiImport }));
  return JSON.parse(out.trim());
}

Benchmarked: ~9ms compile (one-time), ~3ms per Shelley call, ~13ms for legacy.

Nix integration

Downstream flakes consume the WASM as a package:

{
  inputs.cardano-addresses.url = "github:IntersectMBO/cardano-addresses";

  outputs = { cardano-addresses, ... }: {
    packages.wasm = cardano-addresses.packages.x86_64-linux.wasm;
    # result/cardano-addresses.wasm
  };
}

---