Contributing to BTQ Core

BTQ follows a maintainer-led governance model inspired by Bitcoin Core, emphasizing technical merit, peer review, and transparent decision-making.

Getting Started

Prerequisites

1. Familiarity with C++ and Bitcoin's architecture
2. Understanding of post-quantum cryptography (helpful but not required)
3. Git and GitHub workflow knowledge

Development Setup

# Clone the repository
git clone https://github.com/btq-ag/btq-core.git
cd btq-core

# Build
./autogen.sh
./configure --enable-debug
make -j$(nproc)

# Run tests
make check
./test/functional/test_runner.py

Contribution Workflow

1. Find or Create an Issue

• Check existing issues for something to work on
• Create an issue for new features or bugs
• Discuss approach before starting large changes

2. Create a Branch

git checkout -b feature/my-feature
# or
git checkout -b fix/my-bugfix

3. Make Changes

• Follow the code style guide
• Add tests for new functionality
• Update documentation as needed

4. Test Your Changes

# Unit tests
make check

# Specific test
./src/test/test_btq --run_test=dilithium_key_tests

# Functional tests
./test/functional/test_runner.py

# Lint checks
./test/lint/lint-all.sh

5. Submit a Pull Request

• Use a clear, descriptive title
• Reference related issues
• Include test instructions
• Be responsive to feedback

Code Review Culture

BTQ uses Bitcoin Core's ACK/NACK review system:

Review Checklist

• Code correctness and edge cases
• Test coverage for changes
• Documentation updates
• Performance implications
• Security considerations (especially for crypto code)

Merge Requirements

• Minimum 2 ACKs from reviewers
• Domain expert ACK for consensus/cryptographic changes
• All CI tests passing
• Public review on GitHub (no private approvals)

Roles

Coding Standards

C++ Style

• Follow Bitcoin Core's coding style
• Use clang-format for formatting
• Prefer clear code over clever code
• Add comments for complex logic

Commit Messages

component: Short summary (50 chars max)

Longer description of the change, why it's needed,
and any important implementation details.

- Use bullet points for multiple changes
- Reference issues: Fixes #123

Documentation

• Update RPC help text for API changes
• Add entries to release notes for user-visible changes
• Keep code comments current

Testing Requirements

Unit Tests

Required for:

• New cryptographic functions
• Wallet key management
• Address encoding/decoding
• Script evaluation

Location: src/test/

Functional Tests

Required for:

• RPC endpoint changes
• Wallet operations
• Network behavior

Location: test/functional/

Fuzz Testing

Required for:

• Parsers and deserializers
• Signature verification
• Address validation

Location: src/test/fuzz/

Security

Reporting Vulnerabilities

Do NOT open public issues for security vulnerabilities.

Contact: [email protected]

Include:

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

Security Review

All cryptographic changes require:

• Domain expert review
• Additional scrutiny for consensus impact
• Consideration of side-channel attacks

Release Process

1. Feature Freeze: Cut release branch
2. Release Candidate: Tag vX.Y.Zrc1
3. Testing Period: Community testing
4. Final Release: Tag vX.Y.Z
5. Announcement: GitHub + channels

Releases use deterministic Guix builds with multi-party signatures.

Communication

Dilithium-Specific Guidelines

When working on Dilithium code:

Key Management

• Always use memory_cleanse() for secret key cleanup
• Use proper key ID derivation (not dummy values)
• Test both encrypted and unencrypted wallets

Signatures

• Handle 2,420-byte signatures correctly
• Append sighash type byte properly
• Skip DER checks for large signatures

Scripts

• Use OP_CHECKSIGDILITHIUM for Dilithium verification
• Auto-detect based on pubkey size (>100 bytes = Dilithium)
• Construct witness stacks correctly: [signature, pubkey]

Testing

Run the Dilithium test suite:

# Unit tests
./src/test/test_btq --run_test=dilithium_key_tests
./src/test/test_btq --run_test=dilithium_address_script_tests
./src/test/test_btq --run_test=dilithium_wallet_tests
./src/test/test_btq --run_test=dilithium_descriptor_tests

# Manual testing
./test_dilithium_wallet.sh

Resources

• Bitcoin Core Developer Notes
• Dilithium Integration Phases
• Testing Guide

Questions?

Open a GitHub Discussion or reach out to the maintainers.