refactor(app): lazy network contexts, unified network switch, MCP network tools

[lklimek]

Summary

Imagine you're switching from testnet to mainnet. Previously, the app froze for up to 10 seconds while creating the mainnet context (SDK init, DAPI address parsing). Now the UI shows a progress banner and stays responsive — the context is created on a background thread. And if you're using the CLI or MCP, you can switch networks with det-cli network-switch network=mainnet.

Key changes

• Lazy network contexts: Only the active network's AppContext is created at startup. All others are deferred and created on first switch. Startup is faster — no wasted time on networks the user doesn't use.
• Unified SwitchNetwork flow: BackendTask::SwitchNetwork is a regular backend task handled by run_backend_task(). Both GUI and MCP use the same path — dispatch the task, get NetworkContextCreated, handle the result. No special interception needed.
• Graceful startup: If the saved network has no DAPI addresses, the app tries other networks before giving up. Actionable error message points to "Refresh DAPI endpoints" button.
• 3 new MCP tools:
  • network_switch — switch active network (creates context if needed)
  • network_reinit_sdk — rebuild SDK with current config (after credential changes)
  • network_info — show active/available networks
• Headless SPV mode: CLI/MCP forces SPV backend (no Dash Core node needed). Uses volatile in-memory switch so the GUI's saved RPC preference is untouched.
• SPV auto-start on network switch: BackendTask::SwitchNetwork accepts a start_spv: bool flag. MCP/CLI always passes true (headless needs SPV). GUI reads the user's auto_start_spv DB setting. When true, the handler forces SPV mode (volatile) and starts the SPV client on the new context — no more 10-minute timeouts waiting for SPV that was never started.
• SPV stale lock recovery: When the SPV data directory is locked by a crashed process, SpvManager automatically falls back to a temporary directory instead of failing. Prevents MCP tools from hanging forever waiting for SPV sync that can never complete.
• Platform tools don't gate on SPV: platform_addresses_list no longer waits for SPV sync — it queries DAPI directly. Previously, if SPV was unavailable, this tool would hang indefinitely. Docs (MCP.md, MCP_TOOL_DEVELOPMENT.md, resolve.rs) now clarify which tools need SPV and which don't.
• Network persist in backend task: BackendTask::SwitchNetwork handler persists the chosen network to DB, so both GUI and MCP get persistence for free.
• Unified context storage: MCP's ContextHolder enum supports both HTTP mode (shared ArcSwap with GUI) and CLI mode (ArcSwapOption with lazy init), enabling network_switch in all modes.
• Network chooser: Mainnet and Testnet always visible; Devnet and Local only in developer mode.
• Screen initialization: Uses active_context instead of hardcoded mainnet_app_context. Eliminated 4-way if-else chain (~25 screen constructors duplicated per network).
• Doc rename: EXPOSING_BACKEND_TASKS.md → MCP_TOOL_DEVELOPMENT.md for discoverability.

Architecture

Startup:
  Try saved network → if fails, try Mainnet → Testnet → Devnet → Regtest
  First success → active context. All others deferred.

Network switch (GUI):
  AppAction::SwitchNetwork(network)
  → change_network()
    → fast path: context exists → finalize_network_switch()
    → slow path: handle_backend_task(BackendTask::SwitchNetwork { network, start_spv })
      → run_backend_task creates new AppContext
      → if start_spv: force SPV mode + start_spv()
      → TaskResult::Success(NetworkContextCreated { spv_started })
      → store in network_contexts, update screens, update MCP ArcSwap

Network switch (MCP/CLI):
  network_switch tool
  → dispatch_task(BackendTask::SwitchNetwork { start_spv: true })  ← same handler
  → service.swap_context(new_ctx)

Headless SPV:
  init_app_context() forces SPV mode (volatile, not persisted)
  → ensure_spv_synced() checks SPV status only (no RPC needed)
  → wallet tools work without Dash Core node

SPV gate rule:
  Core-chain tools (send, receive addr, balances, asset lock) → ensure_spv_synced()
  Platform-only tools (DAPI queries: platform_addresses, withdrawals) → NO SPV gate

GUI and MCP share the same BackendTask::SwitchNetwork handler. The only difference is what they do with the result — GUI updates screens, MCP swaps its ArcSwap.

Test plan

