How flare-foundation/fassets works
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