# flare-labs-ltd/fassets architecture

> Architecture diagram of the GitHub repository flare-labs-ltd/fassets, 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/flare-labs-ltd/fassets
- Repository: https://github.com/flare-labs-ltd/fassets

## Overview

##### Project type and purpose
- This is a blockchain‐focused system: a collection of Solidity smart contracts (“FAsset contracts”) plus accompanying TypeScript tooling, deployment scripts (Hardhat, Diamond Cuts), and test suites. Its purpose is to mint and manage “FAssets” (wrapped assets secured by collateral) on Flare and Songbird chains using on‐chain protocols (FTSO, FDC).

##### Main architectural components
a. On-chain Contracts (Solidity)
- Core modules:
- AssetManager (facets, implementation, interfaces, libraries, mocks)
- Diamond (facets, implementation, interfaces; implements EIP-2535 Diamond pattern)
- FAssetToken (implementation, interfaces, libraries, mocks)
- FDC bridge contracts
- Governance contracts (timelock, upgradeability)
- OpenZeppelin utilities (ERC20, security, EIP712, token permits)
- UserInterfaces (data types, helper contracts)
- Shared Utils (libraries, interfaces)
b. Off-chain Deployment & Tooling (TypeScript + JSON)
- Deployment scripts under /deployment: configuration schemas, chain-specific parameters, DiamondCut JSON, deploy utilities, verify scripts
- Hardhat config & tasks (hardhat.config.ts, hardhat-tasks.config.ts)
c. Off-chain Libraries & Actors
- /lib folders host:
- Domain boundaries (fasset, state, underlying-chain abstractions)
- Actor models (Challenger, LiquidationTrigger)
- Helpers (deepCopy, events formatting, blockchain adapters)
- Scripts for flattening, documentation, CLI runners
d. Test Suites
- Unit tests (per module, mocks)
- Integration tests (fasset‐simulation flows)
- Fuzzing tests (property‐based with custom actors)
- Test utilities (helpers, chain simulators)
e. Documentation
- /docs (interfaces, specs, deployment guide)

##### Key relationships & data flows
- Users or off-chain services (CLI, scripts, front-ends) → submit transactions to On-chain Contracts via JSON-RPC (Hardhat, Infura, local node).
- On-chain AssetManager/Diamond uses FTSO price feeds and FDC data connectors to secure minted FAssets.
- Governance contracts control upgrades (DiamondCut) and parameter modifications.
- Deployment pipeline: TypeScript scripts read JSON schemas → deploy diamond, facets, libraries → link contracts → verify on Tenderly/Etherscan.
- Test harness simulates underlying chains and FDC/FTSO behavior to drive integration/fuzzing tests.

##### Architectural patterns & principles
- EIP-2535 Diamond pattern (modular facets + proxy) for upgradability
- Layered separation:
- Interface contracts + implementation contracts + libraries
- On-chain vs Off-chain concerns
- Schema-driven deployment (JSON parameter schemas for each network)
- Extensive mocking for deterministic unit/fuzzing tests

##### Final checklist
- Clearly separated On-chain vs Off-chain vs External
- Annotations for architectural patterns: Diamond, library layering, JSON schema inputs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        direction TB
        FTSO["FTSO Price Oracle"]:::external
        FDCBridge["FDC Data Bridge"]:::external
        Underlying["Underlying Chains\n(XRP, BTC, DOGE, LTC)"]:::external
        JSONRPC["JSON-RPC Provider"]:::external
    end

    %% On-chain Contracts
    subgraph "On-chain Contracts" 
        direction TB
        AM["AssetManager\n(contracts/assetManager)"]:::onchain
        DMD["Diamond Proxy & Facets\n(contracts/diamond)"]:::onchain
        FAT["FAssetToken\n(contracts/fassetToken)"]:::onchain
        FDC["FDC Bridge Contracts\n(contracts/fdc)"]:::onchain
        GOV["Governance Contracts\n(contracts/governance)"]:::onchain
        OZ["OpenZeppelin Utilities\n(contracts/openzeppelin)"]:::onchain
        UI["UserInterfaces\n(contracts/userInterfaces)"]:::onchain
        SU["Shared Utils\n(contracts/utils)"]:::onchain
    end

    %% Off-chain Tools
    subgraph "Off-chain Tools & Deployment" 
        direction TB
        DEP["Deployment & Tooling\n(deployment)"]:::offchain
        HHCONF["Hardhat Config & Tasks\n(hardhat.config.ts,\nhardhat-tasks.config.ts)"]:::offchain
        LIB["Off-chain Libraries & Actors\n(lib)"]:::offchain
    end

    %% Test Harness
    subgraph "Test Harness" 
        direction TB
        UT["Unit Tests\n(test/unit)"]:::test
        IT["Integration Tests\n(test/integration)"]:::test
        FT["Fuzzing Tests\n(test/fuzzing)"]:::test
        TU["Test Utilities\n(test/utils)"]:::test
    end

    %% Documentation
    DOCS["Documentation\n(docs)"]:::docs

    %% Relationships
    DEP -->|deploy via JSON-RPC| DMD
    DEP -->|deploy facets & libs| AM
    DEP -->|deploy token| FAT
    HHCONF -->|configures| DEP
    LIB -->|scripts/CLI| AM
    LIB -->|scripts/CLI| FAT
    LIB -->|scripts/CLI| GOV
    LIB -->|adapters| FDC
    LIB -->|helpers| DMD

    AM -->|FTSO price feed| FTSO
    FDC -->|data feed| FDCBridge
    JSONRPC -->|transactions| AM
    JSONRPC -->|transactions| FAT
    JSONRPC -->|transactions| DMD
    JSONRPC -->|transactions| GOV

    UT -->|simulate & test| AM
    IT -->|simulate flows| AM
    FT -->|property tests| AM
    TU -->|helpers| UT

    FTSO -->|on-chain data| AM
    FDCBridge -->|on-chain data| FDC

    DOCS -.->|guides & specs| DEP
    DOCS -.->|interfaces| AM

    %% Click Events
    click AM "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/assetManager"
    click DMD "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/diamond"
    click FAT "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/fassetToken"
    click FDC "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/fdc"
    click GOV "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/governance"
    click OZ "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/openzeppelin"
    click UI "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/userInterfaces"
    click SU "https://github.com/flare-labs-ltd/fassets/tree/main/contracts/utils"
    click DEP "https://github.com/flare-labs-ltd/fassets/tree/main/deployment"
    click HHCONF "https://github.com/flare-labs-ltd/fassets/blob/main/hardhat.config.ts"
    click LIB "https://github.com/flare-labs-ltd/fassets/tree/main/lib"
    click UT "https://github.com/flare-labs-ltd/fassets/tree/main/test/unit"
    click IT "https://github.com/flare-labs-ltd/fassets/tree/main/test/integration"
    click FT "https://github.com/flare-labs-ltd/fassets/tree/main/test/fuzzing"
    click TU "https://github.com/flare-labs-ltd/fassets/tree/main/test/utils"
    click DOCS "https://github.com/flare-labs-ltd/fassets/tree/main/docs"

    %% Styles
    classDef onchain fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef offchain fill:#ABEBC6,stroke:#145A32,color:#0B5345
    classDef external fill:#FAD7A0,stroke:#B9770E,color:#6E2C00
    classDef test fill:#D5D8DC,stroke:#566573,color:#1C2833
    classDef docs fill:#F5CBA7,stroke:#B03A2E,color:#641E16
```
