Document internal wallet startup cache behavior

Author: endophysics

zebra-crosslink/docs/internal-wallet-snapshot.md

@@ -0,0 +1,37 @@
+# Internal Wallet Snapshot
+
+The Crosslink internal wallet keeps an optional restart cache at:
+
+```text
+<state.cache_dir>/wallet.snapshot
+```
+
+The snapshot is a local cache for the internal wallet's derived state: manual wallet records, known transactions, the PoW hash cache, and the Orchard shard tree. Zebra state, `pos.chain`, and `secret.seed` remain the authoritative node state.
+
+## When snapshots are used
+
+- Persistent state runs save and load `wallet.snapshot` from `state.cache_dir`.
+- Ephemeral state runs do not save or load the snapshot.
+- A snapshot is used only if its stored `secret.seed` bytes and genesis hash match the current run.
+- Missing, mismatched, or invalid snapshots are ignored and the internal wallet scans from genesis.
+
+The file is written atomically via a temporary file and rename. The reader checks the snapshot magic, version, seed, genesis hash, bounded lengths, and trailing bytes before accepting it.
+
+## Operational notes
+
+- Treat `wallet.snapshot` as a local plaintext cache; do not share it as a recovery authority.
+- After rollback or state rebuild, move `wallet.snapshot` aside and let it regenerate from the rebuilt chain state.
+- The internal wallet requires zaino. If zaino is enabled but cannot start, `zebrad start` fails rather than continuing into a wallet sync loop that cannot make progress.
+
+## Related config
+
+```toml
+[crosslink]
+disable_the_headless_wallet = false
+disable_zaino = false
+reset_zaino_on_startup = false
+```
+
+- `disable_the_headless_wallet`: skips the internal wallet task.
+- `disable_zaino`: skips zaino startup. Use this only when the internal wallet is also disabled.
+- `reset_zaino_on_startup`: deletes the zaino cache under `state.cache_dir` before starting zaino.

zebra-crosslink/sams_config.toml

@@ -46,6 +46,12 @@ checkpoint_sync = true
 [crosslink]
 do_not_manipulate_config = false
 i_am_the_unstaker = true
+# Set to true to skip starting the internal wallet task.
+disable_the_headless_wallet = false
+# Set to true to skip starting zaino. The internal wallet requires zaino.
+disable_zaino = false
+# Set to true to delete the zaino cache under state.cache_dir on startup.
+reset_zaino_on_startup = false
 bft_peers = []
 
 [mempool]

zebra-crosslink/zebrad/src/commands/start.rs

@@ -117,15 +117,21 @@ impl StartCmd {
     async fn start(&self) -> Result<(), Report> {
 
         let config = APPLICATION.config();
-        let mut wallet_snapshot_path = config.state.cache_dir.clone();
-        wallet_snapshot_path.push("wallet.snapshot");
-        *wallet::WALLET_SNAPSHOT_PATH.lock().unwrap() = Some(wallet_snapshot_path.clone());
+        let wallet_snapshot_path = if config.state.ephemeral {
+            None
+        } else {
+            let mut path = config.state.cache_dir.clone();
+            path.push("wallet.snapshot");
+            Some(path)
+        };
+        *wallet::WALLET_SNAPSHOT_PATH.lock().unwrap() = wallet_snapshot_path.clone();
+        let wallet_requires_zaino = cfg!(feature = "viz_gui") || !config.crosslink.disable_the_headless_wallet;
 
         #[cfg(not(feature = "viz_gui"))]
         {
             if config.crosslink.disable_the_headless_wallet == false {
                 let wallet_state = Arc::new(std::sync::Mutex::new(wallet::WalletState::new()));
-                tokio::spawn(zebra_crosslink::wallet::wallet_main(wallet_state, Some(wallet_snapshot_path)));
+                tokio::spawn(zebra_crosslink::wallet::wallet_main(wallet_state, wallet_snapshot_path.clone()));
             }
         }
         *zebra_crosslink::wallet::GUI_ENABLE_MINE.lock().unwrap() = config.mining.internal_miner;
@@ -221,8 +227,6 @@ impl StartCmd {
                 // },
                 mining: zebra_rpc::config::mining::Config {
                     miner_address: Some(config.mining.miner_address.clone().unwrap_or_else(||{
-                        use zcash_address::ToAddress;
-
                         let t_addr = wallet::default_p2pkh_from_entropy(&config.network.network, &global_seed).expect("unable to initialize miner");
                         info!("Miner address unspecified. Mining to {}", wallet::string_from_t_addr(&config.network.network, t_addr));
                         t_addr.to_zcash_address(config.network.network.kind().into())
@@ -834,6 +838,11 @@ impl StartCmd {
             *zebra_crosslink::wallet::wallet_main_zaino_port.lock().unwrap() = zebra_port_base + 10001;
 
             if let Err(err) = zainodlib::indexer::spawn_indexer(zaino_config).await {
+                if wallet_requires_zaino {
+                    return Err(eyre!(
+                        "failed to start zaino indexer required by the internal wallet: {err:?}"
+                    ));
+                }
                 warn!(
                     ?err,
                     "failed to start zaino indexer; continuing without zaino"