# bitcoin/libblkmaker architecture

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

- Interactive diagram: https://gitdiagram.com/bitcoin/libblkmaker
- Repository: https://github.com/bitcoin/libblkmaker

## Overview

##### Project Type and Purpose
- This is an open-source C library (libblkmaker) for constructing Bitcoin block templates according to BIP-23, consuming JSON-encoded template data (e.g., from a Bitcoin node’s RPC), rolling headers and time fields, and producing completed block headers/merkle roots for mining.
- Key use cases: embedding into mining software, CLI examples (`example.c`), test harnesses (`test.c`, `test.sh`).

##### File-Structure Analysis
- Top-level sources:
- blkmaker.c / blkmaker.h – core API for building block headers
- blktemplate.c / blktemplate.h – parsing/manipulating BIP-23 template objects
- blkmaker_jansson.c / blkmaker_jansson.h – Jansson-based JSON I/O glue
- base58.c – Base58 encoding (for block height in coinbase)
- hex.c – hex ⇄ binary conversions
- private.h – internal helpers / constants
- example.c, test.c, testinput.c – CLI/test apps showing usage
- test.sh – test runner
- Build/config: autogen.sh, configure.ac, Makefile.am, .travis.yml, pkgconfig template.

##### README Insights
- Dependencies: Jansson ≥2.0 (JSON parser), libgcrypt for SHA256.
- Usage: assign a SHA256 implementation via function pointer, call blkmk_get_mdata, respect ntime limits per BIP-23.
- No network client built in—expects JSON on stdin or via caller’s HTTP client.

a. Main Components
- Caller/CLI Layer (example.c, test.c)
- libblkmaker Core API
- JSON I/O Module (blkmaker_jansson)
- Template Parser/Manager (blktemplate)
- Hashing Module (abstracted via blkmk_sha256_impl → libgcrypt)
- Helpers: base58, hex
- External Dependencies: Jansson, libgcrypt, stdin or HTTP RPC input

b. Relationships & Data Flow
1. Caller (CLI or host software) fetches JSON template (stdin or RPC).
2. JSON I/O Module parses into in-memory template struct.
3. Template Manager validates BIP-23 limits, prepares coinbase, merkle branches.
4. Caller sets `blkmk_sha256_impl` to point at libgcrypt’s SHA256.
5. Core API executes header building and ntime rolling, calling SHA256 via the function pointer.
6. Base58 and hex helpers format outputs (e.g. block height in coinbase, hex-encoded header).
7. Caller receives finalized block header/blob for submission to miner or network.

c. Architectural Patterns & Principles
- Modular C library: separation of concerns by module (JSON, hashing, template logic, encoding).
- Use of function pointers for pluggable crypto implementations.
- Configuration via autoconf/automake for portability.
- Test-driven: example and test harnesses exercise public API.

