Settlement

TL;DR: At maturity, all positions are settled based on the difference between Fixed Yield and actual Variable Yield. This guide covers the settlement process, what to expect, and how to collect your returns.

What is Settlement?

Settlement is the process of closing positions at maturity and distributing PnL:

┌─────────────────────────────────────────────────────────────┐
│                    SETTLEMENT PROCESS                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   At maturity:                                              │
│                                                             │
│   1. Oracle reports final Variable Yield for the term      │
│   2. Protocol calculates each position's cashflow          │
│   3. Profitable positions receive funds                     │
│   4. Losing positions have funds deducted                   │
│   5. LP positions return any remaining liquidity            │
│   6. Margin (± PnL) is returned to users                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

When Can You Settle?

Check Maturity

function canSettle(poolKey) {
    const currentTime = BigInt(Math.floor(Date.now() / 1000)) * 10n**18n;
    const maturityTime = poolKey.termEndTimestampWad;
    
    return currentTime >= maturityTime;
}

// Usage
if (canSettle(poolKey)) {
    console.log("Pool has matured! You can settle.");
} else {
    const remaining = Number(poolKey.termEndTimestampWad - currentTime) / 1e18;
    const days = remaining / 86400;
    console.log(`${days.toFixed(1)} days until maturity`);
}

Settlement Math

The Formula

Settlement Cashflow = fixedTokenBalance × fixedFactor 
                    + variableTokenBalance × variableFactor

Where:
- fixedFactor = (termEnd - termStart) / SECONDS_IN_YEAR / 100
- variableFactor = Accumulated VY from oracle over the term

FY Position Example

Position (Locked Fixed Yield):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Notional: 100,000 USDC
fixedTokenBalance: +100,000 (receiving FY)
variableTokenBalance: -100,000 (giving up VY)
Term: 90 days
FY locked: 6%
VY actual: 4%

Calculation:
fixedFactor = 90 / 365 / 100 = 0.00247 (for 1% rate)
At 6%: fixedContribution = 100,000 × 6 × 0.00247 = 1,479

variableFactor ≈ 4% × (90/365) = 0.00986
variableContribution = -100,000 × 0.00986 = -986

Cashflow = 1,479 + (-986) = +$493 profit ✓

VY Position Example

Position (Trading Variable Yield):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Notional: 100,000 USDC
fixedTokenBalance: -100,000 (giving up FY)
variableTokenBalance: +100,000 (receiving VY)
Term: 90 days
FY given up: 6%
VY actual: 8%

Calculation:
fixedContribution = -100,000 × 6 × 0.00247 = -1,479
variableContribution = +100,000 × 8% × (90/365) = +1,973

Cashflow = -1,479 + 1,973 = +$494 profit ✓

Executing Settlement

Step 1: Verify Maturity

const poolKey = {
    underlyingAsset: USDC,
    compoundToken: aUSDC,
    termStartTimestampWad: ...,
    termEndTimestampWad: ...,
    feeWad: ...,
    tickSpacing: 10
};

// Check if matured
const currentTime = BigInt(Math.floor(Date.now() / 1000)) * 10n**18n;
if (currentTime < poolKey.termEndTimestampWad) {
    throw new Error("Pool has not matured yet");
}

Step 2: Call settlePosition

const SETTLE_ABI = [
    "function settlePosition(tuple(address,uint96,address) account, tuple(address,address,uint256,uint256,uint256,int24) poolKey) external"
];

const collateralEngine = new ethers.Contract(
    COLLATERAL_ENGINE,
    SETTLE_ABI,
    signer
);

const tx = await collateralEngine.settlePosition(
    [account.owner, account.id, account.isolatedMarginToken],
    [
        poolKey.underlyingAsset,
        poolKey.compoundToken,
        poolKey.termStartTimestampWad,
        poolKey.termEndTimestampWad,
        poolKey.feeWad,
        poolKey.tickSpacing
    ]
);

await tx.wait();
console.log("Position settled!");

Step 3: Check Final Balance

const finalBalance = await collateralEngine.getAccountMargin(account, USDC);
console.log(`Final USDC balance: ${ethers.formatUnits(finalBalance, 6)}`);

Negative Cashflow (Losses)

When You Lose

If your cashflow is negative (VY moved against you):

Losing FY Position:
━━━━━━━━━━━━━━━━━━━
FY locked: 6%
VY actual: 10%
Cashflow: (6% - 10%) × Notional × Time = Negative

Your margin is reduced by this amount.

Settler Exchange

If your margin is insufficient:

Settlement Process for Losses:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Protocol first uses your underlying asset (USDC)
2. If insufficient, uses other margin tokens
3. Tokens sold at oracle price with discount
4. Covers the loss owed to counterparties

