# uniswap/smart-order-router architecture

> Architecture diagram of the GitHub repository uniswap/smart-order-router, 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/uniswap/smart-order-router
- Repository: https://github.com/uniswap/smart-order-router

## Overview

Based on our analysis of the file tree and the README, this project is a “Smart Order Router” for the Uniswap V3 protocol. Essentially, its purpose is to determine the most efficient way to swap tokens (token A for token B) by considering various swapping routes, splitting orders, and gas cost tradeoffs. It’s a CLI-driven node/TypeScript application that heavily relies on modular components (routers, providers, and utility modules) to generate quotes and simulate blockchain swap operations.

##### Main Components
- CLI Interface:
- Represented by the “cli” and “bin” directories.
- The CLI commands (such as “quote” and “quote-to-ratio”) serve as the entry points for users and testing.
- Core Routing Logic:
- Under “src/routers”, you have at least two distinct router implementations – the “alpha-router” (the primary, modern router with extensive logic, including candidate pool selection, route calculation, gas models, and quoters) and the “legacy-router” (for backward compatibility or alternative strategies).
- Providers:
- The “src/providers” directory contains many provider modules handling data retrieval and logic for computing quotes (gas pricing, pool data, on-chain quotes, token data, etc.).
- Use of caching providers (e.g., caching-gas-provider, caching-token-provider) and versioned implementations under “v2”, “v3”, “v4” directories.
- ABIs and Smart Contract Integration:
- The “src/abis” folder holds JSON ABI files that are used to interface with on-chain contracts.
- Utilities and Configuration:
- “src/util” holds helper functions (for addresses, amounts, gas parameters, and logging).
- Configuration files such as “hardhat.config.js”, various .env instructions in the README, and test configurations (“jest.config.js”, “tsconfig.json”) should be depicted.
- Testing Infrastructure:
- The “test” directory is well-populated with both unit and integration tests, indicating a robust testing practice.

##### Relationships and Interactions
- User interacts with the system via the CLI, which triggers internal commands.
- The CLI layer calls into the “src/index.ts” and then leverages the routers (specifically the alpha router) to compute routing decisions.
- Routers rely on several providers to query external systems – for example, fetching gas prices, pool details, token properties, and simulation data.
- Caching layers are used to enhance performance and reduce redundant external calls. This is part of the provider implementations and is evident from directories like “src/providers/caching/…”.
- External communication is accomplished by calling blockchain nodes (via JSON RPC providers) and simulation services (like Tenderly), guided by environment variables and configurations.
- Utilities support all layers with common functions (logging, address management, parameter serialization, etc.).

##### Architectural Patterns and Design Principles
- Modularity: The project is partitioned into well-defined components (CLI, routers, providers, utilities) that encapsulate distinct functionality.
- Abstraction and Extensibility: Implementation for different versions (v2, v3, v4) of providers and routers allow for extension or replacement without affecting the overall system.
- Layered Architecture: The CLI presentation layer sits on top of core routing and provider layers which interact with external smart contracts and blockchain data.
- Caching and Optimization: Specialized caching components improve performance when fetching frequently used data.

