# 1inch/spot-price-aggregator architecture

> Architecture diagram of the GitHub repository 1inch/spot-price-aggregator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1inch/spot-price-aggregator
- Repository: https://github.com/1inch/spot-price-aggregator

## Overview

##### Project type and purpose
- This is an open‑source, off‑chain “Spot Price Aggregator” for blockchain tokens.
- It consists of Solidity smart contracts (oracles, wrappers, multi‑wrapper, offchain oracle) plus deployment scripts, client examples, tests, docs, and CI pipelines.
- Its job: off‑chain code queries a set of on‑chain contracts to fetch and aggregate DEX prices, applying wrappers (e.g., wETH, cDAI) and connectors (intermediate tokens) when no direct pair exists.

##### File structure
- contracts/
– oracles/ : per‑DEX pricing modules (Uniswap, Curve, Chainlink, etc.)
– wrappers/ : token‑wrap adapters (Aave, Compound, ERC‑4626, custom)
– MultiWrapper.sol : orchestrates wrappers
– OffchainOracle.sol : entry point aggregator contract
- deploy/ + deployments/ : Hardhat scripts and per‑network JSON addresses
- scripts/ + examples/ : off‑chain Node.js Ethers.js clients to call the aggregator
- test/ : JavaScript tests for oracles, wrappers, aggregator
- docs/ : Markdown descriptions and interface specs
- hardhat.config.js, migrations/, .github/workflows : build, test, CI/CD

##### README for additional insights
- Readme explains core modules: “Wrappers,” “Connectors,” “Supported DEXes,” “Examples,” and “Oracle Deployment Guide.”
- Highlights that usage is off‑chain: client code calls OffchainOracle.readPrice(…) which in turn invokes on‑chain oracles and wrappers.
- Deployment scripts register networks, deploy contracts, and populate deployments/ with addresses per chain.

##### Elements
- Blue: on‑chain contract modules
- Green: off‑chain client & scripts
- Orange: deployment pipeline
- Gray: external services (DEXes, RPC)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Off-chain Client Layer"
        CLIENT["Node.js scripts & examples"]:::offchain
    end

    subgraph "CI/CD Pipeline"
        CI["GitHub Actions\n(.github/workflows/test.yml)"]:::offchain
        TEST["Tests\n(test/)"]:::deploy
    end

    subgraph "Deployment Layer"
        DEPLOY_CLI["Deployment CLI & commands"]:::deploy
        CREATE3["Network‑agnostic Create3"]:::deploy
        MIGRATIONS["Truffle‑style Migrations"]:::deploy
        DEPLOY_ART["Deployment Artifacts\n(deployments/)"]:::deploy
    end

    subgraph "Smart Contracts Layer"
        OFFCHAIN["OffchainOracle"]:::onchain
        MULTI["MultiWrapper"]:::onchain
        INTERFACES["IOracle & IWrapper"]:::onchain
        ORAC["Oracle Modules"]:::onchain
        WRAP["Wrapper Modules"]:::onchain
        LIB["OraclePrices Library"]:::onchain
        HELP["Helper Contracts"]:::onchain
    end

    subgraph "Blockchain Networks"
        ETH["Ethereum Mainnet\n(deployments/)"]:::external
        BSC["BSC"]:::external
        POLY["Polygon"]:::external
    end

    subgraph "External Services"
        RPC["RPC Providers"]:::external
        DEX["DEX Pools & Protocols"]:::external
        EXPL["Etherscan‑like Explorers"]:::external
    end

    CLIENT -->|"readPrice()"| RPC
    RPC --> OFFCHAIN
    OFFCHAIN -->|"getPrice()"| ORAC
    OFFCHAIN -->|"wrap() / unwrap()"| MULTI
    MULTI -->|"uses adapter"| WRAP
    ORAC -->|"fetch price from"| DEX
    ORAC -->|"uses library"| LIB
    OFFCHAIN -->|"registers oracles & wrappers"| INTERFACES
    MULTI -->|"implements"| INTERFACES
    ORAC -->|"calls helpers"| HELP
    OFFCHAIN -->|"returns price" | CLIENT

    DEPLOY_CLI --> RPC
    RPC --> OFFCHAIN
    RPC --> MULTI
    RPC --> ORAC
    RPC --> WRAP
    RPC --> INTERFACES
    RPC --> HELP
    RPC --> LIB
    RPC --> DEPLOY_ART
    MIGRATIONS --> DEPLOY_ART
    CREATE3 --> OFFCHAIN
    CI --> TEST
    TEST --> DEPLOY_CLI

    classDef offchain fill:#b2f2bb,stroke:#2f9e44,color:#000
    classDef onchain fill:#74c0fc,stroke:#228be6,color:#000
    classDef deploy fill:#ffd43b,stroke:#f08c00,color:#000
    classDef external fill:#dee2e6,stroke:#495057,color:#000

    click OFFCHAIN "https://github.com/1inch/spot-price-aggregator/blob/master/contracts/OffchainOracle.sol"
    click MULTI "https://github.com/1inch/spot-price-aggregator/blob/master/contracts/MultiWrapper.sol"
    click ORAC "https://github.com/1inch/spot-price-aggregator/tree/master/contracts/oracles/"
    click WRAP "https://github.com/1inch/spot-price-aggregator/tree/master/contracts/wrappers/"
    click INTERFACES "https://github.com/1inch/spot-price-aggregator/blob/master/contracts/interfaces/IOracle.sol"
    click INTERFACES "https://github.com/1inch/spot-price-aggregator/blob/master/contracts/interfaces/IWrapper.sol"
    click LIB "https://github.com/1inch/spot-price-aggregator/blob/master/contracts/libraries/OraclePrices.sol"
    click HELP "https://github.com/1inch/spot-price-aggregator/tree/master/contracts/helpers/"
    click DEPLOY_CLI "https://github.com/1inch/spot-price-aggregator/tree/master/deploy/commands/"
    click CREATE3 "https://github.com/1inch/spot-price-aggregator/tree/master/deploy/commands/use-create3/"
    click MIGRATIONS "https://github.com/1inch/spot-price-aggregator/tree/master/migrations/"
    click DEPLOY_ART "https://github.com/1inch/spot-price-aggregator/tree/master/deployments/"
    click CLIENT "https://github.com/1inch/spot-price-aggregator/tree/master/scripts/"
    click CLIENT "https://github.com/1inch/spot-price-aggregator/tree/master/examples/"
    click TEST "https://github.com/1inch/spot-price-aggregator/tree/master/test/"
    click CI "https://github.com/1inch/spot-price-aggregator/blob/master/.github/workflows/test.yml"
```
