CrypChain Documentation

Introduction

CrypChain is a modern, TypeScript-based blockchain implementation designed for educational purposes and real-world applications. It demonstrates core blockchain concepts while maintaining a clean, maintainable codebase.

Setup locally

Prerequisites

• Node.js (v16 or higher)
• npm (v7 or higher)
• TypeScript (v4.5+)
• Git

Installation

1. Clone the repository

   git clone https://github.com/iminoaru/CrypChain.git

2. Navigate to the project directory

   cd CrypChain

3. Install the dependencies

   npm install

4. Build the project

   npm run build

Core Concepts

Blockchain Structure

Each block in CrypChain contains:

• Timestamp
• Previous block hash
• Transaction data
• Nonce value
• Difficulty target

Mining Process

The mining process follows these steps:

1. Collect pending transactions from the pool
2. Create a new block with these transactions
3. Calculate the target difficulty
4. Find a nonce that satisfies the difficulty requirement
5. Broadcast the new block to the network

API Endpoints

CrypChain provides a RESTful API for interacting with the blockchain:

GET Endpoints

• GET /blockchain

  Returns the entire blockchain. Response includes block height, timestamp, and transaction count.

• GET /transactions

  Returns all pending transactions in the pool. Includes sender, recipient, amount, and timestamp.

• GET /public-key

  Returns the node's public key for receiving transactions.

• GET /mine-transactions

  Triggers the mining process for pending transactions.

• GET /peers

  Returns a list of connected peer nodes.

POST Endpoints

• POST /mine

  Mines a new block. Request body should include the block data.

  {
    "data": "Block data here"
  }

• POST /transfer

  Creates a new transaction. Required fields:

  {
    "recipient": "public_key_here",
    "amount": 100
  }

Running Multiple Instances

To create a local test network, run multiple instances with different ports:

# Terminal 1 (Primary Node)
HTTP_PORT=3001 P2P_PORT=5001 npm run dev

# Terminal 2 (Secondary Node)
HTTP_PORT=3002 P2P_PORT=5002 PEERS=ws://localhost:5001 npm run dev

# Terminal 3 (Tertiary Node)
HTTP_PORT=3003 P2P_PORT=5003 PEERS=ws://localhost:5001,ws://localhost:5002 npm run dev

Network Architecture

CrypChain implements a decentralized peer-to-peer network where each node:

• Maintains a complete copy of the blockchain
• Validates new blocks and transactions
• Participates in the consensus mechanism
• Propagates new blocks and transactions to peers

Node Discovery

Nodes discover peers through:

• Static peer configuration
• Dynamic peer discovery
• Automatic peer sharing

Transaction Lifecycle

1. Transaction creation and signing
2. Propagation to network
3. Validation by nodes
4. Addition to transaction pool
5. Block inclusion during mining
6. Confirmation through block propagation

Development Guidelines

Code Style

The project follows these conventions:

• ESLint for code linting
• Prettier for code formatting
• TypeScript strict mode enabled
• Jest for testing

Contributing

To contribute to CrypChain:

1. Fork the repository
2. Create a feature branch
3. Implement your changes
4. Add tests for new functionality
5. Submit a pull request

Troubleshooting

Common Issues

• Node Connection Issues

  Verify firewall settings and port availability

• Mining Delays

  Check system resources and difficulty adjustment

• Transaction Failures

  Ensure proper key pair generation and sufficient balance