Architecture

Architecture

Technical documentation of PoCX Wallet's internal architecture.

Overview

PoCX Wallet is built with a modular architecture separating core cryptographic functionality from the CLI interface and service management.

┌─────────────────────────────────────────────────────────────────┐
│                         PocxWallet.Cli                          │
│  ┌─────────────┐ ┌─────────────────┐ ┌───────────────────────┐  │
│  │   Program   │ │  WalletCommands │ │ DynamicServiceMenu    │  │
│  │  (Entry)    │ │                 │ │     Builder           │  │
│  └─────────────┘ └─────────────────┘ └───────────────────────┘  │
│  ┌─────────────┐ ┌─────────────────┐ ┌───────────────────────┐  │
│  │   Wallet    │ │ ServiceDefiniti │ │  DockerService        │  │
│  │  Manager    │ │    onLoader     │ │    Manager            │  │
│  └─────────────┘ └─────────────────┘ └───────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                        PocxWallet.Core                          │
│  ┌─────────────────┐ ┌─────────────────┐ ┌───────────────────┐  │
│  │     HDWallet    │ │  Bech32Encoder  │ │ VanityAddress     │  │
│  │    (NBitcoin)   │ │                 │ │   Generator       │  │
│  └─────────────────┘ └─────────────────┘ └───────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Project Structure

PocxWallet.Core

Core cryptographic and wallet functionality.

PocxWallet.Core/
├── Address/
│   └── Bech32Encoder.cs      # Custom Bech32 encoding for pocx prefix
├── Wallet/
│   └── HDWallet.cs           # HD wallet implementation using NBitcoin
└── VanityAddress/
    └── VanityAddressGenerator.cs  # Multi-threaded vanity search

HDWallet.cs

The main wallet class providing:

• Mnemonic generation (BIP39)
• Key derivation (BIP84 paths)
• Address generation (Bech32 with pocx prefix)
• WIF export
• Descriptor generation with checksums

Key Methods:

// Create new wallet
public static HDWallet CreateNew(WordCount wordCount, string? passphrase)

// Restore from mnemonic
public static HDWallet FromMnemonic(string mnemonic, string? passphrase)

// Derive PoCX address
public string GetPoCXAddress(uint account, uint index, bool testnet, bool change)

// Get descriptor with checksum
public string GetDescriptor(bool testnet, uint account, uint index)

Bech32Encoder.cs

Custom Bech32 encoding supporting:

• pocx prefix for mainnet
• tpocx prefix for testnet
• Witness version 0 (P2WPKH)

VanityAddressGenerator.cs

Multi-threaded vanity address search:

• Uses all available CPU cores
• Progress reporting via IProgress
• Cancellation support
• Pattern matching on generated addresses

PocxWallet.Cli

Command-line interface and service management.

PocxWallet.Cli/
├── Program.cs                    # Entry point and main menu
├── Commands/
│   └── WalletCommands.cs         # All wallet menu handlers
├── Configuration/
│   ├── ServiceDefinition.cs      # YAML model classes
│   ├── ServiceDefinitionLoader.cs # YAML loading/saving
│   ├── DynamicServiceMenuBuilder.cs # Dynamic menu generation
│   ├── WalletManager.cs          # Multi-wallet persistence
│   └── CommandTemplateEngine.cs  # Custom command processing
├── Services/
│   ├── DockerServiceManager.cs   # Docker container operations
│   └── BackgroundServiceManager.cs # Background process tracking
└── Resources/
    └── Strings.cs                # UI strings for localization

Program.cs

Application entry point:

• Initializes services
• Loads services.yaml
• Runs main menu loop
• Handles graceful shutdown

WalletCommands.cs

Handles all wallet-related menus:

• Create (random, vanity)
• Import (from mnemonic, to node)
• Select/Switch
• Info queries
• Transaction operations
• Settings

DynamicServiceMenuBuilder.cs

Builds menus dynamically from services.yaml:

• Reads service definitions
• Generates menu structure
• Handles service actions (start/stop/logs)
• Parameter and settings management

WalletManager.cs

Singleton managing multiple wallets:

• Load/save to wallet.json
• Active wallet tracking
• Legacy format migration
• Settings persistence

DockerServiceManager.cs

Docker container management:

• Container lifecycle (create, start, stop, remove)
• Log retrieval
• Command execution in containers
• Network management

Data Flow

Wallet Creation Flow

User Input → WalletCommands.CreateRandomWalletAsync()
           → HDWallet.CreateNew()
           → NBitcoin.Mnemonic (generates entropy)
           → HDWallet.GetPoCXAddress()
           → Bech32Encoder.Encode()
           → WalletManager.AddWallet()
           → WalletManager.Save() → wallet.json

Service Start Flow

User Selection → DynamicServiceMenuBuilder.StartServiceAsync()
              → BuildCommand() (from parameters)
              → BuildVolumeMappings()
              → BuildPortMappings()
              → DockerServiceManager.StartContainerAsync()
              → docker run command

Node Command Flow

User Action → WalletCommands.ExecuteNodeCommandAsync()
           → Check node running status
           → DockerServiceManager.ExecInContainerAsync()
           → docker exec command
           → Parse and display output

Key Design Decisions

1. Dynamic Service Configuration

Services are defined in services.yaml rather than hardcoded:

• Easy to add new services without code changes
• Parameter validation from schema
• Portable configuration

2. Multi-Wallet Support

The wallet file supports multiple named wallets:

• One active wallet at a time
• Automatic legacy format migration
• Settings stored alongside wallets

3. BIP84 Derivation

Uses BIP84 (native SegWit) paths:

• m/84'/0'/0'/0/0 for mainnet
• m/84'/1'/0'/0/0 for testnet
• Compatible with modern Bitcoin wallets

4. Spectre.Console UI

Rich terminal UI using Spectre.Console:

• Selection prompts for menus
• Progress bars for long operations
• Panels for structured output
• Markup for colors

5. Docker-First Architecture

Default deployment via Docker:

• No build dependencies on host
• Consistent environment
• Easy updates via image pulls

Dependencies

Core Dependencies

Package	Purpose
NBitcoin	Bitcoin cryptography
YamlDotNet	YAML parsing
Spectre.Console	Terminal UI

External Services

Service	Purpose
Docker	Container runtime
Bitcoin-PoCX Node	Blockchain operations
Electrs	Electrum protocol

Security Architecture

Mnemonic Handling

• Generated using NBitcoin's secure random
• Stored encrypted in wallet.json (user responsibility)
• Never transmitted over network
• Displayed once during creation

Private Key Derivation

• Keys derived on-demand from mnemonic
• Never stored separately
• WIF export for node import only

Container Isolation

• Services run in Docker containers
• Network isolation via Docker network
• Volume mounts for persistent data only

Extension Points

Adding New Services

1. Add service definition to services.yaml
2. Define parameters, ports, volumes
3. Service automatically appears in menu

Custom Actions

Services can define custom commands:

command:
  binary: "bitcoin-cli"
  arguments: ["getblockchaininfo"]
  show_output: true

Localization

All UI strings centralized in Strings.cs:

• Can be extended for multiple languages
• Consistent formatting

---

← CLI Reference | Home