> ## 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.

# System Data Flows

> Sequence diagrams for oracle price publishing, keeper automation, fee distribution, LP deposits, and subgraph indexing — showing how off-chain services interact with onchain contracts

## Infrastructure Interactions

These diagrams show how off-chain services (publisher, keeper, gateway) interact with onchain contracts to maintain protocol liveness, distribute fees, and index data.

<Tabs>
  <Tab title="Oracle Pricing">
    The publisher fetches EUR/USD spot from Pyth, computes forward prices using interest rate parity, and publishes them onchain. The OracleModule applies safeguard checks before storing.

    ```mermaid theme={null}
    sequenceDiagram
        participant Pyth as Pyth Network
        participant Pub as Publisher (Rust)
        participant OM as OracleModule
        participant PM as PositionManager

        Pub->>Pyth: 1. Fetch Pyth-signed update bytes via Hermes API
        Pyth-->>Pub: EUR/USD VAA (spot ≈ 1.0850, publishTime)

        Note over Pub: 2. Compute forward per tenor<br/>F = S × (1 + pairForwardRateBps × t / (365d × 10000))<br/>1D: 1.0851, 1W: 1.0856, 1M: 1.0872

        Pub->>OM: 3. publishRound(pairId, pythUpdateData[], fixings[], prices[], roundIds[]) payable

        Note over OM: 4. parsePriceFeedUpdates → verified spot<br/>lastPublishedSpot[pairId] = verifiedSpot<br/>emit SpotPublished

        Note over OM: 5. Per-tenor safeguard checks<br/>- minUpdateSpacing (10s)<br/>- maxOracleMove (2% per update)<br/>- maxDeviation vs prior (0.5%)<br/>- anchor-deviation vs lastPublishedSpot × IRP carry (1.5%)

        Note over OM: 6. Store in forwardRounds[pairId][fixingTimestamp]<br/>emit ForwardRoundPublished per tenor

        PM->>OM: 6. getForwardPrice(pairId, tenor)
        OM-->>PM: forward price for position entry

        Note over Pub: Loop: every 30s
    ```

    For safeguard parameters and deviation thresholds, see [Oracle Safeguards](/protocol/oracle-safeguards). For the forward pricing formula, see [Oracle & Forward Pricing](/protocol/oracle-pricing).
  </Tab>

  <Tab title="Keeper Automation">
    The keeper polls for matured and liquidatable positions, then processes them in batches. All settlement and liquidation functions are permissionless.

    ```mermaid theme={null}
    sequenceDiagram
        participant K as Keeper (Rust)
        participant SE as SettlementEngine
        participant PM as PositionManager

        K->>PM: 1. getPositionStats(pairId)
        PM-->>K: maturedIds[], liquidatableIds[]

        K->>SE: 2. batchSettlePositions(maturedIds[])
        SE->>PM: settle each position
        PM-->>SE: position closed
        SE-->>K: batch complete

        K->>SE: 3. batchLiquidatePositions(liquidatableIds[])
        SE->>PM: liquidate each position
        PM-->>SE: position liquidated
        SE-->>K: batch complete

        Note over K: Loop: every block time<br/>Batch size: up to 50 positions (~10M gas)
    ```

    For operational details, see [Keeper Automation](/deploy/keeper-automation).
  </Tab>

  <Tab title="Fee Distribution">
    Trading fees and liquidation penalties are split between treasury and pool via FeeLib. Oracle fees go directly to the oracle fee receiver.

    ```mermaid theme={null}
    sequenceDiagram
        participant TC as Triggering Contract
        participant FL as FeeLib (Library)
        participant TR as Treasury (30%)
        participant PV as PoolVault (70%)

        TC->>FL: distributeFee(tradingFee or liqPenalty)

        FL->>TR: treasury share = fee × 3000 / 10000
        FL->>PV: pool share = fee × 7000 / 10000

        Note over PV: Pool share increases<br/>vault totalAssets,<br/>raising LP share price

        Note over TC: Oracle fee (0.10 USDC)<br/>→ oracleFeeReceiver<br/>(direct, not via FeeLib)
    ```

    For fee formulas and parameters, see [Fee Structure](/protocol/fees). For LP share price impact, see [Fee Distribution](/deploy/fee-distribution).
  </Tab>

  <Tab title="LP Deposit">
    LPs deposit USDC into the ERC-4626 PoolVault. Shares are minted proportional to existing total assets, making fee accrual automatic.

    ```mermaid theme={null}
    sequenceDiagram
        participant LP as LP Wallet
        participant PV as PoolVault (ERC-4626)
        participant USDC as USDC Token

        LP->>USDC: 1. approve(PoolVault, amount)

        LP->>PV: 2. deposit(assets, receiver)
        PV->>USDC: 3. transferFrom(LP, PoolVault, amount)
        USDC-->>PV: USDC received

        Note over PV: 4. Mint shares<br/>shares = assets × totalShares / totalAssets

        PV-->>LP: vault shares minted
    ```

    For vault mechanics and share price calculation, see [Vault Mechanics](/deploy/vault-mechanics) and [Share Price](/deploy/share-price).
  </Tab>

  <Tab title="Subgraph Indexing">
    Contracts emit events that Graph Node processes via handler mappings. Entities are stored and queryable via GraphQL through the Gateway API.

    ```mermaid theme={null}
    sequenceDiagram
        participant C as Contracts (onchain)
        participant GN as Graph Node (Indexer)
        participant SS as Subgraph Store
        participant GW as Gateway API (CF Worker)

        C->>GN: 1. Emit events (PositionOpened, Deposit, ForwardPublished, ...)

        GN->>SS: 2. Process via handler mappings

        Note over SS: 3. Store entities<br/>Position, Account, PoolState,<br/>OracleRound, DailyStats

        GW->>SS: 4. GraphQL query
        SS-->>GW: 5. JSON response

        Note over GW: Gateway reads from<br/>Subgraph (GraphQL) + RPC
    ```

    For subgraph schema and query examples, see [Subgraph Overview](/build/subgraph-overview) and [Query Examples](/build/subgraph-queries).
  </Tab>
</Tabs>

## Next Steps

<Columns cols={3}>
  <Card title="Trading Flows" icon="arrow-right-arrow-left" href="/protocol/trading-flows">
    Position open, increase, reduce, margin adjust, and settlement sequences.
  </Card>

  <Card title="Keeper Automation" icon="robot" href="/deploy/keeper-automation">
    Operational details for publisher and keeper services.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/nile-markets/architecture">
    System overview, contract registry, and technology stack.
  </Card>
</Columns>