Learn blockchain fundamentals by building one from scratch -- blocks, mining, wallets, transactions, and P2P networking in TypeScript.
- The Problem
- The Solution
- Features
- Tech Stack
- Getting Started
- Usage
- Architecture
- Project Structure
- Roadmap
- Contributing
- License
- Acknowledgments
Understanding blockchain technology is hard without hands-on experience. Most tutorials and courses stay theoretical -- explaining hash functions, consensus, and distributed ledgers in the abstract. Without building a blockchain from scratch, concepts like proof-of-work mining, peer-to-peer chain synchronization, and transaction signing remain opaque.
TS-Blockchain is a fully functional blockchain implementation in TypeScript that you can run, modify, and extend. It includes a REST API, P2P networking over WebSockets, proof-of-work mining with adjustable difficulty, and a wallet system with elliptic-curve-signed transactions -- all designed as a learning tool.
// Start a node, create a transaction, and mine a block
const bc = new Blockchain();
const wallet = new Wallet();
const tp = new TransactionPool();
const transaction = wallet.createTransaction(recipientAddress, 50, bc, tp);
const miner = new Miner(bc, tp, wallet, p2pServer);
const block = miner.mine(); // mines pending transactions into a new block- Blockchain core with genesis block and chain validation
- Proof-of-work mining with adjustable difficulty and mine rate
- Wallet system with elliptic-curve key pairs (secp256k1)
- Signed transactions with input/output model
- Transaction pool with duplicate detection and updates
- Mining rewards (66 coins per block)
- P2P networking via WebSockets for chain and transaction sync
- REST API with Express for interacting with the node
- Comprehensive test suite with Jest
- Swagger API documentation (planned)
- Data persistence (planned)
- Smart-contract engine (planned)
- Plugin system (planned)
| Layer | Technology |
|---|---|
| Language | TypeScript 4.0 |
| Runtime | Node.js >= 14.13 |
| HTTP Server | Express 4.17 |
| P2P Networking | ws 7.4 (WebSocket) |
| Cryptography | elliptic 6.5 (secp256k1), crypto-js 4.0 (SHA-256) |
| Identity | uuid 8.3 |
| Testing | Jest 26.6, ts-jest 26.4 |
| Linting | ESLint + Prettier |
- Node.js >= 14.13
- Yarn (or npm)
git clone https://github.com/Atypical-Consulting/ts-blockchain.git
cd ts-blockchain
yarn install# Build and start the node (default port 3001)
yarn start
# Run tests with coverage
yarn test
# Start in watch mode for development
yarn build:watchGET /blocks # Get the full blockchain
POST /mine # Mine a new block with arbitrary data
GET /transactions # List pending transactions in the pool
POST /transact # Create a new transaction
GET /mine-transactions # Mine all pending transactions into a block
GET /public-key # Get this node's public keyGet the blockchain:
curl http://localhost:3001/blocksCreate a transaction:
curl -X POST http://localhost:3001/transact \
-H "Content-Type: application/json" \
-d '{"recipient": "04a1b2c3...", "amount": 50}'Mine pending transactions:
curl http://localhost:3001/mine-transactionsMine a block with custom data:
curl -X POST http://localhost:3001/mine \
-H "Content-Type: application/json" \
-d '{"data": "hello blockchain"}'Start additional nodes on different ports and connect them via WebSocket:
# Terminal 1 (default node)
yarn start
# Terminal 2 (second peer)
HTTP_PORT=3002 P2P_PORT=5002 PEERS=ws://localhost:5001 yarn start┌─────────────────────────────────────────────────┐
│ REST API (Express) │
│ /blocks /mine /transact ... │
└────────────────────┬────────────────────────────┘
│
┌────────────┼────────────────┐
▼ ▼ ▼
┌──────────┐ ┌─────────────┐ ┌───────────┐
│Blockchain│ │ Wallet │ │Transaction│
│ │ │ (EC keys) │ │ Pool │
│ - chain │ │ - sign │ │ - pending │
│ - blocks │ │ - verify │ │ - update │
│ - valid. │ │ - balance │ │ - clear │
└────┬─────┘ └──────┬──────┘ └─────┬─────┘
│ │ │
└───────────┬───┘───────────────┘
▼
┌──────────────────┐
│ P2P Server (ws) │
│ - sync chains │
│ - broadcast txns │
│ - peer discovery │
└──────────────────┘
ts-blockchain/
├── src/
│ ├── app/
│ │ ├── index.ts # Express server & route definitions
│ │ ├── miner.ts # Mining logic (reward transactions)
│ │ └── p2p-server.ts # WebSocket P2P server
│ ├── blockchain/
│ │ ├── block.ts # Block class (hash, nonce, difficulty)
│ │ ├── block.test.ts # Block unit tests
│ │ ├── index.ts # Blockchain class (chain, validation)
│ │ └── index.test.ts # Blockchain unit tests
│ ├── wallet/
│ │ ├── index.ts # Wallet class (keys, signing, balance)
│ │ ├── index.test.ts # Wallet unit tests
│ │ ├── transaction.ts # Transaction class (inputs/outputs)
│ │ ├── transaction.test.ts # Transaction unit tests
│ │ ├── transaction-pool.ts # Transaction pool management
│ │ └── transaction-pool.test.ts
│ ├── chain-util.ts # Crypto utilities (EC, hash, verify)
│ ├── config.ts # Constants (difficulty, mine rate, rewards)
│ ├── errors.ts # Custom error classes
│ └── dev-test.ts # Development test script
├── .github/workflows/ # CI configuration (Qodana)
├── jest.config.js # Jest test configuration
├── tsconfig.json # TypeScript configuration
├── package.json # Dependencies and scripts
└── LICENSE # MIT License
- Add Swagger/OpenAPI documentation
- Add data persistence (database layer)
- Build a smart-contract engine
- Implement a plugin system
- Add Docker support for easy deployment
- Improve peer discovery mechanism
Want to contribute? Pick any roadmap item and open a PR!
Contributions are welcome! Here's how to get started:
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit using conventional commits (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
MIT (c) 2019 Atypical Consulting
- Node TypeScript Boilerplate for the project scaffolding
- The blockchain and cryptocurrency community for educational resources
Built with care by Atypical Consulting -- opinionated, production-grade open source.