# certora/aquarius-cantina-fv architecture

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

- Interactive diagram: https://gitdiagram.com/certora/aquarius-cantina-fv
- Repository: https://github.com/certora/aquarius-cantina-fv

## Overview

##### Project type and purpose
- This is a Rust-based, multi-crate repository for Soroban smart contracts and their formal verification.
- It bundles:
- A suite of Soroban contracts (e.g., token, liquidity-pool, access_control) compiled to WASM.
- A formal verification toolchain using Certora Sunbeam in the `fees_collector` crate.
- Integration tests and Taskfiles/Justfiles for building, testing, and running the prover.
- Primary purpose: develop, test, and formally verify properties of on-chain smart contracts in the Aquarius contest.

##### File structure
- Top-level workspace with Cargo.toml, GitHub Actions, Taskfile.yaml, and subfolders for each contract crate.
- Each crate (e.g., `access_control`, `liquidity_pool`, `token`) has its own Cargo.toml, source, tests, and Taskfile/Justfile.
- The `contracts` folder holds pre-built WASM blobs for deployment.
- `fees_collector` is special: it contains:
- `confs/` (Certora run configurations)
- `src/certora_specs/` (spec files, mocks, summaries)
- `mutations/` (mutant code for evaluating coverage)
- `integration_tests` runs end-to-end tests against all contracts.
- Common utilities in `utils` crate.

##### README for additional insights
- Describes the Formal Verification (FV) contest, prize structure, and Certora integration.
- Emphasizes the Certora folder layout in `fees_collector` for specs, mocks, summaries, and mutations.
- Details build steps: `just build`, then `certoraSorobanProver` with .conf files.

##### Elements
- Clear labels: e.g., “access_control crate”, “token crate”, “fees_collector::certora_specs”.
- from contract crates → integration_tests
- from fees_collector → Certora CLI → proofs
- from Taskfile → cargo build/test/prover
- Blue rectangles for Rust crates
- Orange hexagons for external tools (Soroban, Certora)

