QBitcoin Documentation

Qbitcoin is a next-generation blockchain platform designed to be quantum-resistant using post-quantum cryptographic signatures. Built with Python, it implements the Falcon-512 signature scheme to ensure security against both classical and quantum computer attacks.

Post-Quantum Cryptography

• Falcon-512 Signatures: NIST-standardized post-quantum cryptographic algorithm
• Quantum Resistance: Secure against attacks from quantum computers
• Future-Proof: Maintains security as quantum computing advances

Advanced Blockchain Features

• Proof-of-Work Consensus: Secure mining-based consensus mechanism
• Multi-Signature Support: Complex transaction authorization schemes
• Custom Tokens: Create and manage your own tokens
• Smart Contracts: Programmable transaction logic

User-Friendly Interfaces

• Web-Based GUI: Modern browser interface for node management
• Desktop Application: Native desktop application with full features
• Command Line Interface: Powerful CLI for advanced users
• RESTful APIs: Complete API access for developers

Network Architecture

• Peer-to-Peer Network: Decentralized node communication
• Mining Support: Solo and pool mining capabilities
• Real-time Monitoring: Live blockchain and network statistics

Core Concepts

Addresses and Keys

• Falcon-512 Keys: Each wallet uses post-quantum cryptographic keys
• Address Format: 25-byte addresses with Q prefix: Network byte (0x01) + RIPEMD160(SHA256(PublicKey)) + Checksum
• Key Sizes: Public keys are 897 bytes, private keys are 1281 bytes

Transactions

• Transfer Transactions: Send QBC coins between addresses
• Token Transactions: Create and transfer custom tokens
• Multi-Signature Transactions: Require multiple signatures for authorization
• Message Transactions: Embed messages in the blockchain

Mining

• Proof-of-Work: Uses computational puzzles to secure the network
• Block Rewards: Miners receive QBC for successfully mining blocks
• Difficulty Adjustment: Network automatically adjusts mining difficulty
• Solo and Pool Mining: Multiple mining options available

Why Qbitcoin?

Quantum Security

Traditional cryptocurrencies like Bitcoin use ECDSA signatures, which are vulnerable to quantum computer attacks. Qbitcoin uses Falcon-512, a NIST-approved post-quantum signature scheme that remains secure even against quantum computers.

Developer Friendly

Built with Python and modern frameworks, Qbitcoin is easy to understand, modify, and extend. The codebase includes comprehensive documentation and examples.

Future-Ready

As quantum computing technology advances, cryptocurrencies will need quantum-resistant security. Qbitcoin is built from the ground up with this future in mind.

Technical Specifications

This guide will walk you through installing Qbitcoin on different operating systems.

System Requirements

Minimum Requirements

• OS: Linux (Ubuntu 18.04+), macOS (10.14+), Windows 10+
• RAM: 4 GB minimum, 8 GB recommended
• Storage: 20 GB free space for blockchain data
• CPU: Dual-core processor, quad-core recommended
• Network: Stable internet connection

Recommended Requirements

• RAM: 8 GB or more
• Storage: SSD with 50+ GB free space
• CPU: 4+ cores for efficient mining
• Network: High-speed broadband connection

Prerequisites

Python Installation

Qbitcoin requires Python 3.9 or higher. Python 3.10+ is recommended.

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3 python3-pip python3-venv git

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python git

Windows

1. Download Python 3.9+ from python.org
2. Install Git from git-scm.com
3. Ensure Python and Git are added to PATH

Installation Methods

Method 1: Using pip (Recommended)

1. Install Qbitcoin via pip

   pip install qbitcoin

2. Install build dependencies

   # Ubuntu/Debian
   sudo apt install -y build-essential cmake swig python3-dev libssl-dev libboost-all-dev libuv1-dev
   
   # CentOS/RHEL
   sudo yum groupinstall "Development Tools"
   sudo yum install cmake swig python3-devel openssl-devel boost-devel libuv-devel
   
   # macOS
   brew install cmake swig boost libuv

3. Run the smart installer

   python3 -m qbitcoin.smart_installer

4. Start the node

   qbitcoin

Method 2: Development Installation (From Source)

1. Clone the repository

   git clone https://github.com/qbitcoin/qbitcoin.git
   cd qbitcoin

2. Install build dependencies

   sudo apt install -y build-essential cmake swig python3-dev libssl-dev libboost-all-dev libuv1-dev

3. Create virtual environment

   python3 -m venv qbitcoin-env
   source qbitcoin-env/bin/activate  # On Windows: qbitcoin-env\Scripts\activate

4. Install dependencies

   pip install -r requirements.txt

5. Start the node

   python start_qbitcoin.py

Post-Installation Setup

1. Configuration

After installation, the smart installer will create your configuration:

# Configuration will be created automatically at:
# ~/.qbitcoin/config.yml (Linux/macOS)
# %APPDATA%\qbitcoin\config.yml (Windows)

2. Start the Node

# If installed via pip
qbitcoin

# If using development installation
python start_qbitcoin.py

3. Create Your First Wallet

Open a new terminal while the node is running:

# Using the CLI tool
python -m qbitcoin.cli wallet_gen

# Or if installed globally
qbitcoin-cli wallet_gen

Verification

Check Node Status

# Using CLI
python -m qbitcoin.cli state

# Or check with gRPC
grpcurl -plaintext localhost:19009 qrl.PublicAPI/GetNodeState

Check Wallet

# List wallet addresses
python -m qbitcoin.cli wallet_ls

# Check specific address balance  
python -m qbitcoin.cli balance Q01050...

Test API Connection

# Test Public API
curl -X POST http://localhost:19009 \
  -H "Content-Type: application/json" \
  -d '{"method": "GetNodeState"}'

Common Installation Issues

Issue 1: Python Version Error

