# ref-finance/ref-contracts architecture

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

- Interactive diagram: https://gitdiagram.com/ref-finance/ref-contracts
- Repository: https://github.com/ref-finance/ref-contracts

## Overview

##### Project type and purpose
- This is a monorepo for a set of NEAR‐based smart contracts written in Rust and compiled to WebAssembly (WASM).
- Primary contracts:
- ref-exchange: the main exchange logic for depositing, withdrawing, and swapping tokens.
- ref-farming: staking and reward distribution functionality.
- test-token and various mock-* crates: support testing and simulate external services (price oracles, wrapped NEAR).
- The repo also includes documentation, build/deploy scripts, CI workflows, and multiple versions of compiled WASM releases.

##### File structure
- Top-level directories:
- .github/workflows: CI for building/testing contracts.
- doc/ and docs.md: feature and fee documentation.
- mock-*: standalone crates simulating external dependencies (boost farming logic, price oracles, tokens).
- ref-exchange/ and ref-farming/: each contains a Rust crate with src/, tests/, build scripts, and release notes.
- test-token/: a simple NEP-21 token for integration tests.
- scripts/ and Makefile/Dockerfile: automation for building, testing, and deploying.
- Patterns inside each contract crate:
- src/actions_of_*.rs and src/* files separate business logic modules (e.g., seed, pool, farm).
- src/storage_impl.rs isolates persistent state.
- src/view.rs exposes read-only methods.
- tests/common and tests/fuzzy/integration tests using NEAR Simulation framework.

##### Key insights from README
- Confirms Rust/WASM toolchain (rustup, target wasm32-unknown-unknown).
- Testing via cargo test and NEAR Simulation.
- Deployment to TestNet via near dev-deploy.
- ref-exchange is the “main” contract—other crates support testing or specialized logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer Environment
    subgraph "Developer Environment" 
        direction TB
        RustToolchain["Rust & Cargo"]:::dev
        BuildScripts["Build Scripts (Makefile, build.sh)"]:::dev
        CI_Cd["CI/CD (GitHub Actions, Docker)"]:::dev
        Simulation["NEAR Simulation Framework"]:::dev
        CodeHash["Code Hash Utilities"]:::dev
    end

    %% Mock Testing Modules
    subgraph "Mock & Test Modules" 
        direction TB
        MockBoost["mock-boost-farming"]:::test
        MockOraclePrice["mock-price-oracle"]:::test
        MockOraclePyth["mock-pyth"]:::test
        MockWNEAR["mock-wnear"]:::test
        TestRatedToken["test-rated-token"]:::test
    end

    %% NEAR Blockchain
    subgraph "NEAR Blockchain" 
        direction TB
        RefExchange["ref-exchange"]:::chain
        RefFarming["ref-farming"]:::chain
        TestToken["test-token"]:::chain
    end

    %% Releases
    Releases["Compiled WASM Releases"]:::dev

    %% External Users
    Users["Users / Frontend"]:::ext

    %% Flows
    Users -->|"transactions (swap, deposit, stake)"| RefExchange
    Users -->|"transactions (stake, withdraw)"| RefFarming

    RefExchange -->|"cross-call"| RefFarming
    RefExchange -->|"NEP-141 transfers"| TestToken
    RefFarming -->|"NEP-141 transfers"| TestToken

    RefExchange -.->|emits events| Users
    RefFarming -.->|emits events| Users

    %% Testing Connections
    MockBoost -->|used in tests| RefFarming
    MockOraclePrice -->|used in tests| RefExchange
    MockOraclePyth -->|used in tests| RefExchange
    MockWNEAR -->|used in tests| RefExchange
    TestRatedToken -->|used in tests| RefExchange

    Simulation -->|runs integration tests| RefExchange
    Simulation -->|runs integration tests| RefFarming

    %% Build & Deploy Flow
    RustToolchain --> BuildScripts
    BuildScripts -->|compiles to WASM| Releases
    CI_Cd -->|build & test| BuildScripts
    CI_Cd -->|deploy| RefExchange
    CI_Cd -->|deploy| RefFarming

    Releases -->|deploy via near dev-deploy| RefExchange
    Releases -->|deploy via near dev-deploy| RefFarming

    %% Click Events
    click RefExchange "https://github.com/ref-finance/ref-contracts/tree/main/ref-exchange/"
    click RefFarming "https://github.com/ref-finance/ref-contracts/tree/main/ref-farming/"
    click TestToken "https://github.com/ref-finance/ref-contracts/tree/main/test-token/"
    click MockBoost "https://github.com/ref-finance/ref-contracts/tree/main/mock-boost-farming/"
    click MockOraclePrice "https://github.com/ref-finance/ref-contracts/tree/main/mock-price-oracle/"
    click MockOraclePyth "https://github.com/ref-finance/ref-contracts/tree/main/mock-pyth/"
    click MockWNEAR "https://github.com/ref-finance/ref-contracts/tree/main/mock-wnear/"
    click TestRatedToken "https://github.com/ref-finance/ref-contracts/tree/main/test-rated-token/"
    click CI_Cd "https://github.com/ref-finance/ref-contracts/blob/main/.github/workflows/exchange.yaml"
    click BuildScripts "https://github.com/ref-finance/ref-contracts/tree/main/Makefile"
    click BuildScripts "https://github.com/ref-finance/ref-contracts/blob/main/scripts/codehash.py"
    click CodeHash "https://github.com/ref-finance/ref-contracts/blob/main/codehash.sh"
    click Releases "https://github.com/ref-finance/ref-contracts/tree/main/releases/"

    %% Styles
    classDef chain fill:#e0ffe0,stroke:#0a0,stroke-width:1px
    classDef dev fill:#e0f0ff,stroke:#00a,stroke-width:1px
    classDef test fill:#fff7e0,stroke:#da8,stroke-width:1px
    classDef ext fill:#ffe0e0,stroke:#a00,stroke-width:1px
```
