Skip to content
/ CoreRelay Public

CoreRelay is a verifiable, censorship-resistant RPC infrastructure network designed specifically for Core Chain's Bitcoin-aligned ecosystem. By combining multi-client consensus verification, native Bitcoin light-client integration, and optimized support for Core's Satoshi Plus dual-staking model, CoreRelay eliminates the trust assumptions.

core-relay.vercel.app

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

Marvy247/CoreRelay

BranchesTags

Repository files navigation

CoreRelay

The Decentralized RPC Layer Purpose-Built for Core Chain and BTCfi Applications

License: MIT Rust Core Chain

Overview

CoreRelay is a verifiable, censorship-resistant RPC infrastructure network designed specifically for Core Chain's Bitcoin-aligned ecosystem. By combining multi-client consensus verification, native Bitcoin light-client integration, and optimized support for Core's Satoshi Plus dual-staking model, CoreRelay eliminates the trust assumptions inherent in centralized RPC providers while maintaining production-grade performance.

Perfect for:

  • 🪙 BTCfi Applications requiring trustless Bitcoin staking queries
  • 🔐 Non-Custodial Bitcoin Protocols needing verifiable on-chain data
  • 🌐 Core Chain dApps demanding censorship resistance
  • 💼 Institutional Users requiring cryptographic audit trails
  • 🏗️ Developers building on Core's dual-staking infrastructure

Why CoreRelay?

The Problem

Core Chain's explosive growth in BTCfi is threatened by centralized infrastructure. When you query an RPC provider like Infura or Alchemy:

  • ❌ You trust they return accurate data (no cryptographic proof)
  • ❌ They can censor your transactions or specific addresses
  • ❌ They see all your activity (privacy violation)
  • ❌ Single point of failure (when they go down, your dApp goes down)
  • ❌ No Core-native features (generic Ethereum, no Bitcoin integration)

The CoreRelay Solution

✅ Trustless: Multi-client consensus with BLS signature verification
✅ Censorship-Resistant: Decentralized P2P mesh (50+ nodes at mainnet)
✅ Core-Native: chainId 1116, core_getStakingInfo, Bitcoin finality checks
✅ Bitcoin-Integrated: Light client for BTC L1 finality verification
✅ Verifiable: Every response includes Merkle proof bundle
✅ Private: Requests distributed across anonymous mesh nodes
✅ Drop-In Compatible: Works with ethers.js, web3.js, viem, Hardhat

Architecture

graph TB
    subgraph "dApp Layer"
        A[BTCfi dApp<br/>web3.js/ethers.js]
        B[Core Wallet]
        C[DeFi Protocol]
    end
    
    subgraph "CoreRelay Gateway"
        D[Load Balancer]
        E[Request Router]
        F[Consensus Verifier]
        G[Bitcoin Finality Checker]
        H[Redis Cache]
    end
    
    subgraph "Mesh Network"
        I1[Mesh Node 1<br/>Helios + BTC Light Client]
        I2[Mesh Node 2<br/>Nimbus + BTC Light Client]
        I3[Mesh Node 3<br/>Lodestar + BTC Light Client]
        I4[Mesh Node N...]
    end
    
    subgraph "Data Sources"
        J[Core Chain Nodes<br/>chainId 1116]
        K[Bitcoin Network<br/>L1 Finality]
        L[Portal Network<br/>Distributed Storage]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    E --> G
    F --> H
    
    E --> I1
    E --> I2
    E --> I3
    E --> I4
    
    I1 --> J
    I2 --> J
    I3 --> J
    I4 --> J
    
    I1 --> K
    I2 --> K
    I3 --> K
    
    I1 --> L
    I2 --> L
    I3 --> L
    
    style A fill:#FF6B00
    style B fill:#FF6B00
    style C fill:#FF6B00
    style F fill:#00D395
    style G fill:#F7931A
    style K fill:#F7931A
Loading

How It Works:

  1. Your dApp sends a standard JSON-RPC request (e.g., core_getStakingInfo)
  2. CoreRelay Gateway queries 3+ diverse mesh nodes running different light clients
  3. Each node returns response + BLS signature + Merkle proof
  4. Gateway performs consensus verification (requires 2/3 agreement)
  5. For BTC-related queries, Bitcoin light client verifies L1 finality
  6. Verified response returned with proof bundle (auditable)

Quick Start

Docker Compose (Fastest)

git clone https://github.com/core-relay/corerelay.git
cd corerelay
docker-compose up -d

# Test Core Chain RPC
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}  # 0x45c = 1116 (Core Chain)

Use in Your dApp

// ethers.js v6
import { ethers } from 'ethers';

// Replace centralized RPC with CoreRelay
const provider = new ethers.JsonRpcProvider('http://localhost:8545');