Error: "This application requires at least Python 3.5"

Solution: Update Python to version 3.5 or higher

Issue 2: Missing Dependencies

Error: "ModuleNotFoundError: No module named 'falcon'"

Solution: Ensure you're in the virtual environment and run:

pip install -r requirements.txt

Issue 3: Permission Errors (Linux/macOS)

Error: "Permission denied"

Solution: Use proper file permissions or run with sudo if necessary

Issue 4: Port Already in Use

Error: "Address already in use"

Solution: Check if another instance is running or change the port in configuration

Welcome to Qbitcoin! This guide will get you up and running in 15 minutes.

What You'll Learn

By the end of this guide, you'll have:

• ✅ A running Qbitcoin node
• ✅ A wallet with your first addresses
• ✅ Basic understanding of key commands
• ✅ Connected to the Qbitcoin network

Before You Start

Make sure you have:

• ☐ Completed installation
• ☐ At least 4 GB RAM available
• ☐ Stable internet connection
• ☐ 20+ GB free disk space

Step 1: First Launch (2 minutes)

Start Your Node

Open terminal in your Qbitcoin directory and run:

python start_qbitcoin.py

You should see output like:

[INFO] Qbitcoin Node Starting...
[INFO] Loading configuration...
[INFO] Initializing blockchain...
[INFO] Starting P2P network...
[INFO] Node is ready on port 9000

🎉 Congratulations! Your node is now running.

Stop Your Node

To stop the node, press Ctrl+C in the terminal.

Step 2: Create Your First Wallet

Generate New Wallet

python -m qbitcoin.cli wallet_gen

You'll be prompted to:

1. Set a password (remember this!)
2. Backup your wallet file (secure storage is essential!)

Example output:

Enter wallet password: ********
Confirm password: ********

🔐 Wallet created successfully!

Wallet address: Q01050058bb3f8cb66fd90d0347478e5bdf3a475e82cfc5fe5dc276500ca21531e6edaf3d2d0f7e

IMPORTANT: Your wallet contains Falcon-512 keys:
- Public Key: 897 bytes
- Private Key: 1281 bytes (encrypted in wallet file)

Backup your wallet file securely!

Step 3: Check Your Wallet (1 minute)

View Wallet Information

python -m qbitcoin.cli wallet_ls

Output:

💰 Wallet Information:
Balance: 0.00000000 QBC
Addresses: 1
Status: Ready

Generate New Address

python -m qbitcoin.cli wallet_add

Step 4: Start the GUI (Optional - 2 minutes)

Launch Desktop Interface

python gui/qbitcoin_gui.py

This opens a user-friendly desktop application with:

• 📊 Real-time balance and transactions
• 🏗️ Built-in mining interface
• 📤 Easy transaction sending
• ⚙️ Configuration management

Step 5: Connect to Network (5 minutes)

Check Network Status

python -m qbitcoin.cli state

Expected output:

🌐 Network Information:
Connected Peers: 8
Network: mainnet
Sync Status: Syncing (45.2%)
Best Block: 125,847

Monitor Synchronization

Your node needs to download the blockchain. This can take several hours depending on:

• Internet speed
• Computer performance
• Network congestion

Tip: Leave your node running overnight for initial sync.

Step 6: Basic Commands Reference

Node Operations

# Start node
python start_qbitcoin.py

# Start with testnet
python start_qbitcoin.py --network-type testnet

# Start with custom config
python start_qbitcoin.py --qrldir /custom/path

# Start with mining enabled
python start_qbitcoin.py --mining_thread_count 2 --miningAddress YOUR_ADDRESS

Wallet Operations

# Create new wallet
python -m qbitcoin.cli wallet_gen

# List wallet addresses
python -m qbitcoin.cli wallet_ls

# Add new address to wallet  
python -m qbitcoin.cli wallet_add

# Check address balance
python -m qbitcoin.cli balance <address>

Transaction Operations

# Send transaction
python -m qbitcoin.cli tx_transfer

# Create token transaction
python -m qbitcoin.cli tx_token

# Send token transfer
python -m qbitcoin.cli tx_transfertoken

# Send message transaction
python -m qbitcoin.cli tx_message

Mining Operations

# Start solo mining
python start_qbitcoin.py --mining_thread_count 4 --miningAddress YOUR_ADDRESS

# Start node with mining enabled
python start_qbitcoin.py --mining_thread_count 2

# Check node state
python -m qbitcoin.cli state

Next Steps

Now that you have Qbitcoin running:

1. 📖 Read the Wallet Creation Guide
2. 💰 Learn about Transactions
3. ⚡ Try Advanced CLI Commands
4. 🏗️ Set up Mining

This guide explains the post-quantum cryptographic features that make Qbitcoin quantum-resistant.

What is Post-Quantum Cryptography?

Post-quantum cryptography refers to cryptographic algorithms that are secure against attacks by both classical and quantum computers. Traditional cryptocurrencies like Bitcoin use ECDSA (Elliptic Curve Digital Signature Algorithm), which can be broken by sufficiently powerful quantum computers using Shor's algorithm.

The Quantum Threat

Why Qbitcoin is Different

Qbitcoin implements quantum-resistant algorithms that remain secure even against quantum computers, ensuring your cryptocurrency is future-proof.

Qbitcoin's Cryptographic Stack

1. FALCON Digital Signatures

Qbitcoin uses FALCON (Fast-Fourier Lattice-based Compact Signatures over NTRU) for digital signatures.

Key Features

• Quantum-resistant: Based on lattice problems that are hard for quantum computers
• Compact signatures: Smaller than many post-quantum alternatives
• Fast verification: Efficient signature verification process
• NIST standardized: Part of NIST's post-quantum cryptography standards

Technical Specifications

