Skip to content

Latest commit

 

History

History
265 lines (207 loc) · 9.21 KB

CLAUDE.md

File metadata and controls

265 lines (207 loc) · 9.21 KB

Dash Core Development Guide

Overview

Dash Core is the reference implementation for Dash, a cryptocurrency. It builds on top of Bitcoin Core, a codebase that is primarily written in C++20 (requiring at least Clang 16 or GCC 11.1). Dash Core uses the GNU Autotools build system.

Directory Structure

  • Implementation src/ - C++20 codebase
    • src/bench/ - Performance benchmarks (uses nanobench)
    • src/fuzz/ - Fuzzing harnesses
    • src/index/ - Optional indexes
    • src/interfaces/ - Interfaces for codebase isolation and inter-process communication
    • src/qt/ - Implementation of Dash Qt, the GUI (uses Qt 5)
    • src/rpc/ - JSON-RPC server and endpoints
    • src/util/ - Utility functions
    • src/wallet/ - Wallet implementation (uses Berkeley DB and SQLite)
    • src/zmq/ - ZeroMQ notification support for real-time event publishing
  • Unit Tests
    • src/test/, src/wallet/test/ - C++20 unit tests (uses Boost::Test)
    • src/qt/test/ - C++20 unit tests for GUI implementation (uses Qt 5)
  • Functional Tests: test/functional/ - Python tests (minimum version in .python-version) dependent on dashd and dash-node

Directories to Exclude

Under any circumstances, do not make changes to:

  • guix-build* - Build system files
  • releases - Release artifacts
  • Vendored dependencies:
    • src/{crc32c,dashbls,gsl,immer,leveldb,minisketch,secp256k1,univalue}
    • src/crypto/{ctaes,x11}

Unless specifically prompted, avoid:

  • .github - GitHub workflows and configs
  • depends - Dependency build system
  • ci - Continuous integration
  • contrib - Contributed scripts
  • doc - Documentation

Build Commands

Setup and Build

# Generate build system
./autogen.sh

# Build dependencies for the current platform
make -C depends -j"$(( $(nproc) - 1 ))" | tail 5

# Configure with depends (use the path shown in depends build output)
# Example paths: depends/x86_64-pc-linux-gnu, depends/aarch64-apple-darwin24.3.0
./configure --prefix=$(pwd)/depends/[platform-triplet]

# Developer configuration (recommended)
./configure --prefix=$(pwd)/depends/[platform-triplet] \
            --disable-hardening \
            --enable-crash-hooks \
            --enable-debug \
            --enable-reduce-exports \
            --enable-stacktraces \
            --enable-suppress-external-warnings \
            --enable-werror

# Build with parallel jobs (leaving one core free)
make -j"$(( $(nproc) - 1 ))"

Testing Commands

Unit Tests

# Run all unit tests
make check

# Run specific test (e.g. getarg_tests)
./src/test/test_dash --run_test=getarg_tests

# Debug unit tests
gdb ./src/test/test_dash

Functional Tests

# Run all functional tests
test/functional/test_runner.py

# Run specific test
test/functional/wallet_hd.py

# Extended test suite
test/functional/test_runner.py --extended

# Parallel execution
test/functional/test_runner.py -j$(nproc)

# Debug options
test/functional/test_runner.py --nocleanup --tracerpc -l DEBUG

Code Quality

# Run all linting
test/lint/all-lint.py

# Common individual checks
test/lint/lint-python.py
test/lint/lint-shell.py
test/lint/lint-whitespace.py
test/lint/lint-circular-dependencies.py

High-Level Architecture

Dash Core extends Bitcoin Core through composition, using a layered architecture:

Dash Core Components
├── Bitcoin Core Foundation (Blockchain, consensus, networking)
├── Masternodes (Infrastructure)
│   ├── LLMQ (Quorum infrastructure)
│   │   ├── InstantSend (Transaction locking)
│   │   ├── ChainLocks (Block finality)
│   │   ├── EHF Signals (Hard fork coordination)
│   │   └── Platform/Evolution (Credit Pool, Asset Locks)
│   ├── CoinJoin (Coin mixing)
│   └── Governance Voting (Masternodes vote on proposals)
├── Governance System (Proposal submission/management)
└── Spork System (Feature control)

Key Architectural Components

Masternodes (src/masternode/, src/evo/)

  • Deterministic Masternode Lists: Consensus-critical registry using immutable data structures
  • Active Masternode Manager: Local masternode operations and BLS key handling
  • Special Transactions: ProRegTx, ProUpServTx, ProUpRegTx, ProUpRevTx for masternode lifecycle