// All standard Core Chain methods work
const balance = await provider.getBalance('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
console.log('Balance:', ethers.formatEther(balance), 'CORE');

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

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

Core Chain-Specific Features

1. Native Core Chain Support (chainId 1116)

Out-of-the-box support for Core mainnet and testnet with optimized configurations.

2. Dual-Staking Query Methods

// Query Bitcoin staking information
core_getStakingInfo(address) → {
  btcStaked: bigint,
  coreStaked: bigint,
  btcDelegations: Delegation[],
  coreDelegations: Delegation[],
  rewards: bigint
}

// Get validator delegations
core_getDelegations(validatorAddress) → {
  totalBtcDelegated: bigint,
  totalCoreDelegated: bigint,
  delegators: Address[]
}

// Query validator set with dual-staking weights
core_getValidatorSet(blockNumber) → {
  validators: [{
    address: Address,
    btcPower: bigint,
    corePower: bigint,
    hybridScore: bigint
  }]
}

3. Bitcoin L1 Finality Verification

// Verify Bitcoin transaction finality for non-custodial staking
core_verifyBtcTransaction(txHash, requiredConfirmations) → {
  confirmed: boolean,
  confirmations: number,
  blockHeight: number,
  merkleProof: string[],
  btcBlockHash: string
}

4. BTC-Aware Load Balancing

CoreRelay automatically routes Bitcoin-related queries to mesh nodes with synced Bitcoin light clients, ensuring low-latency cross-chain verification.

5. Fee Market Support

Full support for Core Chain's EIP-1559 implementation plus Core-specific fee fields:

core_feeHistory(blockCount, newestBlock) → {
  baseFeePerGas: bigint[],
  gasUsedRatio: number[],
  coreSpecificFee: bigint[]  // Core Chain validator rewards
}

Supported RPC Methods

Standard Ethereum JSON-RPC (Core Chain Compatible)

  • eth_blockNumber, eth_getBalance, eth_getCode
  • eth_call, eth_estimateGas, eth_sendRawTransaction
  • eth_getBlockByNumber, eth_getBlockByHash
  • eth_getTransactionByHash, eth_getTransactionReceipt
  • eth_getLogs, eth_getStorageAt
  • eth_chainId (returns 1116 for Core mainnet)
  • eth_gasPrice, eth_maxPriorityFeePerGas, eth_feeHistory

Core Chain-Specific Extensions

  • core_getStakingInfo - Dual-staking (BTC + CORE) data
  • core_getDelegations - Validator delegation queries
  • core_getValidatorSet - Satoshi Plus validator info
  • core_verifyBtcTransaction - Bitcoin L1 finality checks
  • core_feeHistory - Core-specific fee market data

CoreRelay Meta Methods

  • corerelay_getProof - Retrieve cryptographic proof bundle for any request
  • corerelay_getNodeInfo - Mesh network status and peer info
  • corerelay_verifyResponse - Client-side proof verification

Performance

Latency Benchmarks (Core Chain Mainnet)

Method Centralized RPC CoreRelay (uncached) CoreRelay (cached)
eth_blockNumber 42ms 165ms 6ms
eth_getBalance 78ms 298ms 11ms
core_getStakingInfo 95ms 340ms 14ms
core_verifyBtcTransaction N/A 450ms 18ms
eth_call 142ms 425ms N/A

Cache Hit Rate: 72-85% for typical BTCfi workloads
Consensus Overhead: ~2.2x vs single centralized provider
Trade-off: Trustlessness and censorship resistance for modest latency increase

Deployment Options

Development (Local)

docker-compose up -d
# Starts: 1 Gateway, 3 Mesh Nodes, Redis cache

Production (Self-Hosted)

# Install CoreRelay
curl -sSL https://install.corerelay.network | bash

# Configure for Core Chain
corerelay init --network core-mainnet --nodes 5

# Start services
systemctl start corerelay-gateway
systemctl start corerelay-mesh-node

Cloud (Kubernetes)

# Deploy to Core Chain-optimized cluster
kubectl apply -f k8s/corerelay-core-mainnet.yaml

Minimum Requirements:

  • Gateway: 4GB RAM, 2 CPU cores, 20GB SSD
  • Mesh Node: 8GB RAM, 4 CPU cores, 100GB SSD (includes BTC light client)

Roadmap

Current: MVP (Q4 2025) ✅

  • 17 supported RPC methods (Ethereum-compatible)
  • 3 test mesh nodes operational
  • Multi-client consensus (Helios integration)
  • Basic proof bundles

Phase 1: Core Chain Integration (Q1 2026)

  • Native Core Chain support (chainId 1116)
  • Core-specific RPC methods (core_getStakingInfo, etc.)
  • Bitcoin light client integration (BTC finality verification)
  • Optimized caching for dual-staking queries
  • 20+ mesh nodes (geographically distributed)

Phase 2: Mainnet Launch (Q2 2026)

  • Security audit (Trail of Bits)
  • 50+ mesh nodes globally
  • WebSocket subscriptions for real-time events
  • Advanced peer reputation system
  • Public gateway (rpc.corerelay.network)

Phase 3: Ecosystem Growth (Q3-Q4 2026)

  • SDK/libraries (JavaScript, Python, Rust, Go)
  • Wallet integrations (Core Wallet, MetaMask Snap)
  • BTCfi protocol partnerships (5+ integrations)
  • Economic incentives (CORERELAY token)
  • Governance DAO launch

Phase 4: Advanced Features (2027+)

  • zkSNARK proof aggregation
  • Cross-chain verification (Core ↔ Bitcoin ↔ Ethereum)
  • Advanced Bitcoin scripting support
  • Lightning Network integration
  • Private mesh networks for institutions

Security

Multi-Layered Verification

  1. Cryptographic Signatures: Every mesh node signs responses with BLS keys
  2. Merkle Proofs: State queries include proofs linking to Core Chain state root
  3. Client Diversity: Requires consensus from ≥2 different light client implementations
  4. Bitcoin Finality: BTC transactions verified against Bitcoin L1 (6+ confirmations)
  5. Consensus Quorum: Minimum 2/3 agreement required (Byzantine fault tolerant)

Threat Model

✅ Protected Against:

  • Malicious RPC provider returning fake data
  • Single light client implementation bugs
  • Sybil attacks (client diversity requirement)
  • Eclipse attacks (random peer selection)
  • Censorship (permissionless P2P mesh)

❌ Not Protected Against:

  • Compromised ≥2/3 of queried mesh nodes (same as any BFT system)
  • Bugs in ≥2 different light client implementations simultaneously
  • Fundamental cryptographic primitive breaks (SHA-256, BLS12-381)

Audit Status

  • Current: Internal security review completed
  • Planned: Trail of Bits audit (Q2 2026, funded by Core DAO grant)

Use Cases

1. BTCfi Protocols

Non-custodial Bitcoin staking dApps need verifiable on-chain data:

// Trustlessly verify user's BTC stake before allowing withdrawals
const stakingInfo = await provider.send('core_getStakingInfo', [userAddress]);
const proof = await provider.send('corerelay_getProof', [stakingInfo.requestId]);

// Cryptographically verify proof (can be done off-chain for auditing)
assert(verifyProof(proof, stakingInfo));

// Safe to process withdrawal
processWithdrawal(userAddress, stakingInfo.btcStaked);

2. Core Chain Wallets

Privacy-preserving RPC access without centralized providers seeing all transactions:

// Requests distributed across mesh, no single observer
const balance = await provider.getBalance(userAddress);  // Node A
const nonce = await provider.getTransactionCount(userAddress);  // Node B
const gasPrice = await provider.getFeeData();  // Node C

// Centralized provider would see: address + balance + nonce + timing
// CoreRelay: Each node sees only one piece, can't correlate

3. DeFi Protocols

High-value DeFi needing audit trails and verifiable data:

// Every price feed query is cryptographically provable
const price = await oracle.getPrice('BTC/CORE');
const proof = await provider.send('corerelay_getProof', [price.requestId]);

// Store proof for audit/regulatory compliance
await auditLog.store(price, proof);  // Immutable proof bundle

4. Cross-Chain Bridges

Bitcoin ↔ Core Chain bridges requiring trustless verification:

// Verify Bitcoin transaction finalized before minting wrapped BTC
const btcTx = await provider.send('core_verifyBtcTransaction', [
  txHash, 
  6  // require 6 confirmations
]);

if (btcTx.confirmed) {
  await wbtcContract.mint(recipient, amount, btcTx.merkleProof);
}

Contributing

CoreRelay is open-source and community-governed. We welcome contributions!

Ways to Contribute

Development Setup

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

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

# Build
cargo build --release

# Run tests
cargo test --all

# Start local development environment
docker-compose -f docker-compose.dev.yml up

Community & Support

Grant Inquiries

CoreRelay is actively seeking support from the Core DAO ecosystem grants program. If you're interested in supporting decentralized infrastructure for Core Chain:

License

CoreRelay is open-source software licensed under the MIT License.

Copyright (c) 2025 CoreRelay Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, subject to the following conditions:

[See LICENSE file for full text]

Acknowledgments

Built for the Core Chain and Bitcoin communities.

Powered by:

Special Thanks:

  • Core DAO team for building Bitcoin-aligned EVM infrastructure
  • Ethereum light client teams for trustless verification primitives
  • The BTCfi ecosystem for pioneering non-custodial Bitcoin DeFi

Build trustless. Build decentralized. Build on CoreRelay.

About

CoreRelay is a verifiable, censorship-resistant RPC infrastructure network designed specifically for Core Chain's Bitcoin-aligned ecosystem. By combining multi-client consensus verification, native Bitcoin light-client integration, and optimized support for Core's Satoshi Plus dual-staking model, CoreRelay eliminates the trust assumptions.

core-relay.vercel.app

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages