# n42blockchain/erc20sdk architecture

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

- Interactive diagram: https://gitdiagram.com/n42blockchain/erc20sdk
- Repository: https://github.com/n42blockchain/erc20sdk

## Overview

##### Project Type and Purpose
- This is a TypeScript SDK (a client‐side library) for interacting with ERC-20 tokens on the N42 blockchain. It exposes high‐level abstractions (ERC20 token instance, Wallet, SDK bootstrap, event subscriptions), while under the hood driving HTTP RPC calls, WebSocket subscriptions, encoding/decoding of transactions, and error/retry logic.

##### High-Level Architecture Overview
1. **Consumer/Application** (top layer)
– Your user’s code (mobile app, web front end, script) that calls `N42SDK` APIs.
2. **SDK Facade**
– `src/index.ts` / `src/sdk.ts` ⇒ Initializes `RPCClient` & `WSClient`, provides `erc20(address)`, `waitForReceipt()`.
– `src/types.ts` ⇒ Shared TypeScript types and interfaces.
3. **Core Modules**
– **ERC20 Module** (`src/erc20/erc20.ts`)
– **Wallet** (`src/wallet/wallet.ts`)
– **Events/WS** (`src/ws/client.ts`)
– **RPC Client** (`src/rpc/client.ts`)
– **Utils** (`src/utils/*.ts`) – gas estimation, retry policy, token‐amount conversions
– **Error Definitions** (`src/errors.ts`)
4. **External Systems** (bottom layer)
– N42 HTTP RPC endpoint
– N42 WebSocket endpoint

##### Component Details & Interactions
a. **N42SDK** (Facade)
– Initialization: ties together `RPCClient` and `WSClient` with user‐provided config (`N42Config`).
– Exposes `erc20()`, `waitForReceipt()`.
– Relies on `types.ts` for proper interfaces.

b. **ERC20 Module**
– Uses `RPCClient` to call on-chain read methods (name, symbol, totalSupply, balanceOf, allowance).
– Builds and signs transactions via `Wallet`, then sends via `RPCClient`.
– Emits or subscribes to events via `WSClient`.

c. **Wallet**
– Cryptographic key management (mnemonic, private key import).
– Signs transactions (used by ERC20 transfer/approve).

d. **RPCClient**
– HTTP calls to the RPC endpoint.
– Wrapped by retry logic (`utils/retry.ts`) and gas utilities (`utils/gas.ts`).
– Throws typed errors (`errors.ts`) on network, nonce, revert, insufficient funds.

e. **WSClient**
– Maintains WebSocket connection to subscribe to ERC20 events.
– Provides subscription handles to cancel, using back-off (`utils/retry.ts`).

f. **Utils & Types**
– `token-amount.ts`: convert between min-units and human decimal.
– `retry.ts`: exponential back-off wrapper.
– `gas.ts`: estimates and formats gas fees.
– `types.ts`: common type definitions for config, transfer/approve DTOs, event callbacks.

##### Architectural Patterns & Design Principles
- **Facade Pattern**: The `N42SDK` class hides complexity of RPC/WS/client instantiation.
- **Modularization**: Each concern (RPC, WS, ERC20 logic, wallet, utils) in its own directory.
- **Typed Interfaces**: Strong TypeScript types/interfaces separate implementation from API.
- **Retry & Resilience**: Centralized retry logic module for RPC and WS.
- **Event-Driven**: WebSocket module for real-time event subscription.

##### Essential Elements to Capture
- **Public API layer** vs. **Internal modules** vs. **External network**
- Data flow: method invocation, network requests, event streaming
- Error propagation from RPC → typed errors → public API
- Retry back-off integration with both RPC and WS modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    subgraph "Consumer/Application" 
        direction TB
        App["User Application"]:::consumer
    end

    %% SDK Facade Layer
    subgraph "SDK Facade"
        direction TB
        N42SDK["N42SDK"]:::publicAPI
        Types["Shared Types & Interfaces"]:::internal
    end

    %% Core Modules Layer
    subgraph "Core Modules"
        direction TB
        ERC20["ERC20 Module"]:::publicAPI
        Wallet["Wallet Manager"]:::publicAPI
        RPCClient["RPCClient (HTTP JSON-RPC)"]:::internal
        WSClient["WSClient (WebSocket)"]:::internal
        GasUtil["Gas Estimation & Formatting"]:::internal
        RetryUtil["Retry & Back-off Logic"]:::internal
        TokenAmt["Token Amount Conversion"]:::internal
        Errors["Error Definitions"]:::internal
    end

    %% External Systems Layer
    subgraph "External Systems"
        direction TB
        HTTP["N42 HTTP RPC Endpoint"]:::external
        WS["N42 WebSocket Endpoint"]:::external
    end

    %% Connections
    App -->|calls| N42SDK
    N42SDK -->|uses types| Types
    N42SDK -->|initializes| RPCClient
    N42SDK -->|initializes| WSClient

    ERC20 -->|calls read methods| RPCClient
    ERC20 -->|builds & signs txns| Wallet
    ERC20 -->|subscribes/emits events| WSClient

    Wallet -->|signs transaction| RPCClient

    RPCClient -->|HTTP JSON-RPC request/response| HTTP
    WSClient -->|WebSocket subscription message| WS

    RPCClient -->|wrapped by| RetryUtil
    WSClient -->|uses| RetryUtil
    RPCClient -->|uses| GasUtil
    ERC20 -->|uses| TokenAmt
    N42SDK -->|throws typed errors| Errors

    WSClient -->|delivers callbacks| App

    %% Legend
    subgraph Legend
        direction TB
        L1["Public API Modules"]:::publicAPI
        L2["Internal Helpers"]:::internal
        L3["External Systems"]:::external
    end

    %% Click Events
    click N42SDK "https://github.com/n42blockchain/erc20sdk/blob/main/src/index.ts"
    click N42SDK "https://github.com/n42blockchain/erc20sdk/blob/main/src/sdk.ts"
    click Types "https://github.com/n42blockchain/erc20sdk/blob/main/src/types.ts"
    click ERC20 "https://github.com/n42blockchain/erc20sdk/blob/main/src/erc20/erc20.ts"
    click Wallet "https://github.com/n42blockchain/erc20sdk/blob/main/src/wallet/wallet.ts"
    click RPCClient "https://github.com/n42blockchain/erc20sdk/blob/main/src/rpc/client.ts"
    click WSClient "https://github.com/n42blockchain/erc20sdk/blob/main/src/ws/client.ts"
    click Errors "https://github.com/n42blockchain/erc20sdk/blob/main/src/errors.ts"
    click GasUtil "https://github.com/n42blockchain/erc20sdk/blob/main/src/utils/gas.ts"
    click RetryUtil "https://github.com/n42blockchain/erc20sdk/blob/main/src/utils/retry.ts"
    click TokenAmt "https://github.com/n42blockchain/erc20sdk/blob/main/src/utils/token-amount.ts"

    %% Styles
    classDef publicAPI fill:#c6f6d5,stroke:#2f855a,color:#2f855a;
    classDef internal fill:#bee3f8,stroke:#2b6cb0,color:#2b6cb0;
    classDef external fill:#fed7d7,stroke:#c53030,color:#c53030;
    classDef consumer fill:#faf089,stroke:#d69e2e,color:#d69e2e;
```
