Dev Node

Node Version: v0.0.1

Setup Guide

This guide will walk you through the process of setting up and running a Hypestate network node using Docker Compose.

Prerequisites

• Software

  • Docker (version 20.10.0 or higher)

  • Docker Compose (version 2.0.0 or higher)

  • Git

• Hardware

  • CPU: 2+ cores recommended

  • RAM: 2GB

  • Storage: 4GB

  • Network: 5Mbps

Note: Requirements may vary based on network activity, transaction volume, number of connected peers, and chain state growth.

Installation Steps

1. Clone the Repository

git clone https://github.com/running-corsa.git
cd running-corsa

# checkout release version
git checkout v0.0.1

# Initialize submodules
git submodule init

2. Configure Environment Variables

# Create and edit the .env file
cp env.example .env

In the .env file, set the FAUCET_PRIVATE_KEY and INDEXER_START_BLOCK variables. The indexer start block is important if you are restarting the indexer and don't want to write duplicate blocks to the database. For the faucet private key it is easiest to use the private key of the address who gets the initial allocation of network tokens in the network's genesis file.

3. Build and Start the Services

# Build all services
docker compose build

# Start the entire stack
docker compose up -d

# View all active containers
docker ps

Service Architecture

The stack consists of the following services:

• nginx-proxy (Port 18444)

  • Reverse proxy service based on nginx:alpine

  • Handles routing and load balancing

  • Configured via mounted nginx.conf file

• bitcoin-regtest (Port 18443)

  • Bitcoin Core node running in regtest mode

  • Provides the underlying Bitcoin network functionality

• corsa-reth (Port 8545)

  • EVM-compatible JSON-RPC endpoint

  • Handles Ethereum-compatible transactions and smart contracts

• bitcoin-tx-queue (Port 5558)

  • Manages Bitcoin transaction queue

  • Coordinates with the Bitcoin regtest node

• corsa-enclave (Port 5555)

  • Handles network signing operations

  • Manages cryptographic operations

• hyperstate-utxos (Port 5557)

  • Tracks and manages UTXO state

  • Provides UTXO-related services

• hyperstate-indexer

  • Indexes Bitcoin blockchain data

  • Maintains synchronization with the Bitcoin node

• faucet (Port 5556)

  • Provides test tokens for development

  • Requires FAUCET_PRIVATE_KEY environment variable

Network Health Checks

Verify the execution client JSON-RPC endpoint:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545

Verify the bitcoin regtest client JSON-RPC endpoint:

curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"1.0","method":"getblockchaininfo","params":[],"id":1}' \
  -u user:password http://localhost:18443

Volumes

The following persistent volumes are used:

• bitcoin-data: Stores Bitcoin blockchain data

• utxo-data: Stores UTXO state information

• logs: General logging volume

All services are connected through a dedicated corsa bridge network for secure internal communication.