cardano-wallet: the Haskell wallet server behind Daedalus, now in maintenance mode

A server that other wallets talk to

Cardano Wallet is software that helps you manage your ADA, and it can send and receive payments on the Cardano blockchain. The important framing is in the repository description: it is an HTTP Application Programming Interface and a command-line interface for working with your wallet, and it can be used as a component of a frontend such as Daedalus, which provides a friendly user interface for wallets.

The project then says plainly that most users who would like to use Cardano should start with Daedalus. That sentence is the adoption decision in one line. What lives in this repository is infrastructure, not an application.

The executable itself is an HTTP server that manages your wallets, and to retrieve blockchain data and to send transactions it has to connect to a running cardano-node process. So there are two moving parts, a node that talks to the chain and a wallet that talks to the node, and the wallet is the part with an API in front of it.

The primary language is Haskell and the licence is Apache-2.0. The repository carries a substantial amount of specification and design documentation alongside the code, including a specifications directory, a specs directory, prototypes, reports and design documents published as a website, which is the mark of a project that had to define the wallet API before it could implement it.

For an engineer, the audience is a team that wants to operate Cardano infrastructure themselves, or that wants to write a wallet interface and needs a well specified backend to sit on.

Maintenance-only since April 2025

The notice at the top of the project page is the single most important fact for anyone evaluating this code, and it is easy to miss if you only skim the badges.

Starting April 1st, 2025, the Cardano Wallet is in maintenance-only mode. The Cardano Foundation is committed to maintaining it for the foreseeable future, and the listed commitments are concrete: upgrading to new versions of cardano-node, fixing bugs, improving the quality and stability of both the code and the server, and providing general user support.

Contributions for new features are welcome and will be thoroughly reviewed, but no new features will be developed by the Cardano Foundation.

That is a useful distinction to hold on to. The project is not dead and it is not abandoned. It receives dependency upgrades and bug fixes, and it is explicitly open to outside feature work that its maintainers are willing to review. What it will not get is the Foundation building new capability on request.

Practically, that changes the risk profile of adoption. If you are building something that needs a feature the wallet does not have today, you should plan to implement it yourself or choose a different foundation, rather than assuming it will arrive. If you need a stable, well specified wallet API that tracks cardano-node releases, this is a reasonable dependency.

The repository also carries files that suggest active housekeeping rather than dormancy, with ERA-CHANGES.md, MAINTAINERS.md, TODO.md, a SECURITY.md and a set of bump-changelog files for specific versions.

The node is a prerequisite, not an optional extra

The dependency on cardano-node shapes everything about how you deploy this.

The QuickStart guide is explicit that in order to retrieve blockchain data and send transactions, the cardano-wallet executable must connect to a running cardano-node process, and it presents several ways of doing that which you can later customise to your needs.

The Docker path is the documented one. You can use Docker to download, configure and start the cardano-wallet and cardano-node executables. The first decision is the network, because the guide puts it first: the network mainnet keeps track of the real money, while the networks private, sanchonet and preprod are test networks.

After choosing a network you change into the matching directory and use a small script for everything:

./run.sh start
./run.sh stop
./run.sh logs
./run.sh sync

The four commands cover the operational cycle. start brings up a node and a wallet, stop shuts them down, logs shows you what is happening, and sync is the one worth understanding: it starts a node and a wallet, waits until they are fully synchronized to the network, and stops again. Synchronization is the slow part of joining a Cardano network, and having a command that does it for you saves a lot of guesswork.

The accepted variables for the start command are documented too, beginning with WALLET_PORT, whose default is 8090, the port the wallet listens on.

The practical advice for a first run is to use a test network. The compose file supports the mainnet path, but a development setup that talks to mainnet and holds real funds is a different proposition from the same code on sanchonet or preprod.

One compose file, three services

The compose file in the repository shows how the pieces fit, and it is more informative than the prose.

The cardano-node service runs the node, with the node database mounted at /data and a socket directory at /ipc shared with the wallet, and the configuration coming from a mounted./configs/cardano directory. Its command line is the node's own run command with the topology, database path, socket path and config all pointed into those mounts.

cardano-node run --topology /configs/${NETWORK}/topology.json
  --database-path /data
  --socket-path /ipc/node.socket

