From 1fd1e4b01d0eb8ccef196c25cdbbb1bcf111a028 Mon Sep 17 00:00:00 2001 From: Alex Hentschel Date: Thu, 19 Mar 2026 17:35:21 -0700 Subject: [PATCH 1/3] initial AI draft --- docs/adr/User-Balance_in_Earn_product.md | 81 ++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 docs/adr/User-Balance_in_Earn_product.md diff --git a/docs/adr/User-Balance_in_Earn_product.md b/docs/adr/User-Balance_in_Earn_product.md new file mode 100644 index 00000000..a3a31141 --- /dev/null +++ b/docs/adr/User-Balance_in_Earn_product.md @@ -0,0 +1,81 @@ +# Displayed to the User in `Earn` Product + +**Status**: Proposed +**Date**: 2026-02-19 +**Authors**: Alex Hentschel, Dete Shirley +**Component**: Flow Earn + +### References +[Slack discussion](https://flow-foundation.slack.com/archives/C08QF29F7TK/p1771567751505249?thread_ts=1771355840.068079&cid=C08QF29F7TK) and +[Q&A meeting notes from Feb 19, 2026](https://docs.google.com/document/d/1npAwIq1W-EU7S7c2sX17zMdZffu5mr06DD6krBkvTFo/edit?usp=sharing) + +## Context + +Flow's Automated Lending Protocol [ALP] and Flow Earn (the yield-source management component built on top of ALP) need to display position balances to users. At maturity, ALP will support positions with **multiple collateral types and multiple borrowed assets**. However, the current Flow Earn implementation only supports a **single collateral type and single yield type per position**. + +The question is: what balance should Earn display to the user, and how should the underlying price be determined? + +## Decision + +### 1. Balance formula for Earn + +The balance displayed to a user in Flow Earn is: + +``` +Balance = CT + (YV - CD) / CP +``` + +Where: +- **CT** = Count of collateral tokens held +- **YV** = Value of yield tokens (denominated in MOET) +- **CD** = Current debt amount (denominated in MOET) +- **CP** = Current price of collateral tokens (denominated in MOET) + +Note: `CD` can exceed `YV`, making the second term negative. The result represents the user's net position denominated in collateral tokens. + +### 2. Price source: spot price + +For `CP`, use the **spot price** of the collateral token. This is the simpler approach and aligns with how most brokerages and crypto trading platforms report asset values. + +The displayed balance must be clearly labeled to indicate it is an **estimate based on spot prices** and does not account for slippage that would occur if the user unwound their position. + +### 3. Scope: Earn only + +This formula and display logic apply **only to Flow Earn**. ALP itself does not need to display converted balances to users at this time — ALP balances would simply show deposited and borrowed amounts without conversion. + +### 4. ALP: anticipate multi-asset positions + +Engineers should **anticipate** (but not yet fully implement) support for positions with multiple collateral types and multiple borrowed assets in ALP's design. Since Earn only deals with a single collateral and single yield type per position, no proportional distribution of `(YV - CD)` across different asset types is needed now. + +## Rationale + +1. **Simplicity.** Spot price is the simplest computation to implement. Dete's guidance was to implement whichever approach is easiest, as long as it is clearly communicated to the user. +2. **User familiarity.** Spot-price-based balances match the convention used by most existing finance platforms and crypto exchanges. Users expect this presentation. +3. **Transparency over precision.** Rather than showing an "exit value" (which would be pessimistic for large positions due to slippage), showing spot price with a clear disclaimer is more straightforward. Users with large positions would otherwise see an unnecessarily deflated balance. +4. **Single-asset simplification.** Since Earn only supports one collateral type and one yield type per position, the formula is straightforward — no multi-asset weighting or proportional distribution is required. + +## Alternatives Considered + +### Exit-value-based pricing + +Instead of spot price, compute `CP` as a quote for fully unwinding the user's Earn position (i.e., accounting for slippage). + +- **Pro:** More accurate reflection of what the user would actually receive upon exit. +- **Con:** Pessimistic for large positions — slippage from a hypothetical full unwind in a single transaction would understate the position's value. +- **Con:** More complex to compute (requires simulating a full unwind against the AMM). +- **Con:** Departs from the convention used by most finance platforms. + +If this approach were chosen, the displayed value should be labeled as "current exit value" to set correct user expectations. + +Either approach is acceptable per Dete's guidance, as long as the methodology is clearly documented and communicated to the user. + +## Implementation Notes + +- **Clear labeling:** The UI and documentation must state that the Earn balance is an estimate based on spot prices and does not account for slippage. +- **Negative balances:** Handle the case where `CD > YV` gracefully — the second term becomes negative, reducing the displayed balance below `CT`. +- **Future multi-asset support:** ALP's data model should be designed to accommodate multiple collateral and debt types per position, even though Earn will only use single-type positions initially. + +## User Impact + +- **Earn users** will see a single consolidated balance denominated in their collateral token, providing a clear view of their net position value. +- **Large position holders** should be aware that the displayed balance is based on spot prices and may not reflect the exact amount receivable upon full withdrawal (due to slippage). From 1636fecff6c23aff676cb47677fc0625e03fc7b8 Mon Sep 17 00:00:00 2001 From: Alex Hentschel Date: Thu, 19 Mar 2026 20:31:40 -0700 Subject: [PATCH 2/3] =?UTF-8?q?ARD:=20User=20balances=20displayed=20in=20E?= =?UTF-8?q?ARN=20product=20=E2=80=A2=20first=20complete=20version?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/adr/User-Balance_in_Earn_product.md | 58 +++++++++++++++--------- 1 file changed, 37 insertions(+), 21 deletions(-) diff --git a/docs/adr/User-Balance_in_Earn_product.md b/docs/adr/User-Balance_in_Earn_product.md index a3a31141..e8579126 100644 --- a/docs/adr/User-Balance_in_Earn_product.md +++ b/docs/adr/User-Balance_in_Earn_product.md @@ -1,9 +1,9 @@ -# Displayed to the User in `Earn` Product +# User Balance Displayed in the EARN Product **Status**: Proposed -**Date**: 2026-02-19 +**Date**: 2026-02-19 **Authors**: Alex Hentschel, Dete Shirley -**Component**: Flow Earn +**Component**: Flow EARN ### References [Slack discussion](https://flow-foundation.slack.com/archives/C08QF29F7TK/p1771567751505249?thread_ts=1771355840.068079&cid=C08QF29F7TK) and @@ -11,15 +11,15 @@ ## Context -Flow's Automated Lending Protocol [ALP] and Flow Earn (the yield-source management component built on top of ALP) need to display position balances to users. At maturity, ALP will support positions with **multiple collateral types and multiple borrowed assets**. However, the current Flow Earn implementation only supports a **single collateral type and single yield type per position**. +Flow's Automated Lending Protocol [ALP] and Flow EARN (the yield-source management component built on top of ALP) need to display position balances to users. At maturity, ALP will support positions with **multiple collateral types and multiple borrowed assets**. However, the current Flow EARN implementation only supports a **single collateral type and single yield type per position**. -The question is: what balance should Earn display to the user, and how should the underlying price be determined? +The question is: what balance should EARN display to the user, and how should the underlying price be determined? ## Decision -### 1. Balance formula for Earn +### 1. Balance formula for EARN -The balance displayed to a user in Flow Earn is: +The balance displayed to a user in Flow EARN is: ``` Balance = CT + (YV - CD) / CP @@ -35,30 +35,37 @@ Note: `CD` can exceed `YV`, making the second term negative. The result represen ### 2. Price source: spot price -For `CP`, use the **spot price** of the collateral token. This is the simpler approach and aligns with how most brokerages and crypto trading platforms report asset values. +For `CP`, use the **spot price** of the collateral token. This was confirmed in the Q&A meeting (2026-02-19) and aligns with how most conventional brokerages and crypto trading platforms report asset values. The displayed balance must be clearly labeled to indicate it is an **estimate based on spot prices** and does not account for slippage that would occur if the user unwound their position. -### 3. Scope: Earn only +### 3. Scope: EARN Product only -This formula and display logic apply **only to Flow Earn**. ALP itself does not need to display converted balances to users at this time — ALP balances would simply show deposited and borrowed amounts without conversion. +This formula and display logic apply **only to Flow's EARN product**. ALP itself does not need to present converted balances to users for the time being. ### 4. ALP: anticipate multi-asset positions -Engineers should **anticipate** (but not yet fully implement) support for positions with multiple collateral types and multiple borrowed assets in ALP's design. Since Earn only deals with a single collateral and single yield type per position, no proportional distribution of `(YV - CD)` across different asset types is needed now. +Engineers should **anticipate** (but not yet fully implement) support for positions with multiple collateral types and multiple borrowed assets in ALP's design. -## Rationale +_Outlook on ALP reporting user balances:_ +0. ALP reporting user balances is likely not needed at all _for the initial version of FCM_, as users interact with the EARN product rather than ALP directly. +1. The most universal approach for ALP would be to report a user's position as a list of their collateral and debt amounts in their native tokens, without converting to a single denomination. This is simpler to implement and avoids the complexities of multi-asset valuation. +2. If unified representations are desired for ALP in the future, they can be built on top of the aforementioned per-token report. + + + +## Alternatives Considered, Rationale for Chosen Approach & Conclusions + +### Using spot price for user balances in EARN (chosen approach) 1. **Simplicity.** Spot price is the simplest computation to implement. Dete's guidance was to implement whichever approach is easiest, as long as it is clearly communicated to the user. 2. **User familiarity.** Spot-price-based balances match the convention used by most existing finance platforms and crypto exchanges. Users expect this presentation. 3. **Transparency over precision.** Rather than showing an "exit value" (which would be pessimistic for large positions due to slippage), showing spot price with a clear disclaimer is more straightforward. Users with large positions would otherwise see an unnecessarily deflated balance. -4. **Single-asset simplification.** Since Earn only supports one collateral type and one yield type per position, the formula is straightforward — no multi-asset weighting or proportional distribution is required. - -## Alternatives Considered +4. **Single-asset simplification.** Since EARN only supports one collateral type and one yield type per position, the formula is straightforward — no multi-asset weighting or proportional distribution is required. -### Exit-value-based pricing +### Alternative: Exit-value-based pricing -Instead of spot price, compute `CP` as a quote for fully unwinding the user's Earn position (i.e., accounting for slippage). +Instead of spot price, compute `CP` as a quote for fully unwinding the user's EARN position (i.e., accounting for slippage). - **Pro:** More accurate reflection of what the user would actually receive upon exit. - **Con:** Pessimistic for large positions — slippage from a hypothetical full unwind in a single transaction would understate the position's value. @@ -67,15 +74,24 @@ Instead of spot price, compute `CP` as a quote for fully unwinding the user's Ea If this approach were chosen, the displayed value should be labeled as "current exit value" to set correct user expectations. -Either approach is acceptable per Dete's guidance, as long as the methodology is clearly documented and communicated to the user. + +### Conclusion + +Either approach would be acceptable per Dete's guidance, as long as the methodology is clearly documented and communicated to the user. The prevalent market standard is to use spot prices, and there is no reason to deviate from that established convention in EARN. + +In addition, the following practical and product considerations further support the spot price approach: Slippage depends heavily on market conditions and the user's strategy for unwinding (e.g., breaking into multiple transactions vs. a single transaction). Estimating the exit value of larger positions — which would incur significant slippage when unwound — is therefore highly challenging. If we assumed the position was unwound in a single trade, we would report potentially over-pessimistic values, hurting the user's perception of FCM's performance. In practice, users with large positions generally intend to unwind gradually to minimize slippage losses, so the spot price probably better reflects the exit value they are planning for. For small positions where slippage is negligible, the spot price directly provides a reasonable estimate of the position's value. + + + ## Implementation Notes -- **Clear labeling:** The UI and documentation must state that the Earn balance is an estimate based on spot prices and does not account for slippage. +- **Clear labeling:** The UI and documentation must state that the EARN balance is an estimate based on spot prices and does not account for slippage. - **Negative balances:** Handle the case where `CD > YV` gracefully — the second term becomes negative, reducing the displayed balance below `CT`. -- **Future multi-asset support:** ALP's data model should be designed to accommodate multiple collateral and debt types per position, even though Earn will only use single-type positions initially. +- **Future multi-asset support:** ALP's data model should be designed to accommodate multiple collateral and debt types per position, even though EARN will only use single-type positions for the time being. +- **CP availability:** An open question was raised during the Q&A: whether the current price of collateral denominated in MOET (`CP`) is reliably available on every block. This needs to be confirmed during implementation. ## User Impact -- **Earn users** will see a single consolidated balance denominated in their collateral token, providing a clear view of their net position value. +- **EARN users** will see a single consolidated balance denominated in their collateral token, providing a clear view of their net position value. - **Large position holders** should be aware that the displayed balance is based on spot prices and may not reflect the exact amount receivable upon full withdrawal (due to slippage). From 6bde638dfd5f8616fa53cd48587fde50257b3cba Mon Sep 17 00:00:00 2001 From: Alex Hentschel Date: Thu, 19 Mar 2026 20:47:42 -0700 Subject: [PATCH 3/3] link fix and clarifying EARN's "one-asset" limitations --- docs/adr/User-Balance_in_Earn_product.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/adr/User-Balance_in_Earn_product.md b/docs/adr/User-Balance_in_Earn_product.md index e8579126..6662c8ae 100644 --- a/docs/adr/User-Balance_in_Earn_product.md +++ b/docs/adr/User-Balance_in_Earn_product.md @@ -7,11 +7,11 @@ ### References [Slack discussion](https://flow-foundation.slack.com/archives/C08QF29F7TK/p1771567751505249?thread_ts=1771355840.068079&cid=C08QF29F7TK) and -[Q&A meeting notes from Feb 19, 2026](https://docs.google.com/document/d/1npAwIq1W-EU7S7c2sX17zMdZffu5mr06DD6krBkvTFo/edit?usp=sharing) +[Q&A meeting notes from Feb 19, 2026](https://docs.google.com/document/d/1jGj-ypjLO1Uo2ZPL4xtRyRlMAdbW4THozGc2i3z6TAc/edit?tab=t.buc00sqsnehk) ## Context -Flow's Automated Lending Protocol [ALP] and Flow EARN (the yield-source management component built on top of ALP) need to display position balances to users. At maturity, ALP will support positions with **multiple collateral types and multiple borrowed assets**. However, the current Flow EARN implementation only supports a **single collateral type and single yield type per position**. +Flow's Automated Lending Protocol [ALP] and Flow EARN (the yield-source management component built on top of ALP) need to display position balances to users. At maturity, ALP will support positions with **multiple collateral types and multiple borrowed assets**. However, a single EARN position only supports a **single collateral type and single yield type** for the time being. Users can still utilize EARN with different supported collaterals by opening independent positions, each of which is managed separately. The question is: what balance should EARN display to the user, and how should the underlying price be determined?