Security Level: NIST Level 1 (equivalent to AES-128)
Signature Size: ~690 bytes (FALCON-512)
Public Key Size: ~897 bytes
Private Key Size: ~1,281 bytes

2. Hash-Based Addresses

Qbitcoin addresses are derived using quantum-resistant hash functions:

Address Generation Process

1. Public Key Generation: Create FALCON public/private key pair
2. Hash Function: Apply SHA-256 to public key
3. Address Encoding: Encode with base58check and Qbitcoin prefix

Example Address Structure

Public Key (FALCON) → SHA-256 → RIPEMD-160 → Add 0x01 prefix → Add Checksum → Hex encode with Q prefix

3. Merkle Tree Signatures (Future)

Planned implementation of hash-based signatures for additional quantum resistance:

• XMSS (eXtended Merkle Signature Scheme)
• SPHINCS+ for stateless signatures

How FALCON Works

Mathematical Foundation

FALCON is based on the NTRU lattice problem, which involves:

1. Lattice-based cryptography: Uses mathematical structures called lattices
2. Ring-Learning with Errors: A specific type of lattice problem
3. Gaussian sampling: Advanced mathematical technique for signature generation

Signature Process

Key Generation

# Simplified representation
private_key = generate_falcon_private_key()
public_key = derive_public_key(private_key)

Signing Process

def sign_transaction(message, private_key):
    # 1. Hash the message
    hash_msg = sha256(message)
    
    # 2. Generate FALCON signature
    signature = falcon_sign(hash_msg, private_key)
    
    return signature

Verification Process

def verify_signature(message, signature, public_key):
    # 1. Hash the message
    hash_msg = sha256(message)
    
    # 2. Verify FALCON signature
    is_valid = falcon_verify(hash_msg, signature, public_key)
    
    return is_valid

Quantum Resistance Analysis

Security Levels

Timeline Considerations

Performance Comparison

Size Comparison

Speed Comparison

• Key Generation: FALCON is ~10x slower than ECDSA
• Signing: FALCON is ~5x slower than ECDSA
• Verification: FALCON is ~2x slower than ECDSA

Implementation in Qbitcoin

Transaction Signatures

Every transaction in Qbitcoin is signed using FALCON-512:

Transaction {
    inputs: [TransactionInput],
    outputs: [TransactionOutput],
    falcon_signatures: [FalconSignature]  // Quantum-resistant signatures
}

Address Generation

Qbitcoin addresses are quantum-resistant by design:

1. Generate FALCON-512 key pair
2. Extract public key (897 bytes)
3. Apply SHA-256 hash
4. Apply RIPEMD-160 hash
5. Add network prefix (0x01)
6. Add checksum (double SHA-256)
7. Hex encode with Q prefix

Future Quantum Resistance

Hybrid Approaches

Qbitcoin is designed to support multiple post-quantum algorithms:

• Current: FALCON-512 signatures
• Planned: SPHINCS+ for stateless signatures
• Research: XMSS for one-time signatures

Algorithm Agility

The Qbitcoin protocol supports algorithm upgrades through soft forks, ensuring long-term quantum resistance as new threats emerge.

Complete reference for Qbitcoin command-line interface (CLI).

Overview

The Qbitcoin CLI provides powerful command-line tools for:

• Node management and monitoring
• Wallet operations and transactions
• Mining control and optimization
• Network diagnostics and maintenance
• Configuration and administration

Basic Command Structure

Standard Format

python start_qbitcoin.py [OPTIONS] [COMMAND] [ARGS]

Global Options

--config PATH          # Specify custom configuration file
--data-dir PATH        # Set custom data directory
--network NAME         # Choose network (mainnet/testnet)
--port PORT           # Set custom port
--verbose             # Enable verbose logging
--quiet               # Suppress output
--help                # Show help information

Node Management Commands

Starting and Stopping

Start Node

# Start with default settings
python start_qbitcoin.py

# Start with custom configuration
python start_qbitcoin.py --config /path/to/config.yml

# Start on testnet
python start_qbitcoin.py --network testnet

# Start with custom port
python start_qbitcoin.py --port 9002

# Start with verbose logging
python start_qbitcoin.py --verbose

Stop Node

# Graceful shutdown (from another terminal)
python start_qbitcoin.py --stop

# Force stop (Ctrl+C in running terminal)

Node Information

Node Status

# Basic node information
python start_qbitcoin.py --node-info

# Detailed node status
python start_qbitcoin.py --node-status --verbose

# Check if node is running
python start_qbitcoin.py --ping

Example output:

🔗 Node Information:
Version: 1.0.0
Status: Running
Uptime: 2 hours, 34 minutes
Data Directory: /home/user/.qbitcoin
Network: mainnet
Port: 9000
Peers: 12

Network Information

# Network statistics
python start_qbitcoin.py --network-info

# Peer information
python start_qbitcoin.py --peers

# Connection status
python start_qbitcoin.py --connection-status

Blockchain Information

Blockchain Status

# Current blockchain height
python start_qbitcoin.py --height

# Sync status
python start_qbitcoin.py --sync-status

# Block information
python start_qbitcoin.py --block-info [BLOCK_HASH]

# Latest block
python start_qbitcoin.py --latest-block

Chain Statistics

# Blockchain statistics
python start_qbitcoin.py --chain-stats

# Difficulty information
python start_qbitcoin.py --difficulty

# Hash rate
python start_qbitcoin.py --hashrate

Wallet Commands

Wallet Management

Create Wallet

# Create new wallet
python start_qbitcoin.py --create-wallet

# Create named wallet
python start_qbitcoin.py --create-wallet --name "savings"

# Create wallet with custom path
python start_qbitcoin.py --create-wallet --wallet-path /path/to/wallet

Wallet Information

# Default wallet info
python start_qbitcoin.py --wallet-info

# Specific wallet
python start_qbitcoin.py --wallet-info --name "savings"

