single debt and collateral per position by nialexsan · Pull Request #184 · onflow/FlowALP

nialexsan · 2026-02-27T16:34:52Z

Closes: #???

Description

support borrowing tokens from the protocol reserves, not just minting MOET
temporary limitations:

one position supports one type of collateral and one type of debt
this limitation is required to simplify rebalancing, closing position logic, and liquidations, otherwise the rebalancer would need to decide which tokens to move first.
There are multiple ways to implement this logic:

Which debt to repay first when deleveraging?

high interest rate
high liquidation penalty / hard-to-repay
high volatility relative to collateral
large share of total borrow

Which collateral to sell first to fund repay?

lowest liquidation threshold contribution per $ (i.e. “worst LT efficiency”)
lowest yield / least strategic
most liquid / lowest slippage

For contributor use:

Targeted PR against master branch
Linked to Github issue with discussion and accepted design OR link to spec that describes this work.
Code follows the standards mentioned here.
Updated relevant documentation
Re-reviewed Files changed in the Github PR explorer
Added appropriate labels

cadence/contracts/FlowALPv0.cdc

jordanschalm

Are you sure about limiting positions to one collateral/debt type? It seems a big change from the current implementation, which is built around the idea that a position can contain multiple collateral/debt balances (eg. using a map for balances field, queuedDeposits).

If we do really want to make Position limited to one collateral/debt balance, I think there are more targeted ways to accomplish this:

add a collateralType/debtType field to Position
replace balances with collateralBalance, debtBalance
make queuedDeposits just a vault

jordanschalm · 2026-02-27T17:58:25Z

cadence/contracts/FlowALPv0.cdc

+                // MOET cannot be seized as collateral (it should never exist as collateral)
+                if seizeType == Type<@MOET.Vault>() {
+                    panic("Cannot seize MOET as collateral. MOET should not exist as collateral in any position.")
+                }


Are you sure it is the desired behaviour, that MOET cannot be used as collateral?

@dete do we want to allow MOET as a collateral?
It creates a vulnerability for the protocol, since MOET is a fully synthetic token and not directly backed by any stable coin.

Yes, MOET should be allowed as collateral. Of course, you can't borrow MOET against MOET, so we're not creating a "stack of turtles" here. If you try to "withdraw" MOET when you have a MOET balance, you just draw down your collateral.

