Skip to content

Architectural backend refactor: separate Stealth into reusable modules #10

Description

@satsfy

Stealth is aiming to become a local-node-backed privacy analysis engine, but backend scanning logic is currently too tightly coupled to its transport layer. Furthermore, a pending Rust refactor is indicated in the README.md.

To address that, I propose splitting the backend into three explicit Rust layers:

  • stealth-core: scanning logic, report types, RPC-backed wallet analysis, and shared validation/scanning primitives
  • stealth-api: thin HTTP transport over stealth-core
  • stealth-cli: thin command-line entrypoint over stealth-core

stealth-core

stealth-core should own the actual analysis engine.

That includes:

  • Bitcoin/Core RPC integration
  • descriptor / descriptors / UTXO scan targets
  • wallet import / rescan flow
  • report generation
  • scan errors and shared types

stealth-api

The API should stay transport-focused.

Its job should be:

  • accept HTTP input
  • validate request shape
  • call into stealth-core
  • map errors into HTTP responses

That keeps the web layer thin and makes it easier to evolve or replace without rewriting scanner behavior.

stealth-cli

The CLI should be a first-class local interface to the same engine.

That matters because Stealth is explicitly local-node oriented. A CLI gives:

  • a direct operator/developer workflow
  • a simple way to test scans without needing the frontend
  • a stable interface for scripting, automation, and infra use
  • a second consumer of the same core API, which helps keep the core genuinely reusable

What this unlocks

This split directly supports the roadmap:

  • real wallet analysis against a local Bitcoin node
  • a reusable Rust library for wallet ecosystems
  • external clients that can consume Stealth through either a library boundary or a thin HTTP layer
  • less duplication and less architectural lock-in

It also makes future work like testnet/mainnet deployments, integration testing, and third-party client support much easier to reason about.

Implementation notes

My intended implementation is:

  • use rust-bitcoin for Bitcoin-domain types and parsing
  • use corepc for Bitcoin Core JSON-RPC integration
  • centralize scanning in stealth-core
  • keep stealth-api as a thin adapter around the core scanner
  • keep stealth-cli as a thin local/operator interface around the same scanner

Expected outcome

After this, Stealth should have:

  • one source of truth for wallet privacy analysis
  • one thin HTTP transport
  • one thin CLI transport
  • a cleaner base for wallet integrations and external clients
  • a more credible path from regtest/dev flows to real node-backed wallet analysis

If Stealth is going to be a modular privacy engine rather than just a single app flow, this separation is the right foundation.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions