# flare-foundation/fassets architecture

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

- Interactive diagram: https://gitdiagram.com/flare-foundation/fassets
- Repository: https://github.com/flare-foundation/fassets

## Overview

##### Project type and purpose
- This is a blockchain-focused system of Solidity smart contracts (FAsset) plus TypeScript orchestration and test code, designed to mint and manage synthetic assets on Flare/Songbird using collateral, decentralized price oracles (FTSO), and a cross-chain data bridge (FDC).

##### Top-level components from the file tree and README
a. On-chain “contracts” module
- contracts/diamond – the Diamond proxy and its core facets (implementation, interfaces, library, mock)
- contracts/assetManager – facets and logic for asset management (mint, redeem, collateral pooling)
- contracts/fassetToken – facets for the ERC-20 FAsset token logic (minting, checkpoints)
- contracts/governance – governance timelock & upgradeable logic
- contracts/openzeppelin & contracts/utils – shared libraries, interfaces, security utilities
b. Deployment pipelines (“deployment” directory)
- config – per-network JSON schemas and parameter files (coston, hardhat, songbird)
- cuts – diamond cut files describing facet additions/updates over time
- deploys – JSON output of past deployments
- lib – TypeScript deployment scripts (deploy-cuts.ts, link-contracts.ts, verify-fasset-contracts.ts, etc.)
- test – scripts to mock or simulate deployments in CI / staging
c. Off-chain support library (“lib” directory)
- lib/fasset – types & conversion logic (AssetManagerTypes, ChainInfo)
- lib/underlying-chain – interfaces & helpers for FDC bridge and blockchain events
- lib/actors & lib/state – simulation/test actors (Challenger, LiquidationTrigger) and state trackers for fuzzing/integration tests
- lib/utils – general helpers (file-utils, event formatting, logging)
d. Tooling & configuration
- Hardhat config (hardhat.config.ts, hardhat-tasks.config.ts)
- Scripts (flatten, makedoc, parsedoc) for code generation and documentation
- CI/CD definitions (.github/workflows, .gitlab-ci.yml, .gitpod.yml)

##### Core architectural patterns
- Diamond (EIP-2535) proxy pattern: a single proxy contract delegates calls to multiple facets (modules) for AssetManager, FAssetToken, Governance, etc.
- Modular facet structure: each business domain (mint/redeem, collateral, governance, token) is isolated in its own facet directory under contracts.
- Off-chain orchestration via TypeScript scripts (Hardhat) for deployment, upgrades, and verification.
- Testing layers: unit tests (contracts only), integration simulations (fasset-simulation), and fuzzing (actor/state modeling).

