Skip to content

cardano-node-clients

Channel-driven Haskell clients for Cardano node Ouroboros mini-protocols.

Overview

This library provides high-level interfaces for communicating with a Cardano node:

  • Provider -- query UTxOs and protocol parameters
  • Submitter -- submit signed transactions
  • Balance -- exact-fee balancing and fee-dependent output convergence
  • TxBuild -- Conway-era transaction builder DSL with Peek fixpoints and pluggable Ctx queries
  • TxDiff -- structural transaction diffing with blueprint-aware datum/redeemer decoding (architecture)
  • Validity -- pick an invalid-hereafter slot inside the chain's plutus-translation horizon (details)

Balance and TxBuild are implemented by the public cardano-node-clients:tx-build sublibrary. The main library re-exports those modules for compatibility, while transaction-only consumers can depend on the smaller component without node communication, indexer, daemon, socket, or RocksDB dependencies.

The interfaces are protocol-agnostic records-of-functions. Each transport protocol supplies its own constructor:

Protocol Provider Submitter
N2C (Unix socket) mkN2CProvider mkN2CSubmitter
N2N (TCP) planned planned

Executables

  • tx-diff -- compare two Conway transactions, optionally decode Plutus datum/redeemer data with blueprints, and group repeated list diffs with YAML collapse rules (manual). Install released builds from the GitHub Release assets on Linux or with brew tap lambdasistemi/tap && brew install tx-diff on macOS.

Current TxBuild status

The transaction builder DSL is under active development and currently implements the first complete branch scope:

  • spending, script spending, outputs, collateral, minting, required signers, attached scripts, reference inputs, and validity intervals
  • Peek-driven fixpoint values for indices and fee-dependent assembly
  • pure drafting with draft and draftWith
  • effectful building with build and InterpretIO
  • pluggable context queries through Ctx
  • opt-in final-transaction validation via Valid
  • balancing with eval retry, fee oscillation handling, bisection, and final maxFee re-iteration

Testing

  • Unit tests cover exact getMinFeeTx balancing, eval retry, oscillation handling, bumpFee, and the TxBuild instruction set.
  • E2E tests run against a real devnet for provider, balanceFeeLoop, chainsync, chain population, and a submitted TxBuild transaction that exercises spend, payTo, payTo', ctx, peek, valid, requireSignature, and validFrom/validTo.

Quick start

import Cardano.Node.Client.N2C.Connection
import Cardano.Node.Client.N2C.Provider
import Cardano.Node.Client.N2C.Submitter
import Control.Concurrent.Async (async)
import Ouroboros.Network.Magic (NetworkMagic (..))

main :: IO ()
main = do
    lsqCh  <- newLSQChannel 16
    ltxsCh <- newLTxSChannel 16
    -- connect in background
    _ <- async $
        runNodeClient
            (NetworkMagic 764824073)  -- mainnet
            "/run/cardano-node/node.socket"
            lsqCh
            ltxsCh
    let provider  = mkN2CProvider lsqCh
        submitter = mkN2CSubmitter ltxsCh
    -- use provider / submitter ...
    pure ()

Build

nix develop -c just build   # compile
nix develop -c just ci      # format + lint + build