The cardano-wallet service shares the same socket directory, which is how the two processes find each other, and exposes the wallet's port:

  cardano-wallet:
    image: cardanofoundation/cardano-wallet:${WALLET_TAG}
    volumes:
      - ${WALLET_DB}:/wallet-db
      - ${NODE_SOCKET_DIR}:/ipc
      - ./configs/cardano:/configs
    ports:
      - ${WALLET_PORT}:8090

The wallet's command line shows the whole surface of its configuration, which is a node socket path, a wallet database path and a listen address:

cardano-wallet serve --node-socket /ipc/${NODE_SOCKET_NAME} --database /wallet-db --listen-address 0.0.0.0

The entrypoint logic is worth noticing too, because the command is chosen by network. On mainnet the wallet is started with --mainnet, and otherwise with --testnet pointed at the byron genesis file for that network. A wallet that talks to the wrong network is a mistake the compose file makes harder to make by accident.

A third service, icarus, runs with host networking and its own pinned image tag.

Both Cardano services use the same image with a tag selected by the WALLET_TAG variable, so the wallet and the node are version matched by construction.

Haskell build hygiene, spelled out in a justfile

The development tooling of a Haskell project is unusual enough to be worth reading, because it shows how the project keeps a large codebase consistent.

The justfile is the entry point. There is a syntax target that runs the same script CI uses to check code formatting, and a fmt target that formats every Haskell, Cabal and Nix file the check covers: fourmolu in inplace mode over the tracked.hs files, cabal-fmt over the.cabal files in lib, and nixfmt over the tracked.nix files. There is an hlint target that runs the linter over lib inside a nix develop shell, and a lint-lib target that lints and tests a single library, for example delta-types, so a change can be checked in isolation.

The build target is where the strictness shows:

cabal build {{target}} --enable-benchmarks --enable-tests \
  --minimize-conflict-set -O0 -v0 --ghc-options="-Werror "

Warnings are errors, which is why the compiler flags matter. The -O0 optimisation level and --minimize-conflict-set are there to keep builds fast and dependency versions coherent in a workspace with many packages.

The wider toolchain is visible in the repository root as well: a cabal.project for the build plan, flake.nix and flake.lock for a Nix development shell, a fourmolu.yaml and an.hlint.yaml for the two formatters and linters, floskell.json for the Floskell Haskell formatter, a weeder.dhall file for dead code detection, and hie-direnv.yaml for IDE integration through direnv.

The CI badges match that investment, with separate workflows for benchmarks, end-to-end tests on Linux, a Mithril sync job, and unit and integration jobs on macOS and Windows. Continuous integration across three operating systems is a reasonable expectation for a wallet backend that people are asked to run themselves.

Daedalus is the real alternative for most people

The alternative to this project is not another wallet server, it is Daedalus, and the difference in approach is what the README describes.

Daedalus is a frontend. It provides a friendly user interface for wallets, and it uses Cardano Wallet as a component underneath. Running cardano-wallet directly means you own the node, the wallet database, the socket configuration and the API client, and you build the interface yourself.

For an end user with no infrastructure interest, that is a strictly worse arrangement, and the project says so. For a team writing an interface, an exchange, a monitoring tool or a research harness, the opposite is true, and the API documentation, the CLI manual and the design documents give you a contract to build against.

The documentation structure is worth mapping, because it tells you which audience each part is written for. The user manual is for people using Cardano Wallet, with the CLI manual and the API documentation nested under it for users of the API. The design documents are for anyone interested in wallet design and specifications, with the specifications nested under that. The contributor manual is for anyone interested in the project and its development process, and there is a separate Adrestia documentation site for the same audience.

Splitting design from specification from contribution guidance is what lets a protocol implementation stay coherent while remaining buildable by people outside the original team, and it is also what makes it possible to review a change against a written specification rather than against the code alone.

Editorial conclusion

cardano-wallet suits engineers building on top of Cardano who need a wallet backend with a documented API, or a team that wants to run their own node and wallet on a test network such as sanchonet or preprod. It is the wrong choice for an end user, because the project says most people who want to use Cardano should start with Daedalus, and it is the wrong choice for a team looking for new functionality, since the Foundation has said no new features will be developed. Verify three things before you build on it: that the cardano-node version you plan to run is one the wallet has been upgraded against, that your chosen network is a test network rather than mainnet while you are still developing, and that the API and CLI manuals match the version of the executable you have deployed.

Frequently asked questions

Official sources

1. cardano-foundation/cardano-wallet on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases