From: merge-script <withtvpeter@gmail.com>
Date: Wed, 8 Jul 2026 21:06:40 +0000 (+0100)
Subject: Merge bitcoindevkit/bdk-cli#278: Refactor bdk-cli structure
X-Git-Url: http://internal-gitweb-vhost/blockdata/script/encode/-script/error/-non-standard-bare-script/index.html?a=commitdiff_plain;p=bdk-cli

Merge bitcoindevkit/bdk-cli#278: Refactor bdk-cli structure

63f769a68f72855c0de7fd7a6f5c459e0ace1b2d revert parallel request wallet parameter (Vihiga Tyonum)
8dc0503ab8887c119ac49d4b490aecb0170aab64 drop verbose flag (Vihiga Tyonum)
5da76608fcd5e0ae340010f19a778750a68a86e1 feat(handlers): mv feats into subdirs in handlers (Vihiga Tyonum)
5951c17152d64f44e5a38deaf369ce8795b81893 feat(dns-payment): port dns payment instruction (Vihiga Tyonum)
b3fe86098e6b35e5280a715e0ff2902161975c4b feat(sp): fix command_requires_db fn match arm (Vihiga Tyonum)
c2ca2ddbdfea5bcc7b8aaeed79bfd39798a2165c ref(payjoin): add payjoin persistence (Vihiga Tyonum)
249948eac1ceb7b83b76d03751669ed0dbde7a35 ref(compile):compile tr desc with rand unspend key (Vihiga Tyonum)
6a6390fcc5b823e1901a7105fa424689947e7dbf feat(WalletEvents): Add wallet events to clients (Vihiga Tyonum)
cb9634fd71d494e27648ca2bfc99013e0e0991f7 ref(create_tx): enforce single recp for sendall (Vihiga Tyonum)
188e68d147f7c548041c802dab2f7c425c3732b8 refactor(runtime): Add address and createtx to db (Vihiga Tyonum)
75b51413d9bdc4f981831cb91dc966318b0dc0a4 refactor(sp-payment): Rebase silent payment feat (Vihiga Tyonum)
aa8876d192d773e9f431bebbc6397f78868661aa refactor(main): add runtime wallet module (Vihiga Tyonum)
63162bed1ba9804486048a401b2c927a66060ce2 refactor(handlers): Apply app context (Vihiga Tyonum)
f3deed85868f15f9b97355d1680d2df6d1432120 Refactor(handlers): Define app context states (Vihiga Tyonum)
5ced5aa764407d0b117b43ddeb6a9addfa15c8ed refactor(output): apply generics to output mod (Vihiga Tyonum)
1b05c0309670574bec54f88aa1354332aed3e452 ref(handlers): fix offline, online and desc mod (Vihiga Tyonum)
dcaeb5534b45e0fd9f46126d9f45556fd0121a92 ref(handlers): refactor config, descr and key mods (Vihiga Tyonum)
f77ddccb9b01ce0fa77e576ca7513554c8e98772 ref(main): add run to handle routing (Vihiga Tyonum)
528956d244a1eb83b255c8e6a37fef66fa3967ea ref(pretty): remove `--pretty` flag (Vihiga Tyonum)
cf9d13bd0974e2eb73a956915e30edf86660feaa ref(persister): collapse wallet subdir to persister (Vihiga Tyonum)
7a0e68bd3379cfe880cc7d25f57e7aaccc1e0ed4 update namespace and update types (Vihiga Tyonum)
eaa4e11428b6443be09afb30b9c8db642f39adad revert mod names for command and clients (Vihiga Tyonum)
ada34858d7e2d2a29dfa7d3ccfd311ff19a919f6 ref(utils): use types in desc output in utils (Vihiga Tyonum)
90017cdf87538b8f4f14496e55c9ee92f7f96d74 ref(handlers): rebase bip322 feature (Vihiga Tyonum)
990f30a7da5e840f3b2d1e68a94dc45235f7874f ref(types): add simple table helper (Vihiga Tyonum)
055e1fd48e993bfe94d83e97b7c66bdcc0aa9930 ref(handlers): add types for desc, key & wallets (Vihiga Tyonum)
a9732732e4d55547489a9768134cdb4093b54fa7 refactor(handlers): Add types for outputting data (Vihiga Tyonum)
3e2eec8e24883fe68a9a25f534793aaf0538b1bb ref(main): update main entry point (Vihiga Tyonum)
0bf3e66c7f733fed152171e0dab63f070d24ff10 ref(handlers): split handler fns into repl (Vihiga Tyonum)
bf0551b71c5da8cce5b3200f47202dd787e46a65 ref(handlers):mv handler fns into offline & others (Vihiga Tyonum)
03307c96cf6e19238021949da9b805a0b3aafdd2 ref(handlers): split handlers into config, key (Vihiga Tyonum)
eb3a6aa7798a9994b4a69a85abc65a32163b945f ref(persister): mv persister into wallet subdir (Vihiga Tyonum)
24820444164026b47d0b8909b6e795872e6b92c8 ref(utils): refactor utils into utils subdir (Vihiga Tyonum)
739dec3f3f46330416d2395bf1f992f1abd531c4 ref(config): move config into config subdir (Vihiga Tyonum)
5c286d64aec3f1b34a889047222dd1c559e9d4a6 ref(commands): mv commands & clients into subdirs (Vihiga Tyonum)