Note that it's the lending protocol itself that makes MOET safe, so it's not unreasonable for the lending protocol to assume that its safe (so long as MOET isn't backed by MOET, which we will never allow).

Like other assets, there should be deposit interest on MOET collateral (which is always < the borrow interest on the same asset). Note that since all MOET is created by borrowing, and all borrowed MOET pays interest, the interest we pay on MOET deposits are always less than the MOET we earn by charging interest on debts. So, you can think of the interest we pay on MOET deposits as passing directly through the protocol from the original borrower to the current holder.

Critically: We don't allow USDC or PyUSD0 or any other stables to be deposited as collateral. So folks will have to "swap into" MOET if they want to have USD-denominated collateral. (Again, this has been modelled and is HEALTHY for the protocol, not risky.)

Thanks for being cautious, Alex! But this is part of the design and included in our stability analysis. 🙇

nialexsan · 2026-02-27T18:46:04Z

@jordanschalm this is a soft limitation until we figure out how to do rebalancing and position closing with multiple collaterals and debts.
there are multiple ways of how to do rebalancing of multi token positions, but currently I don't know which one is more suited for our platform

jordanschalm · 2026-03-03T18:25:00Z

Hey @nialexsan, should this be targeting nialexsan/pre-refactor instead of main?

zhangchiqing

LGTM, some minor suggestions

zhangchiqing · 2026-03-03T20:04:30Z

cadence/contracts/FlowALPv0.cdc

+            let positionBalance = position.getBalance(seizeType)
+            if positionBalance == nil {
+                // Liquidation is seizing collateral - validate single collateral type
+                position.validateCollateralType(seizeType)


I noticed the validation is always done before setBalance, does it make sense to simply add the validation to setBalance? That way, we don't need to add it everywhere.

by Jordan's suggestion I moved the check to post condition

zhangchiqing · 2026-03-03T20:18:44Z

cadence/contracts/FlowALPv0.cdc

+            // Re-fetch balance to check if direction changed
+            positionBalance = position.getBalance(type)
+            if wasCredit && positionBalance!.direction == FlowALPModels.BalanceDirection.Debit {
+                position.validateDebtType(type)


could we validate before the recordWithdrawal? So that instead of returning the error message "Internal error, Position has multiple debt types", which is confusing, we could provide better error message, saying "Position already has debt type X. Cannot borrow Y"

if currentBalance.direction == Credit && currentBalance.wouldFlipToDebit(amount, tokenState) { position.validateDebtType(type) } position.borrowBalance(type)!.recordWithdrawal(...)

Follow-up for this validation-order path is in PR #200:
We now validate debt type before recordWithdrawal on credit->debit flip flows, so invalid attempts fail with the intended domain error instead of the internal invariant assert.

cadence/contracts/FlowALPv0.cdc

jordanschalm · 2026-03-03T21:30:51Z

cadence/contracts/FlowALPv0.cdc

            let seizeState = self._borrowUpdatedTokenState(type: seizeType)
-            if position.getBalance(seizeType) == nil {
+            let positionBalance = position.getBalance(seizeType)
+            if positionBalance == nil {


Same here: it doesn't make sense to seize collateral from a position which does not have a balance for that collateral type, so we should remove the nil check and let it panic.

jordanschalm · 2026-03-04T00:20:37Z

cadence/contracts/FlowALPModels.cdc

        /// If nil, the Pool will not pull underflown value, and liquidation may occur.
        access(EImplementation) fun setTopUpSource(_ source: {DeFiActions.Source}?)
+
+        /// Returns the current collateral types for this position based on existing Credit balances


The current implementation injects checks in all places where we might add/remove a debt/collateral balance, and uses the validate* functions below to guard against adding more balances than we want to support.

I am wondering if we can use post-conditions and these getCollateralTypes functions to simplify this new logic and localize the temporary balance constraint to a smaller cross-section of the code. For example, if we added something like the following post-conditions to all functions which are able to modify position balances:

// we can localize the temporary constraint to one validation function, and document the reasoning behind it here fun positionSatisfiesTemporaryBalanceConstraint(pid): Bool { return getCollateralTypes(pid) <= 1 && getDebtTypes(pid) <= 1 } // then, in functions which might violate the constraint, we can add a post-condition post { self.positionSatisfiesTemporaryBalanceConstraint(pid): "..." }

This way, we don't need to make any modifications to the business logic of affected functions, we just let them execute as normal and revert if their end state conflicts with the constraint.

jordanschalm · 2026-03-04T00:34:43Z

cadence/contracts/FlowALPv0.cdc

            self._queuePositionForUpdateIfNecessary(pid: pid)

-            let withdrawn <- reserveVault.withdraw(amount: amount)
+            // Get tokens either by minting (MOET) or from reserves (other tokens)


Dete suggested an abstraction to help simplify this different behaviour between MOET and other tokens in this thread. I think we should apply that, or a similar idea here to minimize the additional complexity we are adding.

This function was already ~150 LOC before this PR, which is beyond the threshold where a person can reasonably understand its behaviour, in my opinion. This is a serious technical risk for introducing and hiding security vulnerabilities. We should ideally be working on improving code quality over time, but at a minimum we need to stop making the problem worse. If you find yourself adding new functionality inline to a >100LOC function, I think that should be a strong signal that we can afford to spend the time to decompose the function into more manageable components as part of adding that functionality.

added abstraction with interfaces for reserve handlers

jordanschalm · 2026-03-04T00:36:46Z

cadence/contracts/FlowALPv0.cdc

+                assert(self.state.borrowReserve(type) != nil, message: "Cannot withdraw \(type.identifier) - no reserves available")
+                let reserveVault = self.state.borrowReserve(type)!
+                assert(reserveVault.balance >= amount, message: "Insufficient reserves for \(type.identifier): need \(amount), have \(reserveVault.balance)")


If we remove these two assert statements, won't withdraw panic anyway?

jordanschalm · 2026-03-04T00:43:38Z

cadence/contracts/FlowALPv0.cdc

                        )
-                        let sinkVault <- FlowALPv0._borrowMOETMinter().mintTokens(amount: sinkAmount)
+
+                        // Get tokens either by minting (MOET) or from reserves (other tokens)


This seems very similar to the logic on lines 1597-1608 - can we make a shared helper function to avoid duplicating big chunks of code inline?

Co-authored-by: Jordan Schalm <jordan.schalm@gmail.com>

liobrasil · 2026-03-04T21:40:17Z

cadence/contracts/FlowALPv0.cdc

+            let positionBalance = position.getBalance(type)
+            // Determine if this is a repayment or collateral deposit
+            // based on the current balance state
+            let isRepayment = positionBalance != nil && positionBalance!.direction == FlowALPModels.BalanceDirection.Debit


Follow-up fix for this logic is available in #196 .
isRepayment is computed from pre-deposit state, so MOET over-repayments (deposit > current debt) route the full amount through depositRepayment and burn all of it, while accounting still records surplus as credit collateral. PR #196 splits the accepted deposit into repayment vs surplus collateral before reserve routing to keep reserves/accounting aligned.

a post check should address this issue

liobrasil · 2026-03-04T22:10:57Z

cadence/contracts/FlowALPv0.cdc

+            if positionBalance == nil {
+                // Validate single collateral type constraint
+                position.validateCollateralType(type)
+


Follow-up for the collateral-type bypass case is in #197 .
When a deposit starts as repayment, deposit > current debt can flip surplus into Credit and create a second collateral type unless validated before recording. PR #197 adds that pre-check in _depositEffectsOnly and includes a regression test (testCannotCreateSecondCollateralTypeByOverRepayingDebt).

a post check should address this issue

liobrasil · 2026-03-04T22:31:32Z

cadence/contracts/FlowALPModels.cdc

+        access(all) fun getCollateralTypes(): [Type] {
+            let types: [Type] = []
+            for type in self.balances.keys {
+                if self.balances[type]!.direction == BalanceDirection.Credit {


Follow-up fix: this type discovery now needs to ignore zero balances. Otherwise exact repay/full withdraw can leave a phantom type that still trips validateDebtType/validateCollateralType. Addressed in PR #199

…ypes

Clear phantom debt/collateral types after exact zeroing

nialexsan · 2026-03-05T18:43:17Z

don't need this any more, after QnA
the protocol uses top-up source for rebalancing

nialexsan · 2026-03-05T18:45:30Z

@jordanschalm I'll clean up the PR and leave reserve handing without all the single token restrictions

jordanschalm · 2026-03-05T18:47:48Z

@jordanschalm I'll clean up the PR and leave reserve handing without all the single token restrictions

Thanks -- also take a look at this thread if you haven't seen it: https://flow-foundation.slack.com/archives/C08QF29F7TK/p1772730444226649. We can simplify that reserve interface to two methods.

multi debt

f8e0c64

nialexsan requested a review from a team as a code owner February 27, 2026 16:34

Merge remote-tracking branch 'origin/main' into nialexsan/multi-debt

921efff

nialexsan commented Feb 27, 2026

View reviewed changes

cadence/contracts/FlowALPv0.cdc Outdated Show resolved Hide resolved

nialexsan added 3 commits February 27, 2026 12:30

Apply suggestion from @nialexsan

cfbcd1a

fix refs

7b1a144

fix balance

c492f20

jordanschalm reviewed Feb 27, 2026

View reviewed changes

nialexsan added 7 commits February 27, 2026 18:23

revert MOET collateral restriction

a7f0828

fix test

4c9e452

fix testing transactions

a916839

Merge branch 'main' into nialexsan/multi-debt

aa091eb

add tests

2b1ed97

fix test

7187d1e

method names for multi types

1a6b4ec

vishalchangrani mentioned this pull request Mar 3, 2026

Enable PyUSD0 as a collateral for the Flow Looping Vault strategy. onflow/FlowYieldVaults#184

Open

zhangchiqing approved these changes Mar 3, 2026

View reviewed changes

jordanschalm requested changes Mar 4, 2026

View reviewed changes

nialexsan and others added 2 commits March 4, 2026 13:54

reserve handler

093d823

Apply suggestion from @jordanschalm

e3dcb84

Co-authored-by: Jordan Schalm <jordan.schalm@gmail.com>

liobrasil reviewed Mar 4, 2026

View reviewed changes

liobrasil mentioned this pull request Mar 4, 2026

Block collateral-type bypass on debt over-repayment #197

Open

liobrasil reviewed Mar 4, 2026

View reviewed changes

Fix phantom debt/collateral types after exact zero balances

8153647

liobrasil mentioned this pull request Mar 4, 2026

Clear phantom debt/collateral types after exact zeroing #199

Merged

liobrasil reviewed Mar 4, 2026

View reviewed changes

nialexsan added 2 commits March 4, 2026 17:35

trim tests

368dbaa

fix test

a414472

Merge branch 'nialexsan/multi-debt' into lionel/fix-phantom-balance-t…

385387f

…ypes

liobrasil mentioned this pull request Mar 4, 2026

Validate debt type before withdrawal credit-to-debit flip #200

Open

Merge pull request #199 from onflow/lionel/fix-phantom-balance-types

3641469

Clear phantom debt/collateral types after exact zeroing

nialexsan mentioned this pull request Mar 5, 2026

Nialexsan/close position #188

Merged

6 tasks

nialexsan added 2 commits March 4, 2026 21:56

move around

ebffab0

address comments

5d9b84c

nialexsan requested a review from jordanschalm March 5, 2026 03:18

nialexsan added 3 commits March 4, 2026 22:25

Merge branch 'main' into nialexsan/multi-debt

6e95bab

fix test

af6b9d7

skip multi collateral tests

5058488

nialexsan changed the title ~~multi debt~~ single debt and collateral per position Mar 5, 2026

nialexsan added 2 commits March 5, 2026 10:07

skip test

9fbd813

fix zero balance check

b65f0ff

nialexsan closed this Mar 5, 2026

nialexsan reopened this Mar 5, 2026

nialexsan marked this pull request as draft March 5, 2026 18:44

liobrasil and others added 6 commits March 5, 2026 19:44

Merge branch 'main' into nialexsan/multi-debt

c0713a7

clean-up

416a9d2

simplify handler

23603b4

tweak handler

ee601c1

switch tests to use dummy token

08fd6fd

revert unnecessary changes

8d48045

nialexsan mentioned this pull request Mar 8, 2026

reserves handler changes #245

Draft

6 tasks

Conversation

nialexsan commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

Uh oh!

jordanschalm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nialexsan commented Feb 27, 2026

Uh oh!

jordanschalm commented Mar 3, 2026

Uh oh!

zhangchiqing left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liobrasil Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jordanschalm Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liobrasil Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liobrasil Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

liobrasil Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nialexsan commented Mar 5, 2026

Uh oh!

nialexsan commented Mar 5, 2026

Uh oh!

jordanschalm commented Mar 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nialexsan commented Feb 27, 2026 •

edited

Loading

liobrasil Mar 4, 2026 •

edited

Loading

jordanschalm Mar 4, 2026 •

edited

Loading

liobrasil Mar 4, 2026 •

edited

Loading

liobrasil Mar 4, 2026 •

edited

Loading

liobrasil Mar 4, 2026 •

edited

Loading