# dfinity/hardware-wallet-cli architecture

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

- Interactive diagram: https://gitdiagram.com/dfinity/hardware-wallet-cli
- Repository: https://github.com/dfinity/hardware-wallet-cli

## Overview

##### Project type and purpose
- This is a Node.js‐based command-line interface (CLI) tool named **hardware-wallet-cli**.
- Purpose: allow users to send commands (e.g., balance queries, transfers) to the Internet Computer App on a Ledger Nano S/X via USB, handling identity, signing (secp256k1), and network calls to the DFINITY Internet Computer.

##### File structure
- Top-level:
- **src/** – TypeScript source, containing:
– **index.ts** – CLI entry point & dispatcher
– **parsers.ts** – argument parsing & command definitions
– **ledger/** – Ledger transport & app identity (`identity.ts` + `secp256k1.ts`)
– **utils.ts**, **constants.ts** – shared helpers & config
- **scripts/** – build/time utilities (version bump, packaging for npm/next)
- **esbuild.mjs** – bundling config to produce a single executable
- **dfx.json** – local Internet Computer/DFX network definitions
- **.github/workflows/publish.yml** – CI for packaging & publishing to npm
- Patterns: layered separation (CLI → parsing → command handlers → transport/crypto → network)

##### README for additional insights
- CLI supports commands like `ic-hardware-wallet icp balance`
- Relies on Node ≥18.13, esbuild for bundling, supports custom network URLs
- Warns about token decimals & unsupported tokens (CKETH, ckERC20)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    Shell["User / Shell"]:::external

    %% Runtime Core
    subgraph "Runtime"
        direction TB
        Parser["Argument Parser"]:::core
        Dispatcher["Command Dispatcher"]:::core
        Handlers["Command Handlers"]:::core
        subgraph "Transport & Crypto"
            direction TB
            LedgerTransport["Ledger Transport Layer"]:::crypto
            Crypto["Crypto Module"]:::crypto
        end
        NetworkClient["Network Client"]:::core
        ConfigConsts["Configuration & Constants"]:::core
        Utils["Shared Utilities"]:::core
    end

    %% External Devices
    LedgerDevice["Ledger Device (Nano S/X)"]:::external
    ICNetwork["Internet Computer Network"]:::external

    %% Packaging & CI
    subgraph "Build & Release Pipeline"
        direction TB
        BundlerConfig["Bundler Configuration"]:::packaging
        subgraph "Build Scripts"
            direction TB
            GetTokens["get-tokens-list.ts"]:::packaging
            UpdateVersion["update-version.mjs"]:::packaging
            PackageNext["package-next/"]:::packaging
        end
        CI["GitHub Actions CI"]:::packaging
    end

    %% Flows
    Shell -->|runs command| Parser
    Parser -->|parses args| Dispatcher
    Dispatcher -->|dispatches to| Handlers
    Handlers -->|uses transport| LedgerTransport
    Handlers -->|uses crypto| Crypto
    Handlers -->|sends request| NetworkClient
    Handlers -->|reads config| ConfigConsts
    Handlers -->|calls utils| Utils
    NetworkClient -->|endpoint config| ConfigConsts
    NetworkClient -->|queries| ICNetwork
    LedgerTransport -->|communicates via USB| LedgerDevice

    BundlerConfig -->|bundles runtime| Dispatcher
    GetTokens -->|utility| Dispatcher
    UpdateVersion -->|version bump| BundlerConfig
    PackageNext -->|pack next| BundlerConfig
    CI -->|publishes package| BundlerConfig

    %% Click Events
    click Dispatcher "https://github.com/dfinity/hardware-wallet-cli/blob/main/src/index.ts"
    click Parser "https://github.com/dfinity/hardware-wallet-cli/blob/main/src/parsers.ts"
    click LedgerTransport "https://github.com/dfinity/hardware-wallet-cli/blob/main/src/ledger/identity.ts"
    click Crypto "https://github.com/dfinity/hardware-wallet-cli/blob/main/src/ledger/secp256k1.ts"
    click ConfigConsts "https://github.com/dfinity/hardware-wallet-cli/blob/main/src/constants.ts"
    click Utils "https://github.com/dfinity/hardware-wallet-cli/blob/main/src/utils.ts"
    click NetworkClient "https://github.com/dfinity/hardware-wallet-cli/blob/main/dfx.json"
    click BundlerConfig "https://github.com/dfinity/hardware-wallet-cli/blob/main/esbuild.mjs"
    click GetTokens "https://github.com/dfinity/hardware-wallet-cli/blob/main/scripts/get-tokens-list.ts"
    click UpdateVersion "https://github.com/dfinity/hardware-wallet-cli/blob/main/scripts/update-version.mjs"
    click PackageNext "https://github.com/dfinity/hardware-wallet-cli/tree/main/scripts/package-next/"
    click CI "https://github.com/dfinity/hardware-wallet-cli/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef core fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef crypto fill:#E8F5E9,stroke:#43A047,stroke-width:1px
    classDef external fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef packaging fill:#ECEFF1,stroke:#78909C,stroke-width:1px
```