##### Relationships and data flows
- External actors (users, oracles, FDC bridge) → send transactions/events to Smart Contract Proxy on Flare/Songbird
- Proxy → dispatch to specific Facet (AssetManager, FAssetToken, Governance)
- Facets → read/write contract storage (CollateralPool, AgentVaults, Token balances)
- FTSO Oracle contracts → push price updates into price-store facet → AssetManager uses prices for collateral valuation
- FDC Bridge → posts underlying-chain payment events → AssetManager facet processes attestations for minting
- Off-chain deployment scripts → read config JSON → deploy/update Diamond and Facets (use DiamondCut JSON)
- Test Actors → inject synthetic events and simulate user operations against local Hardhat network

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% On-Chain Components
    subgraph "On-Chain (Flare/Songbird)"
        direction TB
        Proxy["Smart Contract Proxy\n(EIP-2535 Diamond)"]:::onchain
        subgraph "Facets"
            direction TB
            AM["AssetManager Facets"]:::onchain
            FTKN["FAssetToken Facets"]:::onchain
            GOV["Governance Facets"]:::onchain
            UTIL["Utility Facets"]:::onchain
        end
        Proxy --> AM
        Proxy --> FTKN
        Proxy --> GOV
        Proxy --> UTIL
        AM --> Storage
        FTKN --> Storage
        GOV --> Storage
        UTIL --> Storage
    end

    Storage["Contract Storage\n(collateral, vaults, balances)"]:::storage

    %% External Protocols
    subgraph "External Protocols"
        direction TB
        FTSO["FTSO Price Oracle"]:::external
        FDC["FDC Data Connector"]:::external
        Chains["Underlying Chains\n(XRP, BTC, DOGE)"]:::external
    end

    FTSO -->|"price updates"| AM
    FDC -->|"attestations"| AM
    Chains --> FDC

    %% Off-Chain Deploy & Tests
    subgraph "Off-Chain Deploy & Tests"
        direction TB
        Config["Deployment Config\n(JSON)"]:::offchain
        Cuts["Diamond Cuts\n(JSON)"]:::offchain
        Deploys["Historical Deploy Outputs"]:::offchain
        Scripts["TS Deployment Scripts"]:::offchain
        TestDeploy["Deployment Test Scripts & Mocks"]:::offchain
        HardhatCFG["Hardhat Config\n(.ts)"]:::offchain
        LibF["lib/fasset"]:::offchain
        LibU["lib/underlying-chain"]:::offchain
        Actors["Simulation Actors"]:::offchain
        State["State Trackers"]:::offchain
        Utils["General Utils"]:::offchain
        ScriptsDoc["Docs & Flatten\nScripts"]:::offchain
        CI["CI/CD Workflows"]:::offchain
        UT["Unit Tests"]:::offchain
        IT["Integration Tests"]:::offchain
        FZ["Fuzzing Tests & Actors"]:::offchain
    end

    Scripts --> Config
    Scripts --> Cuts
    Scripts --> Deploys
    Scripts --> HardhatCFG
    TestDeploy --> Scripts
    UT --> Proxy
    IT --> Proxy
    FZ --> Actors

    %% Click Events
    click Proxy "https://github.com/flare-foundation/fassets/tree/main/contracts/diamond"
    click AM "https://github.com/flare-foundation/fassets/tree/main/contracts/assetManager"
    click FTKN "https://github.com/flare-foundation/fassets/tree/main/contracts/fassetToken"
    click GOV "https://github.com/flare-foundation/fassets/tree/main/contracts/governance"
    click UTIL "https://github.com/flare-foundation/fassets/tree/main/contracts/utils"
    click Config "https://github.com/flare-foundation/fassets/tree/main/deployment/config"
    click Cuts "https://github.com/flare-foundation/fassets/tree/main/deployment/cuts"
    click Deploys "https://github.com/flare-foundation/fassets/tree/main/deployment/deploys"
    click Scripts "https://github.com/flare-foundation/fassets/tree/main/deployment/lib"
    click TestDeploy "https://github.com/flare-foundation/fassets/tree/main/deployment/test"
    click LibF "https://github.com/flare-foundation/fassets/tree/main/lib/fasset"
    click LibU "https://github.com/flare-foundation/fassets/tree/main/lib/underlying-chain"
    click Actors "https://github.com/flare-foundation/fassets/tree/main/lib/actors"
    click State "https://github.com/flare-foundation/fassets/tree/main/lib/state"
    click Utils "https://github.com/flare-foundation/fassets/tree/main/lib/utils"
    click HardhatCFG "https://github.com/flare-foundation/fassets/blob/main/hardhat.config.ts"
    click ScriptsDoc "https://github.com/flare-foundation/fassets/tree/main/scripts"
    click CI "https://github.com/flare-foundation/fassets/tree/main/.github/workflows"
    
    %% Styles
    classDef onchain fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef offchain fill:#E6F4EA,stroke:#22863a,color:#22863a,stroke-width:1px;
    classDef external fill:#FFF5E1,stroke:#D69F15,color:#D69F15,stroke-width:1px;
    classDef storage fill:#F0F0F0,stroke:#666,stroke-width:1px,stroke-dasharray: 4 2;
```
