A simple yet structured implementation of a cryptocurrency built from scratch using C++. This project focuses on understanding the fundamentals of blockchain, cryptography, and distributed systems.
This project implements a minimal but proper cryptocurrency system, including:
- Blockchain data structure
- Proof of Work (PoW)
- UTXO-based transaction model
- Digital signature using OpenSSL (ECDSA)
- P2P Networking (TCP-based)
- Automated Unit & Integration Testing
karbitcoin/
├── CMakeLists.txt
├── src/ # Implementation files
│ ├── core/ # Blockchain, Block, Transaction, Storage logic
│ ├── crypto/ # Hashing, ECDSA, Wallet, UTXO
│ ├── network/ # P2P Node, Serialization
│ └── main.cpp
├── include/ # Header files
├── tests/ # Test suite (GTest)
│ ├── unit/ # Unit tests for components
│ └── integration/ # Integration tests (flow)
└── build/ # Build directory
✅ Implemented
- Blockchain with linked blocks
- SHA-256 hashing
- Proof of Work (mining + difficulty)
- UTXO-based transaction model
- ECDSA digital signature (OpenSSL)
- Address generation from public key
- Transaction validation (Signature & UTXO checks)
- Mempool (pending transactions)
- Mining with block rewards & fees
- Full chain validation
- P2P node communication (TCP)
- Transaction & Block propagation
- Chain synchronization (Handshake + Sync)
- Improved P2P Reliability (Message Queue & Thread Safety)
- JSON-based Persistence (Blocks, UTXO, Metadata)
- Interactive CLI Wallet (Interactive & Persistent)
- Multi-threaded Mining (Configurable thread count)
- Automated Testing (30+ cases)
- C++17 compiler
- CMake (>= 3.16)
- OpenSSL (libcrypto)
- Boost (Asio, System)
- nlohmann_json
- GTest (Google Test)
cmake -S . -B build
cmake --build build -j$(nproc)You can specify a custom port to run multiple nodes on the same machine. Data will be saved in data_<port>/.
./build/bin/karbitcoin [port]Default port is 8333 if not specified.
The application provides a real-time interactive shell to manage your wallet and node.
| Command | Description |
|---|---|
status |
Show node status, wallet address, balance, and chain height. |
balance |
Quick check of your current wallet balance. |
mine |
Mine pending transactions into a new block. |
send <addr> <amt> |
Send coins to a specific address. |
connect <ip> <port> |
Connect your node to a peer. |
info |
Show technical details about the blockchain and data directory. |
help |
Display all available commands. |
exit |
Safely stop the node and exit. |
- Start Node A (Miner):
./build/bin/karbitcoin 8333 karbitcoin> mine karbitcoin> status # Balance should be 50 KBC
- Start Node B (Receiver):
Open another terminal:
./build/bin/karbitcoin 8334 karbitcoin> status # Copy the Wallet Address
- Connect and Send:
Back in Node A terminal:
karbitcoin> connect 127.0.0.1 8334 karbitcoin> send <address_node_b> 10.5 karbitcoin> mine karbitcoin> status # Balance decreases after send + reward
We use Google Test for verification.
cd build
ctest --output-on-failureTests include:
test_crypto: Hash, ECDSA, UTXO, and Wallet logic.test_core: Transaction, Block, Blockchain integrity, and Persistence.test_integration: Full mining flow (Transaction -> Mining -> Balance check).
- Simplicity over completeness
- Readability over optimization
- Incremental learning approach
- Robust Persistence: JSON-based storage with auto-recovery support for UTXO sets from block history.
- Persistent Wallets: Keys are saved to
wallet.jsonin the data directory.
This project is for educational purposes only. Do NOT use this implementation in production or for real financial systems.
- Core blockchain
- Proof of Work
- Transactions & UTXO
- Digital signatures
- Mempool & Validation
- Networking (Basic P2P + Sync)
- Testing Framework (GTest)
- Persistence (Save/Load to disk)
- CLI Wallet interface
- Difficulty adjustment algorithm
- Multi-threaded mining
Feel free to fork and experiment. This project is designed to be a learning playground.
MIT License