Cardano Balance Transaction Guide

cardano-balance-transaction guide

Standalone Haskell library (no executable) that turns a partial Cardano transaction into a fully balanced, ready-to-sign one. The single public entry point is balanceTx. Targets the two most recent eras: Conway and Dijkstra.

Repository map

Build, test, run

Everything routes through the flake (same as .github/workflows/ci.yml):

nix develop                  # dev shell (GHC 9.12.2, cabal, CHaP access)
just build                   # nix build .#lib .#unit-tests
just unit                    # nix run .#unit-tests
just unit "Surplus"          # run a matching subset
just CI                      # build + tests + fourmolu + hlint + nixfmt
just format                  # fourmolu, cabal-fmt, nixfmt
just docs-build              # mkdocs build --strict

Inside nix develop, cabal works too: cabal build lib:cardano-balance-tx -O0, cabal test unit -O0.

Navigating the code

• Start at balanceTx in Balance.hs (defined around line 529). Its internal worker is balanceTxInner. The module re-exports the selection, surplus, and error types callers need.
• The balancing loop is iterative: add inputs → re-estimate fee/size → recompute change → repeat until the fee stabilises, then assign redeemers and validate.
• Era handling is centralised in Eras.hs: pattern-match RecentEra era (RecentEraConway / RecentEraDijkstra); add era constraints via IsRecentEra / RecentEraConstraints. To support a new era you touch Eras.hs first.
• Ledger ↔ primitive conversions live in Primitive/Convert.hs (toConwayTxOut, toDijkstraTxOut, toLedgerCoin, …).

Using cardano-balance-tx

Consume it as a library (source-repository-package in cabal.project). The public surface is one function:

balanceTx
    :: forall era m changeState
     . (MonadRandom m, IsRecentEra era)
    => PParams era
    -> TimeTranslation
    -> UTxOAssumptions
    -> UTxOIndex era
    -> ChangeAddressGen changeState
    -> changeState
    -> PartialTx era
    -> ExceptT (ErrBalanceTx era) m (Tx era, changeState)

• Build the UTxOIndex era with constructUTxOIndex.
• Failures come back as ErrBalanceTx era (e.g. ErrBalanceTxAssetsInsufficientError, ErrBalanceTxUnableToCreateChangeError, ErrBalanceTxInsufficientCollateralError).
• The era type parameter must satisfy IsRecentEra — instantiate it at Conway or Dijkstra.

Answering questions

• "What does this library do / how does balancing work?" → README.md ("What is this", "Architecture") and docs/architecture.md (pipeline + iteration diagrams).
• "Which eras are supported?" → Conway and Dijkstra (the two most recent eras). Source of truth: RecentEra in lib/Cardano/Balance/Tx/Eras.hs. Babbage is a non-recent era kept only for serialization round-trip fixtures.
• "How do I call it / what's the API?" → README "Usage" and docs/modules.md; the signature is balanceTx in Balance.hs.
• "How do I build/test it?" → README.md "Development", docs/getting-started.md, the justfile, and .github/workflows/ci.yml.
• "Where did it come from?" → NOTICE and the README "Origin" section (extracted from cardano-wallet lib/balance-tx/).
• When a user claims a behaviour the docs don't cover, verify against the source under lib/Cardano/Balance/Tx/ before answering.