# levana-protocol/levana-perps architecture

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

- Interactive diagram: https://gitdiagram.com/levana-protocol/levana-perps
- Repository: https://github.com/levana-protocol/levana-perps

## Overview

##### Project type and purpose
- This is a full-stack, multi-chain perpetual-swap protocol (Perps V2)
- On-chain: CosmWasm smart contracts (Rust) implementing financial primitives (market, factory, tokens, vaults, copy-trading, etc.)
- Off-chain: CLI executables (Rust bins under packages/perps-exes), TypeScript SDK, CI/CD pipelines, testing harnesses, static site templates
- Research and schema generation are also included

##### File structure – group into major domains
1. Smart Contracts
– `contracts/…` subdirs: each CosmWasm contract module (market, factory, cw20, vault, etc.)
2. Off-chain Tools & CLI
– `packages/perps-exes/…`: Rust binaries (`perps-deploy`, `perps-bots`, `perps-companion`, `perps-market-params`, `perps-qa`, `perps-bridge`) + Web UI templates + CI scripts
3. SDKs
– `ts-schema/…`: Yarn project that generates TypeScript types from contract schemas
– Native Rust/WASM SDK lives alongside `contracts/`, exposed via `perpswap/…` crate
4. Testing & Fuzzing
– `packages/multi_test`: integration test harness simulating chains & contracts
– `packages/fuzz`: cargo-fuzz targets on core logic
– `contracts/*/proptest-regressions`
5. CI/CD and DevOps
– `.ci/`: Dockerfiles, shell scripts for building contracts, migrating chains, packaging source tarballs
– `.github/workflows`: YAML for build, test, bots, market-analyzer, perps-deploy pipelines
– `justfile`: recipe runner for local commands (build-contracts, local-deploy, fuzz, coverage)
6. Documentation & Research
– `README.md`, `docs/`, `research/price-manip-modeling`
7. Data & Assets
– `data/rewards`: CSV incentives history
– `packages/perps-exes/assets`, `static/`, `templates/`

##### README for architecture clues
- Emphasis on multichain support, Dockerized contract builds, local Osmosis testnet, TypeScript & Rust/WASM SDKs
- Deployment flows via the `perps-deploy` CLI
- Testing flows (off-chain, on-chain, prop tests, fuzz)

##### Main components (to appear
A. On-chain layer
1. Cosmos chains (Local Osmosis, Testnet, Mainnet)
2. CosmWasm VM – hosts multiple smart contract modules from `contracts/`
B. Off-chain orchestration & deployment
1. perps-deploy CLI (Rust) – stores code, instantiates/migrates contracts
2. perps-bots CLI – operational bot suite (cranking, liquidity checks, alerts, etc.)
3. perps-companion – companion service with HTTP API and Postgres DB migrations
4. perps-market-params – service fetching market data (Coingecko, S3, Slack) and pushing updates
5. perps-qa – automated QA suite
6. perps-bridge – bridging messages or assets
C. SDK & API layer
1. Rust/WASM SDK (`perpswap/…`) exposing contract calls
2. TypeScript SDK and schema generator (`ts-schema/…`) for front-ends and devs
D. Testing & Continuous Integration
1. multi_test harness simulating chain & contract interactions in Rust
2. fuzz targets ensuring core logic correctness
3. GitHub Actions / CI scripts executing build, test, coverage, and deployment
E. Data & UI Assets
1. Static site assets & templates used by perps-companion and market-params front ends
2. Historical rewards data

##### Relationships & data flows
- Developer → runs Just recipes or CI pipelines → builds WASM contracts (Docker/Cargo) → pushed to chain via perps-deploy
- perps-deploy communicates via Cosmos RPC to the chain → stores code IDs & instantiates contracts
- perps-bots & companion services poll chain state via RPC/SDK → perform cranks, compute PnL, trigger migrations
- TypeScript & Rust/WASM SDKs call smart contracts on chain → used by front-ends or other services
- multi_test harness uses Rust SDK to instantiate in-memory chains, run scenarios, report results
- CI pipelines orchestrate lint, test, build, publish crates, push containers, and deploy CLI tools

##### Architectural patterns & principles
- Modular CosmWasm contract packages (each contract is a component)
- CLI-based microservices pattern (each Rust binary is a separate microservice)
- Shared SDK crates for code reuse (perpswap, CosmJS wrappers)
- Infrastructure as code: Docker, Just, shell scripts, GitHub workflows
- Multi-chain abstraction via config files and chain-specific `assets/*.toml`
- Testing isolation: fuzz tests, proptests, multi_test scenarios