# List all wallets
python start_qbitcoin.py --list-wallets

# Wallet balance
python start_qbitcoin.py --balance

Address Management

Generate Addresses

# Generate new address
python start_qbitcoin.py --new-address

# Generate with label
python start_qbitcoin.py --new-address --label "Mining rewards"

# Generate multiple addresses
python start_qbitcoin.py --new-address --count 5

List Addresses

# List all addresses
python start_qbitcoin.py --list-addresses

# List with balances
python start_qbitcoin.py --list-addresses --with-balance

# List with labels
python start_qbitcoin.py --list-addresses --with-labels

Transaction Commands

Send Transactions

# Basic send
python start_qbitcoin.py --send RECIPIENT_ADDRESS AMOUNT

# Send with custom fee
python start_qbitcoin.py --send RECIPIENT_ADDRESS AMOUNT --fee 0.001

# Send from specific address
python start_qbitcoin.py --send RECIPIENT_ADDRESS AMOUNT --from SOURCE_ADDRESS

# Send with message
python start_qbitcoin.py --send RECIPIENT_ADDRESS AMOUNT --message "Payment for services"

# Send all balance
python start_qbitcoin.py --send-all RECIPIENT_ADDRESS

Transaction History

# List recent transactions
python start_qbitcoin.py --transactions

# List with limit
python start_qbitcoin.py --transactions --limit 50

# Get specific transaction
python start_qbitcoin.py --transaction TRANSACTION_ID

# List pending transactions
python start_qbitcoin.py --pending-transactions

Mining Commands

Mining Control

# Start mining
python start_qbitcoin.py --mine

# Start mining with specific threads
python start_qbitcoin.py --mine --threads 4

# Start mining to specific address
python start_qbitcoin.py --mine --mining-address YOUR_ADDRESS

# Stop mining
python start_qbitcoin.py --stop-mining

Mining Information

# Mining status
python start_qbitcoin.py --mining-info

# Hash rate
python start_qbitcoin.py --hashrate

# Mining statistics
python start_qbitcoin.py --mining-stats

# Set mining address
python start_qbitcoin.py --set-mining-address ADDRESS

Configuration Commands

Configuration Management

# Show current configuration
python start_qbitcoin.py --show-config

# Set configuration value
python start_qbitcoin.py --set-config KEY VALUE

# Reset to default configuration
python start_qbitcoin.py --reset-config

# Validate configuration
python start_qbitcoin.py --validate-config

Utility Commands

Data Management

# Backup wallet
python start_qbitcoin.py --backup-wallet [PATH]

# Restore wallet
python start_qbitcoin.py --restore-wallet PATH

# Import private key
python start_qbitcoin.py --import-key PRIVATE_KEY

# Export address
python start_qbitcoin.py --export-address ADDRESS

Network Utilities

# Add peer
python start_qbitcoin.py --add-peer IP:PORT

# Remove peer
python start_qbitcoin.py --remove-peer IP:PORT

# Ban peer
python start_qbitcoin.py --ban-peer IP

# Test connection
python start_qbitcoin.py --test-connection IP:PORT

Debug Commands

Debugging and Diagnostics

# Enable debug mode
python start_qbitcoin.py --debug

# Generate debug report
python start_qbitcoin.py --debug-report

# Check blockchain integrity
python start_qbitcoin.py --verify-chain

# Rebuild blockchain index
python start_qbitcoin.py --reindex

Command Examples

Common Workflows

Setup New Node

# 1. Create wallet
python start_qbitcoin.py --create-wallet

# 2. Generate mining address
python start_qbitcoin.py --new-address --label "Mining"

# 3. Start node
python start_qbitcoin.py

# 4. Start mining (in another terminal)
python start_qbitcoin.py --mine

Send Payment

# 1. Check balance
python start_qbitcoin.py --balance

# 2. Send payment
python start_qbitcoin.py --send qbitcoin1abc123... 10.5

# 3. Check transaction status
python start_qbitcoin.py --transactions --limit 1

Monitor Node

# Check node health
python start_qbitcoin.py --node-info
python start_qbitcoin.py --peers
python start_qbitcoin.py --sync-status

# Monitor mining
python start_qbitcoin.py --mining-info
python start_qbitcoin.py --hashrate

Keyboard Shortcuts

When running the node interactively:

• Ctrl+C - Graceful shutdown
• Ctrl+Z - Suspend process (Linux/Mac)
• Ctrl+D - Send EOF signal

Important Notes

Complete guide to operating your own Qbitcoin node for network participation and enhanced security.

Why Run a Node?

Running your own node provides:

• Full validation: Verify all transactions and blocks independently
• Enhanced privacy: Direct blockchain access without third parties
• Network support: Contribute to Qbitcoin's decentralization
• Faster transactions: Direct submission to the network
• Mining capability: Enable solo or pool mining
• Development platform: Test applications and features

Node Types

System Requirements

Initial Setup

1. Configuration

Create or edit ~/.qbitcoin/config.yml:

# Node configuration
node:
  # Network settings
  network: mainnet          # mainnet, testnet
  port: 9000               # P2P network port
  max_peers: 20            # Maximum peer connections

  # Data settings
  data_dir: ~/.qbitcoin    # Blockchain data directory

  # Performance settings
  cache_size: 300          # Memory cache in MB
  db_cache: 450           # Database cache in MB

  # Logging
  log_level: info         # debug, info, warning, error
  log_file: qbitcoin.log  # Log file location

# Network specific settings
mainnet:
  bootstrap_nodes:
    - "node1.qbitcoin.org:9000"
    - "node2.qbitcoin.org:9000"
    - "node3.qbitcoin.org:9000"

testnet:
  bootstrap_nodes:
    - "testnet1.qbitcoin.org:9000"
    - "testnet2.qbitcoin.org:9000"

