Refactor `wallet.Interface` into Role-Based Interfaces

[yyforyongyu]

This doc serves as the master tracking issue.

Motivation

The btcwallet package currently exposes a large, monolithic wallet.Interface with approximately 50 methods. Its primary consumer, lnd, defines its own lnwallet.WalletController interface with around 40 methods, many of which are duplicates or slight variations of the wallet.Interface methods.

This duplication and the sheer size of these interfaces make the code difficult to maintain, test, and reason about. It violates the Interface Segregation Principle and the Single Responsibility Principle.

The goal of this refactoring is to decompose these monolithic interfaces into a new set of clean, logical, and role-based interfaces within the btcwallet package. This will provide a more secure, flexible, and intuitive API for all consumers.

For a full breakdown of the design, please see the wallet architecture documentation. For the analysis of the current code structure, check this analysis.

Guiding Principles

All implementation work must adhere to the following key principles:

• Separation of Concerns: A primary goal of this refactoring is to create a clean separation between business logic (the "how") and data persistence (the "what"). The new interfaces should be implemented in a way that the database logic is fully encapsulated and abstracted, preparing for the upcoming transition to a SQL backend.
• Actor Model: Concurrency should be managed using the Actor Model to ensure thread safety and avoid complex locking.
• SOLID Principles: The implementation should follow the SOLID principles, particularly the Single Responsibility and Interface Segregation Principles.

Implementation Plan

The following is a checklist of the new interfaces to be implemented. Each item represents an ADR that can be picked up by a developer,

• Implement and Refactor WalletController Interface Design for WalletController #1030

  • Responsibility: Manages the wallet's lifecycle (Start, Stop, Lock, Unlock) and provides high-level status information.

• Implement and Refactor AccountManager Interface Design for AccountManager #1031

  • Responsibility: Handles the creation, querying, and renaming of accounts, and is also responsible for querying account-specific or total wallet balances.

• Implement and Refactor AddressManager Interface Design for AddressManager #1032

  • Responsibility: Manages the generation, import, and inspection of addresses and scripts.

• Implement and Refactor UtxoManager Interface Design for UtxoManager #1033

  • Responsibility: Manages the wallet's UTXO set, including listing unspent outputs and managing UTXO leases.

• Implement and Refactor TxPublisher Interface Design for TxPublisher #1034

  • Responsibility: A command-oriented interface for all "write" operations related to transactions, such as creating and broadcasting them.

• Implement and Refactor PsbtManager Interface Design for PsbtManager #1035

  • Responsibility: A dedicated interface for the multi-step PSBT workflow (Fund, Sign, Finalize).

• Implement and Refactor TxReader Interface Design for TxReader #1036

  • Responsibility: A query-oriented interface for all "read" operations related to transaction history.

• Implement and Refactor Signer Interface Design for Signer #1037

  • Responsibility: A low-level interface providing direct access to cryptographic operations like signing and key derivation.

[MStreet3]

Is there an order you planned to pick these up in? I'd be interested in picking up #1030

[yyforyongyu]

@MStreet3 thanks! This series is pretty much finished tho. Reviews are welcome here!