btcwallet Documentation

The wtxmgr package is responsible for the storage and spend tracking of wallet transactions, including their inputs and outputs.

Key capabilities include:

• Transaction Storage: Maintains records of relevant wallet transactions.
• Output Control: Ability to mark specific outputs as being controlled by the wallet.
• UTXO Management: Provides an Unspent Transaction Output (UTXO) index.
• Balance Tracking: Monitors wallet balances.
• Spend Tracking: Automatically tracks spending when transactions are inserted or removed.
• Reorg Resilience: Detects and corrects double spends following blockchain reorganizations.
• Scalable Design: Uses specific prefixes to allow cursor iteration over transaction inputs and outputs and operates under its own walletdb namespace.

The primary method for interacting with the wallet from external processes is through its built-in gRPC server. This allows client programs to perform remote procedure calls to manage wallet operations.

For detailed information on how to use this interface, refer to the following resources:

• API Specification: Defines the available services and methods.
• Client Usage: Provides guidance on how to implement and use clients to interact with the server.

Note: A legacy JSON-RPC API (compatible with Bitcoin Core's wallet) is available but is not covered in this documentation.

The walletdb package provides a namespaced database interface designed for the btcwallet daemon. It allows different components of a wallet (such as address management, voting pools, or metadata) to store data in their own isolated namespaces within a single shared database. This prevents key collisions between different packages while maintaining atomicity.

Key features include:

• Key/value store: Standard KV operations.
• Namespace support: Enables multiple packages to operate in their own area without conflicts.
• Transactions: Supports both read-only and read-write transactions in both manual and managed modes.
• Nested buckets: Allows for hierarchical data organization.
• Pluggable backends: Supports registration of different backend database types via drivers.

When starting the btcwallet daemon, the following lifecycle occurs regarding database and network management:

1. Network Selection: The daemon reads the active network flag (e.g., --network=testnet).
2. DSN Lookup: It selects the corresponding db.dsn from the btcwallet.conf file for that specific network.
3. Network Binding Verification: To prevent data corruption (such as accidentally pointing a testnet configuration to a mainnet database), btcwallet uses a meta table within the database to bind it to a specific network.
4. Startup Safety: On every startup, the daemon verifies this binding. If the network specified by the CLI flag does not match the network bound in the database's meta table, btcwallet will refuse to start and will output a clear error.

To manage concurrency and state safely, the project uses the Actor Model. Instead of sharing memory and protecting it with mutexes, state is isolated within independent, long-running goroutines called "actors."

An actor follows these three rules:

1. Owns its state exclusively: No other part of the system can touch its internal data.
2. Runs in a dedicated goroutine.
3. Communicates only via messages: Messages are sent over channels (the actor's "mailbox").

This approach ensures concurrency safety and decouples subsystems for easier testing and maintenance.

A core architectural goal is to ensure a module's interface is significantly simpler than its internal implementation. This reduces the cognitive load on users of the API.

Example Pattern: Instead of exposing the complexities of mempool checks and database synchronization, the TxPublisher interface provides a single, clean method:

// The user sees this simple interface
TxPublisher.Broadcast(tx)

// Internally, it handles:
// 1. Mempool acceptance checks
// 2. Atomic database updates via addTxToWallet
// 3. Network broadcast

Passing a context.Context through every function call in a request's lifecycle is the most important pattern for controlling behavior. It allows for:

• Enforcing timeouts.
• Propagating cancellation signals.
• Gracefully tearing down work for abandoned requests.

Best Practice: Inside long-running loops, always check for cancellation using select { case <-ctx.Done(): ... }.

// Every function that is part of a request accepts a context.
func (a *MyActor) ProcessPayment(ctx context.Context, payment Payment) error {
    // Pass the context down to the next actor/function.
    err := a.db.Save(ctx, payment)
    if err != nil {
        return err
    }
    // ...
    return nil
}

// Inside a long-running loop, always check for cancellation.
for {
    select {
    case <-ctx.Done():
        return ctx.Err() // Exit cleanly
    // ... do other work
    }
}

The Pipeline Pattern structures work as a series of actors (stages) connected by channels. Each actor performs a specific task and passes its output to the next actor in the chain. This is used to break down complex processes into simple, decoupled, and reusable stages.

// Stage 1: Doubles numbers
func doubler(in <-chan int, out chan<- int) {
    for num := range in {
        out <- num * 2
    }
    close(out)
}

// Stage 2: Adds 5 to numbers
func adder(in <-chan int, out chan<- int) {
    for num := range in {
        out <- num + 5
    }
    close(out)
}

// Building the pipeline:
// inputChan -> doubler -> adder -> outputChan

In table-driven tests, the test case struct should only contain data (inputs and expected outputs).

Avoid embedding setup logic: Do not include functions or complex setup logic inside the test case struct. Embedding setup (like a setup func(...) field) obscures the test's behavior and makes it harder to understand each case in isolation. Setup should be explicit and clear within the test's body.

// Good Example: Data-only Struct
func TestBuildTxDetail(t *testing.T) {
    tests := []struct {
        name             string
        details          *wtxmgr.TxDetails // Input
        currentHeight    int32             // Input
        expectedTxDetail *TxDetail         // Expected Output
    }{
        // ... test cases defined here
    }

    for _, test := range tests {
        // ... test logic here
    }
}