2. First Start

# Start your node
python start_qbitcoin.py

# Or with custom configuration
python start_qbitcoin.py --config /path/to/config.yml

Blockchain Synchronization

Monitor Sync Progress

# Check sync status
python start_qbitcoin.py --sync-status

# Monitor in real-time
watch "python start_qbitcoin.py --sync-status"

# Detailed sync information
python start_qbitcoin.py --sync-status --verbose

Node Management

Peer Management

# List current peers
python start_qbitcoin.py --peers

# Add specific peer
python start_qbitcoin.py --add-peer 203.0.113.1:9000

# Remove peer
python start_qbitcoin.py --remove-peer abc123...def789

# Ban misbehaving peer
python start_qbitcoin.py --ban-peer 203.0.113.1

Maintenance Tasks

# Daily tasks
python start_qbitcoin.py --health-check
python start_qbitcoin.py --system-stats

# Weekly tasks
python start_qbitcoin.py --optimize-db
python start_qbitcoin.py --clear-cache
python start_qbitcoin.py --backup-node --dest /backup/location/

# Monthly tasks
python start_qbitcoin.py --verify-blockchain
python start_qbitcoin.py --performance-report

Complete guide to creating, managing, and securing Qbitcoin wallets.

Understanding Qbitcoin Wallets

A Qbitcoin wallet is a software program that:

• Stores private keys: Securely holds your cryptographic keys
• Manages addresses: Creates and tracks your Qbitcoin addresses
• Signs transactions: Authorizes spending of your coins
• Monitors balance: Tracks incoming and outgoing transactions
• Interfaces with blockchain: Communicates with the Qbitcoin network

Wallet Components

Creating Your First Wallet

Prerequisites

Method 1: Command Line (Recommended)

# Create new wallet with default name
python start_qbitcoin.py --create-wallet

# Create named wallet
python start_qbitcoin.py --create-wallet --name "primary"

# Create wallet with custom location
python start_qbitcoin.py --create-wallet --path "/secure/location/"

Interactive Creation Process

🚀 Creating new Qbitcoin wallet...

Enter wallet name (default: wallet): primary
Enter strong password: ********
Confirm password: ********

⚠️  IMPORTANT: Write down your seed phrase!

Your 24-word recovery phrase:
abandon ability able about above absent absorb abstract...

📝 Write this down on paper and store safely!
❌ Never store electronically or share with anyone!
✅ You will need this to recover your wallet!

Wallet created successfully!
📍 Location: /home/user/.qbitcoin/wallets/primary/

Method 2: GUI Application

# Launch GUI
python gui/qbitcoin_gui.py

1. Click "Create New Wallet"
2. Enter wallet name and password
3. Write down seed phrase
4. Confirm seed phrase
5. Wallet ready for use

Wallet Types

Wallet Security

Password Security

Password Examples

❌ Bad: password123
❌ Bad: myname1990
❌ Bad: qbitcoin2024

✅ Good: Tr7$mK9#pL2@nQ8
✅ Good: My!D0g&L0ves#C00kies99
✅ Good: Q8b!tc0in$W4ll3t@2024

Seed Phrase Security

Wallet Management Commands

# View wallet summary
python start_qbitcoin.py --wallet-info

# Check balance
python start_qbitcoin.py --balance

# List all wallets
python start_qbitcoin.py --list-wallets

# Backup wallet
python start_qbitcoin.py --backup-wallet --dest /backup/path/

# Restore from seed
python start_qbitcoin.py --restore-wallet --seed-file /path/to/seed.txt

Complete guide to sending, receiving, and managing Qbitcoin transactions.

Understanding Qbitcoin Transactions

A Qbitcoin transaction is a digitally signed transfer of value that:

• Transfers ownership of coins between addresses
• Uses post-quantum cryptography (FALCON signatures)
• Is recorded permanently on the blockchain
• Requires network confirmation to be final
• Includes transaction fees for miners

Transaction Components

Transaction Lifecycle

Sending Qbitcoin

Prerequisites

Basic Send Commands

# Basic send command
python start_qbitcoin.py --send RECIPIENT_ADDRESS AMOUNT

# Example: Send 1.5 QBC
python start_qbitcoin.py --send qbitcoin1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh 1.5

# Send with custom fee
python start_qbitcoin.py --send qbitcoin1qxy... 1.5 --fee 0.002

# Send from specific wallet
python start_qbitcoin.py --wallet "savings" --send qbitcoin1qxy... 1.5

Interactive Send Process

💰 Sending Qbitcoin Transaction

From wallet: primary
To address: qbitcoin1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
Amount: 1.5 QBC
Fee: 0.001 QBC
Total cost: 1.501 QBC

Current balance: 5.0 QBC
Remaining after: 3.499 QBC

❓ Confirm transaction? (y/N): y
🔐 Enter wallet password: ********

✅ Transaction created successfully!
Transaction ID: 0x1234567890abcdef...
Status: Broadcasting to network...

🎉 Transaction sent! Check status with:
python start_qbitcoin.py --tx-status 0x1234567890abcdef...

Advanced Send Options

# Send to multiple recipients
python start_qbitcoin.py --send-many \
    qbitcoin1abc...=1.0 \
    qbitcoin1def...=0.5 \
    qbitcoin1ghi...=2.0

# Send all funds (minus fee)
python start_qbitcoin.py --send-all qbitcoin1qxy...

# Add transaction comment
python start_qbitcoin.py --send qbitcoin1qxy... 1.5 \
    --comment "Payment for services" \
    --comment-to "John's design work"

Receiving Qbitcoin

Generate Receiving Addresses

# Generate new receiving address
python start_qbitcoin.py --new-address

# Generate with descriptive label
python start_qbitcoin.py --new-address --label "Payment from Alice"