##### Detailed breakdown
- Of crates
- CI / workflow triggers
- Verification layer (`fees_collector`):
- Testing layer: `integration_tests` crate → local Soroban runtime.
- Utility layer: `utils` crate supporting all others.
- Automation layer: Taskfile/Justfile → orchestrates all build/test/verify tasks.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Workspace Root
    subgraph "Workspace Root"
        direction TB
        RootCargo["Cargo.toml"]:::config
        RootTaskfile["Taskfile.yaml"]:::config
        CI[".github/workflows/rust.yml"]:::external
    end

    %% Contract Layer
    subgraph "Contract Crates" 
        direction TB
        AC["access_control crate"]:::crate
        TK["token crate"]:::crate
        LP["liquidity_pool crate"]:::crate
        LPCalc["liquidity_pool_liquidity_calculator crate"]:::crate
        LPPlane["liquidity_pool_plane crate"]:::crate
        LPFee["liquidity_pool_provider_swap_fee crate"]:::crate
        LPFeeFactory["liquidity_pool_provider_swap_fee_factory crate"]:::crate
        LPRouter["liquidity_pool_router crate"]:::crate
        LPStable["liquidity_pool_stableswap crate"]:::crate
        LPEvents["liquidity_pool_events crate"]:::crate
        LPValErr["liquidity_pool_validation_errors crate"]:::crate
        LF["locker_feed crate"]:::crate
        RW["rewards crate"]:::crate
        UP["upgrade crate"]:::crate
        TS["token_share crate"]:::crate
    end

    %% WASM artifacts
    subgraph "Pre-built WASM Blobs"
        direction TB
        WASM["contracts/*.wasm"]:::artifact
    end

    %% Verification Layer
    subgraph "Fees Collector Crate" 
        direction TB
        FC["fees_collector crate"]:::crate
        FCConfs["confs/"]:::config
        FCSpecs["src/certora_specs/"]:::config
        FCMuts["mutations/"]:::config
        FCCode["src/*.rs"]:::crate
    end

    %% Testing Layer
    subgraph "Integration Tests"
        direction TB
        IT["integration_tests crate"]:::crate
    end

    %% Utility Layer
    subgraph "Utils Crate"
        direction TB
        UT["utils crate"]:::crate
    end

    %% External Tools
    Soroban["Soroban Runtime"]:::external
    Certora["Certora Sunbeam Prover"]:::external
    GHActions["GitHub Actions CI"]:::external

    %% Artifact Layer
    Proofs["Proof/Coverage Reports"]:::artifact

    %% Flows
    RootTaskfile -->|orchestrates build| AC
    RootTaskfile -->|orchestrates build| TK
    RootTaskfile -->|orchestrates build| LP
    RootTaskfile -->|orchestrates build| LPCalc
    RootTaskfile -->|orchestrates build| LPPlane
    RootTaskfile -->|orchestrates build| LPFee
    RootTaskfile -->|orchestrates build| LPFeeFactory
    RootTaskfile -->|orchestrates build| LPRouter
    RootTaskfile -->|orchestrates build| LPStable
    RootTaskfile -->|orchestrates build| LPEvents
    RootTaskfile -->|orchestrates build| LPValErr
    RootTaskfile -->|orchestrates build| LF
    RootTaskfile -->|orchestrates build| RW
    RootTaskfile -->|orchestrates build| UP
    RootTaskfile -->|orchestrates build| TS
    RootTaskfile -->|runs tests| IT
    RootTaskfile -->|runs prover| FC

    %% Compilation to WASM
    AC -->|compiles to| WASM
    TK -->|compiles to| WASM
    LP -->|compiles to| WASM
    LPCalc -->|compiles to| WASM
    LPPlane -->|compiles to| WASM
    LPFee -->|compiles to| WASM
    LPFeeFactory -->|compiles to| WASM
    LPRouter -->|compiles to| WASM
    LPStable -->|compiles to| WASM
    LPEvents -->|compiles to| WASM
    LPValErr -->|compiles to| WASM
    LF -->|compiles to| WASM
    RW -->|compiles to| WASM
    UP -->|compiles to| WASM
    TS -->|compiles to| WASM

    %% Integration tests flow
    IT -->|deploys to| Soroban
    WASM -->|loaded on| Soroban

    %% Verification flow
    FC -->|reads confs| FCConfs
    FC -->|reads specs| FCSpecs
    FC -->|reads mutations| FCMuts
    FC -->|executes code| FCCode
    FC -->|invokes| Certora
    Certora -->|outputs| Proofs

    %% CI flow
    GHActions -->|triggers| RootTaskfile
    GHActions -->|runs| IT
    GHActions -->|runs| FC

    %% Click events
    click RootCargo "https://github.com/certora/aquarius-cantina-fv/blob/main/Cargo.toml"
    click RootTaskfile "https://github.com/certora/aquarius-cantina-fv/blob/main/Taskfile.yaml"
    click CI "https://github.com/certora/aquarius-cantina-fv/blob/main/.github/workflows/rust.yml"
    click AC "https://github.com/certora/aquarius-cantina-fv/tree/main/access_control/"
    click TK "https://github.com/certora/aquarius-cantina-fv/tree/main/token/"
    click LP "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool/"
    click LPCalc "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_liquidity_calculator/"
    click LPPlane "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_plane/"
    click LPFee "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_provider_swap_fee/"
    click LPFeeFactory "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_provider_swap_fee_factory/"
    click LPRouter "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_router/"
    click LPStable "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_stableswap/"
    click LPEvents "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_events/"
    click LPValErr "https://github.com/certora/aquarius-cantina-fv/tree/main/liquidity_pool_validation_errors/"
    click LF "https://github.com/certora/aquarius-cantina-fv/tree/main/locker_feed/"
    click RW "https://github.com/certora/aquarius-cantina-fv/tree/main/rewards/"
    click UP "https://github.com/certora/aquarius-cantina-fv/tree/main/upgrade/"
    click TS "https://github.com/certora/aquarius-cantina-fv/tree/main/token_share/"
    click FC "https://github.com/certora/aquarius-cantina-fv/blob/main/fees_collector/Cargo.toml"
    click FCConfs "https://github.com/certora/aquarius-cantina-fv/tree/main/fees_collector/confs/"
    click FCSpecs "https://github.com/certora/aquarius-cantina-fv/tree/main/fees_collector/src/certora_specs/"
    click FCMuts "https://github.com/certora/aquarius-cantina-fv/tree/main/fees_collector/mutations/"
    click FCCode "https://github.com/certora/aquarius-cantina-fv/blob/main/fees_collector/src/lib.rs"
    click IT "https://github.com/certora/aquarius-cantina-fv/tree/main/integration_tests/"
    click UT "https://github.com/certora/aquarius-cantina-fv/tree/main/utils/"
    click GHActions "https://github.com/certora/aquarius-cantina-fv/blob/main/.github/workflows/rust.yml"

    %% Styles
    classDef crate fill:#E3F2FD,stroke:#1976D2,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px,stroke-dasharray: 5 5
    classDef artifact fill:#C8E6C9,stroke:#388E3C,stroke-width:1px,stroke-dasharray: 2 2
    classDef config fill:#FFF9C4,stroke:#F9A825,stroke-width:1px,stroke-dasharray: 2 2
```
