chore(deps): upgrade Zcash stack for NU6.3

.env.example

@@ -21,9 +21,9 @@
 # Image pins. Defaults live in docker-compose.yml as ${VAR:-tag} fallbacks;
 # override per pin here to test a pre-release or pin a digest.
 # To opt into a moving tag such as zfnd/zebra:latest, see docs/faq.md.
-# Z3_ZEBRA_IMAGE=zfnd/zebra:6.0.0-rc.0
-# Z3_ZAINO_IMAGE=zingodevops/zainod:0.5.1-no-tls   # indexer profile (--profile indexer)
-# Z3_ZALLET_IMAGE=zodlinc/zallet:v0.1.0-alpha.4@sha256:3097751a2502857294d7031a360023834b53a6ebd31ed4520f6cd3a148074dbf
+# Z3_ZEBRA_IMAGE=zfnd/zebra:6.2.0
+# Z3_ZAINO_IMAGE=zingodevops/zainod:0.6.0-no-tls   # indexer profile (--profile indexer)
+# Z3_ZALLET_IMAGE=zodlinc/zallet:v0.1.0-beta.1@sha256:1849b4469875dc0165942c06d15fa6a7da76b2d43bade578cc8e5903a639869d
 # Z3_ZEBRA_BUILD_FEATURES=default-release-binaries
 
 # Platform pin. Zebra and Zallet are multi-arch and select the host arch

.github/workflows/ci.yaml

@@ -124,12 +124,14 @@ jobs:
     name: Regtest smoke test
     runs-on: ubuntu-latest
     needs: contract-validation
-    # External identifiers for the regtest stack. Keep aligned with
-    # z3-contract.yaml networks.regtest.{external_network,volumes.cookie}.
+    # Resource identifiers exercised by this smoke test. Keep the external
+    # identifiers aligned with z3-contract.yaml and the internal CA volume
+    # aligned with its explicit name in docker-compose.yml.
     # Values are literal constants, not user input — safe in run: blocks.
     env:
       COOKIE_VOLUME: z3-regtest-cookie
       EXTERNAL_NETWORK: z3-regtest
+      ZALLET_CA_CERTIFICATES_VOLUME: z3-regtest-zallet-ca-certificates
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
@@ -162,8 +164,8 @@ jobs:
             http://127.0.0.1:29232 | jq .
 
       - name: Mine the activation blocks
-        # config/regtest activates NU5 at height 2; mine two blocks so the
-        # network is past activation before wallet init.
+        # config/regtest activates NU5 through NU6.3 at height 2; mine two
+        # blocks so the network is past activation before wallet init.
         run: |
           curl -sf -u zebra:zebra -X POST -H "Content-Type: application/json" \
             -d '{"jsonrpc":"2.0","method":"generate","params":[2],"id":1}' \
@@ -196,6 +198,14 @@ jobs:
             --datadir /var/lib/zallet --config /etc/zallet/zallet.toml \
             generate-mnemonic
 
+      - name: Assert CA bundle is readable by Zallet's compose user
+        run: |
+          ZALLET_USER="$(docker compose --env-file .env.regtest config --format json \
+            | python3 -c 'import json, sys; print(json.load(sys.stdin)["services"]["zallet"]["user"])')"
+          docker run --rm --user "$ZALLET_USER" \
+            -v "$ZALLET_CA_CERTIFICATES_VOLUME":/etc/ssl/certs:ro alpine \
+            sh -c 'test -s /etc/ssl/certs/ca-certificates.crt && cat /etc/ssl/certs/ca-certificates.crt >/dev/null'
+
       - name: Start Zallet and rpc-router, verify wallet RPC
         run: |
           docker compose --env-file .env.regtest up -d zallet rpc-router

README.md

