Blockchain

A minimal proof-of-work blockchain node written in Rust, with P2P networking and a web UI.

Features

• Proof-of-Work mining with dynamic difficulty adjustment
• P2P networking — connect multiple nodes to form a decentralized network
• Transaction signing with secp256k1 ECDSA
• Account balance model with integer-based fixed-point amounts (1 coin = 100,000,000 base units)
• Full chain validation — hash linkage, PoW verification, signature verification, balance checks
• Persistence — blockchain saved to disk, survives restarts
• Web UI for interacting with the node (key generation, transactions, mining, faucet)
• Graceful shutdown with signal handling

Quick Start

Build and run locally

cargo build --release
./target/release/blockchain 8080

Open http://localhost:8080 in your browser.

Docker

docker build -t blockchain .
docker run -p 8080:8080 blockchain

Multiple nodes

# Terminal 1
./target/release/blockchain 8080

# Terminal 2
./target/release/blockchain 8081

Then use the web UI on either node to connect to the other by entering its IP and port.

Usage

1. Create a Genesis Block — click "Create Genesis Block" on one node
2. Connect Nodes — enter the target node's IP and port, click "Connect"
3. Generate Keys — click "Generate Key Pair" to get a keypair for transactions
4. Get Coins — use the faucet to request coins (requires the miner to have a balance)
5. Start Mining — toggle the mining switch to begin PoW mining
6. Send Transactions — fill in sender keys, receiver key, and amount

API Endpoints

Endpoint	Method	Description
/	GET	Web UI
/health	GET	Node health status
/blockchain_info	GET	Full chain, nodes, and pending transactions
/generate_key_pair	GET	Generate a new secp256k1 keypair
/miner_keys	GET	Get the node's miner public key
/genesis_block	POST	Create the genesis block
/transaction/submit	POST	Submit a signed transaction
/faucet	POST	Request coins (rate-limited)
/balance	POST	Check account balance
/mine	POST	Start/stop mining
/connect	POST	Connect to another node

Configuration

• Port: passed as the first CLI argument
• Log level: set via RUST_LOG environment variable (default: blockchain=info)

RUST_LOG=blockchain=debug ./target/release/blockchain 8080

Architecture

src/
├── main.rs          # Entry point, router, graceful shutdown
├── block.rs         # Block structure, hashing, validation
├── blockchain.rs    # Chain management, balance tracking, validation
├── transaction.rs   # Transaction signing, verification, coinbase
├── mining.rs        # PoW mining, difficulty adjustment, broadcasting
├── node.rs          # Node/peer management
├── server.rs        # HTTP handlers
├── storage.rs       # File-based persistence
└── utils.rs         # Config, shared state, crypto helpers

License

MIT