Configuration reference

Zallet reads its configuration from zallet.toml in the datadir (override the file with -c/--config, and the datadir with -d/--datadir; see Wallet setup).

The reference below is the output of zallet example-config: every available option with its documentation, generated directly from the source code and checked in CI, so it always matches the release it ships with. Options are commented out where they show a default value.

# Default configuration for Zallet.
#
# This file is generated as an example using Zallet's current defaults. It can
# be used as a skeleton for custom configs.
#
# Fields that are required to be set are uncommented, and set to an example
# value. Every other field is commented out, and set to the current default
# value that Zallet will use for it (or `UNSET` if the field has no default).
#
# Leaving a field commented out means that Zallet will always use the latest
# default value, even if it changes in future. Uncommenting a field but keeping
# it set to the current default value means that Zallet will treat it as a
# user-configured value going forward.

# The chain backend this wallet installation uses.
#
# The `zallet` launcher reads this key to decide which backend binary to run:
# the name `foo` dispatches to the `zallet-foo` binary found next to the
# launcher (or on the PATH). Each backend binary refuses to run against a config
# that names a backend other than the one it provides, since all backends
# operate on the same wallet database. The backends shipped with Zallet are
# `"zebra"` (the launcher's default when this key is unset) and
# `"zaino"`.
#
# When this key is unset, a directly-invoked backend binary accepts the config:
# choosing the binary is already an explicit choice of backend.
#backend = "zebra"


#
# Settings that affect transactions created by Zallet.
#
[builder]

# Whether to spend unconfirmed transparent change when sending transactions.
#
# Does not affect unconfirmed shielded change, which cannot be spent.
#spend_zeroconf_change = true

# The number of confirmations required for a trusted transaction output (TXO) to
# become spendable.
#
# A trusted TXO is a TXO received from a party where the wallet trusts that it will
# remain mined in its original transaction, such as change outputs created by the
# wallet's internal TXO handling.
#
# This setting is a trade-off between latency and reliability: a smaller value makes
# trusted TXOs spendable more quickly, but the spending transaction has a higher
# risk of failure if a chain reorg occurs that unmines the receiving transaction.
#trusted_confirmations = 3

# The number of blocks after which a transaction created by Zallet that has not been
# mined will become invalid.
#
# - Minimum: `TX_EXPIRING_SOON_THRESHOLD + 1`
#tx_expiry_delta = 40

# The number of confirmations required for an untrusted transaction output (TXO) to
# become spendable.
#
# An untrusted TXO is a TXO received by the wallet that is not trusted (in the sense
# used by the `trusted_confirmations` setting).
#
# This setting is a trade-off between latency and security: a smaller value makes
# trusted TXOs spendable more quickly, but the spending transaction has a higher
# risk of failure if the sender of the receiving transaction is malicious and
# double-spends the funds.
#
# Values smaller than `trusted_confirmations` are ignored.
#untrusted_confirmations = 10


#
# Configurable limits on transaction builder operation (to prevent e.g. memory
# exhaustion).
#
[builder.limits]

# The maximum number of Orchard actions permitted in a constructed transaction.
#orchard_actions = 50


#
# Zallet's understanding of the consensus rules.
#
# The configuration in this section MUST match the configuration of the full node being
# used as a data source in the `validator_address` field of the `[indexer]` section.
#
[consensus]

# Network type.
network = "main"

# The parameters for regtest mode.
#
# Ignored if `network` is not `NetworkType::Regtest`.
#regtest_nuparams = []


#
# Settings for how Zallet stores wallet data.
#
[database]

# Path to the wallet database file.
#
# This can be either an absolute path, or a path relative to the data directory.
# Note that on Windows, you must either use single quotes for this field's value, or
# replace all backslashes `/` with forward slashes `/`.
#wallet = "wallet.db"


#
# Settings controlling how Zallet interacts with the outside world.
#
[external]

# Whether the wallet should broadcast transactions.
#broadcast = true

# Directory to be used when exporting data.
#
# This must be an absolute path; relative paths are not resolved within the datadir.
# Note that on Windows, you must either use single quotes for this field's value, or
# replace all backslashes `/` with forward slashes `/`.
#export_dir = UNSET

# Executes the specified command when a wallet transaction changes.
#
# A wallet transaction "change" can be anything that alters how the transaction
# affects the wallet's balance. Examples include (but are not limited to):
# - A new transaction is created by the wallet.
# - A wallet transaction is added to the mempool.
# - A block containing a wallet transaction is mined or unmined.
# - A wallet transaction is removed from the mempool due to conflicts.
#
# `%s` in the command is replaced by the hex encoding of the transaction ID.
#notify = UNSET