Long-Living Masternode Quorums (src/llmq/)

  • Quorum Types: Multiple configurations (50/60, 400/60, 400/85) for different services
  • Distributed Key Generation: Cryptographically secure quorum formation
  • Services: ChainLocks (51% attack prevention), InstantSend, governance voting

CoinJoin Privacy (src/coinjoin/)

  • Mixing Architecture: Masternode-coordinated mixing sessions
  • Denomination: Uniform outputs for privacy
  • Session Management: Multi-party transaction construction

Governance (src/governance/)

  • Governance Objects: Proposals, triggers, superblock management
  • Treasury: Automated payouts based on governance votes
  • Voting: On-chain proposal voting and tallying

Evolution Database (src/evo/evodb)

  • Specialized Storage: Masternode snapshots, quorum state, governance objects
  • Efficient Updates: Differential updates for masternode lists
  • Credit Pool Management: Platform integration support

Dash-Specific Databases

  • CFlatDB: A Dash-specific flat file database format used for persistent storage
    • MasternodeMetaStore: Masternode metadata persistence
    • GovernanceStore: Governance object storage
    • SporkStore: Spork state persistence
    • NetFulfilledRequestStore: Network request tracking
  • CDBWrapper: Bitcoin Core database wrapper extended for Dash-specific data
    • CDKGSessionManager: LLMQ DKG session persistence
    • CEvoDb: Specialized database for Evolution/deterministic masternode data
    • CInstantSendDb: InstantSend lock persistence
    • CQuorumManager: Quorum state storage
    • CRecoveredSigsDb: LLMQ recovered signature storage

Integration Patterns

Initialization Flow

  1. Basic Setup: Core Bitcoin initialization
  2. Parameter Interaction: Dash-specific configuration validation
  3. Interface Setup: Dash manager instantiation in NodeContext
  4. Main Initialization: EvoDb, masternode system, LLMQ, governance startup

Consensus Integration

  • Block Validation Extensions: Special transaction validation
  • Mempool Extensions: Enhanced transaction relay
  • Chain State Extensions: Masternode list and quorum state tracking
  • Fork Prevention: ChainLocks prevent reorganizations

Key Design Patterns

  • Manager Pattern: Centralized managers for each subsystem
  • Event-Driven Architecture: ValidationInterface callbacks coordinate subsystems
  • Immutable Data Structures: Efficient masternode list management using Immer library
  • Extension Over Modification: Minimal changes to Bitcoin Core foundation

Critical Interfaces

  • NodeContext: Central dependency injection container
  • LLMQContext: LLMQ-specific context and state management
  • ValidationInterface: Event distribution for block/transaction processing
  • ChainstateManager: Enhanced with Dash-specific validation
  • Chainstate Initialization: Separated into src/node/chainstate.*
  • Special Transaction Serialization: Payload serialization routines (src/evo/specialtx.h)
  • BLS Integration: Cryptographic foundation for advanced features

Development Workflow

Common Tasks

# Clean build
make clean

# Run dashd with debug logging
./src/dashd -debug=all -printtoconsole

# Run functional test with custom dashd
test/functional/test_runner.py --dashd=/path/to/dashd

# Generate compile_commands.json for IDEs
bear -- make -j"$(( $(nproc) - 1 ))"

Debugging

# Debug dashd
gdb ./src/dashd

# Profile performance
test/functional/test_runner.py --perf
perf report -i /path/to/datadir/test.perf.data --stdio | c++filt

# Memory debugging
valgrind --leak-check=full ./src/dashd

GitHub CI Debugging with gh CLI

# Get detailed check info with JSON output
gh pr checks <PR_NUMBER> --json name,state,link,description

# Filter for failed or pending checks
gh pr checks <PR_NUMBER> --json name,state,link --jq '.[] | select(.state == "FAILURE" or .state == "PENDING")'

# View logs from a specific CI job
gh api repos/dashpay/dash/actions/jobs/<JOB_ID>/logs

# Filter failed jobs and steps from a run
gh run view <RUN_ID> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name, conclusion}'

# Example: Get lint failure logs for PR 6691
# gh api repos/dashpay/dash/actions/jobs/46274126203/logs

Branch Structure

  • master: Stable releases
  • develop: Active development (built and tested regularly)

Important Notes

  • Use make -j"$(( $(nproc) - 1 ))" for parallel builds (leaves one core free)
  • Always run linting before commits: test/lint/all-lint.py
  • For memory-constrained systems, use special CXXFLAGS during configure
  • Special transactions use payload extensions - see src/evo/specialtx.h
  • Masternode lists use immutable data structures (Immer library) for thread safety
  • LLMQ quorums have different configurations for different purposes
  • Dash uses unordered_lru_cache for efficient caching with LRU eviction
  • The codebase extensively uses Dash-specific data structures for performance