blockchainz is a from-scratch blockchain implementation in Go that covers the full lifecycle of a minimal blockchain system: transactions, blocks, validation, networking, and a custom execution environment. This is not a toy snippet repo—it is a cohesive, end-to-end system built to understand how real blockchains work internally by writing every critical component manually.
The project is complete and intended as a technical learning reference for students, backend engineers, and blockchain researchers who want to reason about blockchains at the systems level rather than through SDK abstractions.
If you are looking for shortcuts, frameworks, or production-grade optimizations, this repo is not for you. If you want to understand why blockchains work, keep reading.
- Peer-to-peer communication over TCP
- Signed transactions using ECDSA
- Block construction with header/body separation
- Deterministic hashing and binary encoding
- Full block and transaction validation pipeline
- Chain state management with height and header tracking
- Modular design enabling extension toward consensus and VM execution
-
block.go
Defines theBlockandHeaderstructures, hash computation, and serialization logic. -
transaction.go
Transaction format, sender authentication, digital signatures, and verification. -
blockchain.go
Core chain structure, block storage, height tracking, and block retrieval. -
validator.go
Strict validation rules for blocks and transactions (hashes, signatures, height continuity, parent linkage). -
hasher.go
Pluggable hashing interface with a SHA-256 implementation. -
encoding.go
Low-level binary encoding/decoding helpers to avoid JSON-based shortcuts. -
crypto/
Custom cryptographic utilities for keypair generation and ECDSA signing. -
network/(or equivalent)
TCP-based peer communication, message framing, and concurrency via goroutines. -
test/
Unit tests covering blocks, transactions, hashing, and validation logic.
Each guide maps directly to real code in the repository.
-
Guide 0: Communication System
Goroutines, TCP networking, peer connections, and message exchange. -
Guide 1: Block and Header Design
Block anatomy, header separation, and binary encoding decisions. -
Guide 2: Keypairs and Digital Signatures
ECDSA fundamentals, signing data, and verifying authenticity. -
Guide 3: Block & Transaction Signing
End-to-end signing and verification flow. -
Guide 4: Blockchain Data Structure
Internal chain representation, storage, and retrieval logic. -
Guide 5: Block Validator
Validation rules, failure cases, and correctness guarantees.
This project IS:
- A clean, readable blockchain core written from scratch
- Focused on correctness, clarity, and systems understanding
- Suitable for academic reference, interviews, and research prototyping
This project is NOT:
- A production blockchain
- A consensus-complete system (no PoW/PoS)
- A framework or SDK wrapper
git clone https://github.com/ayushn2/blockchainz.git
cd blockchainz
go test ./...You can explore individual components directly or extend the system with:
- Consensus mechanisms
- State machines / virtual machines
- Persistent storage
- Networking upgrades (gossip, discovery)
Most blockchain tutorials abstract away the hard parts.
This project does the opposite.
Every design choice is explicit. Every cryptographic operation is visible. Every validation rule is enforced in code. The goal is understanding first, scaling later.
This repository is feature-complete and primarily maintained as a reference implementation.
- Issues are welcome for questions or clarifications
- Forks are encouraged for experimentation
- Pull requests should focus on correctness or documentation
Direct pushes to main are disabled.
MIT