Settlement

What happens when a market matures, and how late repayments can still improve lender outcomes.

Overview

The market reaches maturity.
A 5-minute grace period starts.
The first withdrawal after grace sets the settlement factor.
Lenders withdraw based on that factor.
If more funds arrive later, anyone can call re-settlement to improve the factor.

Settlement Factor

The settlement factor is the payout ratio applied to all lenders.

At settlement time, the program computes:

expected_value = scaled_total_supply * scale_factor / WAD
fees_reserved = min(vault_balance, accrued_protocol_fees)
available_for_lenders = vault_balance - fees_reserved
raw_factor = available_for_lenders * WAD / expected_value
settlement_factor = clamp(raw_factor, 1, WAD)

If expected_value = 0, the program sets settlement_factor = WAD.

See Protocol Calculations for details.

Pro-Rata Distribution

All lenders share the same factor.

Lender	Expected	Settlement (75%)
Alice	540,000	405,000
Bob	324,000	243,000
Carol	216,000	162,000
Total	1,080,000	810,000

Grace Period

The protocol enforces a 5-minute grace period after maturity.

Action	During Grace Period
Deposit	Not allowed
Borrow	Not allowed
Repay	Allowed
Withdraw	Not allowed
Re-settle	Not allowed

If a withdrawal is attempted during grace, the transaction fails with SettlementGracePeriod.

Withdrawal Slippage Protection

Withdraw includes an optional min_payout parameter. If the computed payout is below min_payout, the transaction fails with PayoutBelowMinimum (ERR-42).

Use this to protect against receiving less than expected when settlement is distressed or when the vault changes between quote and execution.

Re-Settlement

Re-settlement recalculates the settlement factor after late repayments.

Why It Exists

Initial settlement uses vault funds available at first withdrawal. If the borrower repays more later, re-settlement lets remaining lenders benefit from the higher vault balance.

Rules

Market must already be settled (NotSettled if not).
New factor must be strictly higher (SettlementNotImproved otherwise).
Anyone can call it (permissionless).
Factor can only improve; it never decreases.

Example

Step	Vault / Owed	Factor
Initial settlement	810 / 1,080	75%
Late repayments arrive	1,080 / 1,080	100%
Re-settle called	recomputed	100%

Lenders who already withdrew keep their earlier payout. Lenders who withdraw later use the improved factor.

Viewing the Factor

On-chain

const market = decodeMarket(marketAccount.data);
const factorPercent = Number(market.settlementFactorWad) / 1e16;
console.log('Settlement Factor:', factorPercent, '%');

API

GET /api/markets/:address

{
  "success": true,
  "data": {
    "market": {
      "settlementFactorWad": "750000000000000000"
    }
  },
  "requestId": "f5fd7f52-7ec2-4f3e-85c2-2f17f47ebf4e"
}