HD Wallet Security

Referenced Files in This Document - crypto.py - config.py - server.py - dependencies.py - payments.py - payment.py - transaction.py - manager.py - base.py - w3.py - scanner.py - sweeper.py - listener.py - sweeper_worker.py - requirements.txt - 2026_01_27_1807-5ec6405addd0_initial_database_schema.py

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides comprehensive security documentation for the Hierarchical Deterministic (HD) wallet implementation in the cTrip Payment Gateway. It focuses on the BIP-44 derivation path m/44'/60'/0'/0/{index}, cryptographic foundations, mnemonic generation and storage, private key derivation, seed protection, address generation, checksum validation, secure initialization patterns, backup and disaster recovery, production deployment guidelines, key management best practices, and vulnerability assessments. It also outlines remediation strategies for common pitfalls in HD wallet implementations.

Project Structure

The HD wallet functionality is centered around a dedicated manager that derives Ethereum addresses using BIP-44. The system integrates with blockchain providers, database persistence for payment and address records, and background workers for scanning and sweeping. Initialization occurs during application startup, and runtime access is provided via FastAPI dependency injection.

graph TB subgraph "Application" API["FastAPI App
server.py"] Deps["Dependencies
dependencies.py"] Payments["Payments API
payments.py"] Config["Settings & Secrets
config.py"] Crypto["HDWallet Manager
crypto.py"] end subgraph "Blockchain Layer" Manager["Blockchain Manager
manager.py"] Base["Base Provider
base.py"] W3["W3 Accessor
w3.py"] end subgraph "Persistence" DB["Database Models
payment.py, transaction.py"] Alembic["Schema Migration
2026_01_27_1807-5ec6405addd0_initial_database_schema.py"] end subgraph "Workers" Listener["Listener Worker
listener.py"] SweeperWorker["Sweeper Worker
sweeper_worker.py"] Scanner["Scanner Service
scanner.py"] Sweeper["Sweeper Service
sweeper.py"] end API --> Deps API --> Payments Payments --> Crypto Payments --> Manager Manager --> Base Base --> W3 Payments --> DB DB --> Alembic Listener --> Scanner SweeperWorker --> Sweeper Sweeper --> Crypto Config --> API

Diagram sources - server.py - dependencies.py - payments.py - config.py - crypto.py - manager.py - base.py - w3.py - payment.py - transaction.py - listener.py - sweeper_worker.py - scanner.py - sweeper.py - 2026_01_27_1807-5ec6405addd0_initial_database_schema.py

Section sources - server.py - dependencies.py - payments.py - config.py - crypto.py - manager.py - base.py - w3.py - payment.py - transaction.py - listener.py - sweeper_worker.py - scanner.py - sweeper.py - 2026_01_27_1807-5ec6405addd0_initial_database_schema.py

Core Components

  • HDWalletManager: Implements BIP-44 derivation for Ethereum addresses, mnemonic generation, seed derivation, and address derivation with checksum validation.
  • Settings: Centralized configuration including mnemonic and private key fields with validation.
  • Blockchain Layer: Provider abstraction and Web3 integration for chain connectivity and transaction building/signing.
  • Persistence: SQLAlchemy models for payments and HD wallet addresses, with Alembic migrations defining schema.
  • Workers: Background tasks for scanning and sweeping, interacting with the HD wallet and blockchain providers.

Key security-relevant responsibilities: - Mnemonic handling and seed derivation - Private key derivation and usage - Address derivation and checksum validation - Secure initialization and dependency injection - Production secrets validation

Section sources - crypto.py - config.py - base.py - payment.py - 2026_01_27_1807-5ec6405addd0_initial_database_schema.py

Architecture Overview

The HD wallet is initialized at application startup and exposed via a dependency for API endpoints. Payments requests derive a new payment address per request using BIP-44. Background workers scan for incoming payments and later sweep funds into an administrative wallet derived from a private key.

sequenceDiagram participant Client as "Client" participant API as "Payments API
payments.py" participant Dep as "Dependency Resolver
dependencies.py" participant HD as "HDWalletManager
crypto.py" participant DB as "Database
payment.py" Client->>API : "POST /api/v1/payments" API->>Dep : "get_hdwallet()" Dep-->>API : "HDWalletManager instance" API->>HD : "get_address(index=0)" HD-->>API : "{address, path}" API->>DB : "Persist Payment record" API-->>Client : "PaymentRead"

Diagram sources - payments.py - dependencies.py - crypto.py - payment.py

Section sources - server.py - dependencies.py - payments.py - crypto.py

Detailed Component Analysis

HDWalletManager Security Analysis

  • BIP-44 Derivation: Uses path m/44'/60'/0'/0/{index} for Ethereum, ensuring deterministic derivation and hierarchical structure.
  • Mnemonic Generation: Generates a 12-word mnemonic when none is provided, suitable for secure backup and recovery.
  • Seed Derivation: Derives a seed from the mnemonic with an empty passphrase, aligning with BIP-39 standards.
  • Private Key Derivation: Derives private keys from the seed and path, then creates accounts for checksummed address generation.
  • Address Derivation Security: Relies on the underlying library’s checksum validation for Ethereum addresses.

Security considerations: - Mnemonic exposure: The mnemonic must be treated as a secret and protected at rest and in transit. - Seed protection: Ensure seeds are not logged or persisted unnecessarily. - Path hardening: The path uses hardened indices for purpose, coin type, and account; this prevents certain attacks but does not replace proper secret protection. - Entropy sources: Mnemonic generation relies on the underlying library’s secure randomness.

classDiagram class HDWalletManager { +mnemonic +seed +__init__(mnemonic_phrase) +get_address(index) dict +get_multiple_addresses(count, start_index) list +get_mnemonic() str }

Diagram sources - crypto.py

Section sources - crypto.py

Settings and Secret Management

  • Mnemonic field: Stored as a configurable setting with a default placeholder in development.
  • Private key validation: Validates Ethereum private keys and enforces production secret key changes.
  • Environment-specific behavior: Selects database URLs based on environment and loads chain configurations from YAML.

Security considerations: - Never commit secrets; use environment variables and secure secret stores. - Ensure production environments override defaults. - Validate and sanitize configuration inputs.

flowchart TD Start(["Load Settings"]) --> CheckEnv["Check env field"] CheckEnv --> SetDBURL["Set database_url dynamically"] SetDBURL --> LoadChains["Load chains from YAML"] LoadChains --> ValidatePrivKey["Validate private_key"] ValidatePrivKey --> ValidateSecretKey["Validate/Enforce secret_key change in production"] ValidateSecretKey --> End(["Settings Ready"])

Diagram sources - config.py

Section sources - config.py

Blockchain Provider Integration

  • Provider abstraction supports POA networks and caches gas prices.
  • Transaction building includes EIP-1559 fee calculation with fallback to legacy pricing.
  • Transaction signing and sending use the Account library with provided private keys.

Security considerations: - Validate provider URLs and network IDs. - Ensure gas estimation and fee calculations are performed securely. - Avoid exposing private keys in logs or error messages.

sequenceDiagram participant BC as "BlockchainBase
base.py" participant W3 as "Web3 Provider" participant Acc as "Account Library" BC->>W3 : "Connect and configure middleware" BC->>W3 : "Fetch gas price/fee history" BC->>Acc : "Sign transaction with private key" BC->>W3 : "Send raw transaction" W3-->>BC : "Transaction receipt"

Diagram sources - base.py

Section sources - base.py

Payment Address Generation and Persistence

  • API endpoint derives a payment address using the HD wallet manager and persists the payment record with chain, amount, and expiration.
  • Database schema includes an HD wallet addresses table for tracking derived addresses.

Security considerations: - Ensure address uniqueness and prevent reuse across payments. - Persist only necessary fields; avoid storing mnemonics or private keys. - Apply appropriate indexing and constraints for performance and integrity.

erDiagram PAYMENT { uuid id PK uuid token_id FK string chain string address numeric amount enum status integer confirmations integer detected_in_block timestamp expires_at timestamp created_at } HDWALLET_ADDRESS { uuid id PK string address bigint index string is_swapped timestamp created_at } TOKEN { uuid id PK string chain string address string symbol integer decimals boolean enabled } TOKEN ||--o{ PAYMENT : "references"

Diagram sources - payment.py - 2026_01_27_1807-5ec6405addd0_initial_database_schema.py

Section sources - payments.py - payment.py - 2026_01_27_1807-5ec6405addd0_initial_database_schema.py

Background Workers and Sweeping

  • Listener worker periodically scans blocks for incoming payments and updates statuses.
  • Sweeper worker moves confirmed funds to an administrative wallet derived from a private key.
  • Both workers initialize their own HD wallet instances for sweeping operations.

Security considerations: - Keep sweeping private keys separate from operational mnemonics. - Limit sweeping to minimal necessary permissions. - Monitor and alert on sweeping failures.

sequenceDiagram participant Worker as "Sweeper Worker
sweeper_worker.py" participant Sweeper as "SweeperService
sweeper.py" participant HD as "HDWalletManager
crypto.py" participant Config as "Settings
config.py" participant Chain as "BlockchainBase
base.py" Worker->>Sweeper : "Initialize with session and HD manager" Sweeper->>Config : "Load private_key" Sweeper->>HD : "Derive admin account from private key" Sweeper->>Chain : "Transfer funds to admin address"

Diagram sources - sweeper_worker.py - sweeper.py - config.py - base.py

Section sources - listener.py - sweeper_worker.py - scanner.py - sweeper.py

Dependency Analysis

External libraries and their roles: - eth-account: Provides mnemonic generation, seed derivation, and private/public key/account operations. - web3: Ethereum JSON-RPC client and transaction utilities. - pydantic/pydantic-settings: Configuration loading and validation. - arq: Background task processing.

graph TB Crypto["HDWalletManager
crypto.py"] --> EthAccount["eth-account"] Base["BlockchainBase
base.py"] --> Web3["web3"] Config["Settings
config.py"] --> Pydantic["pydantic/pydantic-settings"] Listener["Listener Worker
listener.py"] --> ARQ["arq"] SweeperWorker["Sweeper Worker
sweeper_worker.py"] --> ARQ

Diagram sources - crypto.py - base.py - config.py - requirements.txt - listener.py - sweeper_worker.py

Section sources - requirements.txt

Performance Considerations

  • Gas price caching reduces repeated RPC calls.
  • Batch block scanning limits per cycle to control resource usage.
  • Transaction gas limits include a small buffer to reduce rejections.

Recommendations: - Tune block batch sizes and polling intervals based on chain conditions. - Monitor RPC latency and adjust timeouts accordingly. - Use fee history for dynamic fee estimation under EIP-1559 networks.

Section sources - base.py - scanner.py

Troubleshooting Guide

Common issues and remediations: - HD wallet not initialized: Ensure the application lifespan initializes the HD wallet manager and exposes it via state. - Unsupported chain errors: Verify chain configurations and provider URLs. - Private key validation failures: Confirm the private key is a valid Ethereum key and environment-specific overrides are applied. - Sweeper failures: Check administrative private key validity and network connectivity.

Operational checks: - Validate mnemonic and private key presence in settings. - Confirm database connectivity and migration status. - Review worker logs for recurring errors and schedule adjustments.

Section sources - server.py - dependencies.py - config.py - payments.py - sweeper.py

Conclusion

The cTrip Payment Gateway implements a secure, deterministic HD wallet using BIP-44 for Ethereum payment addresses. The design separates operational mnemonics from administrative private keys, validates secrets at runtime, and persists only necessary data. By following the production deployment guidelines, key management best practices, and remediation strategies outlined here, the system can maintain strong security posture while remaining operationally robust.

Appendices

BIP-44 Derivation Path Security

  • Path: m/44'/60'/0'/0/{index}
  • Purpose: BIP-44 purpose (44'), Ethereum coin type (60'), account (0'), change (external chain 0), and index for sequential addresses.
  • Hardening: Hardened indices at purpose, coin type, and account mitigate certain attack vectors.
  • Implications: Even if an attacker gains access to a derived public key, they cannot derive prior siblings without the seed.

Section sources - crypto.py - crypto.py

Mnemonic Generation, Storage, and Rotation

  • Generation: 12-word mnemonic generated securely when none is provided.
  • Storage: Store mnemonics encrypted at rest and restrict access to authorized processes.
  • Rotation: Replace mnemonics during controlled maintenance windows; re-derive addresses and update backups.

Section sources - crypto.py - config.py

Private Key Derivation and Seed Protection

  • Derivation: Seed derived from mnemonic; private keys derived deterministically from seed and path.
  • Protection: Avoid logging seeds or private keys; use environment variables and secret managers.
  • Entropy: Rely on the library’s secure randomness for mnemonic generation.

Section sources - crypto.py - crypto.py

Address Generation Security and Checksum Validation

  • Derivation: Addresses derived via private keys and validated with checksums.
  • Validation: Ensure checksummed addresses are used consistently across the system.

Section sources - crypto.py

Secure Initialization Patterns

  • Application lifespan: Initialize blockchain providers and HD wallet manager during startup.
  • Dependency injection: Expose HD wallet via dependency resolver to API endpoints.
  • Configuration: Load settings from environment and validate secrets.

Section sources - server.py - dependencies.py - config.py

Backup and Disaster Recovery

  • Backup strategies: Maintain offline, encrypted backups of mnemonics and administrative private keys.
  • Recovery procedures: Test restoration in isolated environments; rotate keys after breach discovery.

Section sources - crypto.py - config.py

Production Deployment Guidelines

  • Secrets management: Use environment variables and secret stores; never embed in code.
  • Network isolation: Restrict access to private key material and mnemonic backups.
  • Monitoring: Log security-relevant events without sensitive data; alert on failures.

Section sources - config.py - requirements.txt

Vulnerability Assessment for Wallet Components

  • Risk areas: Mnemonic exposure, insecure storage, weak entropy, improper key separation, insufficient validation.
  • Controls: Enforce secret validation, encrypt at rest, restrict access, audit logs, and regular penetration testing.

Section sources - config.py - crypto.py

Common Security Pitfalls and Remediation

  • Pitfall: Storing plaintext mnemonics or private keys.
  • Remediation: Encrypt and restrict access; use secret managers.
  • Pitfall: Using default secrets in production.
  • Remediation: Enforce environment-specific overrides and validation.
  • Pitfall: Logging sensitive data.
  • Remediation: Sanitize logs; avoid printing mnemonics or private keys.
  • Pitfall: Mixing operational and administrative keys.
  • Remediation: Separate HD wallet for payments and administrative private key for sweeping.

Section sources - config.py - sweeper.py