Skip to content

SETUP.md

Latest commit

 

History

History
257 lines (201 loc) · 7.42 KB

SETUP.md

File metadata and controls

257 lines (201 loc) · 7.42 KB
Raw

🚀 BlockSim Setup Guide

Complete step-by-step instructions to get your blockchain visualization platform running.

📋 Prerequisites

Before you begin, ensure you have:

  • Node.js (v16 or higher) - Download here
  • npm (comes with Node.js)
  • A modern web browser (Chrome, Firefox, Edge, or Safari)
  • A code editor (VS Code recommended)

⚡ Quick Start (3 Steps)

1. Install Dependencies

Open your terminal in the blocksim directory and run:

npm install

This will install all required packages:

  • React & React DOM
  • Vite (build tool)
  • Tailwind CSS (styling)
  • Framer Motion (animations)
  • crypto-js (SHA-256 hashing)
  • elliptic (cryptographic signatures)
  • D3.js (visualizations)

2. Start Development Server

npm run dev

The terminal will show:

  VITE v5.0.0  ready in 500 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose

3. Open in Browser

Navigate to http://localhost:3000 in your web browser.

You should see the BlockSim landing page! 🎉

🎯 What You'll See

Landing Page

  • Beautiful animated hero section
  • Three feature cards: Hashing, Mining, Blockchain
  • "Start Simulation" button

Simulation Page

Three interactive tabs:

  1. 🔐 Hashing - SHA-256 hash visualizer with avalanche effect
  2. ⛏️ Mining - Proof-of-work mining simulator
  3. 🧱 Blockchain - Interactive blockchain explorer

Transactions Page

Complete cryptocurrency system:

  • Wallet creation and management
  • Transaction signing with private keys
  • Mempool (pending transactions)
  • Mining rewards
  • Transaction history

🔧 Project Structure

blocksim/
├── src/
│   ├── components/
│   │   ├── layout/
│   │   │   └── Navigation.jsx          # App navigation
│   │   └── visualizers/
│   │       ├── BlockCard.jsx           # Individual block display
│   │       ├── BlockchainVisualizer.jsx # Full blockchain view
│   │       ├── BlockDetailsPanel.jsx   # Block information panel
│   │       ├── DifficultyExplainer.jsx # Mining difficulty chart
│   │       ├── HashVisualizer.jsx      # SHA-256 hash demo
│   │       ├── MempoolVisualizer.jsx   # Pending transactions
│   │       ├── MiningVisualizer.jsx    # Mining simulator
│   │       ├── TransactionForm.jsx     # Create transactions
│   │       ├── TransactionHistory.jsx  # Transaction log
│   │       └── WalletManager.jsx       # Wallet management
│   ├── pages/
│   │   ├── Home.jsx                    # Landing page
│   │   ├── SimulationPage.jsx          # Main simulation
│   │   └── TransactionsPage.jsx        # Cryptocurrency demo
│   ├── utils/
│   │   ├── blockchain/
│   │   │   ├── Block.js                # Block class
│   │   │   ├── Blockchain.js           # Blockchain class
│   │   │   ├── Transaction.js          # Transaction class
│   │   │   ├── Wallet.js               # Wallet class
│   │   │   ├── miningWorker.js         # Async mining
│   │   │   └── test.js                 # Test functions
│   │   └── helpers/
│   │       ├── formatters.js           # Utility functions
│   │       └── hashHelpers.js          # Hash computations
│   ├── constants/
│   │   └── blockchain.js               # Configuration
│   ├── App.jsx                         # Main app component
│   ├── main.jsx                        # React entry point
│   └── index.css                       # Global styles
├── public/                             # Static assets
├── index.html                          # HTML template
├── package.json                        # Dependencies
├── vite.config.js                      # Vite configuration
├── tailwind.config.js                  # Tailwind configuration
└── README.md                           # Documentation

🎮 How to Use

1. Explore Hashing

  • Navigate to Simulation → Hashing
  • Type any text to see its SHA-256 hash
  • Try the avalanche effect to see how small changes create completely different hashes
  • Use preset examples for quick demos

2. Try Mining

  • Navigate to Simulation → Mining
  • Adjust difficulty (1-6)
  • Enter block data
  • Click "Start Mining"
  • Watch the proof-of-work algorithm in action
  • See how difficulty affects mining time

3. Build a Blockchain

  • Navigate to Simulation → Blockchain
  • Add new blocks with custom data
  • Watch blocks connect with cryptographic hashes
  • Try tampering with a block to see validation fail
  • Export/import blockchain as JSON

4. Create Wallets & Transactions

  • Navigate to Transactions page
  • Create a new wallet (generates key pair)
  • Save your private key securely!
  • Create transactions between wallets
  • Mine blocks to confirm transactions
  • Earn mining rewards (50 ⚡)

🛠️ Development Commands

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Run linter
npm run lint

🐛 Troubleshooting

Port Already in Use

If port 3000 is busy, Vite will automatically use the next available port (3001, 3002, etc.)

Dependencies Not Installing

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Build Errors

Make sure you're using Node.js v16 or higher:

node --version

Browser Compatibility

BlockSim works best on modern browsers:

  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+

🔒 Security Notes

⚠️ IMPORTANT: This is an educational tool for learning blockchain concepts.

  • Private keys are generated in your browser
  • No data is sent to any server
  • Private keys are NOT encrypted or stored
  • Do NOT use for real cryptocurrency
  • Treat this as a learning sandbox

📚 Learning Path

Recommended order to explore features:

  1. Hashing (10 mins)

    • Understand cryptographic hashing
    • See avalanche effect
    • Learn why hashes are one-way

  2. Mining (15 mins)

    • Experience proof-of-work
    • Understand difficulty adjustment
    • See computational requirements

  3. Blockchain (20 mins)

    • Build a chain of blocks
    • Understand immutability
    • Try tampering and validation

  4. Transactions (30 mins)

    • Create wallets
    • Sign transactions
    • Mine blocks
    • Track balances

🎓 Educational Features

  • Real Cryptography: Uses actual SHA-256 and elliptic curve cryptography
  • Interactive Visualizations: See concepts in action
  • Step-by-Step: Learn at your own pace
  • Hands-On: Modify and experiment
  • Educational Tooltips: Explanations throughout

💡 Tips

  • Start with low mining difficulty (1-2) for faster demos
  • Create multiple wallets to see transactions flow
  • Export blockchain to save your work
  • Use browser DevTools to see console logs
  • Check the educational info boxes on each page

🤝 Need Help?

  • Check the README.md for detailed documentation
  • Each component has inline comments explaining the code
  • Test functions are available in src/utils/blockchain/test.js

🎉 You're Ready!

Start exploring blockchain technology through interactive visualization. Have fun learning! 🚀

Built for blockchain education | Open source | MIT License