# Generate multiple addresses
python start_qbitcoin.py --new-address --count 5

Address Management

# List all addresses
python start_qbitcoin.py --list-addresses

# List with balances
python start_qbitcoin.py --list-addresses --with-balance

# List with labels
python start_qbitcoin.py --list-addresses --with-labels

Address Format & Best Practices

QR Code Generation

# Generate QR code for address
python start_qbitcoin.py --qr-code qbitcoin1qxy... --output qr.png

# QR code with amount
python start_qbitcoin.py --qr-code qbitcoin1qxy... --amount 1.5 --output qr.png

Transaction Fees

Understanding Fees

Transaction fees are required for:

• Mining incentive: Reward miners for including transactions
• Network security: Maintain blockchain security
• Priority processing: Higher fees get faster confirmation
• Spam prevention: Prevent network abuse

Fee Structure

Fee Estimation

# Get recommended fee for transaction
python start_qbitcoin.py --estimate-fee qbitcoin1qxy... 1.5

# Monitor fee levels
python start_qbitcoin.py --fee-stats

# Check transaction status
python start_qbitcoin.py --tx-status TRANSACTION_ID

Transaction Monitoring

Balance Checking

# Current balance
python start_qbitcoin.py --balance

# Balance for specific address
python start_qbitcoin.py --balance --address qbitcoin1qxy...

# Detailed balance breakdown
python start_qbitcoin.py --balance --detailed

Transaction History

# Recent transactions
python start_qbitcoin.py --transactions --limit 10

# Watch for incoming transactions
python start_qbitcoin.py --monitor-address qbitcoin1qxy...

# Notifications for new transactions
python start_qbitcoin.py --notify-on-payment qbitcoin1qxy...

Complete documentation for Qbitcoin's Remote Procedure Call (RPC) and Public API interfaces.

API Overview

Qbitcoin provides multiple API interfaces for different use cases:

Prerequisites for Developers

# Install Qbitcoin with generated files
pip install qbitcoin

# Or for development installation
pip install -e .

# This ensures generated protobuf files are available at:
# qbitcoin/generated/qbit_pb2.py
# qbitcoin/generated/qbit_pb2_grpc.py

API Configuration

Configure APIs in /path/to/qrl_dir/config.yml:

# Public API Configuration
public_api_enabled: true
public_api_host: "0.0.0.0"  # Change from 127.0.0.1 to expose publicly
public_api_port: 19009
public_api_threads: 1
public_api_max_concurrent_rpc: 100

# Wallet API Configuration  
wallet_api_enabled: true
wallet_api_host: "127.0.0.1"  # Keep private for security
wallet_api_port: 19010
wallet_api_threads: 1
wallet_api_max_concurrent_rpc: 100

# Mining API Configuration
mining_api_enabled: false
mining_api_host: "127.0.0.1"
mining_api_port: 19007

# Admin API Configuration
admin_api_enabled: false
admin_api_host: "127.0.0.1"
admin_api_port: 19008

Connection Examples

gRPC Connection (Python)

import grpc
from qbitcoin.generated import qbit_pb2_grpc, qbit_pb2

# Connect to public API
channel = grpc.insecure_channel('localhost:19009')
stub = qbit_pb2_grpc.PublicAPIStub(channel)

# For public nodes
channel = grpc.insecure_channel('node.example.com:19009')
stub = qbit_pb2_grpc.PublicAPIStub(channel)

Command Line Tools

# Install grpcurl for testing
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# Method 1: Using proto files (RECOMMENDED when reflection is disabled)
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetNodeState

# Method 2: Using reflection (only if enabled on node)
grpcurl -plaintext localhost:19009 list

# List methods for PublicAPI
grpcurl -plaintext localhost:19009 list qrl.PublicAPI

Core API Methods

Node Information

# Python Example
request = qbit_pb2.GetNodeStateReq()
response = stub.GetNodeState(request)

print(f"Version: {response.info.version}")
print(f"Height: {response.info.block_height}")
print(f"Connections: {response.info.num_connections}")
print(f"State: {response.info.state}")

# Command Line with proto files (RECOMMENDED)
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetNodeState

# Command Line with reflection (if enabled)
grpcurl -plaintext localhost:19009 qrl.PublicAPI/GetNodeState

{
  "info": {
    "version": "1.0.9 python",
    "state": "SYNCED",
    "numConnections": 2,
    "numKnownPeers": 3,
    "uptime": "782121",
    "blockHeight": "13600",
    "blockLastHash": "8XxiVZYb+K+U7GzvDwAzIRzhEYhEDgUp2OybLHfrKgA=",
    "networkId": "The sleeper must awaken"
  }
}

Blockchain Data

# Get block by height
request = qbit_pb2.GetBlockReq(
    header_hash=b'',
    height=125849
)
response = stub.GetBlock(request)

# Get transaction by hash
request = qbit_pb2.GetTransactionReq(
    tx_hash=bytes.fromhex('abc123...')
)
response = stub.GetTransaction(request)

Network Statistics

# Python Example
request = qbit_pb2.GetStatsReq()
response = stub.GetStats(request)

print(f"Network ID: {response.node_info.network_id}")
print(f"Block Height: {response.node_info.block_height}")
print(f"Epoch: {response.epoch}")
print(f"Block Reward: {response.block_last_reward} Quarks")
print(f"Coins Emitted: {response.coins_emitted} Quarks")
print(f"Total Supply: {response.coins_total_supply}")

# Convert to QBC (1 QBC = 1,000,000,000 Quarks)
block_reward_qbc = int(response.block_last_reward) / 1e9
coins_emitted_qbc = int(response.coins_emitted) / 1e9
print(f"Block Reward: {block_reward_qbc} QBC")
print(f"Coins Emitted: {coins_emitted_qbc:,.0f} QBC")

