# curvefi/metaregistry architecture

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

- Interactive diagram: https://gitdiagram.com/curvefi/metaregistry
- Repository: https://github.com/curvefi/metaregistry

## Overview

Based on our analysis of the file tree and README, this project is a blockchain-based smart contract system specifically built to aggregate and manage multiple Curve Finance registries. It leverages Vyper contracts (with file extensions “.vy”) for the on-chain logic, a collection of Python deployment and utility scripts for managing deployments and integrations, as well as a robust testing suite (using pytest) and CI/CD workflows (GitHub Actions and Docker) to ensure quality and reproducibility.

##### Main Components
- Smart Contract Layer:
- The MetaRegistry Contract in the “contracts” folder (providing functions like get_registry_handlers_from_pool, pool_list, etc.).
- The child registries and factories (e.g., Curve Stable Registry, Curve Stable Factory, Crypto Registry, Crypto Factory) located under “contracts” with their specific implementations for stable and crypto swap pools.
- Registry Handlers that serve as wrappers around child registries (located in contracts/registry_handlers, and further in subdirectories like “ng”) – these enforce standardized ABI interfaces for integration with the MetaRegistry.
- Interfaces (contracts/interfaces) which provide standard JSON ABI files for external interactions.
- Mocks (contracts/mocks) that simulate contract behavior, useful for testing.

- Deployment and Script Layer:
- Python deployment scripts in the “scripts” directory such as deploy.py, deploy_rate_provider.py, and others which are responsible for orchestrating contract deployments and configurations.

- Testing Environment:
- Integration tests under “tests/mainnet” and unit tests under “tests/unitary”, ensuring smart contract functionality (e.g., API methods such as get_coins, get_balances) is validated correctly.
- Fixtures that simulate accounts, tokens, and deployments.

- Infrastructure / DevOps:
- Docker and docker-compose files, which containerize the deployment environment.
- GitHub workflows (under .github/workflows) for continuous integration processes.
- Configuration files (.dockerignore, .gitignore, setup.cfg, etc.) that assist in project maintenance and build consistency.

##### Relationships and Interactions
- Link the test suites to the contracts layer to explain how different tests call into contract functions (like get_pool_params, get_underlying_balances) and simulate realistic scenarios.
- Optionally, include external links such as blockchain networks (Ethereum Mainnet, zkSync for other chains) and external resources like Etherscan as information points (as seen in the README).

##### Architectural Patterns and Design Principles
- Aggregator Pattern – The MetaRegistry aggregates multiple child registries into a single unified API.
- Wrapper/Adapter Pattern – The Registry Handlers wrap around the original registries to enforce ABI compliance and allow hotfixes.
- Separation of Concerns – The codebase is divided into contracts, deployment scripts, and tests.
- Modularization – With well-organized directories (contracts with subdirectories for AMMs, interfaces, mocks, registries; scripts and tests), each module has its specific responsibility.

##### Specify Relevant Technologies, Frameworks, and Libraries
- Vyper – for smart contract development.
- Python – for scripting deployments and tests (along with Titanoboa for deployment/testing integration).
- Docker – containerization for deployment and testing.
- GitHub Actions – for continuous integration and automation.
- Pytest – for testing the contracts through deployment scripts.
- JSON ABIs – used in the interfaces for interaction with contracts.

