# zondax/ledger-kadena architecture

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

- Interactive diagram: https://gitdiagram.com/zondax/ledger-kadena
- Repository: https://github.com/zondax/ledger-kadena

## Overview

##### Project type and purpose
- This is a firmware application (“app”) for Ledger hardware wallets (Nano S+, Nano X, Flex, Stax) that implements Kadena-blockchain transaction handling via the APDU protocol.
- It includes:
- C/C++ source under `app/src` implementing APDU handlers, JSON parsing, transaction logic, and UI flows
- Submodules in `deps/` for cryptographic libs (BLAKE2), Ledger SDK (`ledger-secure-sdk`), and helper libs (`ledger-zxlib`)
- Build scripts (CMakeLists.txt, Makefile) to cross-compile firmware binaries
- Unit tests (C++), fuzz tests (C++/Python), and integration tests using the Zemu emulator with JS/TS

##### File structure
Top-level folders:
- `app/`
- `app/src/`: core modules—APDU handlers (`apdu_handler.c`), legacy handlers, buffering JSON, crypto, parser, transaction logic, item definitions, UI scripts (`script_*.ld`)
- `app/glyphs`, `app/output`, `app/pkg`: assets and build outputs
- `cmake/`: custom CMake helper scripts (Hunter package manager)
- `deps/`: vendored dependencies (crypto, SDK, libs)
- `docs/`: APDU Specification (`APDUSPEC.md`) and branding assets
- `tests/`: native C++ unit tests and test utilities
- `fuzz/`: fuzzing entry points and harness scripts (C++ and Python)
- `tests_zemu/`: JS/TS emulator tests, snapshots, and test cases powered by the Zemu framework
- CI workflows in `.github/workflows/`

##### README for additional insights
- Describes developer prerequisites (Docker, conan via `make deps`, Node.js for Zemu)
- Standard workflows: `make` to build firmware, `make cpp_test` and `make rust_test` for unit tests, `make zemu_test` for emulator tests, `make test_all` for full cross-device build & test
- APDU spec lives in `docs/APDUSPEC.md`
- Emphasis on not running in production on real funds

- Green for firmware modules
- Blue for external dependencies
- Orange for test harnesses
- Gray for build/CI infrastructure

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development & CI Infrastructure
    subgraph "Development & CI" 
        direction TB
        dev["Developer Host"]:::infra
        ci["CI/CD Workflows"]:::infra
    end

    dev -->|"push code"| ci
    ci -->|"trigger pipelines"| buildSystem
    ci -->|"run tests"| hostTests

    %% Build System
    subgraph "Build System"
        direction TB
        buildSystem["Build System"]:::infra
        cmakeHelpers["CMake Helpers"]:::infra
    end

    buildSystem --> cmakeHelpers
    click buildSystem "https://github.com/zondax/ledger-kadena/blob/main/CMakeLists.txt"
    click cmakeHelpers "https://github.com/zondax/ledger-kadena/blob/main/cmake/HunterGate.cmake"

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        blake["BLAKE2 Library"]:::external
        sdk["Ledger Secure SDK"]:::external
        zxlib["Utility Library"]:::external
    end

    cmakeHelpers --> blake
    cmakeHelpers --> sdk
    cmakeHelpers --> zxlib

    click blake "https://github.com/zondax/ledger-kadena/tree/main/deps/BLAKE2/"
    click sdk "https://github.com/zondax/ledger-kadena/tree/main/deps/ledger-secure-sdk/"
    click zxlib "https://github.com/zondax/ledger-kadena/tree/main/deps/ledger-zxlib/"

    %% Firmware Modules
    subgraph "Firmware Modules" 
        direction TB
        apdu["APDU Handler Layer"]:::firmware
        parser["Parser Layer"]:::firmware
        txLogic["Transaction Logic & Items"]:::firmware
        crypto["Crypto Layer"]:::firmware
        legacy["Legacy JS Minimal JSON"]:::firmware
        ui["UI Layer"]:::firmware
        glyphs["Glyph Assets"]:::firmware
    end

    buildSystem -->|"cross-compile firmware"| apdu
    apdu --> parser
    parser --> crypto
    crypto --> txLogic
    txLogic --> ui
    ui --> glyphs

    click apdu "https://github.com/zondax/ledger-kadena/blob/main/app/src/apdu_handler.c"
    click parser "https://github.com/zondax/ledger-kadena/blob/main/app/src/parser.c"
    click txLogic "https://github.com/zondax/ledger-kadena/blob/main/app/src/common/tx.c"
    click crypto "https://github.com/zondax/ledger-kadena/blob/main/app/src/crypto.c"
    click legacy "https://github.com/zondax/ledger-kadena/blob/main/app/src/jsmn/jsmn.c"
    click ui "https://github.com/zondax/ledger-kadena/blob/main/app/script_s2.ld"
    click glyphs "https://github.com/zondax/ledger-kadena/tree/main/app/glyphs/"

    %% Host-Side Tests
    subgraph "Host-Side Tests"
        direction TB
        hostTests["Host-Side Test Suites"]:::test
        unit["Unit Tests"]:::test
        fuzzTests["Fuzz Tests"]:::test
        zemu["Zemu Emulator Tests"]:::test
    end

    hostTests --> unit
    hostTests --> fuzzTests
    hostTests --> zemu

    click unit "https://github.com/zondax/ledger-kadena/blob/main/tests/json_parser.cpp"
    click fuzzTests "https://github.com/zondax/ledger-kadena/blob/main/fuzz/parser_parse_hash.cpp"
    click zemu "https://github.com/zondax/ledger-kadena/tree/main/tests_zemu/"

    %% Firmware Loading & Device Interaction
    loader["Firmware Loader"]:::infra
    devices["Target Devices (Ledger / Zemu)"]:::infra

    txLogic -->|"produce binary"| loader
    loader --> devices

    %% APDU Flow
    hostTests -->|"APDU Commands"| devices
    devices -->|"APDU Responses"| hostTests

    %% Styles
    classDef firmware fill:#b2f2bb,stroke:#2f862f,color:#000;
    classDef external fill:#cff4fc,stroke:#0d6efd,color:#000;
    classDef test fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef infra fill:#e9ecef,stroke:#6c757d,color:#000;
```