# Command Line
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetStats

{
  "nodeInfo": {
    "version": "1.0.9 python",
    "state": "SYNCED",
    "numConnections": 2,
    "numKnownPeers": 3,
    "uptime": "782198",
    "blockHeight": "13600",
    "blockLastHash": "8XxiVZYb+K+U7GzvDwAzIRzhEYhEDgUp2OybLHfrKgA=",
    "networkId": "The sleeper must awaken"
  },
  "epoch": "136",
  "uptimeNetwork": "829394",
  "blockLastReward": "2500000000",
  "coinsTotalSupply": "30000000",
  "coinsEmitted": "20034000000000000"
}

Address Operations

# Get address balance
# Address must be in bytes format (remove 'qbitcoin' prefix and convert from hex)
address_hex = "01050058bb3f8cb66fd90d0347478e5bdf3a475e82cfc5fe5dc276500ca21531e6edaf3d2d0f7e"
address_bytes = bytes.fromhex(address_hex)

request = qbit_pb2.GetBalanceReq(address=address_bytes)
response = stub.GetBalance(request)

balance_quarks = response.balance
balance_qbc = balance_quarks / 1e9
print(f"Balance: {balance_quarks} Quarks")
print(f"Balance: {balance_qbc} QBC")

# Command Line - Get balance for address
# Note: Address needs to be in hex format without 'qbitcoin' prefix
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 \
  qrl.PublicAPI/GetBalance \
  -d '{"address": "01050058bb3f8cb66fd90d0347478e5bdf3a475e82cfc5fe5dc276500ca21531e6edaf3d2d0f7e"}'

# Get address transactions
request = qbit_pb2.GetAddressTransactionsReq(
    address=b'Q010500...',
    count=10
)
response = stub.GetAddressTransactions(request)

Network Information

Peer Operations

GetKnownPeers

# Get known peers
request = qbit_pb2.GetKnownPeersReq()
response = stub.GetKnownPeers(request)

for peer in response.known_peers:
    print(f"Peer: {peer.ip}")

# Command Line
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetKnownPeers

Real Response Example:

{
  "nodeInfo": {
    "version": "1.0.9 python",
    "state": "SYNCED",
    "numConnections": 2,
    "numKnownPeers": 3,
    "uptime": "782141",
    "blockHeight": "13600",
    "blockLastHash": "8XxiVZYb+K+U7GzvDwAzIRzhEYhEDgUp2OybLHfrKgA=",
    "networkId": "The sleeper must awaken"
  },
  "knownPeers": [
    {
      "ip": "134.122.79.166:19000"
    },
    {
      "ip": "220.158.73.254:19000"
    },
    {
      "ip": "134.209.249.77:19000"
    }
  ]
}

GetPeersStat

# Get peer statistics
request = qbit_pb2.GetPeersStatReq()
response = stub.GetPeersStat(request)

for peer_stat in response.peers_stat:
    print(f"Peer IP: {peer_stat.peer_ip}")
    print(f"Port: {peer_stat.port}")
    print(f"Block Height: {peer_stat.node_chain_state.block_number}")

# Command Line
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetPeersStat

Real Response Example:

{
  "peersStat": [
    {
      "peerIp": "MjIwLjE1OC43My4yNTQ=",
      "port": 56320,
      "nodeChainState": {
        "blockNumber": "13600",
        "headerHash": "8XxiVZYb+K+U7GzvDwAzIRzhEYhEDgUp2OybLHfrKgA=",
        "cumulativeDifficulty": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADYulE=",
        "version": "1.0.9 python",
        "timestamp": "1752566061"
      }
    },
    {
      "peerIp": "OTguODQuOTYuMjM2",
      "port": 35570,
      "nodeChainState": {
        "blockNumber": "13600",
        "headerHash": "8XxiVZYb+K+U7GzvDwAzIRzhEYhEDgUp2OybLHfrKgA=",
        "cumulativeDifficulty": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADYulE=",
        "version": "1.0.9 python",
        "timestamp": "1752566062"
      }
    }
  ]
}

Error Handling

Error Handling Example

import grpc

try:
    response = stub.GetNodeState(request)
except grpc.RpcError as e:
    if e.code() == grpc.StatusCode.UNAVAILABLE:
        print("API service unavailable")
    elif e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
        print("Request timeout")
    else:
        print(f"RPC error: {e.code()}: {e.details()}")

Troubleshooting gRPC API

# ❌ This fails if reflection is disabled
grpcurl -plaintext 134.122.79.166:19009 list

# ✅ This works with proto files
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetNodeState

# Navigate to Qbitcoin root directory
cd /path/to/Qbitcoin

# Verify proto files exist
ls qbitcoin/protos/qbit.proto

# Run grpcurl from project root
grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext NODE:19009 qrl.PublicAPI/METHOD

# Convert from user-friendly format to API format
user_address = "qbitcoin1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
# Remove 'qbitcoin' prefix and use hex format
api_address = user_address[8:]  # Remove 'qbitcoin' prefix
address_bytes = bytes.fromhex(api_address)

Security Considerations

Rate Limiting

Default rate limits for public API:

• 100 requests per minute per IP address
• Max 100 concurrent connections
• Request timeout: 30 seconds

Configure in config.yml to adjust limits based on your needs.

Quick Reference - Working Commands

grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetNodeState

grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetKnownPeers

grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetPeersStat

grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 qrl.PublicAPI/GetStats

grpcurl -import-path qbitcoin/protos -proto qbit.proto -plaintext 134.122.79.166:19009 \
  qrl.PublicAPI/GetBalance \
  -d '{"address": "01050058bb3f8cb66fd90d0347478e5bdf3a475e82cfc5fe5dc276500ca21531e6edaf3d2d0f7e"}'

