BlockRS - Blockchain Simulation in a Localized Environment

Overview

BlockRS is an open-source initiative that demonstrates blockchain technology principles in a localized environment. This project implements core blockchain concepts including distributed networks, mining, transaction signing, and utilizes the POSIX API.

While a Win32 frontend has been conceptualized, it is currently not available due to development constraints. A Dockerfile is provided as an alternative for cross-platform compatibility.

For a comprehensive understanding of the systems design, please refer to the BlockRS Whitepaper (link forthcoming).

Table of Contents

• Overview
• Prerequisites
• Installation
  • Docker Installation
  • Manual Installation
• Building the Project
• Usage Guide
  • Starting the Blockchain Server
  • Running a Node
  • Running a Wallet Server
• API Reference
  • Blockchain Server Endpoints
  • Node Server Endpoints
  • Wallet Server Endpoints
• Contributing
• Support
• License

Prerequisites

• Git
• CMake (3.10 or higher)
• C++ Compiler (with C++17 support)
• Docker (optional, but recommended)
• Unix-like environment (for non-Docker installations)

Installation

Begin by cloning the repository with its submodules:

git clone --recurse-submodules https://github.com/shrehanrajsingh/blockrs.git
cd blockrs

Docker Installation

The simplest way to get started with BlockRS is using Docker, which provides a consistent environment across all platforms.

1. Build the Docker image: docker build -t blockrs .

2. Run the container with required ports: docker run -it -p 8000:8000 -p 8100:8100 -p 9000:9000 blockrs

Important: BlockRS requires at least three exposed ports to run a complete environment:

• Port 8000: Blockchain server
• Port 8100: Node server
• Port 9000: Wallet server

You can modify these port mappings as needed for your environment. Refer to docs/video for a detailed installation guide.

Manual Installation

While Docker is the recommended approach for consistent environments, manual installation is possible on Unix-like systems.

Note: For Windows users, please use Docker or a Unix environment shell like Cygwin.

The project depends on two libraries in the lib/ folder:

• bdwgc/: A garbage collector (experimental)
• secp256k1/: Library for encrypted signing

The bdwgc library is automatically included by CMake, but secp256k1 requires manual building with specific configuration flags.

Build the secp256k1 library with the following commands:

cd lib/secp256k1
./autogen.sh
./configure --enable-module-recovery
make
sudo make install

This installation places:

• libsecp256k1.a in /usr/local/lib
• Header files in /usr/local/include/secp256k1.h and related locations

Note: If you discover a method to integrate secp256k1 directly into the CMake configuration, please share it. This would help reduce the dependency on Docker. Docker support will be maintained regardless to facilitate running networks in dedicated servers beyond localhost.

Building the Project

Once the dependencies are in place, build the project by executing these commands from the root directory:

mkdir build
cmake --build build --config Debug --target all

This build process will generate several components:

• gc: Garbage collector
• cord: String handling library
• blockrs: The main BlockRS library
• TEXE: Test executable

If you encounter any build issues, please check the error messages for missing dependencies or configuration problems. Feel free to open an issue on GitHub for assistance.

Usage Guide

BlockRS is designed as a library (libblockrs) to enable integration into various projects and potentially support different programming languages through API integration.

While a dedicated standalone executable is in development, you can use the test executable to explore the functionality.

Starting the Blockchain Server

To start the blockchain server on port 8000:

cd build/tests
./TEXE -s chain -p 8000

Running a Node

In a separate terminal, start a node server on port 8100:

./TEXE -s node -p 8100

Connect this node to the blockchain network with:

curl -X POST http://127.0.0.1:8100/connect \
         -H "Content-Type: application/json" \
         -d '{"url": "127.0.0.1:8000"}'

Running a Wallet Server

In another terminal, run a wallet server on port 9000:

./TEXE -s wallet -p 9000

Note: Node servers have built-in wallets to receive currency rewards when mining blocks. Future versions will allow linking external wallet servers to node servers.

Once all components are running, you can access the web interfaces:

• Blockchain Server
• Node Server
• Wallet Server

If you need guidance at any step, please refer to the video tutorials in the docs/video/ folder or reach out via email.

API Reference

Blockchain Server Endpoints

Endpoint	Methods	Description
/	GET, POST, HEAD	Basic server information
/info	GET	View the entire blockchain as JSON
/nodes	GET, HEAD	View all connected nodes
/transaction/new	GET, POST	Add a new transaction (requires a Wallet Server)
/transaction/all	GET, POST	View all pending and rejected transactions
/addnode	POST	Add a node to the network (used internally)

Example of adding a node:

curl -X POST http://127.0.0.1:8000/addnode \
        -H "Content-Type: application/json" \
        -d '{"url": "<nodeserver url>"}'

Node Server Endpoints

Endpoint	Methods	Description
/	GET, POST	Basic server information
/info	GET	View server properties as JSON
/connect	POST	Connect to a blockchain server
/mine	GET	Mine a block (one thread at a time)
/update	GET	Fetch latest block data from blockchain
/wallet	GET	View wallet information
/wallet/sign	POST	Sign a transaction using node's wallet
/wallet/verify	POST	Verify a message signature

Example of connecting to a blockchain server:

curl -X POST http://127.0.0.1:8100/connect \
        -H "Content-Type: application/json" \
        -d '{"url": "<blockchain server url>"}'

Example of signing a message:

curl -X POST http://127.0.0.1:8100/wallet/sign \
        -H "Content-Type: application/json" \
        -d '{"nonce": ..., "to": "...", "value": ..., "gas_fee": ..., "data": ...}'

Example of verifying a message:

curl -X POST http://127.0.0.1:8100/wallet/verify \
        -H "Content-Type: application/json" \
        -d '{"message": ..., "sign": "<signature>"}'

Wallet Server Endpoints

Endpoint	Methods	Description
/	GET, POST	Basic server information
/info	GET	Get wallet information (public key and address)
/sign	POST	Sign a message
/verify	POST	Verify a message against a signature

Example of signing a message:

curl -X POST http://127.0.0.1:9000/sign \
        -H "Content-Type: application/json" \
        -d '{"message": ...}'

Example of verifying a message:

curl -X POST http://127.0.0.1:9000/verify \
        -H "Content-Type: application/json" \
        -d '{"message": ..., "signature": "<signature>"}'

If you're unsure about how to use these endpoints, please check the video tutorials in the docs/video/ directory for detailed guidance.

Contributing

Contributions to BlockRS are welcome! Please see the CONTRIBUTING file for guidelines.

Support

If you need assistance or have questions, please contact:

• Email: [email protected] or [email protected]
• GitHub: shrehanrajsingh
• LinkedIn: Shrehan Raj Singh

License

This project is licensed under the terms of the LICENSE file.

---

Developed by Shrehan Raj Singh