> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nilemarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Share Price Calculation

> sharePrice = poolEquity / totalSupply where poolEquity = totalAssets + poolPnl — rises from trader losses and fee accrual, falls from trader profits, the single metric for LP performance

The share price is the single most important metric for liquidity providers. It represents the USDC value
of each vault share token and reflects the cumulative performance of the pool over time. Understanding
what drives share price changes is essential for evaluating LP returns and risk.

## Formula

```
sharePrice = poolEquity / totalSupply
```

Where:

* **poolEquity** = `totalAssets + poolPnl` (**Computed**: derived at query time from vault state and aggregate PnL)
* **totalAssets** = USDC balance held by the vault contract (**Onchain**: ERC-4626 vault balance)
* **poolPnl** = `-aggregateTraderPnl` (zero-sum: pool PnL is the negative of all trader PnL combined, **Computed**: derived from open positions)
* **totalSupply** = total vault share tokens outstanding (**Onchain**: ERC-20 total supply)

<Note>
  When `totalSupply` is zero (no shares outstanding), the share price defaults to 1.0. The first depositor
  receives shares at a 1:1 ratio with their USDC deposit.
</Note>

## What Drives Share Price Up

Three sources of income increase pool equity and therefore share price:

<Columns cols={3}>
  <Card title="Trader Losses" icon="arrow-trend-down">
    When traders lose money on their positions, the pool gains. Every dollar of trader loss is a dollar of
    pool gain. This is the primary driver of share price increases.
  </Card>

  <Card title="Trading Fees" icon="receipt">
    70% of all trading fees flow to the pool (the remaining 30% goes to the protocol treasury). Fees are
    collected on every open, increase, settlement, close, and reduce operation.
  </Card>

  <Card title="Penalty Fees" icon="triangle-exclamation">
    70% of liquidation penalties accrue to the pool. When a position is liquidated, the penalty fee on
    top of the standard trading fee provides additional income to the pool.
  </Card>
</Columns>

<Info>
  Oracle fees (flat per-price-read fees) are also split 70/30, with 70% going to the pool. While smaller
  in magnitude than trading fees, they accumulate with every forward price lookup.
</Info>

## What Drives Share Price Down

<Columns cols={2}>
  <Card title="Trader Profits" icon="arrow-trend-up">
    When traders profit, the pool pays. Large collective trader gains reduce pool equity and share price.
    This is the primary risk for LPs.
  </Card>

  <Card title="Bad Debt Absorption" icon="skull-crossbones">
    If a position's losses exceed its locked margin (bad debt), the pool absorbs the shortfall. The risk
    management system is designed to minimize this through timely liquidation, but it can occur in extreme
    market moves.
  </Card>
</Columns>

## Pool Equity Breakdown

The pool equity formula has two components that move independently:

```
poolEquity = totalAssets + poolPnl
```

### totalAssets

The actual USDC balance in the vault contract. Increases when:

* LPs deposit USDC
* Fees are distributed to the pool
* Trader losses are realized (USDC transferred into the vault)

Decreases when:

* LPs withdraw USDC
* Trader profits are paid out (USDC transferred from the vault)

### poolPnl

The unrealized component, computed as the negative of aggregate trader PnL across all open positions.
This value fluctuates as forward prices move but only materializes when positions settle, close, or
are liquidated.

<Warning>
  Pool equity is clamped to zero -- it cannot go negative. If aggregate trader profits exceed total pool
  assets, the share price reaches zero and LPs have effectively lost their entire deposit. The protocol's
  risk caps, margin requirements, and liquidation mechanisms are the primary defenses against this scenario.
</Warning>

## Example Scenarios

The following scenarios illustrate how share price evolves over time. All examples start from the same
initial state.

