Skip to content

architecture.md

Latest commit

 

History

History
111 lines (83 loc) · 3.94 KB

architecture.md

File metadata and controls

111 lines (83 loc) · 3.94 KB
Raw

Architecture

Overview

GPUCoin is a blockchain where CUDA kernels (.cu files) serve as smart contracts. The system compiles CUDA source through BarraCUDA into BIR (BarraCUDA Intermediate Representation), which is stored on-chain as the canonical bytecode.

Component Layers

Core Layer (src/core/)

  • types.hpp: Fundamental types — Hash256, Address, Signature, uint256_t
  • transaction.hpp/cpp: Three transaction types with serialization
    • Type 0: Transfer (sender, recipient, amount)
    • Type 1: DeployKernel (sender, CUDA source, compiled BIR)
    • Type 2: ExecuteKernel (sender, kernel address, grid/block dims, args)
  • block.hpp/cpp: Block header with PoC fields, block body with transactions and receipts

Crypto Layer (src/crypto/)

  • SHA-256 and double SHA-256 via OpenSSL
  • Keccak-256 for Ethereum-compatible address derivation
  • secp256k1 key generation, signing, and recovery via OpenSSL 3.x EVP API
  • Merkle root computation

State Layer (src/state/)

  • StateDB: RocksDB wrapper with 10 column families:
    • block_headers, block_bodies, block_index
    • transactions, tx_index, receipts
    • state (accounts), kernels, kernel_state, metadata
  • WorldState: High-level state management — accounts, kernels, storage slots
  • MerkleTree: Binary Merkle tree with proof generation and verification

Compiler Layer (src/compiler/)

  • BarraCUDACompiler: RAII C++ wrapper around BarraCUDA's C99 API
    • Pipeline: preprocess -> lex -> parse -> sema -> bir_lower -> bir_mem2reg
    • Produces BIR (target-independent) and optionally .hsaco (AMD GPU binary)
  • KernelCache: Thread-safe LRU cache for compiled .hsaco binaries

Execution Layer (src/execution/)

  • ComputeMeter: BIR opcode cost table (144 opcodes). Deterministic gas calculation.
  • TransactionExecutor: Processes all three transaction types
  • GPURuntime: HIP/HSA kernel dispatch (gated behind GPUCOIN_HAS_GPU)

Consensus Layer (src/consensus/)

  • BIRInterpreter: Deterministic software execution of BIR programs
    • IEEE 754 round-to-nearest-even, no FMA
    • Sequential thread execution for determinism
  • ProofOfComputation: Block validation, difficulty adjustment, rewards
  • FraudProofVerifier: Challenge/response system with 100-block window

Network Layer (src/net/)

  • Custom wire protocol: 12-byte header (magic "GPUC", type, length, checksum)
  • Boost.Asio TCP sessions with async I/O
  • Peer management with scoring and ban lists
  • Two-phase gossip (announce hash, then send data on request)
  • Header-first block sync state machine

RPC Layer (src/rpc/)

  • JSON-RPC 2.0 over Boost.Beast HTTP
  • Ethereum-compatible methods (eth_blockNumber, eth_getBalance, etc.)
  • Custom GPU methods (gpu_deployKernel, gpu_executeKernel, etc.)

Node Layer (src/node/)

  • Chain: Chain management, genesis creation, fork choice (heaviest-compute)
  • FullNode: Wires all components, mining loop, message dispatch

Data Flow

Deploy Kernel

User submits .cu source via RPC
  -> Mempool accepts DeployKernel tx
  -> Miner includes in block
  -> Executor compiles via BarraCUDA
  -> BIR stored in WorldState (Kernels CF)
  -> Kernel address = hash(sender || nonce || source_hash)

Execute Kernel

User submits ExecuteKernel tx via RPC
  -> Mempool accepts tx
  -> Miner includes in block
  -> Executor loads BIR from WorldState
  -> GPU Runtime executes .hsaco on real GPU (fast path)
  -> Output hash + compute used stored in receipt
  -> Any validator can challenge within 100 blocks
  -> Challenge resolved via BIR interpreter (deterministic)

Key Constants

Parameter Value
Chain ID 42069
Block target 15 seconds
Difficulty adjustment Every 256 blocks
Base reward 50,000,000 (halves every 210,000 blocks)
Fee split 80% miner, 20% burned
Fraud proof window 100 blocks
Max BIR instructions 262,144
Max source size 4 MB