Release Zaino 0.6.0 (Ironwood)

.config/nextest.toml

@@ -34,14 +34,15 @@ path = "junit.xml"
 [test-groups]
 live-validators = { max-threads = 6 }
 
-# Live-package tuning: capped concurrency (via the group), a slow-timeout for
-# validator startup, and retries to absorb RPC-timing flakiness. Scoped to the
-# live packages so production unit tests keep retries = 0 and no slow-timeout.
+# Live-package tuning: capped concurrency (via the group) and a slow-timeout for
+# validator startup. Scoped to the live packages so production unit tests keep
+# no slow-timeout. Retries are 0 everywhere: a flaky live test is a signal to
+# fix, not to absorb.
 [[profile.default.overrides]]
 filter = 'package(e2e) | package(clientless)'
 test-group = "live-validators"
 slow-timeout = { period = "60s", terminate-after = "10" }
-retries = 2
+retries = 0
 
 # The canonical test-target inventory consumed by the update/validate-test-targets
 # scripts via `cargo nextest list` -- NOT the CI test run (that is `default`).

.env.testing-artifacts

@@ -5,7 +5,7 @@
 # zcashd Git tag (https://github.com/zcash/zcash/releases)
 ZCASH_VERSION=6.20.0
 
-ZEBRA_VERSION=5.2.0
+ZEBRA_VERSION=6.0.0
 
 # zcash-devtool git ref (https://github.com/zingolabs/zcash-devtool) —
 # the wallet client driven by wallet-tests via zcash_local_net, built
@@ -14,4 +14,6 @@ ZEBRA_VERSION=5.2.0
 # (get-ci-image-tag.sh → resolve_devtool_rev), so a branch HEAD advancing
 # changes the tag automatically and the rebuild always bakes the current
 # binary — no manual SHA bump needed. Pin a tag here only to freeze it.
-DEVTOOL_VERSION=add_regtest
+# Pinned to the NU6.3/Ironwood support commit: tip of
+# `ironwood-valar-portables`, under review as zcash/zcash-devtool#208.
+DEVTOOL_VERSION=2efc8e9c690c6b4a844d6bb0a49bc66ba6fcbb14

.github/workflows/build-n-push-ci-image.yaml

@@ -49,10 +49,15 @@ jobs:
         source .env.testing-artifacts
         set +a
         RUST_VERSION=$(cargo run -q --manifest-path tools/workbench/Cargo.toml --bin get-rust-version)
+        # Resolve ZEBRA_VERSION (the Docker Hub tag) to the git ref the
+        # zebra-builder source stage checks out; fails the job here on an
+        # unresolvable value instead of mid-build.
+        ZEBRA_GIT_REF=$(cargo run -q --manifest-path tools/workbench/Cargo.toml --bin get-zebra-git-ref -- "$ZEBRA_VERSION")
         echo "sha_short=$(git rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
         echo "RUST_VERSION=$RUST_VERSION" >> "$GITHUB_ENV"
         echo "ZCASH_VERSION=$ZCASH_VERSION" >> "$GITHUB_ENV"
         echo "ZEBRA_VERSION=$ZEBRA_VERSION" >> "$GITHUB_ENV"
+        echo "ZEBRA_GIT_REF=$ZEBRA_GIT_REF" >> "$GITHUB_ENV"
         echo "DEVTOOL_VERSION=$DEVTOOL_VERSION" >> "$GITHUB_ENV"
 
     - name: Define build target
@@ -79,4 +84,5 @@ jobs:
           RUST_VERSION=${{ env.RUST_VERSION }}
           ZCASH_VERSION=${{ env.ZCASH_VERSION }}
           ZEBRA_VERSION=${{ env.ZEBRA_VERSION }}
+          ZEBRA_GIT_REF=${{ env.ZEBRA_GIT_REF }}
           DEVTOOL_VERSION=${{ env.DEVTOOL_VERSION }}

.github/workflows/publish-dry-run.yml

@@ -0,0 +1,105 @@
+name: Publish dry-run
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'rc/**'
+      - stable
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+jobs:
+  publish-dry-run:
+    name: cargo publish --dry-run
+    runs-on: ubuntu-latest
+    # Blocking context: direct pushes to rc/** or stable — the branch is in
+    # release-prep state and must publish cleanly.  Advisory context: everything
+    # else, including PRs that *target* rc/** or stable.  Those PRs carry
+    # unbumped dev code; version bumps happen on the RC branch after merge, so
+    # a publish failure at PR time is expected, not actionable.
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      # rust-toolchain.toml auto-installs the pinned toolchain on first cargo
+      # invocation, so no explicit toolchain setup step is needed.
+
+      - name: Compute check mode
+        id: mode
+        run: |
+          if [[ "${{ github.event_name }}" == "push" ]]; then
+            target="${{ github.ref_name }}"
+          else
+            # PRs (including those targeting rc/** or stable) are always
+            # advisory — they carry pre-bump code by design.
+            target=""
+          fi
+          if [[ "$target" == rc/* || "$target" == stable ]]; then
+            echo "mode=blocking" >> "$GITHUB_OUTPUT"
+          else
+            echo "mode=advisory" >> "$GITHUB_OUTPUT"
+          fi
+
+      # A publishable crate whose exact version is already on crates.io with
+      # different content cannot be released without a bump. Advisory mode
+      # warns (unbumped-but-changed is the normal bump-at-release state on
+      # feature branches); blocking mode fails. Also emits the `violations`
+      # output consumed by the dry-run step below.
+      - name: Check for version-reuse violations
+        id: version-check
+        run: |
+          cargo run --manifest-path tools/workbench/Cargo.toml \
+            --bin check-published-versions -- --mode "${{ steps.mode.outputs.mode }}"
+
+      # --workspace resolves sibling dependencies against a local overlay
+      # registry, so packaging succeeds even when members depend on
+      # unpublished sibling changes — emulating a real dependency-ordered
+      # release. A per-crate dry-run loop cannot do this: nothing is uploaded
+      # between iterations, so dependents resolve siblings from crates.io and
+      # any cross-crate change fails spuriously.
+      #
+      # The verify build is weaker than packaging: when a local crate reuses
+      # an already-published version number, the registry artifact shadows
+      # the overlay copy, so dependents verify-compile against the published
+      # content, not the tree's. While version-reuse violations exist
+      # (advisory contexts only — blocking contexts already failed above),
+      # verification is therefore meaningless and the dry-run degrades to
+      # packaging/resolution checks. Release prep bumps the versions, and the
+      # full verify then runs where this job gates.
+      - name: Dry-run publish (workspace overlay)
+        run: |
+          set -euo pipefail
+
+          verify_flag=""
+          if [[ "${{ steps.version-check.outputs.violations }}" == "true" ]]; then
+            verify_flag="--no-verify"
+            echo "Version-reuse violations present: packaged crates would verify-compile"
+            echo "against the already-published versions that shadow the workspace overlay."
+            echo "Running packaging and resolution checks only (--no-verify) until the"
+            echo "versions are bumped at release prep."
+            echo ""
+          fi
+
+          if ! cargo publish --workspace --dry-run $verify_flag 2>&1; then
+            echo ""
+            echo "============================================"
+            echo "cargo publish --workspace --dry-run FAILED"
+            echo "============================================"
+            echo ""
+            echo "The workspace does not publish cleanly as a set. Common causes:"
+            echo "  - a [patch.crates-io] override pulling in unreleased upstream"
+            echo "    code (published crates cannot depend on unpublished revisions)"
+            echo "  - a dependency on a git revision or path outside the workspace"
+            echo "  - a crate that does not compile from its packaged form"
+            echo "  - new cross-crate API or features that exist in the workspace but"
+            echo "    not in the published dependency; resolved by the version bump +"
+            echo "    publish of that dependency at the next release"
+            echo ""
+            if [[ "${{ steps.mode.outputs.mode }}" == "advisory" ]]; then
+              echo "::warning::publish dry-run failed — the workspace would not release cleanly. Advisory on this branch, but it must be resolved before the next release."
+              exit 0
+            fi
+            echo "::error::publish dry-run failed — the workspace would not release cleanly."
+            exit 1
+          fi

CHANGELOG.md

@@ -8,6 +8,46 @@ and this library adheres to Rust's notion of
 ## Unreleased
 
 ### Changed
+- `zaino-state`: `FetchService` and `StateService` are merged into a single
+  generic `NodeBackedIndexerService<Source>` (module
+  `zaino_state::indexer::node_backed_indexer`; the former `backends` module is
+  gone). The validator connection is now selected at runtime rather than by type:
+  `NodeBackedIndexerServiceConfig { common, connection }` carries a
+  `ValidatorConnectionType` of either `Rpc` (JSON-RPC, formerly `Fetch`) or
+  `Direct(DirectConnectionConfig)` (Zebra `ReadStateService`, formerly `State`).
+  The per-backend `Fetch/StateServiceConfig`, `Fetch/StateServiceError`, and
+  `BackendConfig` types are replaced by `NodeBackedIndexerServiceConfig`,
+  `NodeBackedIndexerServiceError`, and `ValidatorConnectionType`.
+- **Breaking** — config: `zainod.toml`'s `backend` selector is renamed
+  `state` → `direct` and `fetch` → `rpc`. The legacy `"state"` / `"fetch"`
+  values are still accepted as aliases, so existing config files keep working.
+- `zaino-state`: the `ChainIndex` trait is split into `ChainIndex` (the
+  wallet-essential core: chain/tx/address/mempool access) and a
+  `ChainIndexRpcExt: ChainIndex` extension (compact-block serving, subtree
+  roots, and the block-explorer / mining / node-passthrough RPCs). The split is
+  a provisional first pass to be refined into finer capability traits later.
+- `zaino-state`: all remaining backend-split RPC functionality has moved out of
+  the `FetchService` (`JsonRpSeeConnector`) and `StateService`
+  (`ReadStateService`) backends and into `BlockchainSource` /
+  `ChainIndex`. Both backends now resolve every fetch through their `ChainIndex`
+  indexer — building responses from Zaino's own indexed state where possible and
+  delegating to the `ValidatorConnector` (`BlockchainSource`) only for
+  validator-only or passthrough data. Validator connection/syncer spawning also
+  moves into `ValidatorConnector::spawn_fetch` / `spawn_state`, so each
+  service/subscriber now holds only `{ indexer, data, config }`. This readies
+  the two backends for their eventual merge into a single
+  `ValidatorBackedIndexerService`. No behaviour change.
+- TLS: zaino now installs rustls's **aws-lc-rs** CryptoProvider as its
+  preferred process-level default (was ring) and enables rustls's
+  `prefer-post-quantum` feature, so the X25519MLKEM768 hybrid key exchange
+  leads zaino's outbound handshakes (ADR-0006). Installation remains
+  first-install-wins: an embedder that installs a provider before zaino
+  keeps its choice.
+
+### Deprecated
+- Classical TLS key exchange (X25519, SECP256R1, SECP384R1) is deprecated:
+  still offered and accepted for wallet compatibility, slated for refusal
+  once major wallet stacks negotiate hybrid key exchange (ADR-0006).
 - **Breaking** — config: `storage.database.sync_write_batch_bytes` (bytes) is
   renamed to `sync_write_batch_size` and given in **GiB** (default raised from
   4 GiB to 32 GiB); this budget now also bounds the txout-set accumulator

CLAUDE.md

@@ -1,5 +1,15 @@
 # Zaino AI Contributor Guidelines
 
+## Tool selection
+
+Always prefer Rust-native tools in domains where they are designed to operate.
+Dependency and manifest changes go through `cargo add` / `cargo remove` /
+`cargo update`. Code navigation and refactors go through rust-analyzer (see
+the LSP section below). Verification goes through `cargo check` /
+`cargo clippy` / `cargo fmt` / `cargo nextest`. Do not reach for Python, sed,
+or regex sweeps over Rust source or `Cargo.toml` when a Rust tool covers the
+job.
+
 ## Visibility: minimum required scope
 
 All items (functions, methods, structs, enums, fields, modules) MUST use the

CONTEXT.md

@@ -0,0 +1,98 @@
+# Zaino
+
+Zaino is a Zcash indexing service. This glossary pins down the canonical
+terms for concepts where the team has picked one word among several.
+
+## Language
+
+### Release engineering
+
+**Publishable set**:
+The workspace members released to crates.io as a unit — every member not
+marked `publish = false`. Derived from workspace metadata, never from a
+hard-coded list.
+_Avoid_: crate list, publish list
+
+**Blocking context**:
+A CI context in which release checks must pass: pushes to `rc/**` or
+`stable`, and pull requests targeting them.
+_Avoid_: strict mode, release mode
+
+**Advisory context**:
+Any CI context that is not a blocking context. Release checks report
+findings (warnings, annotations) but do not fail the build there.
+_Avoid_: soft mode, informational mode
+
+**Version-reuse violation**:
+A publishable crate whose exact version already exists on crates.io while
+its packaged content differs. The tree cannot be released until that crate's
+version is bumped. An unchanged crate keeping its published version is not a
+violation.
+_Avoid_: stale version, forgotten bump
+
+### Chains and networks
+
+**The Public Testnet**:
+The public Zcash test network, and only that. Its regimes are
+non-hermetic — state is shared with other participants, and an epoch
+the public chain has left (e.g. pre-NU6.3 once NU6.3 activates there)
+cannot be re-entered. Always this exact phrase in prose; identifiers
+use `the_pub_testnet` and types use `PubTestnet`.
+_Avoid_: bare "Testnet"/"testnet", and especially "testnet" for any
+locally-launched chain, even one launched under a testnet network kind
+
+**Regtest net**:
+A hermetic, locally-launched chain whose activation heights the
+launcher chooses. Every hermetic local net is a regtest net, whatever
+network-kind flag it runs under.
+_Avoid_: local testnet, custom testnet
+
+### Pools and upgrades
+
+**Ironwood / Orchard (era naming)**:
+Eras, fixtures, and predicates that speak of shielded pools are named by
+pool — Orchard, Ironwood — and a name that mentions one pool pairs with
+the other pool's name, never with the upgrade's. **NU6.3** names only the
+network upgrade itself: activation heights, consensus branch ID,
+consensus rules.
+_Avoid_: mixing vocabularies in one name or one sibling set (e.g. an
+`ORCHARD_ONLY_*` fixture whose sibling is `NU6_3_ACTIVE_*` — the sibling
+is `IRONWOOD_ONLY_*`)
+
+**Cross-address restriction**:
+The post-NU6.3 rule the Orchard Action circuit enforces: "(g_d, pk_d)
+of the output note must equal (g_d, pk_d) of the spent note" — the
+output note must carry the same expanded receiver (diversified base
+g_d, diversified transmission key pk_d) as its spent note, so each
+Orchard action is either change to the spent note's own address or a
+withdrawal (positive value balance). Orchard-to-Orchard transfers to
+any other address — including another address of the same wallet — are
+prohibited. A companion transaction-level rule forbids new value
+entering the pool. Source:
+<https://zcash.github.io/ironwood/design/action-circuit.html#the-cross-address-restriction>
+_Avoid_: "exit-only" (overclaims — same-receiver change still lands in
+the pool and its commitment tree still grows)
+
+### TLS and cryptography
+
+**Preferred CryptoProvider**:
+The TLS cryptography provider zaino installs as the process-wide default
+when no provider is installed yet. A preference, not a mandate: an
+embedder (e.g. zallet) that installs a provider before zaino keeps its
+choice, and zaino handshakes through it.
+_Avoid_: "enforced provider" (implies zaino overrides an embedder's
+already-installed provider; it never does)
+
+**Hybrid key exchange**:
+A TLS 1.3 key-exchange group combining a classical curve with a
+post-quantum KEM (key-encapsulation mechanism), e.g. X25519MLKEM768.
+Secure if either component holds. Hybrids are the post-quantum
+deployment vehicle, not a classical fallback.
+_Avoid_: calling hybrids "classical" because they contain a classical
+component
+
+**Classical key exchange**:
+A key-exchange group with no post-quantum component (X25519, SECP256R1,
+SECP384R1). Deprecated in zaino: still accepted for client
+compatibility, slated for refusal once major wallet stacks negotiate
+hybrids.