Pull request description:

  <!-- You can erase any parts of this template not applicable to your Pull Request. -->

  ### Description

  This PR restructures the bdk-cli codebase to move away from a monolithic handling model towards a modular architecture. The primary goal is to improve code readability, simplify the addition of new features, and decouple core logic into smaller modules.

  Fixes #273

  <!-- Describe the purpose of this PR, what's being adding and/or fixed -->

  ### Notes to the reviewers

  While trying to achieve the above-stated goal, I took maximum care to avoid introducing new bugs. As a result, the existing execution logic was preserved as much as possible.

  <!-- In this section you can include notes directed to the reviewers, like explaining why some parts
  of the PR were done in a specific way -->

  This PR introduces two new subdirectories under `src`:

   - handlers: This contains all the subcommands' execution logic grouped logically according to the top-level commands.  Modules include the `config`, `descriptor`, `key`, `offline`, `online` and `repl` modules. They each contain structures for the subcommand, execution logic, and implementation of the top-level enum.
   - utils: This subdirectory contains helper functions used across the app. They are also grouped logically according to related functionality. So far, we have the descriptor-related module, the output that formats responses, and the `types` module that defines response structures.

   **Other notable changes**

   - main module is retained with added functionality of routing requests to the right module for execution.
   - All client-related functionalities have been moved from various modules into the `client` module, and it defines the enum that holds all the available clients, as well as implements the functionalities such as broadcasting transactions and syncing operations.
   - The `AppCommand` trait that defines how each subcommand should be structured and the `execute` method they should implement.
   - The `AppContext` struct that holds the universal parameters that subcommands may need. Each subcommand's `execute` method accepts this struct and uses the params for its execution.
   - The output module in the util subdirectory attempts to present a uniform presentation layer by having an output trait, the `FormatOutput` trait, which is implemented by all `types` presenting data response to the user.
   - Collapsed the `wallet` subdirectory into the `persister` module that defines all structures and functionalities related to persistence.
   - Introduced a type state pattern for the AppContext: To minimise runtime errors, the `Init`, `OfflineOperations` and `OnlineOperations` state structs were introduced, and AppContext is generic over these states. This moved the validation from runtime to compile time.
  - Introduced `FormatOutput::write_out` and made it generic over the Write trait to allow for flexibility in testing
  - Extracted all initialisation logic (database, config loading and persistence initialisation) into `runtime` module. Also, added the `RuntimeWallet` enum to return options of a persisted wallet and a standard non-persisted wallet. The WalletRuntime struct is a wrapper that determines the type of wallet needed and initialises it and handles loading of a wallet from config.

  **Request-Response Cycle**

  The following outlines how requests are handled and responses are generated after introducing changes to the structure:

  1. When a user enters a set of commands, those commands are received and parsed by the Clap library into Rust structures, such as `CliOpts`, `WalletOpts`, and subcommands. This process takes place in the `commands` module.

  2. The parsed request is then passed to the `main` module. The main module uses the `runtime` module to interpret the request and initialize any necessary resources (such as wallets, databases, and clients) needed to fulfill the request. It then routes the request to the appropriate handler for execution.

  3. Once a particular handler receives the request along with all the required resources, it processes the specific command using the `AppContext` and prepares a response.

  4. After processing is complete, the handler calls the `output` module to format the result, serialize it into JSON, and return it to the terminal.

  ## Changelog notice

     - In the `key derive` subcommand, when printing help message, the clap arg for env=“PATH” often pull all system and displays all system paths. This has been changed to derivation_path I.e. env=“DERIVATION_PATH” to prevent clap from picking the system paths and rendering it
     - Moved the wallet subdirectory that served as persister into the persister module
     - Moved DatabaseType enum from commands module into persister module
     - Removed the —pretty flag

  <!-- Notice the release manager should include in the release tag message changelog -->
  <!-- See https://keepachangelog.com/en/1.0.0/ for examples -->

  ### Checklists

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk-cli/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

Top commit has no ACKs.

Tree-SHA512: e63ed0693e2580fe80fca278e0ad1f7feacccda32f3e7262d57cff1bdf4e9850e2463dfeee1cbcfad4ce1502fd19d3861d5012705e051d19831def8832b6780a
---

898d08cb9aab88015e5b6b9345ff68bc3d2d18d7