<Tabs>
  <Tab title="Initial State">
    | Metric          | Value            |
    | --------------- | ---------------- |
    | Total Assets    | 1,000,000 USDC   |
    | Pool PnL        | 0                |
    | Pool Equity     | 1,000,000 USDC   |
    | Total Supply    | 1,000,000 shares |
    | **Share Price** | **1.000000**     |
  </Tab>

  <Tab title="After Trader Loss + Fees">
    A trader closes a position with a 10,000 USDC loss. Trading fees of 500 USDC are also collected
    (70% = 350 USDC to pool, 30% = 150 USDC to treasury).

    | Metric          | Value                                     |
    | --------------- | ----------------------------------------- |
    | Total Assets    | 1,000,000 + 10,000 + 350 = 1,010,350 USDC |
    | Pool PnL        | 0 (position is now closed)                |
    | Pool Equity     | 1,010,350 USDC                            |
    | Total Supply    | 1,000,000 shares                          |
    | **Share Price** | **1.010350**                              |

    The share price increased by approximately 1.035%.
  </Tab>

  <Tab title="After Large Trader Profit">
    Continuing from the previous state, another trader closes with a 50,000 USDC profit.

    | Metric          | Value                             |
    | --------------- | --------------------------------- |
    | Total Assets    | 1,010,350 - 50,000 = 960,350 USDC |
    | Pool PnL        | 0 (position is now closed)        |
    | Pool Equity     | 960,350 USDC                      |
    | Total Supply    | 1,000,000 shares                  |
    | **Share Price** | **0.960350**                      |

    The share price decreased. LPs have a net unrealized loss of approximately 3.97% from the initial state.
  </Tab>

  <Tab title="With Unrealized PnL">
    Back to initial state. Suppose open positions have aggregate unrealized PnL of +20,000 USDC
    (traders are collectively profitable).

    | Metric          | Value                              |
    | --------------- | ---------------------------------- |
    | Total Assets    | 1,000,000 USDC                     |
    | Pool PnL        | -20,000 (negative of trader gains) |
    | Pool Equity     | 980,000 USDC                       |
    | Total Supply    | 1,000,000 shares                   |
    | **Share Price** | **0.980000**                       |

    The share price reflects unrealized losses even before positions settle.
  </Tab>
</Tabs>

## Fee Contribution to Share Price

Fees provide a consistent upward pressure on share price, partially offsetting trader profit payouts.
The pool receives 70% of all collected fees:

| Fee Type            | Typical Rate                  | Pool Share                |
| ------------------- | ----------------------------- | ------------------------- |
| Trading fee         | 5 bps (0.05%) of notional     | 70% = 3.5 bps effective   |
| Liquidation penalty | 30 bps (0.30%) of notional    | 70% = 21 bps effective    |
| Oracle fee          | 0.10 USDC flat per price read | 70% = 0.07 USDC effective |

<Tip>
  For a pool with balanced long and short exposure, the fee income alone provides positive expected returns
  for LPs, even if aggregate trader PnL is zero. The higher the trading volume, the more fees accumulate.
</Tip>

## PnL Application Mechanics

When a position is settled, closed, or liquidated, the SettlementEngine calls `applyPnl(int256 pnl)` on
the PoolVault:

<AccordionGroup>
  <Accordion title="Positive PnL (pool gains)">
    When `pnl > 0`, the pool has gained from a trader loss. The USDC from the trader's locked margin
    (minus fees) flows into the vault, increasing `totalAssets`. Pool equity increases. Share price
    increases.
  </Accordion>

  <Accordion title="Negative PnL (pool pays)">
    When `pnl < 0`, the pool must pay a profitable trader. USDC is transferred out of the vault via
    `transferOut()`, decreasing `totalAssets`. Pool equity decreases. Share price decreases.
  </Accordion>

  <Accordion title="Zero PnL">
    When `pnl == 0`, only fees are distributed. The pool receives its 70% fee share, resulting in a
    small share price increase.
  </Accordion>
</AccordionGroup>

## Deposits and Share Price

New deposits do **not** change the share price. When an LP deposits USDC:

```
sharesReceived = depositAmount * totalSupply / poolEquity
```

Both `totalAssets` (numerator component) and `totalSupply` (denominator) increase proportionally, leaving
the share price unchanged. Existing LPs are not diluted.

Similarly, withdrawals do not change the share price for the same reason -- both numerator and denominator
decrease proportionally.

## Related Pages

<Columns cols={3}>
  <Card title="ERC-4626 Vault" icon="vault" href="/deploy/vault-mechanics">
    How the vault operates as the counterparty to all positions.
  </Card>

  <Card title="Fee Distribution" icon="money-bill-transfer" href="/deploy/fee-distribution">
    Detailed breakdown of fee types, collection, and distribution.
  </Card>

  <Card title="Pool Utilization" icon="gauge-high" href="/deploy/pool-utilization">
    How utilization caps protect pool liquidity.
  </Card>
</Columns>