# 595014049/lol architecture

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

- Interactive diagram: https://gitdiagram.com/595014049/lol
- Repository: https://github.com/595014049/lol

## Overview

##### Project type and purpose
- This is a backend microservice written in Go that provides an offline wallet signing service (ECDSA and EdDSA) exposed over gRPC/CLI.
- It supports multiple blockchain protocols (Bitcoin, Ethereum, Solana) through modular chain adaptors.
- It persists keys in LevelDB and can optionally integrate with an HSM or software-based SSM key manager.

##### File structure
- Top-level binaries in cmd/wallet-sign-server (main.go, cli.go) launch either RPC or CLI mode.
- chain/ contains protocol-specific adapters (bitcoin/, ethereum/, solana/).
- services/rpc implements the gRPC server endpoint.
- common/ holds shared utilities (CLI app framework, retries, interrupts).
- hsm/ and ssm/ contain hardware and software key management implementations.
- leveldb/ is the on-disk key store.
- protobuf/ defines the wallet.proto and generated gRPC code.
- chaindispatcher/ routes sign requests to the correct chain adapter.
- config/ and config.yml for configuration loading.

##### Key README insights
- The service runs as “wallet-sign-server rpc” after loading config.yml.
- It listens on host/port, loads credentials, key names and path, and enables/disables HSM.
- Chains are registered based on config.

##### Main components
a. Entrypoints
- CLI/REST/gRPC interface (cmd/wallet-sign-server)
b. RPC Server layer (services/rpc)
c. Dispatcher (chaindispatcher)
d. Chain Adaptors (chain/bitcoin, chain/ethereum, chain/solana)
e. Key Manager
- HSM module (hsm/)
- SSM module (ssm/)
f. Storage layer (LevelDB under leveldb/)
g. Configuration loader (config/)
h. Shared Utilities (common/)
i. Protobuf definitions (protobuf/ and generated code)

##### Relationships and data flow
1. Client → CLI/gRPC stub (protobuf wallet.proto)
2. gRPC server (services/rpc) validates request & calls Dispatcher
3. Dispatcher selects appropriate Chain Adapter
4. Chain Adapter invokes sign operation using Key Manager (HSM or SSM)
5. Key Manager fetches private key from LevelDB, performs crypto
6. Signed payload returned back up chain: Adapter → Dispatcher → gRPC stub → Client
7. LevelDB persists any key-related metadata (“common retry” may be used)

##### Architectural patterns & tech highlights
- Hexagonal (ports/adapters) pattern: chain adapters plug into a common dispatcher interface.
- gRPC (protobuf) for the RPC API.
- Plugin-like Key Manager abstraction: HSM vs SSM.
- Embedded LevelDB for local key persistence.
- CLI framework for standalone/offline use.

