> For the complete documentation index, see [llms.txt](https://docs.fermi.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fermi.trade/01-overview.md).

# 01 overview

Fermi-v1 is a **non-custodial, fully on-chain perpetual-futures exchange** on Solana. Traders self-custody collateral and sign their own orders; order placement, cancels, matching, fills, risk checks, funding, and liquidation all execute through the deployed program. There is no off-chain matching engine, no off-chain risk database, no escrow account.

Fermi-v1 is built around four cleanly separated components:

{% stepper %}
{% step %}

## The on-chain exchange program

A Solana program that owns order placement, cancels, the order book, the matching engine, the risk engine, funding, and liquidation. It is the single source of truth for execution.
{% endstep %}

{% step %}

## The [POSq sequencing layer](broken://pages/ac31e9ddbaaf6ba0dc00cd9026f42e08117ea99d)

It orders encrypted transactions over VDF ticks before they are revealed. In v1 POSq runs in single-sequencer mode, making reordering detectable rather than hidden in a black-box sequencer. V2 is planned to add voting, leader rotation, and permissionless participation.
{% endstep %}

{% step %}

## A per-market AMQ-style commit/reveal execution queue

The v5 queue is built into that program and anchors the POSq order on chain before intents touch the book.
{% endstep %}

{% step %}

## The optimistic harness

An off-chain read layer that publishes optimistic and confirmed state to traders over HTTP / SSE, so they see their orders reflected in milliseconds while on-chain finality follows behind.
{% endstep %}
{% endstepper %}

See [02 - Architecture](broken://pages/890697491fdf2eed943cb23b394c6638d28ed1ce) for how these pieces fit together and why the design is both fast and fair.

## What you get

* **Cross-collateral perps.** Spot deposits (USDC, SOL, ETH, BTC, …) back perp positions across all markets in the group. Health is a single signed-USD number.
* **FIFO orderbook.** Two trees per side — fixed price and oracle-pegged — both ordered strictly by price-time, enforced through the on-chain AMQ-style execution queue.
* **Verifiable order sequencing.** [POSq](broken://pages/ac31e9ddbaaf6ba0dc00cd9026f42e08117ea99d) sequences encrypted intents over VDF ticks, then every order is hash-committed on chain *before* it executes. Reordering relative to the emitted POSq sequence is detectable.
* **Replay protection.** A 10-slot, 512-entry intent-hash cache makes signature replay impossible.
* **Censorship fallback.** A direct-submission pool lets users get orders into the queue even if the v1 fast path is offline or refusing admission.
* **Public, low-latency reads.** The optimistic harness pre-plays the deterministic on-chain path and exposes optimistic order-book and account state over SSE; the fanout service scales it horizontally.

## The stack at a glance

```
                ┌─────────────────────────────────────────────┐
                │             Wallet / SDK / UI               │
                └────┬─────────────────────┬─────────────┬────┘
       sign+submit   │  read state         │  read events│
                     ▼                     ▼             ▼
            ┌────────────────┐  ┌─────────────────┐ ┌──────────┐
            │   Relayer      │  │  Optimistic     │ │ Fanout   │
            │   (gRPC :9090) │  │   harness       │ │ (SSE)    │
            │                │  │  (HTTP/SSE)     │ │          │
            └────────┬───────┘  └────────┬────────┘ └─────┬────┘
                     │                   ▲                ▲
            commit + reveal              │ on-chain reads │
                     ▼                   │                │
            ┌────────────────────────────┴────────────────┴────┐
            │       Fermi-v1 on-chain exchange program          │
            │                                                   │
            │  Group · Bank · FermiAccount · PerpMarket         │
            │  BookSide · EventQueue · ExecutionQueueV5         │
            └───────────────────────────────────────────────────┘
                                Solana mainnet-beta
```

{% stepper %}
{% step %}

## Sign

SDK builds a v5-canonical intent payload and the user signs it (wallet pop-up or programmatic Ed25519 signature).
{% endstep %}

{% step %}

## Submit

SDK sends the encrypted intent to the POSq/relayer fast path over gRPC.
{% endstep %}

{% step %}

## Pre-validate

Fast-path services check signature, account staleness, oracle freshness, health, and reduce-only rules off-chain.
{% endstep %}

{% step %}

## Sequence & commit

POSq assigns the intent to a VDF tick/order; the relayer batches up to 64 commits and writes them to the per-market `ExecutionQueueV5` ring.
{% endstep %}

{% step %}

## Reveal & execute

In a later transaction, the executor reveals the payload; the program re-hashes it, verifies the user signature, runs the order through the on-chain Fermi handler, and advances the queue head.
{% endstep %}

{% step %}

## Stream

The executor emits a `FillLogV3` (or `OutEvent`); the fanout service propagates it over SSE.
{% endstep %}

{% step %}

## Settle / fund

PnL is settled by anyone calling `perp_settle_pnl`; funding accrues continuously and is paid at `perp_update_funding`.
{% endstep %}
{% endstepper %}

## What is *not* off-chain

The matching engine, risk engine, liquidator, oracle, fee accrual, funding accrual, settlement, and bankruptcy resolution are all in the on-chain program. POSq/relayer services provide **verifiable sequencing, submission, and pre-flight validation only**. If the v1 fast path refuses an intent before admission, the chain state is unaffected and the direct path remains available; if it reorders relative to the emitted POSq sequence, the VDF-tick/commit trail makes that detectable.

## Properties at a glance

| Property                 | Mechanism                                                                                                                                |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Self-custody             | Fermi account is a PDA you own; only your signature can mutate it.                                                                       |
| Verifiable ordering      | [POSq](broken://pages/ac31e9ddbaaf6ba0dc00cd9026f42e08117ea99d) encrypted VDF ticks + per-market sequence + hash commit prior to reveal. |
| Replay-proof             | On-chain `replay_cache` of consumed intent hashes (10 slots / 512 entries).                                                              |
| FIFO matching            | Composite `(price, !seq)` keys for bids and `(price, seq)` for asks.                                                                     |
| Censorship fallback      | Direct-submit pool with a fixed slot speed-bump.                                                                                         |
| Margin safety            | Three weighted health values: `init`, `maint`, `liquidation_end`.                                                                        |
| Liquidation liveness     | Anyone can liquidate; insurance fund + socialization tail.                                                                               |
| Oracle attack resistance | Init health uses a stable price band; oracles checked for staleness and confidence.                                                      |
| Operational visibility   | Every stage of an intent emits a structured event; trace by `(market, seq)`.                                                             |

## Where to next

* **Investor / evaluator?** Read [02 - Architecture](broken://pages/890697491fdf2eed943cb23b394c6638d28ed1ce) for the system design, trust model, and viability case.
* **Trader?** Start with [03 - Getting Started](broken://pages/c8072c86887d42e609a5a2fc8dee16796fca6b18) → [12 - Order Types](broken://pages/d61d1c45b4e81e4eb4921acecc04a09233799515) → [15 - Margin & Health](broken://pages/854a94521c8968d1ac32269b054622c7369c60d5).
* **Bot author?** Read [22 - Trader Workflow](broken://pages/cac7d3e6caa388b654e79fb8cf990d9bf2291d2f) and [26 - gRPC API](broken://pages/0e7a840819337d746ed8e882c2eb48f78a789e68).
* **Liquidator?** [17 - Liquidation](broken://pages/bec8219b5c85ab951e627331f9357231dbccb330) is the canonical reference; pair it with [18 - Bankruptcy](broken://pages/72e830bc825f1dd6d395844a72534e964ba2a00d).
* **Protocol integrator (CPI)?** [24 - Direct CPI](broken://pages/0a599c7a4024495eee1028623a4e112f9535315c) shows the on-chain instruction shape and required preinstructions.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fermi.trade/01-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.