> For the complete documentation index, see [llms.txt](https://docs.jaawle.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jaawle.xyz/protocol/overview.md). # Overview The protocol is a set of contracts on an EVM chain that together run a perpetual-futures exchange on tokenized stocks, ETFs and crypto. There is no order book. Every market has one liquidity pool that holds the market's assets and takes the other side of every trade. Liquidity providers fund that pool and earn its fees, its borrow and funding charges and the traders' net losses; they bear the traders' net gains and, on stock pools, the pool's own inventory risk. Two things run off-chain: the keeper, which pushes prices and the session, executes queued liquidity requests, rebalances pools through the issuer, liquidates and fires triggers; and the terminal the user sees. Where the prices come from is covered in [Price feeds](/assets-and-prices/price-feeds.md) and the shares themselves in [Tokenized shares and custody](/assets-and-prices/tokenized-shares-and-custody.md). The contracts are the source of truth; the keeper is bounded by them and can never change a parameter or move funds outside the envelopes the contracts enforce. ## The pieces | contract | job | upgrade path | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | | AccessRegistry | roles, the KYC allowlist, per-target and global pause flags. ADMIN is the timelock. | not upgradeable | | PriceFeed | wraps Pyth: bid, ask and mid per asset, staleness, confidence and deviation guards, the NYSE session, the closing mark. | UUPS | | MarketPool (one per market) | holds USDC and the market's shares, mints an LP token at NAV, runs the liquidity request queue and the issuer order escrow, and is the counterparty to every position in its market. | BeaconProxy, one beacon for all pools | | PoolFactory | creates pools (CREATE2, salted by symbol), registers them with the PositionManager. Holds the wiring every new pool is initialised with. | UUPS | | IndexVault | one USDC deposit spread across the stock pools at target weights. Holds child LP tokens and mints its own. | UUPS | | PositionManager | positions, leverage, taker fees, borrow and funding indices, dividend pass-through, liquidations, bad-debt cover. Holds every trader's collateral. | UUPS | | TriggerBook | take-profit and stop-loss per position; executes as a market close through the PositionManager. | UUPS | | LimitBook | resting limit orders with the collateral in escrow; executes as an open through the PositionManager, capped at the limit price. | UUPS | | TradeRouter | one-click trading: subaccount grants and relayed, signed actions, including `SetTrigger`, `PlaceLimit` and `CancelLimit`. Acts for an account through the `...For` entry points. | UUPS | | InsuranceVault | USDC backstop funded by a share of fees and by liquidation penalties; covers bad debt under per-transaction and daily caps. | UUPS | | Timelock | OpenZeppelin `TimelockController`. Holds ADMIN on the registry and owns the pool beacon. 24 h delay in production. | not upgradeable | Off-chain and external: | party | role | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | keeper | prices and session, request execution, issuer orders and rebalancing, liquidations, triggers and limit orders, dividend sweeps, the relayer for one-click actions, the API the terminal reads. | | the issuer | the partner that mints and redeems the tokenized shares the stock pools hold and pays their dividends. Today the issuer is Dinari and the tokens are dShares. | | Pyth | the price source. Stock and ETF marks come from Pyth's tokenized-stock feeds (xStocks), which print around the clock; crypto marks from the ordinary crypto feeds. | ## How they connect ```mermaid flowchart LR subgraph Users W[Trader or LP wallet] K[One-click subaccount key] end subgraph Keeper TW[Keeper worker] API[Relayer API] end subgraph Contracts REG[AccessRegistry] PF[PriceFeed] PM[PositionManager] TB[TriggerBook] LB[LimitBook] TR[TradeRouter] POOL[MarketPool, one per market] FAC[PoolFactory] IDX[IndexVault] INS[InsuranceVault] TL[Timelock] end subgraph External PY[Pyth] ISS[The issuer] end W -- open, close --> PM W -- request liquidity --> POOL W -- request deposit --> IDX W -- set triggers --> TB W -- place, cancel --> LB K -- signed action --> API API -- execute --> TR TR -- acts for the account --> PM TR -- acts for the account --> POOL TR -- acts for the account --> IDX TR -- setFor --> TB TR -- placeFor, cancelFor --> LB TB -- decreasePositionFor --> PM LB -- increasePositionFor --> PM PY -- prices --> TW TW -- refresh, session --> PF TW -- execute requests, place orders, book dividends --> POOL TW -- liquidate --> PM TW -- execute --> TB TW -- execute, expire --> LB TW -- shift, execute requests --> IDX TW -- orders off-chain --> ISS ISS -- shares, cash, dividends --> POOL PM -- settle traders, reserve inventory --> POOL PM -- fund, cover --> INS FAC -- createPool --> POOL IDX -- depositFromParent --> POOL TL -- ADMIN --> REG TL -- owns beacon --> FAC PM -. getPrice .-> PF POOL -. getPrice .-> PF TB -. getPrice .-> PF ``` Every contract reads the same `AccessRegistry` for roles, the allowlist and pause flags, and the same `PriceFeed` for prices. The PositionManager talks to a pool only through five hooks: `reserveInventory` and `releaseInventory` (longs), `increaseShortOi` and `decreaseShortOi` (shorts) and `settleTrader` (money). The pool accepts those calls only from the PositionManager address it was wired with. ## The flows in one paragraph each **Liquidity.** An LP sends a request to a pool (USDC or shares in, LP tokens out, or the reverse). The request escrows the asset and queues. The keeper executes the queue; the LP tokens are minted or the payout made at the NAV of that moment, minus a fee that is cheaper when the request moves the pool toward its target stock weight. Details in [Pools and NAV](/protocol/pools-and-nav.md). **Rebalancing.** When a stock pool drifts from its 60 % stock target the keeper places an order with the issuer: the pool escrows USDC (buy) or shares (sell) to the issuer adapter wallet, the keeper places the order off-chain, and the settler books the fill on-chain. Details in [Issuer orders](/protocol/issuer-orders.md). **Trading.** A trader posts USDC and opens a long or short of a USD notional against the pool at Pyth's ask or bid. A long reserves pool inventory; a short consumes the pool's USDC cap. Borrow accrues per second from utilisation, skew funding is paid by the heavy side to the pool, dividends pass through on the ex-date. Details in [Trading engine](/protocol/trading-engine.md) and [Dividends](/protocol/dividends.md). **Triggers.** A trader (or the one-click subaccount through the router) sets a take-profit and a stop-loss on an open position in the TriggerBook. The keeper executes when the bid (longs) or ask (shorts) crosses; anyone may execute after a priority window from a public flag. Execution is a market close through the PositionManager, so the payout always reaches the account. See [Trading engine](/protocol/trading-engine.md#take-profit-and-stop-loss). **Limit orders.** A trader (or the subaccount through the router) rests an order in the LimitBook with the collateral in escrow. The keeper executes when the ask (buys) or bid (sells) reaches the limit; anyone may after a priority window from a public flag, and anyone may expire an order past its deadline, which refunds the account. Execution is an open through the PositionManager capped at the limit price. See [Trading engine](/protocol/trading-engine.md#limit-orders). **Risk.** A position is liquidatable when its equity falls to the maintenance margin. The keeper has priority; after a window from a public flag anyone can liquidate and take the reward. Large positions are closed in chunks. Shortfalls beyond the collateral are paid to the pool by the insurance vault, under caps. Details in [Liquidation and insurance](/risk/liquidation-and-insurance.md). **Governance.** Every parameter change and every upgrade goes through the timelock. A guardian can pause and nothing else. Details in [Governance and roles](/protocol/governance-and-roles.md). ## Units Inside the contracts USD values are 18-decimal fixed point, USDC amounts use the token's 6 decimals, prices are 18-decimal, and share quantities use the share token's own decimals (`stockUnit`; 1e18 on synthetic pools that hold no token). Basis points are out of 10 000. ## Where to look next * [Pools and NAV](/protocol/pools-and-nav.md): the pool's balance sheet and the LP token. * [Trading engine](/protocol/trading-engine.md): how a position is priced, charged and closed. * [Parameters](/protocol/parameters.md): every number the local and testnet deployments use. * [Worked examples](/protocol/worked-examples.md): the same rules applied to a long, a short, a liquidation, a deposit and a dividend. * [Glossary](/protocol/glossary.md). --- # 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.jaawle.xyz/protocol/overview.md?ask=&goal= ``` `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.