cardano-deps

# Cardano Dependencies Management Managing Cardano Haskell dependencies is complex due to the interconnected ecosystem. This skill provides the workflow for updating dependencies reliably. ## Dependency Update Workflow ### 1. Choose Target cardano-node Version User decides which cardano-node version to align with (e.g., 10.1.0, 10.2.0). ### 2. Clone and Checkout Cardano Dependencies All Cardano dependencies must be cloned locally and checked out to the correct tag. **Required repos** (in `/code/`): - `cardano-node` - `cardano-api` - `cardano-ledger` - `cardano-base` - `ouroboros-network` - `ouroboros-consensus` For each repo: ```bash cd /code/<repo> git fetch --tags git checkout <tag> # matching the target cardano-node version ``` Check cardano-node's `cabal.project` for the exact versions/tags of each dependency. ### 3. Extract Changelogs For each Cardano repo, extract the changelog between current and target version: ```bash cd /code/<repo> git log --oneline <current-tag>..<target-tag> ``` Create a combined changelog document (e.g., `bump-changelog.md`) that: 1. Lists changes from all repos 2. Orders entries chronologically 3. Groups by repo for reference Commit this document. It provides a unified view of all ecosystem changes. ### 4. Align flake.lock with cardano-node **Critical for Windows cross-compilation**: Use the same CHaP version as cardano-node to avoid wine/iserv issues. ```bash # Check cardano-node's CHaP version cd /code/cardano-node git checkout <target-version> cat flake.lock | jq '.nodes.CHaP.locked.rev' # Update cardano-wallet's CHaP to match cd /code/cardano-wallet nix flake update CHaP --override-input CHaP github:intersectmbo/cardano-haskell-packages/<chap-rev> ``` **Why this matters**: Different CHaP versions can resolve different transitive dependency versions (e.g., `th-orphans`, `network`). These differences can cause the `iserv-proxy` derivation to be built differently, leading to wine socket connection failures during Windows cross-compilation. ### 5. Freeze Dependencies ```bash cd /code/cardano-node cabal update cabal freeze ``` This generates `cabal.project.freeze` with exact versions of all dependencies. ### 5. Determine Sublibrary Order Use `cabal-plan` to get topological order: ```bash cabal-plan topo ``` Or for a visual graph: ```bash cabal-plan dot | dot -Tpng -o deps.png ``` ### 6. Update .cabal Files in Order For each sublibrary, from least dependent to most dependent: 1. Open the `.cabal` file 2. Update `build-depends` bounds using freeze as reference: - **Lower bound:** version from freeze - **Upper bound:** next minor version Example: if freeze says `aeson-2.1.2.1`, use `aeson >= 2.1.2.1 && < 2.2` 3. Build the sublibrary 4. Format and lint: - `fourmolu -i` on all source files - `hlint` on all source files 5. If sublibrary has tests: - Build tests - Format and lint test files - (tests don't need to pass - fixing tests is done with the user) 6. **Commit** this sublibrary (one commit per sublibrary) 7. **Never touch this sublibrary again** during the bump This ensures each sublibrary is fully complete before moving to the next. ### 7. Update cabal.project After all .cabal files are updated: - Update `index-state` for hackage and CHaP - Update any `source-repository-package` entries ### 8. Update Node Runtime Version Update the cardano-node input in `flake.nix` to the target version. This is required to run integration tests against the new node version. ### 9. Final Summary Commit Create a final commit that: 1. Summarizes all operations performed during the bump 2. References the changelog document created in step 3 3. Lists all dependency version changes 4. Documents any breaking changes or notable updates from dependencies ## cardano-wallet Sublibrary Order 33 sublibraries in dependency order (update in this sequence): **Level 0 - No internal dependencies:** - `delta-types` - `text-class` - `cardano-numeric` - `std-gen-seed` - `crypto-primitives` - `faucet` - `cardano-wallet-application-tls` **Level 1:** - `cardano-wallet-tracing` - `cardano-wallet-launcher` - `cardano-wallet-test-utils` - `delta-store` - `wai-middleware-logging` - `cardano-wallet-secrets` - `cardano-wallet-application-extras` **Level 2:** - `temporary-extra` - `delta-chain` - `delta-table` - `cardano-api-extra` - `cardano-wallet-primitive` **Level 3:** - `cardano-coin-selection` - `address-derivation-discovery` **Level 4:** - `cardano-balance-tx` **Level 5:** - `cardano-wallet-network-layer` **Level 6:** - `cardano-wallet` - `local-cluster` **Level 7:** - `cardano-wallet-api` **Level 8:** - `cardano-wallet-ui` **Level 9:** - `cardano-wallet-application` **Level 10:** - `cardano-wallet-integration` - `cardano-wallet-unit` **Level 11:** - `cardano-wallet-benchmarks` **Level 12:** - `cardano-wallet-blackbox-benchmarks` ## Key Concepts ### Cardano Haskell Packages (CHaP) CHaP is the custom Hackage repository for Cardano packages: ```cabal repository cardano-haskell-packages url: https://chap.intersectmbo.org/ secure: True root-keys: 3e0cce471cf09815f930210f7827266fd09045445d65923e6d0238a6cd15126f 443abb7fb497a134c343faf52f0b659bd7999bc06b7f63fa76dc99d631f9bea1 a86a1f6ce86c449c46666bda44268677abf29b5b2d2eb5ec7af903ec2f117a82 bcec67e8e99cabfa7764d75ad9b158d72bfacf70ca1d0ec8bc6b4406d1bf8413 c00aae8461a256275598500ea0e187588c35a5d5d7454fb57eac18d9edb86a56 d4a35cd3121aa00d18544bb0ac01c3e1691d618f462c46129271bccf39f7e8ee ``` **index-state** controls which package versions are visible: ```cabal index-state: , hackage.haskell.org 2025-01-01T23:24:19Z , cardano-haskell-packages 2025-03-01T00:00:00Z ``` ### Source Repository Packages For packages not on CHaP or when you need a specific commit: ```cabal source-repository-package type: git location: https://github.com/IntersectMBO/cardano-addresses tag: 2bca06deaa60e54a5322ac757387d744bf043367 --sha256: 1y1mzfly7jac40b9g4xc078rcm5zqhc3xxv77kwxi10yph1jwq7z subdir: command-line core ``` **Getting SHA256:** ```bash nix flake prefetch github:owner/repo/commit-sha ``` ## Bound Format Standard format for dependency bounds: ```cabal build-depends: aeson >= 2.1.2.1 && < 2.2 , base >= 4.18 && < 5 , cardano-api >= 10.0 && < 10.1 ``` - Lower bound: exact version from freeze - Upper bound: next minor version (allows patch updates) ## Troubleshooting ### "Could not resolve dependencies" 1. `cabal update` 2. Check if package exists in CHaP at your index-state 3. Try newer index-state 4. Add as source-repository-package ### Build failures after update 1. `rm -rf dist-newstyle` 2. `cabal update` 3. `cabal build all -O0` ### Windows cross-compilation fails with wine/iserv socket error ``` iserv-proxy: Network.Socket.connect: <socket: 126>: does not exist (Connection refused) <no location info>: error: ghc-iserv terminated (1) ``` This happens when Template Haskell packages (like `th-orphans`) fail during Windows cross-compilation. The root cause is usually a CHaP version mismatch causing different transitive dependencies. **Fix**: Align CHaP with the target cardano-node version: ```bash # Get cardano-node's CHaP rev cd /code/cardano-node && git checkout <target-version> cat flake.lock | jq '.nodes.CHaP.locked.rev' # Update cardano-wallet to use same CHaP cd /code/cardano-wallet nix flake update CHaP --override-input CHaP github:intersectmbo/cardano-haskell-packages/<rev> ``` **Debug steps**: 1. Compare derivation inputs between working (master) and failing builds: ```bash diff <(nix-store -qR /nix/store/<master-drv> | sort) \ <(nix-store -qR /nix/store/<failing-drv> | sort) ``` 2. Look for differences in `iserv-proxy`, `network`, `th-orphans` versions ## Automation Opportunities **Potential tools to create:** 1. **deps-order** - Script to output sublibrary update order from cabal.project 2. **bounds-update** - Parse freeze file, update .cabal bounds automatically 3. **validate-bounds** - Check all .cabal files have consistent bounds These could be added to the justfile or as standalone tools.