feat(config): migrate wallet to use a layered configuration by gustavovalverde · Pull Request #194 · zcash/wallet

gustavovalverde · 2025-08-12T17:56:59Z

Motivation

This pull request migrates Zallet's configuration system from Abscissa to config-rs, to unify the configuration approach across the Z3 stack (Zebra, Zaino, and Zallet).

This work follows the same pattern used in Zebra's configuration migration (Zebra PR #9768) and Zaino's migration (Zaino PR #469).

Solution

The new implementation uses config-rs to load configuration from three sources in order of precedence:

Hard-coded defaults (lowest precedence)
Optional zallet.toml configuration file
Environment variables with ZALLET_ prefix (highest precedence)

Key technical improvements:

Native error handling: Uses config::ConfigError directly, providing structured error information with file paths, keys, and type mismatches
Nested environment variables: Supports ZALLET_SECTION__KEY format for complex configuration structures
Array parsing: Comma-separated lists for arrays (e.g., ZALLET_RPC__BIND=127.0.0.1:8080,127.0.0.1:8081)

The Abscissa Configurable trait is retained for application lifecycle integration, CLI argument injection (like --datadir), and command-specific configuration overrides, but no longer handles configuration file loading.

Implementation Details

Added #[serde(default)] to all nested configuration sections to ensure partial configurations work correctly
Configuration loading logic moved to config.rs for better organization
Error conversion from config::ConfigError to FrameworkError happens only in process_config()
CLI arguments like --datadir and --config are properly integrated with the configuration system

Tests

A test suite has been added at wallet/zallet/tests/config.rs covering:

Default value loading and TOML file parsing
Environment variable overrides with nested structures
Configuration source precedence (env > file > defaults)
Error handling for invalid TOML, missing files, and type mismatches
Array parsing from environment variables (both comma-separated and JSON formats)

Specifications & References

config-rs crate documentation

y4ssi · 2025-08-12T18:14:34Z

LGTM, this is essential for the whole containerization process.

str4d

I am currently on PTO, but I want to ensure this is blocked on my review.

y4ssi · 2025-08-18T18:51:58Z

zallet/src/config.rs


+/// Returns true if a leaf key name should be considered sensitive and blocked
+/// from environment variable overrides.
+fn is_sensitive_leaf_key(leaf_key: &str) -> bool {


zingolabs/zaino@c6cdd75#diff-23720bc613c70ed45d6168fe2dfb63436e0ff76ce7342023c664d33f38a5180fR25

str4d

Reviewed ca41f6e.

Please squash all undos into the first commit.

zallet/Cargo.toml

str4d · 2025-08-20T11:40:00Z

zallet/src/config.rs

 }

+/// Zallet Configuration Filename
+pub const CONFIG_FILE: &str = "zallet.toml";


We place constants at the top of a file (between the imports, and functions/structs/etc), so that we don't lose track of them. Move this to the equivalent location of where it was in zallet/src/commands.rs.

EDIT: after my review comment that EntryPoint::config_path should be un-deleted, this move should instead be undone.

Addressed in c30ceed (#194)

zallet/src/config.rs

str4d · 2025-08-20T13:22:57Z

Cargo.toml

 rust-embed = "8"

 # Parsing and serialization
+config = { version = "0.15.13", features = ["toml", "json"] }


Missing cargo vet audit.

Addressed in ef32182 (#194)

zallet/tests/config.rs

str4d · 2025-08-20T13:34:15Z

zallet/src/config.rs

+        // Add filtered environment variables (highest precedence)
+        builder = builder.add_source(


In the group chat, we discussed only supporting env-var setting in Docker images specifically. If we take that approach, this would be where we configure it:

Suggested change

// Add filtered environment variables (highest precedence)

builder = builder.add_source(

// Add filtered environment variables (highest precedence)

#[cfg(zallet_docker_image)]

builder = builder.add_source(

In Zebra we're removing this feature gates that were specific to Docker (unrelated to config) because it requires us to build a specific image just for the sake of testing and confirming that feature is behaving as expected. It also requires to publish an image just with this feature enabled so it's easier for users.

What would be the benefit here? I'm not completely sure what we're trying to avoid. From my perspective—not adding the feature gate—would allow a consistent way to configure Zallet (containerized or not).

We shouldn’t have different releases, since by avoiding the definition of sensitive parameters as environment variables, I believe there’s no longer a need to maintain two releases

This commit replaces the Abscissa-based configuration system in Zallet with the `config-rs` crate, providing a standard layered configuration approach that unifies the Z3 stack configuration strategy across Zebra, Zaino, and Zallet This change introduces a clear precedence for configuration sources: 1. Hard-coded defaults (lowest precedence) 2. Optional `zallet.toml` configuration file 3. Environment variables with `ZALLET_` prefix (highest precedence) The Abscissa `Configurable` trait remains for application lifecycle integration, CLI argument injection, and command-specific configuration overrides.

- Add is_sensitive_leaf_key() to filter ZALLET_* env vars by leaf key (case-insensitive) - Block env overrides ending with: password, secret, token, cookie, private_key - Pre-filter env vars before passing to config::Environment via .source(Some(filtered_env)) - Preserve existing prefix/separator logic and list parsing for rpc.bind - Keep non-sensitive fields overridable (validator_address, validator_cookie_path, etc.) Aligns with Zebra and Zaino security model for Z3 stack consistency.

Co-authored-by: Jack Grigg <thestr4d@gmail.com>

- Move CONFIG_FILE constant from config.rs to commands.rs - Import functions directly in config.rs instead of using fully qualified paths - Move resolve_config_path method from ZalletConfig to EntryPoint::config_path - Position config_path method after datadir method as requested - Fix test compilation errors with mutable env variables as some tests failed because env variables needed mut to call env.set_var()

- Trust Ed Page for config crate dependency (already trusted by major orgs)

Update ZalletConfig documentation to explain layered configuration approach: - Document Option<T> field usage for default vs explicit value distinction - Explain serde(default) section header UX balance - Clarify config generation vs parsing behavior differences

…ntly ignoring Replace silent ignoring of sensitive environment variables with explicit errors to prevent: - Silent misconfigurations where users think secrets are configured but aren't - Process table exposure of sensitive values even when ignored

gustavovalverde · 2025-08-21T18:40:04Z

Please squash all undos into the first commit.

Once we're done I'll squash. In the meanwhile I'll keep them separate for clarity

gustavovalverde · 2025-08-26T13:02:31Z

I've fixed the merge conflicts. Let me know how'd like to proceed @str4d

y4ssi mentioned this pull request Aug 12, 2025

feat(docker): Multistage Dockerfile with dynamic conf generation #146

Closed

y4ssi added the A-packaging Area: Packaging label Aug 12, 2025

str4d requested changes Aug 12, 2025

View reviewed changes

y4ssi reviewed Aug 18, 2025

View reviewed changes

str4d requested changes Aug 20, 2025

View reviewed changes

gustavovalverde and others added 5 commits August 21, 2025 17:17

chore: apply suggestions from code review

8be9de3

Co-authored-by: Jack Grigg <thestr4d@gmail.com>

chore: apply suggestions from code review

9421288

Co-authored-by: Jack Grigg <thestr4d@gmail.com>

gustavovalverde force-pushed the feat-layered-config branch from c1f983a to c30ceed Compare August 21, 2025 16:42

gustavovalverde added 4 commits August 21, 2025 17:50

chore: reduce diff

2c07816

fix(supply-chain): resolve cargo vet audit issues

ef32182

- Trust Ed Page for config crate dependency (already trusted by major orgs)

gustavovalverde requested a review from str4d August 21, 2025 18:59

gustavovalverde added 3 commits August 26, 2025 12:10

chore: update config-rs to latest version

ea388cb

Merge branch 'main' into feat-layered-config

f27f49d

fix: merge conflict

d42b12f

gustavovalverde mentioned this pull request Aug 26, 2025

feat(config)!: migrate zebrad to use a layered configuration ZcashFoundation/zebra#9768

Merged

3 tasks

pacu moved this to In review in Zallet Contributor's Board Oct 30, 2025

pacu added this to Zallet Contributor's Board Oct 30, 2025

		// Add filtered environment variables (highest precedence)
		builder = builder.add_source(

Conversation

gustavovalverde commented Aug 12, 2025

Motivation

Solution

Implementation Details

Tests

Specifications & References

Uh oh!

y4ssi commented Aug 12, 2025

Uh oh!

str4d left a comment

Choose a reason for hiding this comment

Uh oh!

y4ssi Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

str4d left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

str4d Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

gustavovalverde Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

str4d Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

gustavovalverde Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

str4d Aug 20, 2025

Choose a reason for hiding this comment

Uh oh!

gustavovalverde Aug 21, 2025

Choose a reason for hiding this comment

Uh oh!

y4ssi Aug 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gustavovalverde commented Aug 21, 2025

Uh oh!

gustavovalverde commented Aug 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

y4ssi Aug 21, 2025 •

edited

Loading