# hyoungsungkim/ecc-pow-project architecture

> Architecture diagram of the GitHub repository hyoungsungkim/ecc-pow-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyoungsungkim/ecc-pow-project
- Repository: https://github.com/hyoungsungkim/ecc-pow-project

## Overview

##### Project type and purpose
- This is a blockchain consensus‐algorithm project implementing Error Correction Code Proof‐of‐Work (ECCPoW). It provides:
- Prototype implementations in C++/Python (“Ecc-PoW-pseudo-code”, “LDPC-pseudo-code”)
- A production-grade Go port of the LDPC decoder and difficulty control (“ldpc” folder)
- Integration hooks for go-ethereum’s consensus layer under `consensus/eccpow` (referenced in README)
- Purpose: explore and evaluate an ECC-based PoW variant, optimize decoding performance, then plug it into an Ethereum client.

##### File structure
- Top-level artifacts:
- `.gitignore`, `go.mod`, `go.sum`, `mainForTest.go` (test harness in Go)
- `Ecc-PoW-pseudo-code/` – C++ & Python prototyping of ECCPoW mining (blockchain_core.py, Miner scripts, trader.py)
- `LDPC-pseudo-code/` – two versions of C++ pseudo-code for LDPC integration tests
- `ldpc/` – Go implementation of LDPC decoder, difficulty control, utility functions, and a `forGoEth/` subfolder mirroring the same for direct inclusion in go-ethereum
- Patterns:
- Layered: decoder, difficulty control, consensus algorithm
- Concurrency: extensive goroutine use, channels for stop signals
- Config/inputs: test files (`*_test.go`), presentation assets in `img/`

##### README for additional insights
- The README outlines:
- ECCPoW concept images (error correction + Ethash)
- Porting chronology, optimizations (optimized decoding loops)
- Concurrency mining algorithm (channels: outerLoopSignal, innerLoopSignal, goRoutineSignal)
- Difficulty adjustment formulas for both Ethash and LDPC
- Integration status with go-ethereum consensus

##### Main components
a. Prototype layer (optional for historical context)
– C++/Python scripts for initial ECCPoW mining and trading
b. Core Go components
1) LDPC Decoder Module (`ldpc/decoder.go`, `decoder_concurrency.go`, `decoder_utils.go`)
2) Difficulty Control Module (`ldpc/difficultyControl.go`)
3) Consensus Algorithm (`consensus/eccpow/algorithm.go` in go-ethereum)
4) Test harness (`mainForTest.go`)
c. go-ethereum integration
– Chain reader interface (`consensus.ChainReader`)
– Block header input and block submission output
d. External services
– Crypto/rand for nonce generation
– Go scheduler (goroutines, WaitGroup)

##### Relationships and data flows
1) go-ethereum triggers `Seal()` in consensus/eccpow → passes block header to ECCPoW module
2) ECCPoW algorithm spins up N goroutines
– Each goroutine:
- Generates random LDPCNonce via crypto/rand
- Feeds header + nonce into LDPC Decoder
- Calls `MakeDecision()` to check if PoW target is met
– Channels coordinate early stop on success
3) On success → miner returns completed block to go-ethereum → block is broadcast
4) Difficulty Control module computes next target based on parent difficulty & block time
5) Test harness (`mainForTest.go`) directly invokes LDPC decoder and difficulty functions for benchmarks

##### Architectural patterns and design principles
- Layered separation of concerns:
- Decoder (data-intensive, math-heavy)
- Consensus orchestration (concurrency, channels)
- Difficulty management (parameter tuning, formulas)
- Concurrency via goroutines + channels to maximize CPU utilization and enable early exit
- Test-driven modules (`*_test.go`) ensure deterministic behavior and performance metrics

- Clear labels for each module (e.g., “LDPC Decoder”, “Difficulty Control”)

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Prototype Layer"
    Proto["Prototype Implementations (C++/Python)"]:::prototype
  end
  click Proto "https://github.com/hyoungsungkim/ecc-pow-project/tree/master/Ecc-PoW-pseudo-code/"

  subgraph "Core Go Modules"
    subgraph "LDPC Decoder"
      Decoder["LDPC Decoder Module"]:::compute
      DecConcurrency["Decoder Concurrency"]:::compute
      DecUtils["Decoder Utilities"]:::compute
      EthTypes["Ethereum-specific Types"]:::compute
      Decoder --> DecConcurrency
      Decoder --> DecUtils
    end
    subgraph "Difficulty Control"
      DiffCtrl["Difficulty Control Module"]:::compute
      DiffUtils["Difficulty Utils"]:::compute
      DiffCtrl --> DiffUtils
    end
    subgraph "Consensus Orchestrator"
      Orchestrator["ECCPoW Consensus Orchestrator\ngoroutines (N), channels"]:::orchestrator
      Orchestrator -->|controls goroutines| DecConcurrency
      Orchestrator -->|requests decode| Decoder
      Orchestrator -->|triggers difficulty| DiffCtrl
    end
  end

  subgraph "Go-Ethereum Mirror Modules"
    GE_Decoder["LDPC Decoder Module (GoEth)"]:::compute
    GE_DecConcurrency["Decoder Concurrency (GoEth)"]:::compute
    GE_DecUtils["Decoder Utilities (GoEth)"]:::compute
    GE_DiffCtrl["Difficulty Control (GoEth)"]:::compute
    GE_DiffUtils["Difficulty Utils (GoEth)"]:::compute
    GE_EthTypes["Ethereum-specific Types (GoEth)"]:::compute
    GE_Decoder --> GE_DecConcurrency
    GE_Decoder --> GE_DecUtils
    GE_DiffCtrl --> GE_DiffUtils
  end

  subgraph "go-ethereum Integration"
    GECore["Go-Ethereum Core"]:::external
    SubChainReader["ChainReader Interface"]:::external
    Seal["Seal() Hook"]:::external
    SubChainReader --> Seal
    Seal --> Orchestrator
    Orchestrator -->|valid block| GECore
    DiffCtrl -->|new difficulty| GECore
  end

  subgraph "External Utilities"
    Crypto["Crypto/Rand"]:::external
    Scheduler["Go Scheduler"]:::external
    Crypto --> Orchestrator
    Scheduler --> Orchestrator
  end

  subgraph "Test Harness"
    TestHarness["Test Harness (mainForTest.go)"]:::test
    TestHarness --> Decoder
    TestHarness --> DiffCtrl
  end

  %% Click Events for Core Modules
  click Decoder "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/decoder.go"
  click DecConcurrency "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/decoder_concurrency.go"
  click DecUtils "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/decoder_utils.go"
  click DiffCtrl "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/difficultyControl.go"
  click DiffUtils "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/difficultyControl_utils.go"
  click EthTypes "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/ethTypes.go"

  %% Click Events for Go-Ethereum Mirror
  click GE_Decoder "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/decoder.go"
  click GE_DecConcurrency "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/decoder_concurrency.go"
  click GE_DecUtils "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/decoder_utils.go"
  click GE_DiffCtrl "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/difficultyControl.go"
  click GE_DiffUtils "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/difficultyControl_utils.go"
  click GE_EthTypes "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/ethTypes.go"

  %% Click Events for Unit Tests
  click Decoder "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/decoder_test.go"
  click DiffCtrl "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/difficultyControl_test.go"
  click GE_Decoder "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/decoder_test.go"
  click GE_DiffCtrl "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/ldpc/forGoEth/difficultyControl_test.go"

  %% Click Event for Test Harness
  click TestHarness "https://github.com/hyoungsungkim/ecc-pow-project/blob/master/mainForTest.go"

  %% Styles
  classDef compute fill:#D0E8FF,stroke:#6BA4FF;
  classDef orchestrator fill:#D0FFD6,stroke:#00A85A;
  classDef external fill:#FFE0B3,stroke:#FF9400;
  classDef prototype fill:#F0F0F0,stroke:#A0A0A0;
  classDef test fill:#FFF2CC,stroke:#FFD966;
```