d. Technologies, Frameworks, Libraries
- Language: C99 (assumed)
- JSON: Jansson 2.x
- Crypto: libgcrypt (or any custom SHA256)
- Build system: Autotools (autogen.sh, configure.ac, Makefile.am)
- CI: Travis CI (.travis.yml)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External JSON Source
    JSON["JSON RPC / stdin"]:::external

    %% Caller Layer
    subgraph "Caller/CLI Layer"
        EX1["example.c"]:::cli
        EX2["test.c"]:::cli
        EX3["testinput.c"]:::cli
        EX4["test.sh"]:::cli
    end

    %% Core Library Modules
    subgraph "libblkmaker Core API and Modules"
        BM_C["blkmaker.c"]:::library
        BM_H["blkmaker.h"]:::library
        PH_H["private.h"]:::library
        BT_C["blktemplate.c"]:::library
        BT_H["blktemplate.h"]:::library
        BJ_C["blkmaker_jansson.c"]:::library
        BJ_H["blkmaker_jansson.h"]:::library
        PC_IN["libblkmaker_jansson.pc.in"]:::library
        B58["base58.c"]:::library
        HEX["hex.c"]:::library
    end

    %% External Dependencies
    subgraph "External Dependencies"
        JAN[(Jansson ≥2.0)]:::external
        GCR[(libgcrypt)]:::external
    end

    %% Build & Config
    subgraph "Build & Configuration"
        AG["autogen.sh"]:::config
        CA["configure.ac"]:::config
        MA["Makefile.am"]:::config
        TR[".travis.yml"]:::config
        RD["README"]:::config
        CP["COPYING"]:::config
        AU["AUTHORS"]:::config
        GI[".gitignore"]:::config
    end

    %% Data Flow
    JSON -->|"JSON template"| BJ_C
    BJ_C -->|"parsed JSON"| BT_C
    BT_C -->|"template struct"| BM_C
    EX1 -->|"sets blkmk_sha256_impl"| BM_C
    EX2 -->|"sets blkmk_sha256_impl"| BM_C
    BM_C -->|"calls SHA256 via callback"| GCR
    BM_C -->|"encodes coinbase height"| B58
    BM_C -->|"hex encode header"| HEX
    BM_C -->|"returns block header"| EX1
    BM_C -->|"returns block header"| EX2
    BM_C -->|"returns block header"| EX3

    %% Dependency Links
    BJ_C --> JAN
    BM_C --> BM_H
    BM_C --> PH_H
    BT_C --> BT_H

    %% Build pipeline
    AG --> CA --> MA --> PC_IN
    CA --> MA
    MA --> TR
    MA --> RD
    MA --> CP
    MA --> AU
    MA --> GI

    %% Click Events
    click EX1 "https://github.com/bitcoin/libblkmaker/blob/master/example.c"
    click EX2 "https://github.com/bitcoin/libblkmaker/blob/master/test.c"
    click EX3 "https://github.com/bitcoin/libblkmaker/blob/master/testinput.c"
    click EX4 "https://github.com/bitcoin/libblkmaker/blob/master/test.sh"
    click BM_C "https://github.com/bitcoin/libblkmaker/blob/master/blkmaker.c"
    click BM_H "https://github.com/bitcoin/libblkmaker/blob/master/blkmaker.h"
    click PH_H "https://github.com/bitcoin/libblkmaker/blob/master/private.h"
    click BJ_C "https://github.com/bitcoin/libblkmaker/blob/master/blkmaker_jansson.c"
    click BJ_H "https://github.com/bitcoin/libblkmaker/blob/master/blkmaker_jansson.h"
    click PC_IN "https://github.com/bitcoin/libblkmaker/blob/master/libblkmaker_jansson.pc.in"
    click BT_C "https://github.com/bitcoin/libblkmaker/blob/master/blktemplate.c"
    click BT_H "https://github.com/bitcoin/libblkmaker/blob/master/blktemplate.h"
    click B58 "https://github.com/bitcoin/libblkmaker/blob/master/base58.c"
    click HEX "https://github.com/bitcoin/libblkmaker/blob/master/hex.c"
    click AG "https://github.com/bitcoin/libblkmaker/blob/master/autogen.sh"
    click CA "https://github.com/bitcoin/libblkmaker/blob/master/configure.ac"
    click MA "https://github.com/bitcoin/libblkmaker/blob/master/Makefile.am"
    click TR "https://github.com/bitcoin/libblkmaker/blob/master/.travis.yml"
    click RD "https://github.com/bitcoin/libblkmaker/tree/master/README"
    click CP "https://github.com/bitcoin/libblkmaker/tree/master/COPYING"
    click AU "https://github.com/bitcoin/libblkmaker/tree/master/AUTHORS"
    click GI "https://github.com/bitcoin/libblkmaker/blob/master/.gitignore"

    %% Styles
    classDef library fill:#ADD8E6,stroke:#333;
    classDef external fill:#90EE90,stroke:#333,stroke-dasharray: 5 5;
    classDef cli fill:#FFD700,stroke:#333;
    classDef config fill:#FFA07A,stroke:#333;
```