@@ -108,15 +108,12 @@ Default UI host ports are globally unique across the three networks (mainnet Gra
 
 ### Indexer
 
-The Zaino indexer ships behind a Compose profile. It adds a lightwalletd-compatible gRPC endpoint (mainnet `8137`) and a JSON-RPC proxy (mainnet `8237`) for explorers, faucets, and light-wallet backends. Zallet reaches Zebra directly, so the default stack does not need it.
+The Zaino indexer ships behind a Compose profile. It adds a lightwalletd-compatible gRPC endpoint (mainnet `8137`) and a JSON-RPC proxy (mainnet `8237`) for explorers, faucets, and light-wallet backends. Zallet reaches Zebra directly, so the default stack does not need it. Zebra and Zallet also use the word "indexer" for separate configuration and build surfaces; the [FAQ distinguishes their requirements](docs/faq.md#q-which-indexer-does-z3-use-and-does-zebra-need-the-indexer-build-feature).
 
 ```bash
 docker compose --env-file .env.<network> --profile indexer up -d
 ```
 
-> [!NOTE]
-> The pinned `zingodevops/zainod` release cannot parse Zebra `6.0.0-rc.0` RPC responses. Until upstream ships Ironwood support, run the indexer profile against a Zebra 5.2-era image by setting `Z3_ZEBRA_IMAGE=zfnd/zebra:5.2.0`.
-
 ### Stopping the stack
 
 ```bash
@@ -163,7 +160,7 @@ graph LR
 
 **Zebra** syncs and validates the Zcash blockchain. **Zallet** embeds Zaino's indexer libraries internally and connects directly to Zebra's JSON-RPC; it does not use the standalone Zaino service. The Zallet image also ships a zebra-state backend binary, but z3 runs the `zallet-zaino` binary. **Zaino** is optional, behind the `indexer` profile: it exposes a standalone lightwalletd-compatible gRPC interface for external light wallet clients.
 
-Image pins live as `${VAR:-tag}` defaults in `docker-compose.yml`; override any pin with `Z3_ZEBRA_IMAGE`, `Z3_ZAINO_IMAGE`, or `Z3_ZALLET_IMAGE`. Upstream sources: [Zebra](https://github.com/ZcashFoundation/zebra), [Zaino](https://github.com/zingolabs/zaino), [Zallet](https://github.com/zcash/wallet).
+Image pins live as `${VAR:-tag}` defaults in `docker-compose.yml`; override any pin with `Z3_ZEBRA_IMAGE`, `Z3_ZAINO_IMAGE`, or `Z3_ZALLET_IMAGE`. Upstream sources: [Zebra](https://github.com/ZcashFoundation/zebra), [Zaino](https://github.com/zingolabs/zaino), [Zallet](https://github.com/zcash/zallet).
 
 ### Service endpoints
 
@@ -317,8 +314,9 @@ z3 sets the service-internal vars (`ZEBRA_RPC__LISTEN_ADDR`, `ZAINO_VALIDATOR_SE
 Z3_ZEBRA_RUST_LOG=debug
 Z3_ZAINO_RUST_LOG=debug
 
-# Pin a different image version, or use zfnd/zebra:latest to track Zebra releases
-Z3_ZEBRA_IMAGE=zfnd/zebra:5.2.0
+# Override the tracked Zebra pin, for example to roll back to an earlier release
+Z3_ZEBRA_IMAGE=zfnd/zebra:6.1.0
+# To opt into the moving latest tag instead, follow docs/faq.md
 
 # Move chain state to an external SSD
 Z3_CHAIN_DATA_PATH=/mnt/ssd/zebra-state

config/mainnet/zallet.toml.example

@@ -22,7 +22,7 @@ network = "main"
 # External settings: defaults.
 
 [features]
-as_of_version = "0.1.0-alpha.4"
+as_of_version = "0.1.0-beta.1"
 
 [features.deprecated]
 

config/regtest/zallet.toml.example

@@ -4,28 +4,27 @@ orchard_actions = 250
 [consensus]
 network = "regtest"
 # NU activation heights must match Zebra's regtest config in
-# config/regtest/zebra.toml and Zaino's hardcoded ActivationHeights
-# (Canopy at 1, NU5 at 2, NU6 at 2, NU6.1 at 1000). Diverging in either
-# direction breaks the wallet's view of the chain. NU6.2 is intentionally
-# absent: zcash_protocol 0.7.2 (this Zallet's dep) has no NU6.2 branch id,
-# so a "5437f330:..." entry would fail to parse ("Unknown consensus branch ID").
+# config/regtest/zebra.toml. Zaino adopts the same schedule from Zebra at
+# runtime, and Zallet uses this list to interpret the chain.
 regtest_nuparams = [
     "5ba81b19:1",      # Overwinter
     "76b809bb:1",      # Sapling
     "2bb40e60:1",      # Blossom
     "f5b9230b:1",      # Heartwood
     "e9ff75a6:1",      # Canopy
-    "c2d6d0b4:2",      # NU5 (Orchard); matches Zaino's hardcoded expectation
-    "c8e71055:2",      # NU6; matches Zaino's hardcoded NU6=2 and Zebra's NU6=2
-    "4dec4df0:1000",   # NU6.1; matches Zaino's hardcoded NU6.1=1000
+    "c2d6d0b4:2",      # NU5 (Orchard)
+    "c8e71055:2",      # NU6
+    "4dec4df0:2",      # NU6.1
+    "5437f330:2",      # NU6.2
+    "37a5165b:2",      # NU6.3 (Ironwood)
 ]
 
 [database]
 
 [external]
 
 [features]
-as_of_version = "0.1.0-alpha.4"
+as_of_version = "0.1.0-beta.1"
 
 [features.deprecated]
 

config/regtest/zebra.toml.example

@@ -1,11 +1,10 @@
 # Zebra regtest configuration. `scripts/setup-network.sh regtest` copies this
 # template into a live gitignored config file on first run.
 #
-# Zebra's default regtest stops at Canopy. Activating NU5, NU6, and NU6.1
-# here matches Zaino's hardcoded regtest ActivationHeights
-# (ZEBRAD_DEFAULT_ACTIVATION_HEIGHTS: NU5=2, NU6=2, NU6.1=1000) so its sync
-# loop can read the chain Zebra produces. zebrad reads ~/.config/zebrad.toml
-# automatically. NU6.1 must be 1000 (not 2) to match Zaino's chain view.
+# Zebra's default regtest stops at Canopy. This schedule activates every
+# supported upgrade through NU6.3 at height 2, matching the Zallet
+# configuration. Zaino discovers the schedule from Zebra at runtime. zebrad
+# reads ~/.config/zebrad.toml automatically.
 
 [network]
 network = "Regtest"
@@ -19,4 +18,6 @@ Heartwood = 1
 Canopy = 1
 NU5 = 2
 NU6 = 2
-"NU6.1" = 1000
+"NU6.1" = 2
+"NU6.2" = 2
+"NU6.3" = 2

config/testnet/zallet.toml.example

@@ -22,7 +22,7 @@ network = "test"
 # External settings: defaults.
 
 [features]
-as_of_version = "0.1.0-alpha.4"
+as_of_version = "0.1.0-beta.1"
 
 [features.deprecated]
 

docker-compose.regtest.yml

@@ -16,8 +16,8 @@ services:
     # is a parse error).
     environment:
       ZEBRA_MINING__MINER_ADDRESS: ${ZEBRA_MINING__MINER_ADDRESS:?must be set in .env.regtest or shell environment}
-    # Zebra's default regtest stops at Canopy; this config activates NU5/NU6
-    # at the heights Zaino's regtest defaults expect. zebrad reads
+    # Zebra's default regtest stops at Canopy; this config activates every
+    # supported upgrade through NU6.3 at height 2. zebrad reads
     # ~/.config/zebrad.toml automatically.
     volumes:
       - ${Z3_CONFIG_DIR:-./config/regtest}/zebra.toml:/home/zebra/.config/zebrad.toml:ro
@@ -53,6 +53,7 @@ services:
     # /var/run dirs at runtime).
     volumes: !override
       - ${Z3_ZALLET_DATA_PATH:-zallet}:/var/lib/zallet
+      - zallet_ca_certificates:/etc/ssl/certs:ro
       - ${Z3_CONFIG_DIR:-./config/regtest}/zallet.toml:/etc/zallet/zallet.toml:ro
 
   rpc-router:

docker-compose.yml

@@ -30,7 +30,7 @@ x-common: &common
 
 services:
   zebra:
-    image: ${Z3_ZEBRA_IMAGE:-zfnd/zebra:6.0.0-rc.0}
+    image: ${Z3_ZEBRA_IMAGE:-zfnd/zebra:6.2.0}
     # Zebra is multi-arch; Docker selects the host's native variant.
     # DOCKER_PLATFORM forces a specific arch for cross-architecture testing.
     platform: ${DOCKER_PLATFORM:-}
@@ -78,7 +78,8 @@ services:
       start_period: 90s
       start_interval: 5s
 
-  # Sidecar: makes Zebra's RPC cookie readable inside the shared auth volume.
+  # Sidecar: makes Zebra's RPC cookie readable inside the shared auth volume
+  # and supplies the CA bundle omitted from Zallet's distroless beta image.
   # Zebra writes /var/run/auth/.cookie with mode 0600 owned by uid 10001;
   # Zaino, Zallet, and attached services may run as different users.
   cookie-permissions:
@@ -91,10 +92,12 @@ services:
       ZEBRA_RPC__ENABLE_COOKIE_AUTH: ${ZEBRA_RPC__ENABLE_COOKIE_AUTH:-true}
     volumes:
       - ${Z3_COOKIE_PATH:-cookie}:/var/run/auth
+      - zallet_ca_certificates:/var/run/zallet-ca
     command:
       - sh
       - -c
       - |
+        cp /etc/ssl/certs/ca-certificates.crt /var/run/zallet-ca/ca-certificates.crt
         while true; do
           if [ -f /var/run/auth/.cookie ]; then
             chmod 0644 /var/run/auth/.cookie 2>/dev/null
@@ -105,21 +108,19 @@ services:
       zebra:
         condition: service_started
     healthcheck:
-      test: ["CMD-SHELL", "if [ \"$${ZEBRA_RPC__ENABLE_COOKIE_AUTH:-true}\" = \"false\" ]; then exit 0; fi; test -r /var/run/auth/.cookie"]
+      test: ["CMD-SHELL", "test -s /var/run/zallet-ca/ca-certificates.crt && { [ \"$${ZEBRA_RPC__ENABLE_COOKIE_AUTH:-true}\" = \"false\" ] || test -r /var/run/auth/.cookie; }"]
       interval: 5s
       timeout: 2s
       retries: 12
       start_period: 5s
 
   zaino:
-    # Opt-in via --profile indexer. The pinned zainod parses only a Zebra
-    # 5.2-era RPC surface; override Z3_ZEBRA_IMAGE to a 5.2 Zebra until upstream
-    # adds Ironwood support for Zebra 6.
+    # Opt-in via --profile indexer. Zaino 0.6 supports Zebra 6 and NU6.3.
     profiles: [indexer]
     # The -no-tls tag compiles out Zaino's "TLS required on a non-private bind"
     # guard, so intra-container gRPC on 0.0.0.0:8137 runs as plaintext h2c.
     # Terminate edge TLS at a reverse proxy if Zaino is exposed beyond the host.
-    image: ${Z3_ZAINO_IMAGE:-zingodevops/zainod:0.5.1-no-tls}
+    image: ${Z3_ZAINO_IMAGE:-zingodevops/zainod:0.6.0-no-tls}
     # Zaino publishes linux/amd64 only; arm64 hosts run under emulation unless
     # the operator builds from source (see docker-compose.build.yml).
     platform: ${DOCKER_PLATFORM:-linux/amd64}
@@ -166,9 +167,9 @@ services:
       start_interval: 5s
 
   zallet:
-    # Pinned by digest: upstream re-points the v0.1.0-alpha.4 tag at new builds,
-    # and a silently swapped build can reject the existing wallet database.
-    image: ${Z3_ZALLET_IMAGE:-zodlinc/zallet:v0.1.0-alpha.4@sha256:3097751a2502857294d7031a360023834b53a6ebd31ed4520f6cd3a148074dbf}
+    # Pinned by digest: the beta.1 release image was rebuilt after tagging to
+    # correct its multi-architecture binary packaging.
+    image: ${Z3_ZALLET_IMAGE:-zodlinc/zallet:v0.1.0-beta.1@sha256:1849b4469875dc0165942c06d15fa6a7da76b2d43bade578cc8e5903a639869d}
     # The image is multi-arch and ships multiple binaries; z3 uses the
     # Zaino-backed wallet binary. Docker selects the host's native variant.
     # DOCKER_PLATFORM forces a specific arch for cross-architecture testing.
@@ -189,6 +190,8 @@ services:
     volumes:
       - ${Z3_ZALLET_DATA_PATH:-zallet}:/var/lib/zallet
       - ${Z3_COOKIE_PATH:-cookie}:/var/run/auth:ro
+      # Temporary runtime supply until the upstream image includes this file.
+      - zallet_ca_certificates:/etc/ssl/certs:ro
       - ${Z3_CONFIG_DIR:-./config/mainnet}/zallet.toml:/etc/zallet/zallet.toml:ro
     ports:
       - "${Z3_ZALLET_HOST_RPC_PORT:-28232}:28232"
@@ -307,6 +310,9 @@ volumes:
     name: ${COMPOSE_PROJECT_NAME:-z3-mainnet}-zaino
   zallet:
     name: ${COMPOSE_PROJECT_NAME:-z3-mainnet}-zallet
+  # Internal runtime data, not part of the consumer-facing volume contract.
+  zallet_ca_certificates:
+    name: ${COMPOSE_PROJECT_NAME:-z3-mainnet}-zallet-ca-certificates
   prometheus_data:
   grafana_data:
   alertmanager_data:

docs/docker-architecture.md

@@ -28,7 +28,7 @@ The core principle: **`docker-compose.yml` is self-sufficient for mainnet**. Eve
 Every variable reference in `docker-compose.yml` includes a default value:
 
 ```yaml
-image: ${Z3_ZEBRA_IMAGE:-zfnd/zebra:6.0.0-rc.0}
+image: ${Z3_ZEBRA_IMAGE:-zfnd/zebra:6.2.0}
 environment:
   ZEBRA_NETWORK__NETWORK: ${Z3_NETWORK:-Mainnet}
 volumes:

docs/faq.md

@@ -120,6 +120,37 @@ The same override pattern works for other services through `Z3_ZAINO_IMAGE` and
 
 ---
 
+### Q: Which "indexer" does Z3 use, and does Zebra need the `indexer` build feature?
+
+The default Z3 stack does not require Zebra's `indexer` build feature or its indexer gRPC listener. Z3 runs the `zallet-zaino` wallet backend, which reads Zebra through its regular JSON-RPC endpoint, while the optional `indexer` Compose profile starts the standalone Zaino service.
+
+Several settings use the same word for different capabilities:
+
+| Name | What it does | Changes Zebra's stored state? | Required by default Z3? |
+|------|--------------|:-----------------------------:|:-----------------------:|
+| Compose `--profile indexer` | Starts the standalone Zaino service for lightwalletd-compatible clients | No | No |
+| Zallet's `[indexer]` section | Configures how Z3's `zallet-zaino` process reaches Zebra over JSON-RPC | No | Yes |
+| Zebra's `rpc.indexer_listen_addr` | Starts the `zebra.indexer.rpc.Indexer` gRPC listener in Zebra 6.2 | No | No |
+| Zebra's Cargo `indexer` feature | Adds persistent indexes that map spent outpoints and revealed nullifiers to spending transactions | Yes | No |
+
+The gRPC listener reads Zebra's existing blocks and streams chain-tip, non-finalized-state, and mempool changes. You can enable it on a state directory or restored snapshot that Zebra previously opened without the listener; it does not change the database format, add column families, or backfill data. Set the listener in the operator-local `.env`:
+
+```dotenv
+ZEBRA_RPC__INDEXER_LISTEN_ADDR=0.0.0.0:8155
+```
+
+Then recreate Zebra:
+
+```bash
+docker compose --env-file .env.<network> up -d zebra
+```
+
+Containers attached to the Z3 network can then connect to `zebra:8155`. Z3 does not publish this unauthenticated, plaintext endpoint to the host; add an operator-local Compose port mapping only when a host-side client needs it, and do not expose it to an untrusted network.
+
+The alternative direct-state Zallet backend is different. It shares Zebra's state directory, follows the non-finalized tip over the gRPC listener, and requires a Zebra binary built with the Cargo `indexer` feature. Enabling that build feature against an existing database checks and backfills its persistent spending indexes, so it can make the next startup expensive. Z3 deliberately uses `zallet-zaino` instead, which needs neither the shared state directory nor those additional Zebra indexes.
+
+---
+
 ## For developers and testers
 
 ### Q: How do per-network compose overrides work?

docs/integrations/lightwalletd-client.md

@@ -4,9 +4,6 @@ Your service is a wallet, block explorer, or scanner that speaks the lightwallet
 
 Zaino ships behind the `indexer` Compose profile, so every Z3 command in this guide must include `--profile indexer`. The default Z3 stack does not start Zaino.
 
-> [!NOTE]
-> The pinned `zingodevops/zainod` release cannot parse Zebra `6.0.0-rc.0` RPC responses. Until upstream ships Ironwood support, run the indexer profile against a Zebra 5.2-era image by setting `Z3_ZEBRA_IMAGE=zfnd/zebra:5.2.0` before bringing the stack up.
-
 ## Prerequisites
 
 - A running Z3 stack with the indexer profile: `docker compose --env-file .env.<network> --profile indexer up -d` in the Z3 repo.

docs/regtest.md

@@ -22,8 +22,8 @@ This will:
 1. Copy the per-network config templates (`zebra.toml`, `zaino.toml`, `zallet.toml`) into live gitignored files
 2. Generate the Zallet encryption identity in-container into the data volume (if not already present)
 3. Generate and inject the Zallet RPC password hash in `config/regtest/zallet.toml`
-4. Start Zebra in regtest mode with the activation heights in `config/regtest` (Canopy at 1, NU5/Orchard at 2)
-5. Mine 2 blocks to activate Orchard
+4. Start Zebra in regtest mode with the activation heights in `config/regtest` (Canopy at 1, NU5 through NU6.3 at 2)
+5. Mine 2 blocks to activate Ironwood
 6. Initialize the Zallet wallet (`init-wallet-encryption` + `generate-mnemonic`)
 
 Optionally override the rpc-router password (default is `zebra`). The `REGTEST_` infix marks the var as regtest-scoped:
@@ -81,9 +81,6 @@ Zaino ships behind the `indexer` profile, so start it explicitly:
 docker compose --env-file .env.regtest --profile indexer up -d zaino
 ```
 
-> [!NOTE]
-> The pinned `zingodevops/zainod` release cannot parse Zebra `6.0.0-rc.0` RPC responses. Until upstream ships Ironwood support, run the indexer profile against a Zebra 5.2-era image by setting `Z3_ZEBRA_IMAGE=zfnd/zebra:5.2.0` before bringing the stack up.
-
 Zaino exposes the [lightwalletd-compatible gRPC protocol](https://github.com/zcash/lightwalletd/blob/master/walletrpc/service.proto) as plaintext h2c (no TLS). In regtest the host port is `28137` (`Z3_ZAINO_HOST_GRPC_PORT`); the `-plaintext` flag tells grpcurl to skip TLS.
 
 Fetch the Zaino proto files if you haven't already:
@@ -158,7 +155,7 @@ Regtest monitoring UI ports are Grafana `23000`, Prometheus `29094`, Jaeger UI `
 ## Notes
 
 - Credentials: `zebra` / `zebra` (hardcoded for regtest only)
-- Regtest activates upgrades through Canopy at block 1 and NU5/Orchard at block 2 (Zebra, Zaino, and Zallet all agree)
+- Regtest activates upgrades through Canopy at block 1 and NU5 through NU6.3 at block 2 (Zebra, Zaino, and Zallet all agree)
 - Zaino uses username/password auth in regtest (not cookie auth)
 - Zaino gRPC is plaintext h2c on all networks; terminate edge TLS at a reverse proxy if exposed beyond the host
 - The rpc-router source is in `rpc-router/`; it is built automatically on first `docker compose up`

scripts/regtest-init.sh

@@ -171,7 +171,7 @@ until curl -sf -X POST \
 done
 echo "   Zebra is ready."
 
-echo "==> Mining 2 blocks (config/regtest activates NU5/Orchard at height 2; zebra.toml and zallet.toml agree)..."
+echo "==> Mining 2 blocks (config/regtest activates NU5 through NU6.3 at height 2; Zebra and Zallet agree)..."
 curl -s -u zebra:zebra \
     -X POST -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"generate","params":[2],"id":1}' \