// Settlement with potential exchange
// Settler (msg.sender) may need to provide underlyingAsset

// If you're the settler and account has losses:
// 1. Transfer underlyingAsset to cover losses
// 2. Receive margin tokens at discounted price

// This is handled automatically in settlePosition()

LP Position Settlement

LP-Specific Considerations

LP positions are settled differently:

LP Settlement:
━━━━━━━━━━━━━━

1. Liquidity is converted to final token balances
   - Based on where FY ended relative to your range
   
2. Token balances determine settlement cashflow
   - Same formula as trader positions
   
3. Accumulated fees are already in your margin
   - Fees were added during the term

4. Final margin = Original margin + Fees + Settlement PnL

Example: LP Settlement

LP Position:
- Range: 5% - 8%
- Liquidity: 1,000,000 units
- FY at maturity: 9% (above range)

At settlement:
- Position is 100% fixedTokens (FY went above range)
- fixedTokenBalance: +X
- variableTokenBalance: -X (from the conversion)

Settlement cashflow calculated normally based on these balances.

Multiple Positions

Settling All Positions

If you have multiple positions in the same pool:

// settlePosition settles ALL your positions in that pool
await collateralEngine.settlePosition(account, poolKey);

// After settlement:
// - All positions in that pool are closed
// - Combined PnL added/subtracted from margin
// - Pool removed from your active pools

Multiple Pools

For positions across multiple pools:

// Settle each pool separately
const pools = [poolKey1, poolKey2, poolKey3];

for (const poolKey of pools) {
    if (await canSettle(poolKey)) {
        await collateralEngine.settlePosition(account, poolKey);
        console.log(`Settled pool ${poolKey.compoundToken}`);
    }
}

After Settlement

Withdraw Your Funds

After settling, withdraw your margin:

// Get current balance
const balance = await collateralEngine.getAccountMargin(account, USDC);

// Withdraw everything
await collateralEngine.updateAccountMargin(
    account,
    USDC,
    -balance  // Negative = withdraw
);

console.log(`Withdrawn ${ethers.formatUnits(balance, 6)} USDC`);

What If You Don't Settle?

Positions don't auto-settle. If you don't call settlePosition:

• Your funds remain in the protocol

• You can settle anytime after maturity

• No penalty for delayed settlement

• Anyone can call settlement on your behalf (but you receive the funds)

Settlement Events

Monitoring Settlement

// Listen for settlement events
collateralEngine.on("PositionSettlement", (
    owner,
    accountId,
    isolatedMarginToken,
    poolId,
    settlementCashflow
) => {
    if (owner === yourAddress) {
        console.log(`Position settled!`);
        console.log(`Cashflow: ${ethers.formatUnits(settlementCashflow, 6)} USDC`);
    }
});

Complete Settlement Flow

async function settleAndWithdraw(signer, account, poolKey) {
    const collateralEngine = new ethers.Contract(
        COLLATERAL_ENGINE,
        COLLATERAL_ENGINE_ABI,
        signer
    );
    
    // 1. Check if matured
    const currentTime = BigInt(Math.floor(Date.now() / 1000)) * 10n**18n;
    if (currentTime < poolKey.termEndTimestampWad) {
        console.log("Pool not yet matured");
        return;
    }
    
    // 2. Settle position
    console.log("Settling position...");
    const tx = await collateralEngine.settlePosition(
        [account.owner, account.id, account.isolatedMarginToken],
        [
            poolKey.underlyingAsset,
            poolKey.compoundToken,
            poolKey.termStartTimestampWad,
            poolKey.termEndTimestampWad,
            poolKey.feeWad,
            poolKey.tickSpacing
        ]
    );
    await tx.wait();
    console.log("Position settled!");
    
    // 3. Get final balance
    const balance = await collateralEngine.getAccountMargin(account, USDC);
    console.log(`Final balance: ${ethers.formatUnits(balance, 6)} USDC`);
    
    // 4. Withdraw
    if (balance > 0n) {
        await collateralEngine.updateAccountMargin(
            [account.owner, account.id, account.isolatedMarginToken],
            USDC,
            -balance
        );
        console.log("Funds withdrawn to wallet!");
    }
}

Key Takeaways

1. Settlement happens after maturity — Pool must reach termEndTimestamp

2. Call settlePosition() — Settlement is not automatic

3. Cashflow = FY contribution + VY contribution — Based on token balances

4. Losses deducted from margin — May trigger settler exchange

5. Withdraw after settling — Funds remain in protocol until withdrawn

Next Steps

• Getting Started — Start a new position

• Risk Management — Understand settlement risks

• Math Formulas — Detailed settlement math