View Facet Aggregate

The ViewFacet Aggregate provides read-only functions for querying pre-aggregated position and funding data. For example: if a party has 5,000 open positions spread across 50 symbols, the old system iterated through all 5,000 quotes. The aggregated system only iterates through the 50 symbols, since it maintains running totals per symbol. All functions are view and do not modify state.

This facet is new in v0.8.5. Previously, calculating uPnL required iterating through all individual quotes. With potentially thousands of quotes per party, this was computationally expensive. The aggregated system maintains running totals that are updated incrementally whenever positions are opened, closed, or funding is charged.

---

Overview

The ViewFacet Aggregate is organized into the following categories:

• Position Aggregates: Aggregated open amounts and average open prices per symbol, grouped by position type (LONG/SHORT).

• Funding Aggregates: Weighted paid funding and computed funding debt per symbol.

• Active Symbols: Lists of symbol IDs where a party has open positions, enabling efficient iteration.

• Paginated Batch Functions: Positions and funding debt across all active symbols in paginated calls.

• uPnL Data Functions: Convenience functions that return position data and funding debt together, providing everything needed for off-chain uPnL calculation in a single call.

---

Key Data Structures

struct AggregatedPositionAmount {
    PositionType positionType;  // LONG or SHORT
    uint256 aggregatedAmount;   // Total open position size
    uint256 avgOpenPrice;       // aggregatedNotional / aggregatedAmount
}

struct AggregatedPositionBySymbol {
    uint256 symbolId;
    PositionType positionType;
    uint256 aggregatedOpenAmount;
    uint256 avgOpenPrice;
}

struct AggregatedFundingDebtBySymbol {
    uint256 symbolId;
    PositionType positionType;
    int256 fundingDebt;         // Positive = party owes, negative = party is owed
}

struct UpnlData {
    uint256 symbolId;
    PositionType positionType;
    uint256 aggregatedAmount;
    uint256 avgOpenPrice;
    int256 fundingDebt;
}

---

uPnL Calculation Formula

With aggregated data, uPnL can be calculated off-chain per symbol:

LONG uPnL:  (currentPrice - avgOpenPrice) × aggregatedAmount / 1e18 - fundingDebt
SHORT uPnL: (avgOpenPrice - currentPrice) × aggregatedAmount / 1e18 - fundingDebt

Total uPnL = Σ(per-symbol uPnL for all active symbols)

PartyB's uPnL is the opposite of PartyA's (positions are mirrored).

---

Position Aggregate Functions

Per-symbol aggregated positions, returning LONG and SHORT amounts with average open prices.

Function	Parameters	Description
getPartyBAggregatedPositionBySymbol(partyB, symbolId)	PartyB, symbol	PartyB's global position for a symbol (across all PartyAs)
getPartyBAggregatedPositionBySymbolPerPartyA(partyB, partyA, symbolId)	PartyB, PartyA, symbol	PartyB's position with a specific PartyA
getPartyAAggregatedPositionBySymbolPerPartyB(partyA, partyB, symbolId)	PartyA, PartyB, symbol	PartyA's position with a specific PartyB

Each returns two AggregatedPositionAmount structs (one for LONG, one for SHORT).

---

Funding Aggregate Functions

Raw weighted paid funding values and computed funding debt.

Function	Parameters	Returns
getPartyAAggregatedFundingPerPartyB(partyA, partyB, symbolId, positionType)	PartyA, PartyB, symbol, type	weightedPaidFunding (raw aggregate)
getPartyBAggregatedFundingPerPartyA(partyB, partyA, symbolId, positionType)	PartyB, PartyA, symbol, type	weightedPaidFunding (raw aggregate)
getPartyBAggregatedFunding(partyB, symbolId, positionType)	PartyB, symbol, type	Global weightedPaidFunding (cross mode)
getPartyAAggregateFundingDebt(partyA, partyB, symbolId, positionType)	PartyA, PartyB, symbol, type	Computed funding debt (positive = owes)
getPartyBAggregateFundingDebt(partyB, partyA, symbolId, positionType)	PartyB, PartyA, symbol, type	Computed funding debt per PartyA
getPartyBGlobalAggregateFundingDebt(partyB, symbolId, positionType)	PartyB, symbol, type	Global funding debt (cross mode)

