Funding Rate Facet

The FundingRate Facet manages funding fee mechanics for perpetual positions. Funding fees are the mechanism that keeps perpetual prices aligned with spot prices — at fixed intervals (epochs), one side of the market (long or short) pays the other. The underlying logic is implemented in the FundingRateFacetImpl library.

In v0.8.5, a new accumulated funding rate system is introduced alongside the legacy per-quote charging system. The two systems coexist, with each (symbol, PartyB) pair using one or the other. The key changes:

• Accumulated Weighted Average: Instead of charging every position individually each epoch, the new system tracks a running weighted average rate per symbol. Funding is calculated when actually needed, based on how long a position has been open and what rates were in effect.

• Price-Adjusted Rates: Funding rates are pre-multiplied by the market price at the time of setting, eliminating the need to fetch prices again when charging. This reduces gas costs.

• Aggregate Tracking: Total funding debt is computed in O(symbols) instead of O(quotes) using aggregate weightedPaidFunding counters, enabling efficient solvency checks even with thousands of positions.

• Direct Balance Charging: Funding is now deducted directly from allocated balances (enabled by settleUpnl to realize unrealized PnL when needed), rather than adjusting position open prices.

• Epoch Duration Flexibility: PartyBs can change epoch durations per symbol. Rates are automatically rescaled when durations change.

---

Overview

The FundingRate Facet provides the following key functionalities:

• Legacy Funding Charging: PartyB charges funding rates per-quote using Muon uPnL signatures (chargeFundingRate).

• Set Funding Fees: PartyB sets current long and/or short funding rates for symbols, pre-multiplied by market price (setFundingFee, setLongFundingFee, setShortFundingFee).

• Set Epoch Durations: PartyB configures the funding epoch duration per symbol, activating the accumulated system for that symbol (setEpochDurations).

• Update Accumulated Funding: PartyB advances the accumulated weighted average with new rates and market prices (updateAccumulatedFundingFee).

• Charge Accumulated Funding: PartyB charges accumulated funding fees for a batch of PartyA's positions, deducting directly from allocated balances (chargeAccumulatedFundingFee).

---

chargeFundingRate()

Legacy funding method. PartyB charges funding rates for specific quotes belonging to a given PartyA. The funding is applied by adjusting position economics. Requires a Muon uPnL signature to verify both parties remain solvent after charging.

Function Signature:

function chargeFundingRate(
    address partyA,
    uint256[] memory quoteIds,
    int256[] memory rates,
    PairUpnlSig memory upnlSig
) external whenNotPartyBActionsPaused notLiquidatedPartyA(partyA);

Parameters:

• partyA: The address of PartyA whose positions are being charged.

• quoteIds: An array of quote IDs to charge funding for.

• rates: An array of funding rates corresponding to each quote.

• upnlSig: The Muon signature containing uPnL of both parties for solvency verification.

Access: Only callable by PartyB.

Events Emitted:

• ChargeFundingRate(address partyB, address partyA, uint256[] quoteIds, int256[] rates)

---

setFundingFee()

Sets both long and short funding rates for the specified symbols. Rates are provided in 18 decimals and are pre-multiplied by the market price internally for gas-efficient charging later. This updates the currentLongRate and currentShortRate for each symbol under the calling PartyB.

Function Signature:

function setFundingFee(
    uint256[] memory symbolIds,
    int256[] memory longFees,
    int256[] memory shortFees,
    int256[] memory marketPrices
) external whenNotPartyBActionsPaused onlyPartyB;

Parameters:

• symbolIds: An array of symbol IDs to set rates for.

• longFees: Funding fees for long positions (in 18 decimals).

• shortFees: Funding fees for short positions (in 18 decimals).

• marketPrices: Current market prices used to convert rates to price-adjusted values.

Access: Only callable by PartyB.

Events Emitted:

• SetLongFundingFee(uint256[] symbolIds, int256[] longFees, int256[] marketPrices, address partyB)

• SetShortFundingFee(uint256[] symbolIds, int256[] shortFees, int256[] marketPrices, address partyB)

---

setLongFundingFee()

Sets only the long funding rates for the specified symbols.

Function Signature:

function setLongFundingFee(
    uint256[] memory symbolIds,
    int256[] memory longFees,
    int256[] memory marketPrices
) external whenNotPartyBActionsPaused onlyPartyB;

Parameters:

• symbolIds: An array of symbol IDs.

• longFees: Funding fees for long positions (in 18 decimals).

• marketPrices: Current market prices for price-adjusted conversion.

Access: Only callable by PartyB.

Events Emitted:

