# ocean-xyz/datum_gateway architecture

> Architecture diagram of the GitHub repository ocean-xyz/datum_gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ocean-xyz/datum_gateway
- Repository: https://github.com/ocean-xyz/datum_gateway

## Overview

##### Main Components
- External Systems:
- Bitcoin Node: the external full node (recommended Bitcoin Knots) that provides block templates via RPC and notifies the gateway via blocknotify.
- Mining Hardware: the miners communicating through the Stratum v1 protocol.
- Mining Pool: uses the DATUM protocol for coordination, generation transaction payout splits, and work validation.

- Core DATUM Gateway Application:
- Gateway Core: responsible for retrieving block templates (using GBT mechanisms) from the Bitcoin node.
- Stratum Interface: handles communication with mining hardware, including Stratum v1 version rolling (ASICBoost) to distribute work.
- DATUM Protocol Module: manages encrypted communication and protocol operations with the pool.
- Utility & Support Modules: these include components like:
- datum_api – likely to encapsulate RPC calls and core interface functions,
- datum_conf – handling configurations,
- datum_logger – for logging system events,
- datum_queue, datum_sockets – managing data queues and network communication,
- Additional modules for block template construction (datum_blocktemplates, datum_submitblock) and protocol handling (datum_jsonrpc, datum_stratum and datum_stratum_dupes).

- Infrastructure and Build/Deployment Components:
- Build System: The CMakeLists.txt and cmake scripts, which coordinate the build with various CMake modules (e.g., EmbedResources, GenerateBuildInfo, VerifyExample).
- Packaging: The debian directory suggests packaging and distribution aspects.
- Continuous Integration: .github/workflows for automated builds.
- Web Interface: The www folder provides static HTML/CSS/JS files for configuration portals or a dashboard.

##### Relationships and Data Flow
- The Bitcoin Node provides block templates (via RPC with GBT) and sends block change notifications (using blocknotify) to the gateway.
- The Gateway Core uses this information to construct valid work for mining hardware.
- The Stratum Interface exposes work to mining hardware, handling incoming share submissions and other mining interactions.
- The DATUM Protocol Module manages communication with the pool. It both receives instructions (like generation transaction splits) and submits completed blocks. The exchange is secured - encryption and obfuscation are key.
- Internally, various utility modules (API, configuration, logging, etc.) handle cross-cutting concerns for proper functioning and debugging/monitoring.

##### Architectural Patterns and Technologies
- The project is modular: C source files are split into small, purpose-driven modules (e.g., API handling, configuration, logging). Although simple procedural C code doesn’t impose strict patterns, think of it as a functional modular design.
- The system relies on external libraries (libcurl for web RPC, libjansson for JSON parsing, libmicrohttpd for HTTP endpoints, and libsodium for encryption).
- The web assets (in www/) indicate a minimal dashboard or configuration UI—mark that as a separate presentation layer if needed.
- The build and deployment system is handled through CMake and Debian packaging, which can be noted at the infrastructure level.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        BN["Bitcoin Node\n(RPC,GBT,blocknotify)"]:::external
        MH["Mining Hardware\n(Stratum v1)"]:::external
        MP["Mining Pool\n(DATUM Protocol)"]:::external
    end

    %% DATUM Gateway Application
    subgraph "DATUM Gateway Application"
        %% Core Modules
        subgraph "Core Modules"
            GC["Gateway Core"]:::internal
            SI["Stratum Interface"]:::internal
            DP["DATUM Protocol Module (JSON-RPC)"]:::internal
        end

        %% Utility & Support Modules
        subgraph "Utility & Support Modules"
            API["datum_api"]:::internal
            CONF["datum_conf"]:::internal
            LOGGER["datum_logger"]:::internal
            QUEUE["datum_queue"]:::internal
            SOCKETS["datum_sockets"]:::internal
            BTMPL["Block Templates\n(datum_blocktemplates)"]:::internal
            BSUB["Block Submission\n(datum_submitblock)"]:::internal
            CB["Coinbase Handler\n(datum_coinbaser)"]:::internal
        end

        LIB["External Libraries\n(libcurl, libjansson, libmicrohttpd, libsodium)"]:::internal
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        BUILD["Build System\n(CMakeLists.txt & cmake/scripts)"]:::infra
        PKG["Packaging\n(debian)"]:::infra
        CI["Continuous Integration\n(.github/workflows)"]:::infra
        WEB["Web Interface\n(www)"]:::infra
    end

    %% Data Flows
    BN -->|"GBT/blocknotify"| GC
    GC -->|"constructs work"| SI
    SI -->|"Stratum distribution"| MH
    DP <-->|"Encrypted_DATUM"| MP

    %% Utility Module relations (dotted connections)
    GC ---|"uses"| API
    GC ---|"loads"| CONF
    DP ---|"logs_to"| LOGGER
    SI ---|"communicates_via"| SOCKETS

    %% External Libraries support
    LIB --- GC
    LIB --- SI
    LIB --- DP

    %% Infrastructure supporting the Gateway
    BUILD -->|"builds"| GC
    PKG -->|"packages"| GC
    CI -->|"CI builds"| GC
    WEB -->|"UI for"| GC

    %% Styles
    classDef external fill:#F9E79F,stroke:#D35400,stroke-width:2px;
    classDef internal fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef infra fill:#A9DFBF,stroke:#239B56,stroke-width:2px;

    %% Click Events for Component Mapping
    click GC "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_gateway.c"
    click SI "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_stratum.c"
    click DP "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_protocol.c"
    click API "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_api.c"
    click CONF "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_conf.c"
    click LOGGER "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_logger.c"
    click QUEUE "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_queue.c"
    click SOCKETS "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_sockets.c"
    click BTMPL "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_blocktemplates.c"
    click BSUB "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_submitblock.c"
    click CB "https://github.com/ocean-xyz/datum_gateway/blob/master/src/datum_coinbaser.c"
    click BUILD "https://github.com/ocean-xyz/datum_gateway/blob/master/CMakeLists.txt"
    click PKG "https://github.com/ocean-xyz/datum_gateway/tree/master/debian"
    click CI "https://github.com/ocean-xyz/datum_gateway/tree/master/.github/workflows"
    click WEB "https://github.com/ocean-xyz/datum_gateway/tree/master/www"
```
