# coinchimp/kaspa-krc20-apps architecture

> Architecture diagram of the GitHub repository coinchimp/kaspa-krc20-apps, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coinchimp/kaspa-krc20-apps
- Repository: https://github.com/coinchimp/kaspa-krc20-apps

## Overview

##### Project type and purpose
- This is a command-line toolkit (built on Bun + TypeScript) for secure key generation and KRC20 token operations (mint, deploy, transfer) against the Kaspa blockchain.
- It provides three main CLI tools:
- KeyGenerator (mnemonic → private key → address)
- Kaspa Transfer (sign & send KASPA tokens)
- KRC20 Apps (mint.ts, deploy.ts, transfer.ts)

##### File structure
- Top-level scripts: mint.ts, deploy.ts, transfer.ts, transfer.ts, sendKaspa.ts, keyGeneratorCli.ts
- src/ contains three core modules:
- BalanceChecker/ – queries token balances
- KeyGenerator/ – implements BIP39/BIP32 flows
- TransactionSender/ – builds & broadcasts transactions
- utils/ includes shell helpers, Docker-compose generator, UTXO trackers, status polling.
- Dockerfile & docker-compose support spinning up a local Kaspa node for testing.

##### Architectural components
a. CLI Frontend
- keyGeneratorCli.ts
- sendKaspa.ts
- mint.ts, deploy.ts, transfer.ts
b. Core Libraries (under src/)
- KeyGenerator module
- TransactionSender module
- BalanceChecker module
c. Runtime & Dependencies
- Bun JS runtime + TypeScript
- Kaspa WASM (nodejs/wasm) for RPC bindings
- BIP39/BIP32 crypto libraries
d. External Services
- Kaspa node (remote or local-docker) via JSON-RPC
- Docker container (localnode) for offline/testing
e. Utility Scripts
- generate-docker-compose.sh → local node setup
- utxo-tracker, mint-status, subscribe-utxo-changes, etc.

##### Relationships & data flow
1. Developer invokes a Bun CLI script with flags (–privKey, –destination, etc.)
2. CLI calls into the appropriate core module:
- KeyGenerator generates mnemonic/key/address
- TransactionSender builds & signs a JSON-RPC request
- BalanceChecker polls contract state
3. Core module loads Kaspa WASM bindings and communicates over HTTP/WebSocket to the Kaspa node.
4. Node processes the transaction, updates the blockchain.
5. UTXO-tracker and mint-status watchers in utils poll for confirmations and report back.

##### Architectural patterns & principles
- Modular separation: UI (CLI) vs. domain logic (src/) vs. orchestration (utils/)
- Single-responsibility per script & per module
- Dependency inversion: modules depend on an abstract RPC interface (WASM) rather than a concrete node
- Use of standard cryptographic protocols (BIP39/BIP32)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "CLI Frontend"
        KG["KeyGenerator CLI"]:::cli
        SS["Kaspa Transfer CLI"]:::cli
        MintCLI["KRC20 Mint CLI"]:::cli
        DeployCLI["KRC20 Deploy CLI"]:::cli
        TransferCLI["KRC20 Transfer CLI"]:::cli
    end

    subgraph "Core Modules"
        KGMod["KeyGenerator Module"]:::core
        TSMod["TransactionSender Module"]:::core
        BCMod["BalanceChecker Module"]:::core
    end

    subgraph "Utilities"
        DCGen["Docker Compose Generator"]:::util
        UTXOTr["UTXO Tracker"]:::util
        MintStat["Mint Status Poller"]:::util
        UTXOSub["UTXO Changes Subscriber"]:::util
        KRC20Bal["KRC20 Balance Checker"]:::util
        MintHealth["Mint Container Health Checker"]:::util
        RecSend["Recursive Send-KASPA Helper"]:::util
    end

    subgraph "Docker Setup"
        ProdNode["Production Node Container"]:::external
        LocalNode["Local Node Container"]:::external
    end

    subgraph "External Systems"
        ExternalKaspa["Kaspa Node (JSON-RPC)"]:::external
        Blockchain["Kaspa Blockchain"]:::external
    end

    subgraph "Platform & Runtime"
        Runtime["Bun + TypeScript"]:::platform
        WASM["Kaspa WASM Bindings"]:::platform
        Crypto["BIP39/BIP32 Crypto Libs"]:::platform
    end

    %% CLI to Core
    KG -->|invokes| KGMod
    SS -->|invokes| TSMod
    MintCLI -->|invokes| BCMod
    MintCLI -->|invokes| TSMod
    DeployCLI -->|invokes| TSMod
    TransferCLI -->|invokes| TSMod

    %% Core dependencies
    KGMod -->|uses| Crypto
    KGMod -->|runs on| Runtime
    TSMod -->|runs on| Runtime
    BCMod -->|runs on| Runtime

    TSMod -->|builds & signs via| WASM
    BCMod -->|queries via| WASM

    WASM -->|JSON-RPC over HTTP/WebSocket| ExternalKaspa
    ExternalKaspa -->|processes txs & updates| Blockchain

    %% Utilities to External
    UTXOTr -->|polls| ExternalKaspa
    MintStat -->|polls| ExternalKaspa
    UTXOSub -->|subscribes| ExternalKaspa
    KRC20Bal -->|polls| ExternalKaspa

    %% Docker Setup
    DCGen -->|generates compose for| LocalNode
    LocalNode -->|mock Kaspa node| ExternalKaspa
    ProdNode -->|production node| ExternalKaspa
    MintHealth -->|checks health of| LocalNode

    %% Utility Helpers
    RecSend -->|assists| TSMod

    %% Click Events
    click KG "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/src/keyGeneratorCli.ts"
    click SS "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/src/sendKaspa.ts"
    click MintCLI "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/mint.ts"
    click DeployCLI "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/deploy.ts"
    click TransferCLI "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/transfer.ts"
    click KGMod "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/src/KeyGenerator/index.ts"
    click TSMod "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/src/TransactionSender/index.ts"
    click BCMod "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/src/BalanceChecker/index.ts"
    click DCGen "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/utils/generate-docker-compose.sh"
    click UTXOTr "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/utils/utxo-tracker.ts"
    click MintStat "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/utils/mint-status.ts"
    click UTXOSub "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/utils/subscribe-utxo-changes.ts"
    click KRC20Bal "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/utils/krc20-balance.ts"
    click MintHealth "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/utils/check-mint-container.ts"
    click RecSend "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/utils/send-kaspa-recursive.sh"
    click ProdNode "https://github.com/coinchimp/kaspa-krc20-apps/tree/main/Dockerfile"
    click LocalNode "https://github.com/coinchimp/kaspa-krc20-apps/blob/main/Dockerfile.localnode"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#004085
    classDef core fill:#d4edda,stroke:#155724
    classDef util fill:#e2e3e5,stroke:#6c757d
    classDef external fill:#fff3cd,stroke:#856404
    classDef platform fill:#f8d7da,stroke:#721c24
```
