MineRace — Build Your Own Blockchain

minerace/
├── config.js              # All tuneable parameters
├── server.js              # Express app entry point
├── blockchain/
│   ├── Block.js           # Block class
│   ├── Blockchain.js      # Chain + balances + mempool + validation
│   ├── Transaction.js     # Transaction class (sign/verify)
│   └── Wallet.js          # Key pair generation (ECDSA)
├── bots/
│   └── botMiner.js        # Server-side bot mining logic
├── routes/
│   ├── chain.js           # GET /api/chain, /api/chain/:index
│   ├── mining.js          # GET /api/challenge, POST /api/submitBlock
│   ├── transactions.js    # POST /api/transaction, GET /api/mempool
│   └── chat.js            # POST /api/chat (Ollama integration)
├── data/
│   └── blocks/            # ONE JSON FILE PER BLOCK
│       ├── block-0.json   # Genesis block (created on first start)
│       ├── block-1.json   # Mined by Bot-Paris
│       ├── block-2.json   # Mined by you
│       └── ...
├── public/                    # Served statically by Express
│   ├── index.html         # Main frontend page
│   ├── style.css          # Styles
│   ├── app.js             # Frontend logic (wallets, UI, polling)
│   └── miner-worker.js    # Web Worker for browser-side mining
├── my-bot.js                  # YOUR custom mining bot (deliverable)
├── test-step1.js ... test-step10.js  # Test files (provided)
├── Dockerfile
├── docker-compose.yml
└── README.md

{
  "index": 3,
  "timestamp": 1711878400,
  "previousHash": "000a3f8c2e...",
  "transactions": [
    {
      "from": "04a1b2c3d4e5...",      // sender public key
      "to": "04f6a7b8c9d0...",        // recipient public key
      "amount": 20,
      "signature": "3045022100..."    // ECDSA signature
    },
    {
      "from": "MINING_REWARD",         // special: coinbase tx
      "to": "04a1b2c3d4e5...",        // miner's public key
      "amount": 50,
      "signature": null                // no signature needed
    }
  ],
  "nonce": 847,
  "hash": "000f8c2a7b..."             // starts with "000" (difficulty = 3)
}

docker-compose.yml

services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data          # blocks persist on host disk
    environment:
      - OLLAMA_HOST=http://ollama:11434
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama  # model cache persists
    # Pull a model on first start:
    # docker exec minerace-ollama-1 ollama pull llama3.2

volumes:
  ollama-data:

POST /api/transaction
Content-Type: application/json

{
  "from": "04a1b2c3d4e5f6...",       // sender public key (hex)
  "to": "04f6a7b8c9d0e1...",         // recipient public key (hex)
  "amount": 20,
  "signature": "3045022100abc..."     // ECDSA signature of "04a1...04f6...20"
}

Response (201): { "message": "Transaction added to mempool" }
Response (400): { "error": "Insufficient balance (have: 10, need: 20)" }
Response (400): { "error": "Invalid signature" }

POST /api/submitBlock
Content-Type: application/json

{
  "index": 4,
  "timestamp": 1711878400,
  "previousHash": "000a3f8c2e7b...",
  "transactions": [
    { "from": "04a1...", "to": "04f6...", "amount": 20, "signature": "3045..." },
    { "from": "MINING_REWARD", "to": "04a1...", "amount": 50, "signature": null }
  ],
  "nonce": 1847,
  "hash": "0002f8c1a3..."
}

Response (201): { "message": "Block 4 accepted", "miner": "04a1..." }
Response (409): { "error": "Block 4 already mined by Bot-Paris" }
Response (400): { "error": "Invalid previousHash — expected 000f8c..., got 000a3f..." }

{
  "blockHeight": 12,
  "difficulty": 3,
  "chainValid": true,
  "miners": [
    { "address": "Bot-Paris",    "blocksMined": 5, "earnings": 250 },
    { "address": "Bot-Tokyo",    "blocksMined": 3, "earnings": 150 },
    { "address": "04a1b2...e5f6", "blocksMined": 4, "earnings": 200 }
  ],
  "mempool": {
    "pending": 2,
    "totalAmount": 45
  }
}

// routes/chat.js  (server-side, Node.js)

app.post('/api/chat', async (req, res) => {
  const { message } = req.body;

  // 1. Build chain context from the blockchain engine
  const context = buildChainContext(blockchain);
  // e.g. "Block height: 12. Difficulty: 3.
  //        Balances: 04a1b2...=180, 04f6a7...=70, Bot-Paris=250
  //        Last 3 txs: 04a1... sent 20 to 04f6... (block 11) ..."

  // 2. Call Ollama's API
  const response = await fetch('http://ollama:11434/api/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'llama3.2',          // or 'mistral'
      prompt: message,
      system: `You are a blockchain assistant. Here is the current
               state of the chain:\n\n${context}\n\n
               Answer the user's question based on this data.`,
      stream: false                // wait for full response
    })
  });

  const data = await response.json();
  res.json({ reply: data.response });
});

// Example output of buildChainContext(blockchain)

Blockchain Status:
- Block height: 12
- Difficulty: 3
- Chain valid: yes

Balances:
- 04a1b2...e5f6: 180 coins (mined 4 blocks)
- 04f6a7...d0e1: 70 coins (mined 0 blocks)
- Bot-Paris: 250 coins (mined 5 blocks)
- Bot-Tokyo: 150 coins (mined 3 blocks)

Last 5 transactions:
- Block 12: 04a1b2... sent 20 to 04f6a7...
- Block 12: MINING_REWARD → 04a1b2... (50 coins)
- Block 11: Bot-Paris mined empty block (reward only)
- Block 10: 04f6a7... sent 10 to 04a1b2...
- Block 10: MINING_REWARD → Bot-Tokyo (50 coins)

Mempool (pending): 1 transaction
- 04a1b2... → 04f6a7...: 15 coins (waiting to be mined)