Manage your position

A position has four moving parts: collateral, debt, rate, and the block in which you last touched it. Everything you can do is a change to one of them.

The two operations nobody can block

This is the single design commitment the whole protocol is built around. If something goes wrong — the feed dies, a corporate action pauses the oracle, the sequencer stalls, a key freezes minting — reducing your risk still works.

close() is in the same category: it repays the entire debt from your own balance and returns your collateral, in any state including a shut-down branch, where it is the only voluntary exit.

Rules R-1.1.3, R-1.1.5

Adding collateral

addCollateral accepts an onBehalfOf address, so a third party can top up your position without any authorisation from you. Nobody can take collateral out that way — withdrawal is owner-only.

Your collateral ratio rises immediately, your liquidation price falls proportionally, and if a liquidation flag was standing against you it becomes ineffective the moment your ratio clears the threshold again.

Rules R-5.1.1, R-6.1.2

Repaying

Repay any amount up to your full debt. The rule is simple and it is tested against a specific historical bug: repaying exactly getDebt(u) burns exactly that and leaves a debt of zero. There is no rounding trap where the last wei cannot be paid.

The only constraint is that a partial repayment must leave you either at zero or at or above the minimum debt of 100 fyUSD fyUSD.

You can also repay in USDG in one transaction without ever holding fyUSD — see Repay in USDG.

Rules R-1.1.3, R-5.5.4, R-1.1.4

Borrowing more, and withdrawing collateral

These two increase your risk, so they need a fresh price and a resulting ratio at or above the minting threshold for the current session:

They are also refused while the branch is in mint freeze — which happens automatically when the branch-wide ratio falls under 175%, or when any bad debt is outstanding, or during an upgrade freeze on the collateral token. Mint freeze reverses itself automatically, without anyone deciding anything.

Rules R-5.1.2, R-5.1.4, R-5.1.5, R-6.8.1

One block between two risk increases

borrow, withdraw and close require that you have not already touched the position in the same block. Opening atomically — collateral and debt in a single call — is allowed; chaining a deposit and a withdrawal inside one transaction is not. This closes an entire family of price-manipulation attacks in three lines.

Rule R-5.1.6

Changing your rate

setRate moves your position in the queue that redemptions walk. Any value between the tier floor and 100% is accepted. If your last rate change was less than 7 days days ago, a fee of seven days of interest at the new rate is added to your debt. Lowering your risk never carries a fee or a cooldown.

Details, and the delegation mechanism that lets someone else do it inside bounds you set, are in Interest rate and delegation.

Rules R-1.1.6, R-5.7.1

Claiming your surplus

After a full liquidation, a full redemption, a post-shutdown settlement or a closure, any collateral that was not consumed sits in a surplus balance under your address. claimSurplus() returns it.

What happens if you are redeemed down to a small debt

A redemption can leave your debt below the 100 fyUSD minimum. The position is then marked reduced: it leaves the sorted queue and can only be repaid, closed, liquidated, or brought back above the minimum by borrowing again. It is not force-closed and it does not lose its collateral.

Rules R-5.3.1, R-7.4.3

If a branch shuts down

A branch shuts down automatically when its aggregate ratio stays below 120% for an hour, when its price feed has been degraded continuously for seven days, when a token contract upgrade is not cleared within 28 days, or by the Closer key while it exists. In every case:

• Interest stops accruing at the moment of shutdown, permanently.
• repay, addCollateral, close and claimSurplus stay open.
• borrow, withdraw, setRate, flag and normal liquidation are refused.
• Holders of fyUSD can perform urgent redemptions against the branch at the last accepted price, starting immediately — or after seven days if the shutdown came from the Closer, so that borrowers get a week to exit a decision that was not mechanical.
• Thirty days after that, any remaining position is settled permissionlessly at the last good price with zero bonus and zero keeper fee, and the leftover collateral goes to your surplus balance.

Rules R-6.9.1, R-6.9.2, R-6.9.3, R-6.9.5, R-6.9.8

Last reviewed: 2026-09-07 · Spec v0.4