# kybernetwork/kyberswap-dex-lib architecture

> Architecture diagram of the GitHub repository kybernetwork/kyberswap-dex-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kybernetwork/kyberswap-dex-lib
- Repository: https://github.com/kybernetwork/kyberswap-dex-lib

## Overview

##### Main Components
a. Domain Entities and Interfaces
- The “pkg/entity” package defines the core domain objects (for instance, pool data structures and related types) that represent the simulation’s business logic.

b. Liquidity Sources and Pool Simulator Implementations
- The “pkg/liquidity-source” package is a huge folder containing multiple subdirectories each representing a different liquidity source (e.g., balancer-v1, curve, uniswap-v2, etc.). These modules are essentially various pool simulators implementing the DEX logic for different protocols.
- As “Pool Simulator Modules” showing that they all plug into the common simulation framework.
- Since the README explains how new simulators should be registered using go generate and msgpack registration, indicate that these modules are developed in a plug-and-play manner.

c. Serialization and Registration (Msgpack)
- The “pkg/msgpack” package contains the code and generation scripts necessary for marshalling and unmarshalling pool simulator instances.
- Registration process, including “go generate” which uses “generate_register_pool_types.go” to register simulator types.
- Interaction from the msgpack layer into the simulator interface and how the “AfterMsgpackUnmarshal()” hooks are used to perform pointer alias initialization.

d. Utility and Supporting Components
- “pkg/util” and “pkg/valueobject” provide helper functions for common tasks such as handling ABI definitions, big-number arithmetic, Ethereum address manipulations, and more.
- “pkg/pooltypes” includes shared types for pools.
- “pkg/source” aggregates external pool sources and contains adapters to interact with external DEX protocols.
- These should be represented as support layers that feed data and configurations into the simulation engine.

##### Relationships and Data Flow
- The simulation engine picks up the correct pool simulator by “unmarshalling” the data using msgpack; the msgpack layer (in “pkg/msgpack”) uses the registration created by “go generate” to decode the input into the concrete type.
- Once unmarshalled, the “AfterMsgpackUnmarshal()” method ensures any pointer dependencies (pointer aliases) are reset properly.
- The simulator then uses business logic from its module within “pkg/liquidity-source” to perform calculations and simulations.
- Utility packages provide shared functions used across these modules.

##### Important Architectural Patterns and Design Principles
- Modular Design: Separate packages for each liquidity source make the library easily extendible.
- Plugin/Registration Pattern: New pool simulator implementations can be plugged in via go generate and msgpack registration.
- Separation of Concerns: The architecture clearly separates entity definitions (domain), simulation logic (liquidity sources), serialization (msgpack), and utility/helper components.
- Extensibility: The README emphasizes that any changes in pointer dependencies should be handled in “AfterMsgpackUnmarshal()”, which is a callback pattern ensuring that unmarshalled simulators are in a correct runtime state.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs & Processes
    InputData["Serialized Pool Data"]:::external
    GoGenerate["Go Generate Process"]:::externalProcess

    %% Msgpack Layer
    MsgpackLayer["Msgpack Serialization & Registration"]:::serialization
    AfterUnmarshal["AfterMsgpackUnmarshal() Hook"]:::serialization

    %% Core Domain Subgraph
    subgraph "Core Domain"
        DomainEntities["Domain Entities & Interfaces (IPoolSimulator)"]:::core
        LiquiditySources["Liquidity Source Modules"]:::plugin
        DomainEntities -->|"implements"| LiquiditySources
    end

    %% Utilities & Helpers Subgraph
    subgraph "Utilities & Helpers"
        UtilNode["Utility Functions (pkg/util)"]:::utility
        ValueObjectNode["Value Objects (pkg/valueobject)"]:::utility
        PoolTypesNode["Pool Types (pkg/pooltypes)"]:::utility
        UtilNode --> ValueObjectNode
        ValueObjectNode --> PoolTypesNode
    end

    %% External Adapters Subgraph
    subgraph "External Adapters"
        ExternalSources["External Pool Source Adapters"]:::external
    end

    %% Data Flow Connections
    InputData -->|"providesData"| MsgpackLayer
    GoGenerate -->|"registersTypes"| MsgpackLayer
    MsgpackLayer -->|"decodesData"| AfterUnmarshal
    AfterUnmarshal -->|"initializes"| DomainEntities
    DomainEntities -->|"simulatesWith"| LiquiditySources
    DomainEntities -->|"leverages"| UtilNode
    LiquiditySources -->|"leverages"| UtilNode
    LiquiditySources -->|"integratesWith"| ExternalSources

    %% Styles
    classDef external fill:#fbb,stroke:#333,stroke-width:2px;
    classDef externalProcess fill:#fcc,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef plugin fill:#cfc,stroke:#333,stroke-width:2px;
    classDef serialization fill:#ff9,stroke:#333,stroke-width:2px;
    classDef utility fill:#eee,stroke:#333,stroke-width:2px;

    %% Click Events
    click DomainEntities "https://github.com/kybernetwork/kyberswap-dex-lib/tree/main/pkg/entity"
    click LiquiditySources "https://github.com/kybernetwork/kyberswap-dex-lib/tree/main/pkg/liquidity-source"
    click MsgpackLayer "https://github.com/kybernetwork/kyberswap-dex-lib/tree/main/pkg/msgpack"
    click GoGenerate "https://github.com/kybernetwork/kyberswap-dex-lib/blob/main/pkg/msgpack/generate/generate_register_pool_types.go"
    click UtilNode "https://github.com/kybernetwork/kyberswap-dex-lib/tree/main/pkg/util"
    click ValueObjectNode "https://github.com/kybernetwork/kyberswap-dex-lib/tree/main/pkg/valueobject"
    click PoolTypesNode "https://github.com/kybernetwork/kyberswap-dex-lib/tree/main/pkg/pooltypes"
    click ExternalSources "https://github.com/kybernetwork/kyberswap-dex-lib/tree/main/pkg/source"
```