##### Relevant Technologies and Frameworks
- TypeScript is the primary language (evidenced by the .ts file extensions and tsconfig files).
- Oclif patterns are likely in use for the CLI (as inferred from “cli/base-command.ts”).
- Testing is done using Jest.
- Integration with blockchain is done via Hardhat (note “hardhat.config.js”) and JSON RPC calls.
- The project references common tools like ESLint, Prettier, and GitHub workflows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User"]:::external

    subgraph "Presentation Layer (CLI)"
        CLI["CLI Interface"]:::cli
    end
    A -->|"interacts"| CLI

    subgraph "Application Core"
        ME["Main Entry (src/index.ts)"]:::core
        subgraph "Routing Layer"
            AR["Alpha Router"]:::router
            LR["Legacy Router"]:::router
            RI["Routers Index"]:::router
            RInf["Router Interface"]:::router
        end
        ME --> AR
        ME --> LR
        ME --> RI
        ME --> RInf
    end
    CLI -->|"triggers"| ME

    subgraph "Providers Layer"
        CP["Caching Providers"]:::providerGroup
        CGP["Caching Gas Provider"]:::provider
        CTP["Caching Token Provider"]:::provider
        VP["Versioned Providers"]:::providerGroup
        PP["Pool Provider (v3)"]:::provider
        SP["Subgraph Provider (v4)"]:::provider
        CP --> CGP
        CP --> CTP
        VP --> PP
        VP --> SP
    end
    AR -->|"fetchesQuotes"| CP
    AR -->|"fetchesQuotes"| VP
    LR -->|"fetchesQuotes"| CP
    LR -->|"fetchesQuotes"| VP
    RI -->|"coordinates"| CP
    RI -->|"coordinates"| VP
    RInf -->|"interfaces"| CP
    RInf -->|"interfaces"| VP

    subgraph "External Systems"
        EB["Blockchain Node"]:::externalSys
        TS["Tenderly Simulation"]:::externalSys
    end
    CP -->|"requestsData"| EB
    VP -->|"requestsData"| EB
    CP -->|"simulation"| TS
    VP -->|"simulation"| TS

    subgraph "Smart Contract Integration"
        AB["ABIs"]:::abis
    end
    AB -->|"usedBy"| AR
    AB -->|"usedBy"| LR

    subgraph "Utilities & Configuration"
        UTIL["Utilities"]:::util
        CONF["Configuration & Tools"]:::config
    end
    UTIL --> ME
    CONF --> ME
    UTIL --> AR
    CONF --> AR
    UTIL --> CP
    CONF --> CP

    subgraph "Testing Infrastructure"
        TEST["Testing Infrastructure"]:::test
    end
    TEST --> ME

    %% Click Events for CLI Interface
    click CLI "https://github.com/uniswap/smart-order-router/tree/main/cli"
    click CLI "https://github.com/uniswap/smart-order-router/tree/main/bin"
    click CLI "https://github.com/uniswap/smart-order-router/blob/main/cli/base-command.ts"
    click CLI "https://github.com/uniswap/smart-order-router/tree/main/bin/cli"
    click CLI "https://github.com/uniswap/smart-order-router/blob/main/bin/cli.cmd"

    %% Click Events for Routers
    click AR "https://github.com/uniswap/smart-order-router/blob/main/src/routers/alpha-router/alpha-router.ts"
    click LR "https://github.com/uniswap/smart-order-router/blob/main/src/routers/legacy-router/legacy-router.ts"
    click RI "https://github.com/uniswap/smart-order-router/blob/main/src/routers/index.ts"
    click RInf "https://github.com/uniswap/smart-order-router/blob/main/src/routers/router.ts"

    %% Click Events for Providers
    click CP "https://github.com/uniswap/smart-order-router/tree/main/src/providers"
    click CGP "https://github.com/uniswap/smart-order-router/blob/main/src/providers/caching-gas-provider.ts"
    click CTP "https://github.com/uniswap/smart-order-router/blob/main/src/providers/caching-token-provider.ts"
    click PP "https://github.com/uniswap/smart-order-router/blob/main/src/providers/v3/pool-provider.ts"
    click SP "https://github.com/uniswap/smart-order-router/blob/main/src/providers/v4/subgraph-provider.ts"

    %% Click Events for ABIs
    click AB "https://github.com/uniswap/smart-order-router/tree/main/src/abis"
    click AB "https://github.com/uniswap/smart-order-router/blob/main/src/abis/Permit2.json"
    click AB "https://github.com/uniswap/smart-order-router/blob/main/src/abis/erc20.json"

    %% Click Events for Utilities & Configuration
    click UTIL "https://github.com/uniswap/smart-order-router/tree/main/src/util"
    click CONF "https://github.com/uniswap/smart-order-router/blob/main/hardhat.config.js"
    click CONF "https://github.com/uniswap/smart-order-router/blob/main/jest.config.js"
    click CONF "https://github.com/uniswap/smart-order-router/blob/main/tsconfig.json"
    click CONF "https://github.com/uniswap/smart-order-router/blob/main/.eslintrc.json"
    click CONF "https://github.com/uniswap/smart-order-router/blob/main/.prettierrc"

    %% Click Event for Testing
    click TEST "https://github.com/uniswap/smart-order-router/tree/main/test"

    %% Styles
    classDef cli fill:#F39C12,stroke:#000,stroke-width:2px;
    classDef core fill:#D35400,stroke:#000,stroke-width:2px;
    classDef router fill:#2ECC71,stroke:#000,stroke-width:2px;
    classDef provider fill:#3498DB,stroke:#000,stroke-width:2px;
    classDef providerGroup fill:#85C1E9,stroke:#000,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef abis fill:#9B59B6,stroke:#000,stroke-width:2px;
    classDef externalSys fill:#E74C3C,stroke:#000,stroke-width:2px,stroke-dasharray: 2, 2;
    classDef util fill:#E67E22,stroke:#000,stroke-width:2px;
    classDef config fill:#1ABC9C,stroke:#000,stroke-width:2px;
    classDef test fill:#95A5A6,stroke:#000,stroke-width:2px,stroke-dasharray: 5, 5;
    classDef external fill:#BDC3C7,stroke:#000,stroke-width:2px;
```
