Add comprehensive Flow Credit Market (FCM) documentation #1626
Conversation
This commit introduces complete documentation for Flow Credit Market (FCM), a DeFi yield platform that combines automated lending, yield farming strategies, and a synthetic stablecoin. ## Documentation Structure ### ALP (Automated Lending Platform) - 8 documents - Overview and architecture - Credit market mechanics with health factor calculations - Position lifecycle management - Automated rebalancing system - Liquidation mechanisms and safety features - MOET integration and role - DeFi Actions composability framework ### FCM (Flow Credit Market) - 4 documents - Product overview and component integration - Basics tutorial progressing from traditional lending to FCM - Technical architecture with data flow diagrams - Mathematical foundations with formulas and proofs ## Key Features - Visual mermaid diagrams throughout for clarity - Progressive learning path from basics to advanced topics - Cross-referenced sections linking related concepts - Practical examples with real-world scenarios - Mathematical formulas with step-by-step derivations - Professional narrative flow with minimal bullet points ## Content Highlights - Yield-powered liquidation prevention mechanism - Automated capital efficiency through rebalancing - Multi-component architecture (ALP + FYV + MOET) - Complete position lifecycle documentation - Security features and risk management - Integration patterns and best practices This documentation provides comprehensive coverage for users, developers, and DeFi builders looking to understand or integrate with FCM.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
- Replace non-existent flow-yield-vaults and moet directory links with placeholders
- Remove \text{} LaTeX commands causing acorn parsing errors in math.md
- All formulas now use plain text variables instead of \text{} wrapper
- Replace broken links: capital-flows.md, risk-management.md, integration.md - Convert all $$ LaTeX blocks to ```math code blocks for MDX compatibility - Remove LaTeX \sum and \in operators causing acorn parsing errors - Use plain mathematical notation instead of LaTeX commands
- Convert LaTeX math operators to Unicode equivalents (× ÷ ≤ ≥ ≈)
- Replace \frac{a}{b} with (a / b) notation
- Simplify subscripts from _{text} to _text
- Fix misaligned code block markers throughout document
- Remove all remaining LaTeX that causes MDX parsing errors
0xLisanAlGaib
requested review from
Aliserag,
bz-hashtag-0780,
githubwei and
vishalchangrani
|
Instead of FCM as the sidebar title, I think having 'Flow Credit Market (FCM)' for discoverability would be more useful. I think it would also help a bit with LLMs. |
Updated basics.md: - Converted bullet points to paragraphs for better readability - Added diagram styling to highlight key components - Added explanations for TracerStrategy and AutoBalancer - Enhanced composability section Updated math.md: - Fixed liquidation formulas with complete implementation details - Corrected collateral seizure calculations - Added proper debt ratio vs leverage distinction - Fixed mathematical notation and formatting issues - Improved formula parenthesis handling for clarity
Created complete FYV documentation with 9 files covering: - Core concepts: architecture, strategies, AutoBalancer, vault lifecycle - Advanced features: leveraged farming, scheduling system, cross-chain integration - Composability: DeFi Actions framework Documentation follows same structure and quality as ALP and FCM docs.
|
|
||
| **5. Liquidation**: User closes vault, strategy liquidates all positions (closes ALP position for leveraged strategies), converts all value to collateral, and returns final value to user. | ||
|
|
||
| ## Best Practices |
There was a problem hiding this comment.
Who are these best practices for? Users of apps that leverage it?
|
|
||
| Despite atomicity guarantees, vaults can become stuck for several reasons: | ||
|
|
||
| 1. **Transaction failure** during reschedule due to gas issues or network congestion |
There was a problem hiding this comment.
It's not super clear who pays for gas with the rescheduling or if you need to fund an account that sponsors the txns indefinitely
|
|
||
| ## mUSDCStrategy: Cross-Chain Yield Farming | ||
|
|
||
| The mUSDCStrategy leverages the EVM bridge to access Ethereum-compatible ERC4626 yield vaults. |
There was a problem hiding this comment.
Ahh, it's much clearer here than the previous reference I commented on. It's just using the Cross-VM bridge, the other doc I already left a comment on made it seem like it was going to a different chain that was EVM. I would change these references to Cross-VM instead of cross-chain if I'm understanding this piece correctly.
|
|
||
| ### Mitigation Strategies | ||
|
|
||
| **Bridge Audits**: Use only audited, established bridge infrastructure and verify escrow contract security. |
There was a problem hiding this comment.
Not sure if this is a good one to highlight because there is only one cross-VM bridge and we created it.
| @@ -0,0 +1,440 @@ | |||
| --- | |||
| title: DeFi Actions | |||
There was a problem hiding this comment.
Perhaps we should rename this to FYV DeFi actions because we already have a Flow Actions section of the docs
- Replace technical sequence diagrams with intuitive flow diagrams in architecture.md - Add clear asset flow visualization for deposit/auto-borrow and price drop recovery - Convert mermaid diagrams to tables and bullet points for better readability - Fix LaTeX math formulas (health factor, utilization, reserve factor) - Clarify MOET as primary debt token and unit of account - Add time-weighted fairness explanation for interest accrual - Update DeFi Actions section with link to Flow Actions documentation - Condense verbose sections into concise paragraphs - Fix incorrect borrowing capacity calculations in examples - Add security architecture explanation for fund protection
Added new MOET documentation section: - Basic concepts and role in FCM ecosystem - Tokenomics and supply mechanics - Stability mechanisms and peg maintenance - Integration guide for developers Updated existing documentation: - Refined ALP index page structure - Updated MOET role explanations in ALP docs - Improved FCM index page clarity
Remove anchor fragment from DeFi Actions PriceOracle link to resolve build error
|
|
||
| # High-Precision Fixed-Point 128 Bit Math | ||
|
|
||
| Dealing with decimals is a notorious issue for most developers on other chains, especially when working with DeFi. Blockchains are deterministic systems and floating-point arithmetic is non-deterministic across different compilers and architectures, this is why blockchains use fixed-point arithmetic via integers (scaling numbers by a fixed factor). The issue with this is that these fixed-point integers tend to be very imprecise when using various mathematical operations on them. The more operations you apply to these numbers, the more imprecise these numbers become. However [`DeFiActionsMathUtils`] provides a standardized library for high-precision mathematical operations in DeFi applications on Flow. The contract extends Cadence's native 8-decimal precision (`UFix64`) to 24 decimals using `UInt128` for intermediate calculations, ensuring accuracy in complex financial computations while maintaining deterministic results across the network. |
There was a problem hiding this comment.
I do not like the wording of the start of this paragraph. It is confrontational and belitelling in my eyes. Can we rewrite it? Or just remove "on other chains".
|
|
||
| ## The Solution: 24-Decimal Precision | ||
|
|
||
| [`DeFiActionsMathUtils`] solves this by using `UInt128` to represent fixed-point numbers with 24 decimal places (scaling factor of 10^24). This provides 16 additional decimal places for intermediate calculations, dramatically reducing precision loss. |
There was a problem hiding this comment.
Why is the contract called DefiActionMathsUtils and not BigInt or something? The fact that it is used in DefiActions is not really that relevant for all use cases is it?
There was a problem hiding this comment.
There is also FlowALPMath and FlowCreditMarketMath. Would it not be better to have utility math functions centralized one place?
| ### Flash Loan Integration | ||
| Use ALP with flash loans for arbitrage opportunities (advanced). | ||
|
|
||
| See [GitHub examples](https://github.com/onflow/FlowCreditMarket/tree/main/examples) for code samples. |
|
|
||
| ```cadence | ||
| transaction createVault() { | ||
| prepare(signer: AuthAccount) { |
| ```cadence | ||
| import FlowYieldVaults from 0xFlowYieldVaults | ||
|
|
||
| pub fun main(vaultID: UInt64): UFix64 { |
There was a problem hiding this comment.
Seems produced by AI.
| ### Check Vault Schedule Status | ||
|
|
||
| ```cadence | ||
| import FlowYieldVaultsSchedulerRegistry from 0xFYV |
There was a problem hiding this comment.
old import syntax. old cadence syntax.
| All strategies implement the `Strategy` interface, which provides a consistent API regardless of the underlying yield mechanism. | ||
|
|
||
| ```cadence | ||
| pub resource interface Strategy { |
There was a problem hiding this comment.
old cadence syntax, not going to repeat the comment for this file.
| # Output: 1055.62 FLOW | ||
|
|
||
| # Liquidate and withdraw | ||
| flow transactions send liquidate-vault.cdc 42 |
There was a problem hiding this comment.
should these examples not include the network argument?
|
|
||
| ```cadence | ||
| // ALP borrows MOET for user | ||
| pub fun borrow(amount: UFix64): @MOET.Vault { |
| pub event TokensMinted(amount: UFix64, positionID: UInt64, mintedBy: Address) | ||
|
|
||
| // Emitted when MOET is burned | ||
| pub event TokensBurned(amount: UFix64, burnedFrom: UInt64) |
There was a problem hiding this comment.
should this burnedFrom be UInt64? should it not be address? or?
|
I tried to build this and host it locally using the instructions in readme but the formating is off for mermaid, it does not show the diagrams but the syntax. |
|
Would suggest using classes in mermaid and global style configuration for those classes, mermaid has many nice themes with some built in stuff. If not showing this good in white and dark mode would be very hard. |
|
|
||
| **Key Characteristics:** | ||
|
|
||
| - **Synthetic Stablecoin**: Designed to maintain a 1:1 peg with USD through over-collateralization |
There was a problem hiding this comment.
##
To the best of my understanding pegging Moet to USD is no longer a goal. There are overall concerns whether it is even tractable to peg a collateral-backed stablecoin to an external asset X (here USD), unless the entire basket of backing assets is just comprised of asset X.
suggested framing:
Essentially Moet is pegged to the underlying basket of assets backing it. Mathematically, the value of a Moet token is the geometric average of the assets backing Moet (times some constant scaling factor essentially determining the ratio of token supply to total backing assets) [reference: docs.balancer.fi/whitepaper.pdf]
There was a problem hiding this comment.
Only reviewed a few documents that were relevant to what I am working on right now. Noticed:
-
The framing that MOET is pegged to 1USD is very prevalent in the document. But based on my understanding, we no longer aim for a $1 peg. This is because it might be intractable to peg a stablecoin to asset X if the stablecoin is backed by assets other than X. This hasn't been proven, but to the best of my knowledge, all attempts to do so have either failed already or a known to de-peg under edge-case scenarios.
- I have commented on a variety of occurrences, but there are probably more in the various docs that I have not read. The mention of a $1 peg should be removed from all documents.
- Formally, the price of MOET is the geometric weighted average of the backing assets (for a constant product market maker, which we are planning to use). Some of the examples might (not sure) need to be reframed in terms of Moet's value being the geometric mean. Calculations are straight forward but not trivial.
-
We want readers of these documents to stay engaged and be able to access the technical contents in the docs easily. Introducing the meaning of abbreviations in each document they are used is very good practise. Otherwise, we risk loosing the readers, because the details are confusing to them and they don't want to invest the effort into going hunting and searching what abbreviations mean.
-
prevalent examples
HF,CF -
wording suggestion (example).
In the following, we denote the Health Factor by
HFand the collateral factor byCF.Ideally, we would also include a reference to a good explanation of what HF and CF are, so we make accessing the technical contents as low friction as possible for the user.
-
| Every MOET token is backed by collateral worth significantly more than $1: | ||
|
|
||
| ``` | ||
| Example Position: | ||
| ├── Collateral: 1000 FLOW @ $1.00 = $1,000 | ||
| ├── Collateral Factor: 0.8 (80%) | ||
| ├── Effective Collateral: $800 | ||
| ├── Target Health: 1.3 | ||
| ├── Max Borrow: $800 / 1.3 = 615.38 MOET | ||
| └── Collateralization Ratio: $1,000 / $615.38 = 162.5% | ||
| ``` |
There was a problem hiding this comment.
Every MOET token is backed by collateral worth significantly more than $1:
should be rephrased / reframed. Mentioning $1 here only really makes sense in my opinion, if we are considering Moet being pegged to 1 USD. But since that is not the case, I think this needs to be reworded. Moet could be worth significantly less than 1USD but still overcollateralized.
| Every MOET token is backed by collateral worth significantly more than $1: | |
| ``` | |
| Example Position: | |
| ├── Collateral: 1000 FLOW @ $1.00 = $1,000 | |
| ├── Collateral Factor: 0.8 (80%) | |
| ├── Effective Collateral: $800 | |
| ├── Target Health: 1.3 | |
| ├── Max Borrow: $800 / 1.3 = 615.38 MOET | |
| └── Collateralization Ratio: $1,000 / $615.38 = 162.5% | |
| ``` | |
| Every MOET token is backed by collateral worth significantly more than MOET's market price, as the following example illustrates. | |
| ```text | |
| Example Position: | |
| ├── Collateral: 1000 FLOW @ $1.00 = $1,000 | |
| ├── Collateral Factor: 0.8 (80%) | |
| ├── Effective Collateral: $800 | |
| ├── Target Health: 1.3 | |
| ├── Max Borrow: $800 / 1.3 = $615.38 | |
| ├── MOET denominates the amount of debt backed by the collateral, i.e. maximally: $615.38 | |
| └── Collateralization Ratio: $1,000 / $615.38 = 162.5% |
There was a problem hiding this comment.
Moet could be worth significantly less than 1USD but still overcollateralized.
@AlexHentschel I think this is technically true ( as it is coming from from you ), but rings very wrong to my ears.
Can you give an example ? It feels like socializing losses, which is kind of strange from user perspective. Like if I put BTC, got MOET. BTC stayed flat, why my borrowing power will decrease if some XYZ coin crashed ?
If I will pay with MOET to unlock my collateral ( like same amount of MOET initially minted ), then paying unlocking and re-borrowing will increase my MOET ?
maybe I am looking from wrong perspective, but I feel it should self balance somehow.
| - **Debt Tracking**: MOET supply metrics reveal total system leverage and borrowing activity | ||
| - **Collateralization Analysis**: MOET/collateral ratios indicate system health and liquidation risks | ||
| - **Capital Efficiency**: MOET enables borrowed capital to immediately generate yield, improving returns | ||
| - **Systemic Risk**: MOET peg stability is crucial - depeg scenarios could trigger cascading liquidations |
There was a problem hiding this comment.
| - **Contract Name**: MOET | ||
| - **Standard**: Flow FungibleToken + FungibleTokenMetadataViews | ||
| - **Symbol**: MOET | ||
| - **Full Name**: FlowCreditMarket USD |
There was a problem hiding this comment.
|
|
||
| ### Over-Collateralization | ||
|
|
||
| Every MOET is backed by collateral worth significantly more than $1. |
There was a problem hiding this comment.
The only peg we can / want to maintain is the peg of Moet to the geometric weighted average of all backing assets.
| If MOET trades away from $1, arbitrage opportunities arise: | ||
|
|
||
| **MOET Trading Above $1 (e.g., $1.05):** | ||
|
|
||
| ``` | ||
| Arbitrage Strategy: | ||
| 1. Deposit $1,625 of FLOW collateral | ||
| 2. Borrow 1,000 MOET (valued at $1,000) | ||
| 3. Sell 1,000 MOET for: $1,050 (at $1.05 market price) | ||
| 4. Profit: $1,050 - $1,000 = $50 | ||
| 5. Result: Increased MOET supply pushes price down toward $1 | ||
| ``` | ||
|
|
||
| **MOET Trading Below $1 (e.g., $0.95):** | ||
|
|
||
| ``` | ||
| Arbitrage Strategy: | ||
| 1. Buy 1,000 MOET for: $950 (at $0.95 market price) | ||
| 2. Repay $1,000 MOET debt (valued at $1,000) | ||
| 3. Saved: $1,000 - $950 = $50 on repayment | ||
| 4. Withdraw collateral (now unlocked) | ||
| 5. Result: Increased MOET demand pushes price up toward $1 | ||
| ``` | ||
|
|
||
| **Key Principle**: Market participants profit from deviations, naturally stabilizing MOET around $1. |
There was a problem hiding this comment.
This probably needs to be redone discussing the peg of Moet to the geometric weighted average of all backing assets.
|
|
||
| ## MOET as Unit of Account | ||
|
|
||
| All prices in FCM are denominated in MOET, creating a consistent pricing framework: |
There was a problem hiding this comment.
| All prices in FCM are denominated in MOET, creating a consistent pricing framework: | |
| All prices in FCM are denominated in MOET, creating a consistent pricing framework (assuming a MOET price of $1 for simplicity): |
|
|
||
| 2. **Mint-and-Burn Model**: Supply dynamically adjusts with borrowing activity (mint on borrow, burn on repay) | ||
|
|
||
| 3. **Over-Collateralization**: Typical 162.5% backing provides substantial safety margin |
There was a problem hiding this comment.
This only holds true for volatile assets. If backed by stable coins, the overcollateralization will be marginal.
| 3. **Over-Collateralization**: Typical 162.5% backing provides substantial safety margin | |
| 3. **Over-Collateralization**: Typical 162.5% backing for volatile collateral assets provides substantial safety margins |
|
|
||
| 6. **Liquidation Creates Demand**: Profitable liquidations incentivize MOET accumulation | ||
|
|
||
| 7. **Arbitrage Maintains Peg**: Deviations from $1 create profit opportunities that naturally stabilize price |
There was a problem hiding this comment.
The only peg we can / want to maintain is the peg of Moet to the geometric weighted average of all backing assets.
Overview
This PR introduces comprehensive documentation for Flow Credit Market (FCM), a DeFi yield platform that combines automated lending, yield farming strategies, and a synthetic stablecoin.
Documentation Structure
ALP (Automated Lending Platform) - 8 documents
FCM (Flow Credit Market) - 4 documents
Key Features
✅ Visual Documentation - Extensive mermaid diagrams for clarity and understanding
✅ Progressive Learning - Structured path from basics to advanced topics
✅ Cross-Referenced - Links connecting related concepts across documents
✅ Practical Examples - Real-world scenarios with concrete numbers
✅ Mathematical Rigor - Step-by-step formula derivations
✅ Professional Writing - Clear narrative flow optimized for readability
Content Highlights
Documentation Quality
Target Audience
Testing