##### Detail
- Configuration component reading config.yml.
- Call out common utilities (retry, lifecycle) as side-bars or sub-modules.
- Dual path through HSM vs SSM.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface Layer
    subgraph "Interface Layer"
        direction TB
        CLI["CLI Entrypoint\n(cmd/wallet-sign-server)"]:::interface
        GRPCStub["gRPC Stub\n(protobuf)"]:::interface
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        ConfigLoader["Configuration Loader\n(config/)"]:::app
        RPCServer["gRPC Server\n(services/rpc)"]:::app
        Dispatcher["Request Dispatcher\n(chaindispatcher)"]:::app
        CommonUtils["Shared Utilities\n(common/)"]:::app
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        subgraph "Chain Adapters"
            direction TB
            Bitcoin["Bitcoin Adapter\n(chain/bitcoin)"]:::adapter
            Ethereum["Ethereum Adapter\n(chain/ethereum)"]:::adapter
            Solana["Solana Adapter\n(chain/solana)"]:::adapter
            ChainInterface["Adapter Interface\n(chain/chainadaptor.go)"]:::adapter
        end
        subgraph "Key Managers"
            direction TB
            HSM["HSM Module\n(hsm/)"]:::adapter
            SSM["SSM Module\n(ssm/)"]:::adapter
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        LevelDB["LevelDB Store\n(leveldb/)"]:::infra
        ExternalHSM["HSM Appliance\n(external)"]:::external
        BlockchainNet["Blockchain Networks\n(Bitcoin/Ethereum/Solana)"]:::external
    end

    %% Protobuf Definitions
    Protobuf["Protobuf Definitions\n(protobuf/)"]:::app

    %% Data Flow
    Client["Client"]:::external
    Client -->|"SignRequest"| CLI
    Client -->|"SignRequest"| GRPCStub
    CLI -->|"calls"| ConfigLoader
    GRPCStub -->|"SignRequest"| RPCServer
    ConfigLoader -->|"loads config.yml"| RPCServer
    RPCServer -->|"Validate & Forward"| Dispatcher
    Dispatcher -->|"Selects Adapter"| ChainInterface
    ChainInterface -->|"implements"| Bitcoin
    ChainInterface -->|"implements"| Ethereum
    ChainInterface -->|"implements"| Solana
    Dispatcher -->|"Route to Adapter"| Bitcoin
    Dispatcher -->|"Route to Adapter"| Ethereum
    Dispatcher -->|"Route to Adapter"| Solana
    Bitcoin -->|"Sign()"| HSM
    Bitcoin -->|"Sign()"| SSM
    Ethereum -->|"Sign()"| HSM
    Ethereum -->|"Sign()"| SSM
    Solana -->|"Sign()"| HSM
    Solana -->|"Sign()"| SSM
    HSM -->|"Fetch Key & Crypto"| LevelDB
    SSM -->|"Fetch Key & Crypto"| LevelDB
    LevelDB -->|"Key Metadata"| CommonUtils
    RPCServer -->|"SignedTx"| GRPCStub
    GRPCStub -->|"SignedTx"| Client
    CLI -->|"SignedTx"| Client

    %% External Dependencies
    HSM -->|"Hardware Interface"| ExternalHSM
    Bitcoin -->|"Broadcast Tx"| BlockchainNet
    Ethereum -->|"Broadcast Tx"| BlockchainNet
    Solana -->|"Broadcast Tx"| BlockchainNet

    %% Protobuf Flow
    Protobuf -->|"Stub Generation"| GRPCStub

    %% Click Events
    click CLI "https://github.com/595014049/lol/tree/main/cmd/wallet-sign-server"
    click RPCServer "https://github.com/595014049/lol/blob/main/services/rpc/service.go"
    click Dispatcher "https://github.com/595014049/lol/blob/main/chaindispatcher/dispatcher.go"
    click Bitcoin "https://github.com/595014049/lol/tree/main/chain/bitcoin"
    click Ethereum "https://github.com/595014049/lol/tree/main/chain/ethereum"
    click Solana "https://github.com/595014049/lol/tree/main/chain/solana"
    click ChainInterface "https://github.com/595014049/lol/blob/main/chain/chainadaptor.go"
    click HSM "https://github.com/595014049/lol/blob/main/hsm/hsm.go"
    click SSM "https://github.com/595014049/lol/tree/main/ssm"
    click LevelDB "https://github.com/595014049/lol/tree/main/leveldb"
    click ConfigLoader "https://github.com/595014049/lol/blob/main/config/config.go"
    click Protobuf "https://github.com/595014049/lol/blob/main/protobuf/wallet.proto"
    click CommonUtils "https://github.com/595014049/lol/tree/main/common"

    %% Styles
    classDef interface fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef app fill:#90CAF9,stroke:#333,stroke-width:1px
    classDef adapter fill:#A5D6A7,stroke:#333,stroke-width:1px
    classDef infra fill:#FFF59D,stroke:#333,stroke-width:1px
    classDef external fill:#FFCC80,stroke:#333,stroke-width:1px
```