#
# Settings for Zallet features.
#
# Zallet's behaviour evolves over time: new functionality starts out as an
# experimental feature that must be explicitly enabled, and functionality on its way
# out becomes a deprecated feature that must be explicitly re-enabled. This section
# records the non-default choices this wallet has made, along with the Zallet version
# they were made against (`as_of_version`), which enables Zallet to detect when a
# feature named in this config has changed state across an upgrade, rather than
# silently changing the wallet's behaviour.
#
# The lifecycle of a feature:
#
# 1. New unstable functionality is added behind a flag in `[features.experimental]`.
# Setting the flag opts this wallet in; experimental features may change
# incompatibly or be removed without a deprecation cycle.
# 2. If the feature is stabilised, its behaviour becomes the default and the flag is
# retired. A config that still sets the flag is out of date.
# 3. If existing functionality is deprecated, it becomes disabled by default and
# gains a flag in `[features.deprecated]` that temporarily re-enables it, giving
# you time to migrate away.
# 4. When a deprecated feature is removed, its flag is retired; re-enabling is no
# longer possible.
#
# Retired flags left in this config are how Zallet knows to alert you (instead of
# wallet behaviour just changing out from under you), so do not remove a flag from
# this section until you have acted on the corresponding change.
#
[features]

# The most recent Zallet version for which this configuration file has been updated.
#
# This is used by Zallet to detect any changes to experimental or deprecated
# features. If this version is not compatible with `zallet --version`, most Zallet
# commands will error and print out information about how to upgrade your wallet,
# along with any changes you need to make to your usage of Zallet.
as_of_version = "0.1.0-beta.1"

# Enable "legacy `zcashd` pool of funds" semantics for the given seed.
#
# The seed fingerprint should correspond to the mnemonic phrase of a `zcashd` wallet
# imported into this Zallet wallet.
#
# # Background
#
# `zcashd` had two kinds of legacy balance semantics:
# - The transparent JSON-RPC methods inherited from Bitcoin Core treated all
#   spendable funds in the wallet as being part of a single pool of funds. RPCs like
#   `sendmany` didn't allow the caller to specify which transparent addresses to
#   spend funds from, and RPCs like `getbalance` similarly computed a balance across
#   all transparent addresses returned from `getaddress`.
# - The early shielded JSON-RPC methods added for Sprout treated every address as a
#   separate pool of funds, because for Sprout there was a 1:1 relationship between
#   addresses and spend authority. RPCs like `z_sendmany` only spent funds that were
#   sent to the specified addressed, and RPCs like `z_getbalance` similarly computed
#   a separate balance for each address (which became complex and unintuitive with
#   the introduction of Sapling diversified addresses).
#
# With the advent of Unified Addresses and HD-derived spending keys, `zcashd` gained
# its modern balance semantics: each full viewing key in the wallet is a separate
# pool of funds, and treated as a separate "account". These are the semantics used
# throughout Zallet, and that should be used by everyone going forward. They are
# also incompatible with various legacy JSON-RPC methods that were deprecated in
# `zcashd`, as well as some fields of general RPC methods; these methods and fields
# are unavailable in Zallet by default.
#
# However, given that `zcashd` wallets can be imported into Zallet, and in order to
# ease the transition between them, this setting turns on legacy balance semantics
# in Zallet:
# - JSON-RPC methods that only work with legacy semantics become available for use.
# - Fields in responses that are calculated using legacy semantics are included.
#
# Due to how the legacy transparent semantics in particular were defined by Bitcoin
# Core, this can only be done for a single `zcashd` wallet at a time. Given that
# every `zcashd` wallet in production in 2025 had a single mnemonic seed phrase in
# its wallet, we use its ZIP 32 seed fingerprint as the `zcashd` wallet identifier
# in this setting.
#legacy_pool_seed_fingerprint = UNSET


#
# Deprecated Zallet features that you are temporarily re-enabling.
#
# A deprecated feature is disabled by default and scheduled for removal in a future
# Zallet version. Setting its flag to `true` here re-enables it for this wallet.
# Treat that as a stopgap while you migrate away: the flag stops being usable once
# the feature is removed, and the removal will be flagged via
# `features.as_of_version` when you upgrade.
#
[features.deprecated]