• SetLongFundingFee(uint256[] symbolIds, int256[] longFees, int256[] marketPrices, address partyB)

---

setShortFundingFee()

Sets only the short funding rates for the specified symbols.

Function Signature:

function setShortFundingFee(
    uint256[] memory symbolIds,
    int256[] memory shortFees,
    int256[] memory marketPrices
) external whenNotPartyBActionsPaused onlyPartyB;

Parameters:

• symbolIds: An array of symbol IDs.

• shortFees: Funding fees for short positions (in 18 decimals).

• marketPrices: Current market prices for price-adjusted conversion.

Access: Only callable by PartyB.

Events Emitted:

• SetShortFundingFee(uint256[] symbolIds, int256[] shortFees, int256[] marketPrices, address partyB)

---

setEpochDurations()

Sets the epoch duration for funding rate calculations on the specified symbols. Setting an epoch duration for a symbol activates the accumulated funding system for that (symbol, PartyB) pair. All pending funding under the legacy system should be charged before calling this.

When changing an existing epoch duration, all stored rates are automatically rescaled to match the new timescale (e.g., a 0.04% rate per 8 hours becomes 0.005% per 1 hour), preserving economic equivalence.

Function Signature:

function setEpochDurations(uint256[] memory symbolIds, uint256[] memory durations) external whenNotPartyBActionsPaused onlyPartyB;

Parameters:

• symbolIds: An array of symbol IDs.

• durations: An array of epoch durations (in seconds) for each symbol.

Access: Only callable by PartyB.

Example:

// Set 8-hour epochs for two symbols
uint256[] memory ids = new uint256[](2);
ids[0] = 1; ids[1] = 2;
uint256[] memory durations = new uint256[](2);
durations[0] = 28800; durations[1] = 28800; // 8 hours in seconds
symmDiamond.setEpochDurations(ids, durations);

Events Emitted:

• SetEpochDuration(uint256[] symbolIds, uint256[] durations, address partyB)

---

updateAccumulatedFundingFee()

Advances the accumulated weighted average funding rates for the specified symbols with new long and short rates. This is the core update function of the accumulated system — it blends the new rates into the running average weighted by the number of epochs elapsed.

For example, if the accumulated average over 2 epochs is 0.05% and the new rate of 0.03% applies for 3 additional epochs, the new average becomes (0.05% × 2 + 0.03% × 3) / 5 = 0.038%.

Rates are pre-multiplied by market prices for gas-efficient charging.

Function Signature:

function updateAccumulatedFundingFee(
    uint256[] memory symbolIds,
    int256[] memory longRates,
    int256[] memory shortRates,
    int256[] memory marketPrices
) external whenNotPartyBActionsPaused onlyPartyB;

Parameters:

• symbolIds: An array of symbol IDs.

• longRates: New funding rates for long positions (in 18 decimals).

• shortRates: New funding rates for short positions (in 18 decimals).

• marketPrices: Current market prices for price-adjusted conversion.

Access: Only callable by PartyB.

Events Emitted:

• UpdateAccumulatedFundingFee(uint256[] symbolIds, int256[] longRates, int256[] shortRates, int256[] marketPrices, address partyB)

---

chargeAccumulatedFundingFee()

Charges accumulated funding fees for a batch of PartyA's positions with a specific PartyB. For each position, the function calculates the total accumulated funding since the position was opened, subtracts what has already been paid, and deducts the difference directly from allocated balances. Requires a Muon uPnL signature to verify both parties remain solvent after charging.

The aggregate weightedPaidFunding counters are updated incrementally, maintaining the O(symbols) efficiency for future solvency calculations.

Function Signature:

function chargeAccumulatedFundingFee(
    address partyA,
    address partyB,
    uint256[] memory quoteIds,
    PairUpnlSig memory upnlSig
) external whenNotPartyBActionsPaused notLiquidatedPartyA(partyA) notLiquidatedPartyB(partyB, partyA) onlyPartyB;

Parameters:

• partyA: The address of PartyA whose positions are being charged.

• partyB: The address of PartyB charging the funding.

• quoteIds: An array of quote IDs to charge accumulated funding for.

• upnlSig: The Muon signature containing uPnL of both parties for solvency verification.

Access: Only callable by PartyB. Neither party can be in liquidation.

Example:

// PartyB charges accumulated funding for a batch of PartyA's positions
symmioDiamond.chargeAccumulatedFundingFee(partyAAddress, partyBAddress, quoteIds, upnlSig);

Events Emitted:

• ChargeAccumulatedFundingFee(address partyA, address partyB, uint256[] quoteIds, address caller)