Complete documentation for Qbitcoin's Wallet API - the private interface for wallet management and transaction creation.

API Overview

The Qbitcoin Wallet API provides private functionality for wallet management, transaction creation, and account operations.

Key Features

• Wallet Management: Create, encrypt, lock/unlock wallets
• Address Generation: Create new addresses with various configurations
• Transaction Creation: Send transfers, tokens, messages
• Private Operations: Access to sensitive wallet functions
• Slave Key Support: Advanced key management for high-frequency operations

API Types Comparison

API Configuration

Edit your config.yml:

# Wallet API Configuration (KEEP PRIVATE!)
wallet_api_enabled: true
wallet_api_host: "127.0.0.1"  # NEVER change to 0.0.0.0
wallet_api_port: 19010
wallet_api_threads: 1
wallet_api_max_concurrent_rpc: 100

# Security: Ensure other APIs don't conflict
public_api_port: 19009   # Different port
admin_api_port: 19008    # Different port

Connection Setup

Python gRPC Connection

import grpc
from qbitcoin.generated import qbitwallet_pb2_grpc, qbitwallet_pb2

# Connect to Wallet API (LOCAL ONLY!)
channel = grpc.insecure_channel('127.0.0.1:19010')
stub = qbitwallet_pb2_grpc.WalletAPIStub(channel)

# Never use public IPs for wallet API
# ❌ channel = grpc.insecure_channel('public-ip:19010')  # DANGEROUS!

Authentication Example

# If authentication is enabled
import grpc
from grpc import ssl_channel_credentials

# Use TLS for production
credentials = ssl_channel_credentials()
channel = grpc.secure_channel('127.0.0.1:19010', credentials)
stub = qbitwallet_pb2_grpc.WalletAPIStub(channel)

Wallet Management

Create Wallet

# Create new wallet
request = qbitwallet_pb2.CreateWalletReq(
    passphrase="strong_password_123",
    encrypt_wallet=True
)
response = stub.CreateWallet(request)

print(f"Wallet created!")
print(f"Address: {response.address}")
print(f"Mnemonic: {response.mnemonic}")  # Store securely!

Wallet Operations

# Unlock for operations
request = qbitwallet_pb2.UnlockWalletReq(
    passphrase="strong_password_123"
)
response = stub.UnlockWallet(request)

# Lock wallet for security
request = qbitwallet_pb2.LockWalletReq()
response = stub.LockWallet(request)

Address Operations

Generate New Address

# Generate new receiving address
request = qbitwallet_pb2.GetNewAddressReq(
    height=0,  # Use default height
    hash_function="shake128"  # Address hash function
)
response = stub.GetNewAddress(request)

print(f"New address: {response.address}")
print(f"Public key: {response.pk}")

List Addresses

# Get all wallet addresses
request = qbitwallet_pb2.ListAddressesReq()
response = stub.ListAddresses(request)

for addr in response.addresses:
    print(f"Address: {addr.address}")
    print(f"Balance: {addr.balance} QBC")
    print(f"Used: {addr.used}")
    print("---")

Transaction Operations

Send Transaction

# Send Qbitcoin to address
request = qbitwallet_pb2.TransferCoinsReq(
    addresses_to=["qbitcoin1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"],
    amounts=[1500000000],  # 1.5 QBC in Quarks (1 QBC = 10^9 Shors)
    fee=1000000,  # 0.001 QBC fee
    message_data=""  # Optional message
)
response = stub.TransferCoins(request)

print(f"Transaction created!")
print(f"TX Hash: {response.tx.transaction_hash}")
print(f"Fee: {response.tx.fee} Shors")

Advanced Transaction Features

# Send to multiple addresses
request = qbitwallet_pb2.TransferCoinsReq(
    addresses_to=[
        "qbitcoin1qxy...",
        "qbitcoin1abc...",
        "qbitcoin1def..."
    ],
    amounts=[
        1000000000,  # 1.0 QBC
        500000000,   # 0.5 QBC
        2000000000   # 2.0 QBC
    ],
    fee=2000000  # Higher fee for multiple outputs
)

# Send with message data
request = qbitwallet_pb2.TransferCoinsReq(
    addresses_to=["qbitcoin1qxy..."],
    amounts=[1000000000],
    fee=1000000,
    message_data="Payment for services"
)

Query Operations

Wallet Information

# Get wallet balance
request = qbitwallet_pb2.GetBalanceReq()
response = stub.GetBalance(request)

print(f"Balance: {response.balance} Shors")
print(f"Balance: {response.balance / 1e9} QBC")

# Get wallet height
request = qbitwallet_pb2.GetHeightReq()
response = stub.GetHeight(request)

print(f"Wallet height: {response.height}")

# Check if wallet is encrypted
request = qbitwallet_pb2.GetWalletInfoReq()
response = stub.GetWalletInfo(request)

print(f"Encrypted: {response.info.encrypted}")
print(f"Locked: {response.info.locked}")

Transaction History

# Get transaction history
request = qbitwallet_pb2.GetTransactionsByAddressReq(
    address="",  # Empty for all addresses
    item_per_page=10,
    page_number=1
)
response = stub.GetTransactionsByAddress(request)

for tx in response.transactions_detail:
    print(f"TX: {tx.tx.transaction_hash}")
    print(f"Amount: {tx.amount} Quarks")
    print(f"Block: {tx.block_number}")
    print("---")

Security Best Practices

Error Handling

Common Wallet Errors

Error Handling Example

import grpc

try:
    response = stub.TransferCoins(request)
except grpc.RpcError as e:
    if "WALLET_LOCKED" in str(e):
        print("Please unlock wallet first")
        # Unlock wallet and retry
    elif "INSUFFICIENT_BALANCE" in str(e):
        print("Insufficient funds")
    else:
        print(f"Transaction failed: {e}")