#
# Experimental Zallet features that you are using before they are stable.
#
# An experimental feature is disabled by default, and may change incompatibly or be
# removed entirely without a deprecation cycle. Setting its flag to `true` here opts
# this wallet in. When the feature is stabilised or abandoned, the flag is retired,
# and the change will be flagged via `features.as_of_version` when you upgrade.
#
[features.experimental]


#
# Settings for the Zaino chain indexer.
#
[indexer]

# IP address and port of the JSON-RPC interface for the full node / validator being
# used as a data source.
#
# If unset, connects on localhost to the standard JSON-RPC port for mainnet or
# testnet (as appropriate).
#validator_address = UNSET

# Path to the validator cookie file.
#
# If set, cookie file authorization will be used.
#validator_cookie_path = UNSET

# Full node / validator Username.
#validator_user = UNSET

# Full node / validator Password.
#validator_password = UNSET

# Path to the folder where the indexer maintains its state.
#
# This can be either an absolute path, or a path relative to the data directory.
# Note that on Windows, you must either use single quotes for this field's value, or
# replace all backslashes `/` with forward slashes `/`.
#db_path = "zaino"


#
# Settings for the read-state-service indexer backend.
#
# This section is optional. Uncomment the header and fields below to enable it.
#
#[indexer.read_state_service]

# Address (`host:port`) of zebrad's gRPC indexer interface.
#
# Used to follow zebrad's non-finalized chain tip. This must match the
# `indexer_listen_addr` set in zebrad's `[rpc]` config section. Note that the
# indexer interface is only available in a `zebrad` built with the `indexer`
# feature flag; it is not present in a default build.
#grpc_address = "127.0.0.1:8230"

# Path to the running zebrad's existing state cache directory.
#
# Zallet opens this read-only (as a RocksDB secondary instance); it never writes
# to or deletes it. It must be on the same machine as Zallet, and zebrad's on-disk
# state format must be compatible with Zallet's `zebra-state` version.
#
# This can be either an absolute path, or a path relative to the data directory.
#zebra_state_path = "/home/<username>/.cache/zebra"


#
# Settings for the key store.
#
[keystore]

# Path to the age identity file that encrypts key material.
#
# This can be either an absolute path, or a path relative to the data directory.
# Note that on Windows, you must either use single quotes for this field's value, or
# replace all backslashes `/` with forward slashes `/`.
#encryption_identity = "encryption-identity.txt"

# By default, the wallet will not allow generation of new spending keys & addresses
# from the mnemonic seed until the backup of that seed has been confirmed with the
# `zcashd-wallet-tool` utility. A user may start zallet with `--walletrequirebackup=false`
# to allow generation of spending keys even if the backup has not yet been confirmed.
#require_backup = true


#
# Note management configuration section.
#
[note_management]

# The minimum value that Zallet should target for each shielded note in the wallet.
#min_note_value = 1000000

# The target number of shielded notes with value at least `min_note_value` that
# Zallet should aim to maintain within each account in the wallet.
#
# If an account contains fewer such notes, Zallet will split larger notes (in change
# outputs of other transactions) to achieve the target.
#target_note_count = 4


#
# Settings for the JSON-RPC interface.
#
[rpc]

# Addresses to listen for JSON-RPC connections.
#
# Note: The RPC server is disabled by default. To enable the RPC server, set a
# listen address in the config:
# ```toml
# [rpc]
# bind = ["127.0.0.1:28232"]
# ```
#
# # Security
#
# If you bind Zallet's RPC port to a public IP address, anyone on the internet can
# view your transactions and spend your funds.
#bind = []

# Timeout (in seconds) during HTTP requests.
#timeout = 30


#
# A user that is authorized to access the JSON-RPC interface.
#
# Repeat this section to add more entries to the list.
#
#[[rpc.auth]]

# The username for accessing the JSON-RPC interface.
#
# Each username must be unique. If duplicates are present, only one of the passwords
# will work.
#user = UNSET

# The password for this user.
#
# This cannot be set when `pwhash` is set.
#password = UNSET

# A hash of the password for this user.
#
# This can be generated with `zallet rpc add-user`.
#pwhash = UNSET


#
# Settings controlling how Zallet synchronizes the wallet with the chain.
#
[sync]

# The maximum number of blocks that the history-recovery task downloads and scans in
# a single batch.
#
# Larger batches improve scanning throughput, but increase peak memory usage: every
# block in a batch is held in memory while it is downloaded and trial-decrypted.
# Mainnet blocks can currently be up to 2 MiB each, so a batch of N blocks can require
# on the order of N * 2 MiB of memory.
#recover_batch_size = 1000