Skip to main content

Settlement

Settlement on Ollo happens in two layers: margin settlement (how collateral-denominated PnL flows between margin buckets) and token settlement (how virtual FX tokens are reconciled when a position closes). The margin side is covered in the Collateral and Margin section.

In the current closed beta, the allowlisted collateral asset is USDC, so current implementations settle margin in USDC terms.

Why Virtual Tokens Exist​

Ollo's order book is a standard exchange that matches buyers and sellers of two assets. But the assets being traded are not real currencies. They are virtual FX tokens (e.g., fxUSD, fxJPY) minted on demand by the Clearinghouse.

These tokens serve a single purpose: to give the order book something to match. The real economic value of every position lives in the collateral margin. The tokens are phantom accounting and exist only for the duration of a trade and are destroyed when the position closes.

Token Lifecycle​

1. Mint on Open​

When a trader opens a position, the Clearinghouse mints virtual tokens on behalf of their account:

  • Going LONG on USD/JPY: the account mints quote tokens (fxJPY) to spend on the order book, buying base tokens (fxUSD).
  • Going SHORT on USD/JPY: the account mints base tokens (fxUSD) to sell on the order book, receiving quote tokens (fxJPY).

The Clearinghouse records a debt against the account for every token it mints. This debt tracks the account's obligation to return (burn) those tokens later.

2. Trade on the Order Book​

The minted tokens are transferred to the Market contract and matched against resting orders. On fill, the account receives the other side's tokens. A LONG receives fxUSD, and a SHORT receives fxJPY.

At this point the account holds tokens it received from the trade and owes debt for the tokens it minted. These two amounts may not match and the difference reflects the position's PnL.

3. Close and Clear​

When the position is fully closed, the account enters the token clearing phase. PnL has already been realized into margin via the fill callback. The tokens are now accounting artifacts that need to be cleaned up.

For each token type (base and quote), the Clearinghouse performs three operations in sequence:

Burn against debt: burn the lesser of the token balance and the outstanding debt. This covers the portion of the trade that broke even.

Burn surplus: if the account holds more tokens than it owes (the profit case), the excess is burned without reducing debt. These surplus tokens represent the profitable side of the trade. The economic gain is already captured in margin.

Forgive debt: if the account owes more than it holds (the loss case), the remaining debt is written off. The loss has already been deducted from margin via PnL realization, so the debt is now phantom.

Settlement Scenarios​

Breakeven​

The account's token balance equals its debt. All tokens are burned against debt. Nothing is left over.

Profit​

The account holds more tokens than it owes. This happens when the trade moved in the trader's favor where the tokens received on close are worth more than what was originally minted.

The debt portion is burned normally. The surplus is burned via burnSurplus, which destroys the tokens without touching the debt ledger. The actual profit is already sitting in available margin from PnL realization.

Loss​

The account owes more tokens than it holds. This happens when the trade moved against the trader. Closing the position required minting additional tokens to cover the shortfall (e.g., a SHORT at loss needs more quote tokens than it originally received).

The available tokens are burned against debt. The remaining debt is forgiven via forgiveDebt, which reduces the debt ledger without requiring tokens. The actual loss was already deducted from margin.

Why This Design?​

A limit order book works by transferring tokens between buyers and sellers and cannot operate on abstract margin accounting. The virtual tokens give the CLOB concrete assets to custody, match, and settle, while the margin system handles the actual economics.

This separation means the order book is a standard, general-purpose exchange. It does not need to understand leverage, margin, or PnL. It simply matches bids and asks for two ERC-20 tokens. All the perpetual-specific logic lives in the FxAccount and FxEngine layers above it.

Liquidation Settlement​

Liquidation follows the same clearing process. When a position is liquidated:

  1. A market close order is placed through the order book on behalf of the account.
  2. The fill callback realizes PnL into margin (typically a loss).
  3. Token clearing runs, burning what it can and forgiving the rest.
  4. Liquidation rewards are deducted from any remaining available margin and distributed to the liquidator and the insurance fund.

If the account's margin is insufficient to cover the full loss plus liquidation rewards, the shortfall is recorded as bad debt on the market. The insurance fund absorbs this where possible.