Architecture Overview

Ollo Finance is an onchain FX perpetuals protocol built around a central limit order book (CLOB). Positions are collateralized with allowlisted assets, leveraged via virtual FX token minting, and settled through a deterministic price-time priority matching engine.

In the current closed beta, USDC is the only allowlisted collateral asset.

System Components

Contract	Responsibility
FxEngine	Top-level coordinator: accounts, markets, margin, funding, liquidations, order routing
FxAccount	Per-user trading account: margin balances, positions, order state, fill handling, token management
Market	Central limit order book: price-time priority matching via red-black tree + FIFO queues
Clearinghouse	Virtual token lifecycle: mints/burns FX tokens, tracks debt per account
FundingRateOracle	Funding rate calculation: pushed prices + onchain OI to hourly funding rate
FxAccountFactory	Deploys new FxAccount contracts on behalf of FxEngine

Contract Interaction Map

Lifecycle Flows

Account Creation

Each user gets exactly one FxAccount contract. The engine registers it as an authorized clearinghouse participant so it can mint and burn virtual tokens.

Opening a Position

Position Close & Token Clearing

When a position is fully closed, the account enters the token clearing phase. Virtual tokens are phantom accounting. PnL has already been realized into margin via _realizePnL. The clearing step reconciles the token balances and debt:

Funding Settlement

Funding is settled lazily. Cumulative funding is updated on the market config whenever an order is placed or a fill is processed, and each account settles its own delta on the next interaction.

Liquidation

Access Control Model

The protocol uses a layered permission model rather than a single role-based system:

Caller	Can call	Controlled by
Owner (EOA)	FxEngine admin functions, market registration	Deployer
Account Owner	placeOrder, cancelOrder, withdrawMargin via FxEngine	onlyAccountOwner modifier
FxEngine	FxAccount state mutations (handleFill, recordDeposit, settleFunding)	onlyFxEngine modifier on each account
FxAccount	Clearinghouse.mint/burn/forgiveDebt	onlyAuthorized - registered during account creation
Market	FxEngine.onFill callback	onlyMarket - registered during market registration
Price Updater	FundingRateOracle.pushPrices	authorizedPriceUpdaters mapping
Keeper	FundingRateOracle.updateFundingRate	authorizedKeepers mapping

Margin Model

Each FxAccount maintains two margin pools denominated in WAD:

• availableMargin: free collateral, usable for new orders or withdrawals.
• committedMargin: locked against open positions and active orders.

Margin flows:

• Deposit: USDC transferred to account → availableMargin += usdcToWad(amount)
• Order placement: availableMargin -= collateral, committedMargin += collateral
• Fill (open): margin moves from committed to backing the position (pos.margin)
• Fill (close): PnL realized → profit added to availableMargin, margin returned from committedMargin
• Funding payment owed: deducted from availableMargin first, then committedMargin (pushes toward liquidation)
• Funding payment received: added to availableMargin
• Withdrawal: deducted from availableMargin, transferred as USDC

Virtual Token Model

Ollo uses virtual FX tokens (e.g., fxUSD, fxJPY) as the medium of exchange on the order book. These tokens are not held long-term. They exist only for the duration of a position:

1. Mint on open: FxAccount asks Clearinghouse to mint tokens. Debt is recorded against the account.
2. Trade on book: tokens are transferred to the Market contract for matching.
3. Receive on fill: the account receives the other side's tokens.
4. Clear on close: all token balances and debt are reconciled. Burn against debt, burn surplus, forgive remaining debt.

The real economic value lives in the collateral margin. In the current implementation, that means USDC margin. Tokens are phantom accounting that enables the CLOB to function as a standard exchange while all actual PnL settles in margin.