##### Summary checklist
[ ] All on-chain contracts grouped in CosmWasm VM
[ ] SDK layer clearly separated, showing Rust/WASM vs. TS
[ ] Testing harnesses and CI pipelines represented
[ ] External dependencies and data stores drawn

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% On-Chain Layer
    subgraph "On-Chain Layer"
        direction TB
        ChainNodes["Cosmos Chains"]:::cloud
        subgraph "CosmWasm VM (Rust/WASM contracts)"
            direction TB
            Market["Market Module"]:::contract
            Factory["Factory Module"]:::contract
            CW20["CW20 Module"]:::contract
            Vault["Vault Module"]:::contract
            Liquidity["Liquidity Token Module"]:::contract
            Position["Position Token Module"]:::contract
            CopyTrading["Copy-Trading Module"]:::contract
            CounterTrade["Counter-Trade Module"]:::contract
            Tracker["Tracker Module"]:::contract
        end
    end

    %% Off-Chain CLI & Services
    subgraph "Off-Chain CLI & Services"
        direction TB
        PD["perps-deploy CLI"]:::service
        PB["perps-bots CLI"]:::service
        PC["perps-companion HTTP API"]:::service
        PM["perps-market-params Service"]:::service
        PQ["perps-qa QA Suite"]:::service
        PBRI["perps-bridge CLI"]:::service
    end

    %% SDK & API Layer
    subgraph "SDK & API Layer"
        direction TB
        RustSDK["Rust/WASM SDK (perpswap)"]:::sdk
        TSSDK["TypeScript SDK & Schema Generator"]:::sdk
    end

    %% Testing & CI
    subgraph "Testing & CI"
        direction TB
        MT["multi_test Harness"]:::test
        Fuzz["Fuzz Testing Targets"]:::test
        CIWorkflows["CI/CD Workflows & Scripts"]:::ci
    end

    %% Data & Assets
    subgraph "Data & Assets"
        direction TB
        UIAssets["Static UI Assets & Templates"]:::assets
        Rewards["Historical Rewards Data"]:::assets
    end

    %% External Systems
    extCosmos["Osmosis Node / Cosmos RPC"]:::external
    extCoingecko["Coingecko API"]:::external
    extS3Slack["S3 / Slack"]:::external

    %% Connections
    PD -->|"RPC calls"| extCosmos
    PB -->|"RPC calls"| extCosmos
    PC -->|"RPC calls"| extCosmos
    PM -->|"fetch data"| extCoingecko
    PM -->|"push updates"| extS3Slack
    RustSDK -->|"interact with contracts"| ChainNodes
    TSSDK -->|"interact with contracts"| ChainNodes
    MT -->|"uses SDK & simulates"| RustSDK
    MT -->|"runs scenarios on"| ChainNodes
    Fuzz -->|"targets core logic in"| Market
    CIWorkflows -->|"triggers build/test/deploy"| PD
    CIWorkflows -->|"triggers build/test/deploy"| PB
    CIWorkflows -->|"triggers build/test/deploy"| PC
    CIWorkflows -->|"triggers build/test/deploy"| PM
    CIWorkflows -->|"triggers build/test/deploy"| PQ
    CIWorkflows -->|"triggers build/test/deploy"| PBRI
    CIWorkflows -->|"builds contracts"| Market
    CIWorkflows -->|"builds contracts"| Factory
    UIAssets -->|"served by"| PC
    UIAssets -->|"served by"| PM
    Rewards -->|"used by"| PM

    %% Click Events
    click Market "https://github.com/levana-protocol/levana-perps/tree/main/contracts/market/"
    click Factory "https://github.com/levana-protocol/levana-perps/tree/main/contracts/factory/"
    click CW20 "https://github.com/levana-protocol/levana-perps/tree/main/contracts/cw20/"
    click Vault "https://github.com/levana-protocol/levana-perps/tree/main/contracts/vault/"
    click Liquidity "https://github.com/levana-protocol/levana-perps/tree/main/contracts/liquidity_token/"
    click Position "https://github.com/levana-protocol/levana-perps/tree/main/contracts/position_token/"
    click CopyTrading "https://github.com/levana-protocol/levana-perps/tree/main/contracts/copy_trading/"
    click CounterTrade "https://github.com/levana-protocol/levana-perps/tree/main/contracts/countertrade/"
    click Tracker "https://github.com/levana-protocol/levana-perps/tree/main/contracts/tracker/"
    click PD "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/src/bin/perps-deploy/"
    click PD "https://github.com/levana-protocol/levana-perps/tree/main/.ci/perps-deploy/Dockerfile"
    click PD "https://github.com/levana-protocol/levana-perps/blob/main/.github/workflows/perps-deploy.yaml"
    click PB "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/src/bin/perps-bots/"
    click PC "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/src/bin/perps-companion/"
    click PM "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/src/bin/perps-market-params/"
    click PQ "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/src/bin/perps-qa/"
    click PBRI "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/src/bin/perps-bridge/"
    click RustSDK "https://github.com/levana-protocol/levana-perps/tree/main/packages/perpswap/"
    click TSSDK "https://github.com/levana-protocol/levana-perps/tree/main/ts-schema/"
    click MT "https://github.com/levana-protocol/levana-perps/tree/main/packages/multi_test/"
    click Fuzz "https://github.com/levana-protocol/levana-perps/tree/main/packages/fuzz/"
    click CIWorkflows "https://github.com/levana-protocol/levana-perps/tree/main/.github/workflows/"
    click CIWorkflows "https://github.com/levana-protocol/levana-perps/tree/main/.ci/"
    click UIAssets "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/static/"
    click UIAssets "https://github.com/levana-protocol/levana-perps/tree/main/packages/perps-exes/templates/"
    click Rewards "https://github.com/levana-protocol/levana-perps/tree/main/data/rewards/"

    %% Styles
    classDef contract fill:#FDECEF,stroke:#E74646,stroke-width:2px
    classDef service fill:#E8F4FD,stroke:#3E8ED0,stroke-width:2px
    classDef sdk fill:#EDF7ED,stroke:#3AA34A,stroke-width:2px
    classDef test fill:#FFF4E5,stroke:#DFA43A,stroke-width:2px
    classDef ci fill:#F2E8FD,stroke:#8C3ED0,stroke-width:2px
    classDef assets fill:#ECEFF1,stroke:#607D8B,stroke-width:2px
    classDef external fill:#FFFFFF,stroke:#000000,stroke-dasharray: 5 5
    classDef cloud fill:#E3F2FD,stroke:#0288D1,stroke-width:2px,shape:cloud
    class ChainNodes cloud
```
