QUICKSTART.md

CoreRelay - Quick Start Guide

Get CoreRelay running on Core Chain locally in 5 minutes.

Prerequisites

• Docker & Docker Compose installed
• 8GB RAM, 4 CPU cores
• Internet connection

Steps

1. Clone Repository

git clone https://github.com/core-relay/corerelay.git
cd corerelay

2. Start Services

docker-compose up -d

This starts:

• 1x CoreRelay Gateway (port 8545) configured for Core Chain (chainId 1116)
• 3x Mesh Nodes (with Bitcoin light client integration)
• 1x Redis cache

3. Test Core Chain RPC Endpoint

# Verify Core Chain connection (chainId should be 0x45c = 1116)
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_chainId",
    "params": [],
    "id": 1
  }'
# Expected: {"jsonrpc":"2.0","result":"0x45c","id":1}

# Get latest block number on Core Chain
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": [],
    "id": 1
  }'

# Get CORE token balance
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "latest"],
    "id": 1
  }'

# Query dual-staking information (Core-specific method)
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "core_getStakingInfo",
    "params": ["0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"],
    "id": 1
  }'

4. Use in Your Core Chain dApp

// ethers.js v6
const { ethers } = require('ethers');

// Connect to CoreRelay (instead of centralized RPC)
const provider = new ethers.JsonRpcProvider('http://localhost:8545');

// Verify we're connected to Core Chain
const network = await provider.getNetwork();
console.log('Network:', network.name);  // "core"
console.log('Chain ID:', network.chainId);  // 1116

// Standard balance query
const balance = await provider.getBalance('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
console.log('CORE Balance:', ethers.formatEther(balance), 'CORE');

// Core Chain-specific: Query dual-staking info
const stakingInfo = await provider.send('core_getStakingInfo', [
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
]);
console.log('BTC Staked:', stakingInfo.btcStaked);
console.log('CORE Delegated:', stakingInfo.coreDelegated);
console.log('Total Rewards:', stakingInfo.rewards);

// Verify response with cryptographic proof (optional)
const proof = await provider.send('corerelay_getProof', [
  stakingInfo.requestId
]);
console.log('✅ Verified by', proof.consensus.agreements, 'independent nodes');
console.log('Client diversity:', proof.attestations.map(a => a.client_type));

5. Run Example BTCfi dApp

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Run Core Chain example
cd examples
cargo run --example core_btcfi_dapp

This example demonstrates:

• Querying dual-staking (BTC + CORE) information
• Verifying Bitcoin transaction finality
• Checking validator delegations
• Response proof verification

Advanced: Bitcoin L1 Finality Verification

CoreRelay includes Bitcoin light client integration for verifying BTC transactions:

// Verify a Bitcoin transaction has reached finality
// (Critical for non-custodial BTC staking protocols)
const btcTxStatus = await provider.send('core_verifyBtcTransaction', [
  '3a7d8f2e1c4b5a9d6e8f7c2b1a3e5d7f9c8b7a6e5d4c3b2a1f0e9d8c7b6a5e4d',  // BTC tx hash
  6  // Required confirmations (standard for finality)
]);

console.log('Confirmed:', btcTxStatus.confirmed);
console.log('Confirmations:', btcTxStatus.confirmations);
console.log('Block Height:', btcTxStatus.blockHeight);
console.log('Merkle Proof:', btcTxStatus.merkleProof);  // For audit trails

Using CoreRelay in Production (Core Chain Mainnet)

// Production configuration
const provider = new ethers.JsonRpcProvider('https://rpc.corerelay.network', {
  chainId: 1116,  // Core Chain mainnet
  name: 'core'
});

// All requests automatically verified by mesh consensus
// No code changes needed for trustless infrastructure!

What's Next?

• Deploy to Production: Setup Guide
• Run a Core Chain Mesh Node: Node Operator Guide
• Core Chain API Reference: Full JSON-RPC + Core Extensions
• Architecture Deep Dive: CoreRelay Technical Architecture
• Bitcoin Integration: BTC Light Client Setup

Troubleshooting

Gateway won't start

# Check logs
docker-compose logs gateway

# Ensure port 8545 is free
sudo lsof -i :8545

# Verify Core Chain connectivity
docker-compose exec mesh-node-1 curl http://rpc.coredao.org

Slow responses

# Wait for mesh nodes to sync with Core Chain (2-5 minutes)
docker-compose logs mesh-node-1

# Check Core Chain mesh node status
curl http://localhost:9001/health

# Check Bitcoin light client sync status
curl http://localhost:9001/bitcoin-status

Core Chain connection issues

# Verify Core Chain RPC endpoints are reachable
curl -X POST https://rpc.coredao.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

# Should return: {"jsonrpc":"2.0","result":"0x45c","id":1}  # 1116 in hex

# Check CoreRelay configuration
docker-compose exec gateway cat /etc/corerelay/config.toml | grep network
# Should show: network = "core-mainnet"

Bitcoin finality verification slow

# Check Bitcoin light client sync progress
curl http://localhost:9001/bitcoin-status

# Bitcoin initial sync can take 30-60 minutes
# Monitor progress: docker-compose logs btc-light-client -f

Support

• Core DAO Forum: https://forum.coredao.org/c/corerelay
• Discord: https://discord.gg/corerelay
• GitHub Issues: https://github.com/core-relay/corerelay/issues
• Twitter: @CoreRelay
• Email: team@corerelay.network
• Grants Inquiries: grants@corerelay.network

Core Chain Resources

• Core DAO Website: https://coredao.org
• Core Chain Explorer: https://scan.coredao.org
• Core Chain Docs: https://docs.coredao.org
• BTCfi Documentation: https://docs.coredao.org/developer/introduction/btcfi