---

Active Symbols Functions

Lists of symbol IDs where a party has open positions. All paginated functions accept start and size parameters.

Function	Parameters	Returns
getPartyBActiveSymbolsCount(partyB)	PartyB	Count of globally active symbols
getPartyBActiveSymbols(partyB, start, size)	PartyB, pagination	Paginated array of symbol IDs
getPartyBActiveSymbolsCountPerPartyA(partyB, partyA)	PartyB, PartyA	Count of active symbols with this PartyA
getPartyBActiveSymbolsPerPartyA(partyB, partyA, start, size)	PartyB, PartyA, pagination	Paginated symbol IDs with this PartyA
getPartyAActiveSymbolsCountPerPartyB(partyA, partyB)	PartyA, PartyB	Count of active symbols with this PartyB
getPartyAActiveSymbolsPerPartyB(partyA, partyB, start, size)	PartyA, PartyB, pagination	Paginated symbol IDs with this PartyB

---

Paginated Batch Functions

These iterate through active symbols and return aggregated data in bulk. Each accepts start and size for pagination over the active symbols array. Results only include symbols/position types with non-zero open amounts.

Position Batches

Function	Parameters	Returns
getPartyBAggregatedPositionsByActiveSymbols(partyB, start, size)	PartyB, pagination	AggregatedPositionBySymbol[] — global positions
getPartyAAggregatedPositionsByActiveSymbolsPerPartyB(partyA, partyB, start, size)	PartyA, PartyB, pagination	AggregatedPositionBySymbol[] — PartyA's positions with PartyB
getPartyBAggregatedPositionsByActiveSymbolsPerPartyA(partyB, partyA, start, size)	PartyB, PartyA, pagination	AggregatedPositionBySymbol[] — PartyB's positions with PartyA

Funding Debt Batches

Function	Parameters	Returns
getPartyAAggregateFundingDebtByActiveSymbols(partyA, partyB, start, size)	PartyA, PartyB, pagination	AggregatedFundingDebtBySymbol[]
getPartyBAggregateFundingDebtByActiveSymbols(partyB, partyA, start, size)	PartyB, PartyA, pagination	AggregatedFundingDebtBySymbol[]
getPartyBGlobalAggregateFundingDebtByActiveSymbols(partyB, start, size)	PartyB, pagination	AggregatedFundingDebtBySymbol[] — cross mode

---

uPnL Data Functions (Recommended)

These convenience functions return both position data and funding debt in a single call, providing everything needed for off-chain uPnL calculation. They are the recommended entry point for integrators.

Function	Parameters	Returns	uPnL Formula
getPartyAUpnlData(partyA, partyB, start, size)	PartyA, PartyB, pagination	UpnlData[]	LONG: (price - avgOpen) × amount / 1e18 - debt
getPartyBUpnlData(partyB, partyA, start, size)	PartyB, PartyA, pagination	UpnlData[]	LONG: (avgOpen - price) × amount / 1e18 - debt
getPartyBGlobalUpnlData(partyB, start, size)	PartyB, pagination	UpnlData[]	Same as PartyB but across all PartyAs (cross mode)

Note that PartyB's position uPnL is the opposite of PartyA's (the counterparty relationship is mirrored).

Usage Example

let totalUpnl = 0n;
let start = 0;

while (true) {
    const data = await viewFacet.getPartyAUpnlData(partyA, partyB, start, 100);
    if (data.length === 0) break;

    for (const d of data) {
        const price = await getPrice(d.symbolId);
        const positionUpnl = d.positionType === LONG
            ? (price - d.avgOpenPrice) * d.aggregatedAmount / 1e18n
            : (d.avgOpenPrice - price) * d.aggregatedAmount / 1e18n;
        totalUpnl += positionUpnl - d.fundingDebt;
    }
    start += 100;
}