• cargo clippy --all-features --all-targets -- -D warnings passes
• cargo +nightly fmt --all passes
• App starts with mainnet — other networks deferred
• App starts with testnet — mainnet deferred, no freeze
• App starts with empty mainnet addresses — falls back to testnet or shows actionable error
• Switch testnet → mainnet: progress banner, context created in background, UI responsive
• Switch back to testnet: fast path, no banner (context already exists)
• Network chooser: Mainnet + Testnet always visible, Devnet + Local in dev mode only
• det-cli network-switch network=testnet — switches and persists, SPV starts automatically
• det-cli network-info — shows testnet after switch (new process)
• det-cli core-wallets-list — lists wallets on switched network
• det-cli core-balances-get wallet_id=tspv1 — returns balances via SPV (no Core node)
• det-cli network-switch network=mainnet — switches back, DB updated, SPV restarts
• DB core_backend_mode stays RPC (0) after CLI usage — GUI preference untouched
• det-cli network-reinit-sdk network=mainnet — rebuilds SDK
• Invalid network returns clear error message
• SPV auto-start flag: MCP passes true, GUI reads auto_start_spv from DB
• platform_addresses_list works without SPV sync (queries DAPI directly)
• SPV stale lock: kill process, retry — SPV starts in tempdir, tools work

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e80a83e9-51c4-4b60-b1b3-c070a427b4fa

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/lazy-active-context

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[lklimek]

Additional scope: refactor network switch to a backend task

While we're refactoring context creation to be lazy, we should also move the network switch itself (change_network()) to the backend task system instead of running it inline on the UI thread.

Currently, change_network() creates a new AppContext synchronously — which includes SDK initialization, DAPI discovery (with timeouts), and ZMQ listener setup. This blocks the UI thread and can cause visible freezes, especially on first switch to a deferred network.

Proposed approach:

• change_network() returns an AppAction::BackendTask(BackendTask::SwitchNetwork { network }) instead of doing the work inline
• The backend task creates the AppContext, starts ZMQ, and returns the new context via TaskResult
• AppState::update() handles the result by calling change_context() on all screens
• The UI shows a progress indicator during the switch (via MessageBanner or a loading state)

This fits naturally with the lazy context pattern — the lazy creation just moves from "synchronous on UI thread" to "async on backend thread."

_{🤖 Co-authored by Claudius the Magnificent AI Agent}

[Copilot]

Pull request overview

This PR refactors network handling to lazily initialize AppContext per network, unify GUI and MCP/CLI network switching through standard backend tasks, and add MCP tools for network switching and SDK reinitialization. It also improves UI responsiveness during slow network/context operations by moving work off the UI thread and introduces a small theme-handling refactor.

Changes:

• Lazy network context creation + async network switching via BackendTask::SwitchNetwork and BackendTaskSuccessResult::NetworkContextCreated.
• New MCP tools: network_switch and network_reinit_sdk, plus MCP context swapping support for both HTTP and CLI modes.
• Network chooser and app state updated to use a map of contexts (BTreeMap<Network, Arc<AppContext>>) instead of hardcoded per-network fields.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/ui/network_chooser_screen.rs	Switches to context map storage; adds async RPC reinit flow and banner handling.
src/ui/mod.rs	Simplifies Screen::change_context logic and updates Network Chooser context wiring.
src/mcp/tools/network.rs	Adds network_switch and network_reinit_sdk MCP tools dispatching backend tasks.
src/mcp/server.rs	Replaces context provider with swappable context holder supporting HTTP + CLI modes.
src/context/mod.rs	Adds set_core_backend_mode_volatile() for headless SPV forcing without DB persistence.
src/backend_task/mod.rs	Adds new backend tasks/results for network switching and SDK reinit; implements switch handler.
src/backend_task/error.rs	Introduces NetworkContextCreationFailed error variant.
src/app.rs	Refactors to lazily init contexts, async network switching with banner, ZMQ listener spawning, theme state.
docs/MCP.md	Documents new MCP tools.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

tokio::sync::OnceCell doesn’t have a const_new_with(()) constructor (Tokio 1.46 provides OnceCell::new() / OnceCell::const_new()). With --all-features (mcp+cli), this line will fail to compile. Initialize init_guard with a supported constructor (e.g., OnceCell::new()), or avoid creating it in shared/HTTP mode if it’s unused.

Suggested change

	init_guard: Arc::new(tokio::sync::OnceCell::const_new_with(())),
	init_guard: Arc::new(tokio::sync::OnceCell::new()),

[Copilot]

The doc comment for BackendTask::SwitchNetwork says it is intercepted by AppState and never dispatched to AppContext::run_backend_task, but this PR adds a BackendTask::SwitchNetwork match arm inside AppContext::run_backend_task. Please update the comment to reflect the current behavior (it is now a regular backend task).

Suggested change

	/// Create a new network context and switch to it.
	/// Intercepted by `AppState` — never dispatched to `AppContext::run_backend_task`.
	/// Create a new network context and switch to it as a regular backend task
	/// handled by `AppContext::run_backend_task`.

[Copilot]

new_ctx.update_settings(RootScreenNetworkChooser) persists both the network and the start_root_screen (per src/context/settings_db.rs). This means network switches triggered via MCP/CLI (and even some GUI switches) will unexpectedly change the saved start screen to the Network Chooser. Persist the selected network without overwriting start_root_screen (e.g., keep the existing root screen from the current settings row, or introduce a dedicated DB update for network-only persistence).

Suggested change

	// Persist the network choice so subsequent startups (GUI, CLI,
	// MCP) all begin on the same network.
	new_ctx
	.update_settings(crate::ui::RootScreenType::RootScreenNetworkChooser)
	.ok();

[Copilot]

finalize_network_switch() persists the network via update_settings(RootScreenNetworkChooser), but update_settings also updates the start screen in the settings table. This will overwrite the user’s saved start screen whenever a network switch occurs (including switches initiated outside the Network Chooser). Persist the network without changing start_root_screen (e.g., pass the currently selected screen, or add a network-only persistence method).

Suggested change

	// Persist the network choice (fast path — slow path persists in the
	// BackendTask::SwitchNetwork handler, but fast path skips the handler).
	app_context
	.update_settings(RootScreenType::RootScreenNetworkChooser)
	.ok();
	// Persistence of the selected network is handled in the
	// BackendTask::SwitchNetwork handler. Avoid calling `update_settings`
	// here so we do not overwrite the user's saved `start_root_screen`.

[Copilot]

change_network() only ignores duplicate requests for the same pending network. If the user selects a different network while a switch is still in progress, this will dispatch multiple SwitchNetwork tasks concurrently and whichever finishes last will win, potentially switching to an unexpected network and wasting resources. If the intent is “ignore further switch requests while pending”, return early when network_switch_pending.is_some() (or cancel/serialize outstanding switches).

[Copilot]

The “Reconnecting to Dash Core...” banner is created with MessageType::Info, which auto-dismisses after 5s by default. Since the reinit is explicitly async and may take longer, the progress banner can disappear while the task is still running. Consider using BannerHandle::with_elapsed() / OptionBannerExt::replace_with_elapsed() (or disabling auto-dismiss) so the banner remains visible until CoreClientReinitialized (or an error) arrives.

Suggested change

	self.reinit_banner = Some(MessageBanner::set_global(
	ui.ctx(),
	"Reconnecting to Dash Core...",
	MessageType::Info,
	));
	self.reinit_banner = Some(
	MessageBanner::set_global(
	ui.ctx(),
	"Reconnecting to Dash Core...",
	MessageType::Info,
	)
	.with_elapsed(),
	);

[Copilot]

display_message() unconditionally clears reinit_banner and resets config_save_failed. display_message is invoked for unrelated success/info messages (e.g., theme updates, scheduled votes), so this can clear the reconnection banner mid-reinit and also lose the config_save_failed flag before CoreClientReinitialized arrives (leading to the wrong final banner). Only clear/reset these fields when the reinit task completes/fails (e.g., in display_task_result for CoreClientReinitialized and in display_task_error for the reinit failure).

[lklimek]

Replacing with a clean rebased PR from refactor/lazy-active-context-v2. The original branch was based on chore/update-dash-sdk-b70f39dc (PR #767) which was squash-merged into v1.0-dev, making merge impossible (8 conflicts from Git not recognizing the squashed commits). The new branch applies the same diff as a single commit on top of current v1.0-dev.

_{🤖 Co-authored by Claudius the Magnificent AI Agent}