> 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/pools-and-nav.md). # Pools and NAV Each market has one `MarketPool`. The pool holds the market's assets, prices itself at NAV, mints an LP token against that NAV, and is the counterparty to every position in its market. Pools are deployed by the `PoolFactory` as BeaconProxies, so one upgrade moves all of them. ## Two kinds of pool | kind | markets | what the pool holds | target stock weight | | ------------ | ------------- | ------------------------------------------------------------------------- | ------------------- | | share-backed | stocks, ETFs | USDC plus the market's tokenized shares (dShares from the issuer, Dinari) | 60 % of NAV | | synthetic | crypto, memes | USDC only | 0 | A share-backed pool is a two-asset portfolio. The stock leg backs the longs it faces (each long reserves shares from the inventory) and the cash leg backs the shorts and pays redemptions. A synthetic pool is cash only: longs and shorts are both P\&L bets sized against the pool's USDC, and the pool's exposure is the traders' net skew. A synthetic pool refuses stock requests and issuer orders (`SyntheticPool`). ## NAV `totalAssets()` is computed from the pool's internal accounting, never from token balances, so a donation cannot move the share price: ``` NAV = USDC + USD+ + USDC escrowed in issuer orders + (shares held + shares escrowed in issuer orders) x bid - net amount owed to traders (PositionManager.poolExposure) ``` `poolExposure` is the traders' unrealised P\&L at the mid plus the dividend credits accrued to longs minus the debits accrued to shorts. It is positive when the pool owes traders and negative when traders owe the pool. Assets in flight to the issuer stay in NAV at cost, so a deposit or redemption cannot front-run a fill. USDC and shares escrowed for queued liquidity requests are not in NAV; they belong to the requester until executed. Shares are valued at the bid (`depositPrice`), the conservative side for the pool. While a stock market is closed and the feed is quiet, the PriceFeed serves the closing mark with bid = ask = mid, so NAV stays readable (see [Sessions and prices](/product/sessions-and-prices.md)). ## The LP token The LP token is an 18-decimal ERC-20 priced at `NAV / supply`, with a virtual share and a virtual dollar in both numerator and denominator (`VIRTUAL_SHARES = VIRTUAL_ASSETS = 1e18`), so the first depositor cannot be griefed and the share price starts at $1. Deposits round shares down; `sharePrice()` is the value of one LP token in USD. ``` sharesOut = usdIn x (supply + 1e18) / (NAV + 1e18) usdOut = sharesIn x (NAV + 1e18) / (supply + 1e18) ``` The `IndexVault` holds the same LP tokens as any other holder and values them at `sharePrice()`. ## Request, then keeper execute Deposits and redemptions are not instant swaps. The user (or the router, for a one-click account) calls `requestLiquidity(kind, amountIn, minOut)`. The account must be on the KYC allowlist. | kind | in | escrowed | out | executes when | | -------------- | --------------------------- | --------- | --------- | -------------------------------------------------------- | | `DepositUsdc` | USDC (min $10) | USDC | LP tokens | session not Closed (any time on synthetic pools) | | `DepositStock` | shares (min $10 at the bid) | shares | LP tokens | Regular session only | | `RedeemUsdc` | LP tokens | LP tokens | USDC | session not Closed, and only from idle USDC | | `RedeemStock` | LP tokens | LP tokens | shares | Regular session only, and only from unreserved inventory | The request is queued with a `minOut` slippage bound and a 3-day TTL (`requestTtl`). The keeper calls `executeRequests(n)`; each item runs in its own self-call, so one failing request is skipped and the batch continues. A request executes at the NAV of that moment: LP tokens are minted from `usd - fee`, redemptions pay `usd - fee`. If the out amount is below `minOut` the item reverts and stays queued. Execution is deferred at a closing mark on purpose: whoever knows Monday's gap could otherwise deposit or redeem against Friday's price. Requests queue while the market is closed and execute at the first live print. Once a request has passed its TTL without executing, the requester can `cancelRequest(id)` and reclaim the escrow. Only the requester (or the router acting for the account) can cancel; nobody else can touch the escrow. ### Idle USDC and the reserve floor ``` idleUsdc = USDC - NAV x reserveBps (15 %) ``` A USDC redemption or a parent withdrawal larger than the idle cash reverts with `ReserveBreached` and waits. The keeper's rebalance rule then sells shares through the issuer to raise cash (only during the NYSE session, see [Issuer orders](/protocol/issuer-orders.md)), and the redemption executes in a later cycle. `RedeemStock` pays shares the pool already holds and never needs the issuer, but it is limited to `stockBalance - reservedStock`: shares reserved for open longs cannot leave. ## Staking shares A user who has bought tokenized shares outright (the terminal can buy dShares from the issuer, see [Buy and stake stocks](/product/buy-and-stake-stocks.md)) can put them into the stock's pool. Staking is a `DepositStock` request: the shares are escrowed, and when the keeper executes them they are valued at the bid and LP tokens minted at NAV, minus the mint fee. Because the request adds stock to the pool, it earns the rebate whenever the pool is below its 60 % target, and can be free. From then on the staker holds LP tokens: a share of the whole pool, including its trading fees, borrow and funding income and the dividends the pool keeps (see [Dividends](/protocol/dividends.md)). Getting shares back is a `RedeemStock` request. ## The mint and burn fee `feeBps(kind, usdValue)` is charged on every executed request and stays in the pool as NAV for the remaining LPs (`yieldTotals.mintBurnFees`). On a synthetic pool the fee is flat: `baseFeeBps` (30 bps). On a share-backed pool the fee steers the pool toward its target split. The pool computes the stock weight before and after the request (`cur` and `next`, in bps of NAV, against a target of 60 % for stock requests or 40 % for USDC requests): ``` if the request moves the weight toward the target: fee = max(0, baseFeeBps - taxFeeBps x driftBefore / target) else: fee = baseFeeBps + min(taxFeeBps, taxFeeBps x avg(driftBefore, driftAfter) / target) ``` with `baseFeeBps = 30` and `taxFeeBps = 50`, so a request that rebalances the pool can cost nothing and one that unbalances it costs up to 80 bps. The fee is an integer number of basis points (the division is integer division). A worked case is in [Worked examples](/protocol/worked-examples.md#d-an-lp-deposit). ## Balance-sheet rules (share-backed pools) | rule | value | enforced where | | ------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | target stock weight | 60 % of NAV | keeper rebalances toward it; the fee curve steers requests toward it | | USDC reserve floor | 15 % of NAV | `idleUsdc`: redemptions, parent withdrawals and issuer buys cannot breach it | | max deployed | 70 % of NAV in stock plus pending orders | `placeIssuerOrder` (buy) reverts `DeployRatioExceeded` | | one issuer order | at most $200 000 | `placeIssuerOrder` reverts `OrderTooLarge` | | fill deviation | at most 3 % from the mid | `settleIssuerOrder` reverts `FillDeviation` | | minimum deposit | $10 | `requestLiquidity` | | request TTL | 3 days | cancellable after | | short cap | short open interest at most 80 % of the pool's USDC (50 % on meme pools) | `increaseShortOi` | | long cap | reserved shares at most the shares on hand; on a synthetic pool the same USDC cap as shorts, in tokens at the mid | `reserveInventory` | ## What an LP earns and bears Per pool, over a period: ``` LP return = 80 % of taker fees + 80 % of borrow and funding charges + traders' realised losses - traders' realised gains + the collateral left after the penalty on a full liquidation + mint and burn fees paid by other LPs + dividends on the shares the pool holds, net of the long/short pass-through + mark-to-market of the pool's own inventory (share-backed pools) - bad debt the insurance vault did not cover ``` The other 20 % of taker fees and of the borrow and funding leg goes 10 % to the insurance vault and 10 % to the treasury (the protocol fee, see [Governance and roles](/protocol/governance-and-roles.md#treasury-and-the-protocol-fee-switch)). Dividends are not part of the platform's revenue: `dividendFeeBps` is deployed at 0 and the whole net dividend is NAV. On a share-backed pool the LP is structurally long the stock (60 % target weight) on top of being short the traders' net skew; on a synthetic pool the LP is only short the skew. The pool's worst case is a sharp fall in the stock while traders are net short. `yieldTotals` on the pool records the cumulative trading fees, borrow and funding, trader P\&L, mint and burn fees and dividends it has booked, for the terminal's pool page. ## The index vault The `IndexVault` is one deposit spread across the share-backed pools at target weights (the local deployment uses AAPL 30 %, MSFT 25 %, NVDA 25 %, TSLA 20 %). It holds each child's LP tokens and mints its own token, `RWA-LP`, at its own NAV: ``` index NAV = sum over children of (LP tokens held x child sharePrice) + unescrowed USDC ``` A child is valued by the vault's own holding times the child's share price, never by the child's total value, and a paused child is still valued but never touched. Deposits and redemptions are requests like a pool's, with a $10 minimum and a 1-day TTL by default (`setParams` can change both). The keeper executes them: * a deposit is routed in full to the most under-weight enabled, unpaused child through `depositFromParent`, which mints child LP tokens at NAV with no fee; * a redemption pulls USDC from the most over-weight children that have idle cash, through `withdrawToParent`, again fee-free and capped at each child's idle USDC. If the children cannot raise the full amount the item reverts and waits. The keeper also calls `shift(from, to, amount, minSharesOut)` to move cash between children when weights drift. A shift is fee-free, bounded to `maxShiftBps` of index NAV (3 %) and rate-limited by `minRebalanceInterval` (1 hour by default). Both children must be unpaused. Parent hooks are refused while the child's market is closed, for the same reason as any other mint or burn at a mark. ## Pool wiring A pool is created by `PoolFactory.createPool(name, symbol, stock, priceAsset, poolConfig, marketConfig)` under ADMIN. The factory passes its stored wiring (registry, price feed, USDC, USD+, PositionManager, IndexVault, issuer adapter, insurance, treasury), deploys the BeaconProxy at a CREATE2 address salted by the symbol, and registers the market with the PositionManager. Synthetic pools pass `stock = 0` and a `priceAsset` key for the PriceFeed. Adding the pool to the index and setting its risk config are separate admin actions. --- # 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/pools-and-nav.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.