- Components for each child registry (Stable Registry, Crypto Registry, etc.), and show registry handlers wrapping these components.
- A testing layer:
- Tests directory and show which contract endpoints they interact with.
- Finally, include the infrastructure components (Docker, GitHub Actions) with a note indicating continuous integration/deployment pipelines.
- Data flow (e.g., from user/integrators to MetaRegistry API calls).
- Dependency flow (e.g., deployment scripts initiate contract deployment and testing scripts verify contract outputs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Smart Contract Layer
    subgraph "Smart Contract Layer"
        meta["MetaRegistry Contract"]:::contract
        metaL2["MetaRegistry L2 Contract"]:::contract
        
        subgraph "Registries"
            bpr["BasePoolRegistry"]:::contract
            cry["CryptoRegistryV1"]:::contract
        end
        
        subgraph "AMMs & Factories"
            stableswap["AMMs/stableswapng"]:::contractDir
            tricrypto["AMMs/tricryptong"]:::contractDir
            twocrypto["AMMs/twocryptong"]:::contractDir
        end
        
        subgraph "Registry Handlers"
            mainHandlers["Main Handlers"]:::contract
            ngHandlers["NG Handlers"]:::contract
        end
        
        interfaces["Interfaces"]:::contract
        mocks["Mocks"]:::contract
    end

    %% Deployment and Script Layer
    subgraph "Deployment and Script Layer"
        deploymentScripts["Deployment Scripts"]:::deployment
        utilityScripts["Utility Scripts"]:::deployment
    end

    %% Testing Environment
    subgraph "Testing Environment"
        integration["Integration Tests"]:::testing
        unitTests["Unit Tests"]:::testing
    end

    %% Infrastructure / DevOps
    subgraph "Infrastructure / DevOps"
        docker["Docker"]:::devops
        github["GitHub Actions"]:::devops
        config["Config Files"]:::devops
    end

    %% External/Integrators
    external["Ethereum Mainnet"]:::external

    %% Relationships
    %% External interacts with contracts
    external -- "calls" --> meta

    %% Registry Handlers registered with MetaRegistry
    mainHandlers -- "registered" --> meta
    ngHandlers -- "registered" --> meta

    %% MetaRegistry aggregates Registries and AMMs
    meta -- "aggregates" --> bpr
    meta -- "aggregates" --> cry
    meta -- "aggregates" --> stableswap
    meta -- "aggregates" --> tricrypto
    meta -- "aggregates" --> twocrypto

    %% Deployment scripts deploy and configure contracts
    deploymentScripts -- "deploys" --> meta
    deploymentScripts -- "deploys" --> metaL2
    deploymentScripts -- "configures" --> mainHandlers
    deploymentScripts -- "configures" --> ngHandlers

    %% Utility scripts interact with contract interfaces
    utilityScripts -- "aids" --> interfaces

    %% Testing environment validates contracts
    integration -- "tests" --> meta
    integration -- "tests" --> bpr
    integration -- "tests" --> cry
    unitTests -- "tests" --> meta
    unitTests -- "tests" --> mocks

    %% DevOps supports deployment and testing
    github -- "CI/CD" --> deploymentScripts
    github -- "CI/CD" --> integration
    docker -- "containerizes" --> deploymentScripts
    config -- "configures" --> deploymentScripts

    %% Click Events
    click meta "https://github.com/curvefi/metaregistry/blob/main/contracts/MetaRegistry.vy"
    click metaL2 "https://github.com/curvefi/metaregistry/blob/main/contracts/MetaRegistryL2.vy"
    click bpr "https://github.com/curvefi/metaregistry/blob/main/contracts/registries/BasePoolRegistry.vy"
    click cry "https://github.com/curvefi/metaregistry/blob/main/contracts/registries/CryptoRegistryV1.vy"
    click stableswap "https://github.com/curvefi/metaregistry/tree/main/contracts/amms/stableswapng"
    click tricrypto "https://github.com/curvefi/metaregistry/tree/main/contracts/amms/tricryptong"
    click twocrypto "https://github.com/curvefi/metaregistry/tree/main/contracts/amms/twocryptong"
    click mainHandlers "https://github.com/curvefi/metaregistry/tree/main/contracts/registry_handlers"
    click ngHandlers "https://github.com/curvefi/metaregistry/tree/main/contracts/registry_handlers/ng"
    click interfaces "https://github.com/curvefi/metaregistry/tree/main/contracts/interfaces"
    click mocks "https://github.com/curvefi/metaregistry/tree/main/contracts/mocks"
    click deploymentScripts "https://github.com/curvefi/metaregistry/tree/main/scripts"
    click utilityScripts "https://github.com/curvefi/metaregistry/tree/main/scripts/utils"
    click integration "https://github.com/curvefi/metaregistry/tree/main/tests/mainnet"
    click unitTests "https://github.com/curvefi/metaregistry/tree/main/tests/unitary"
    click docker "https://github.com/curvefi/metaregistry/tree/main/Dockerfile"
    click github "https://github.com/curvefi/metaregistry/tree/main/.github/workflows"
    click config "https://github.com/curvefi/metaregistry/blob/main/.gitignore"

    %% Styles
    classDef contract fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef contractDir fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef deployment fill:#66CCFF,stroke:#333,stroke-width:2px;
    classDef testing fill:#CCFF66,stroke:#333,stroke-width:2px;
    classDef devops fill:#FF6666,stroke:#333,stroke-width:2px;
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:2px;
```
