Funding Rate Facet (0.8.4)

Funding Rate Facet

The Funding Rate Facet is responsible for applying periodic funding rate adjustments to open positions. Funding rates reflect the cost or gain from holding a position over time and are applied in discrete epochs defined on a per‑symbol basis. This facet adjusts the open price of a quote and updates the available balances for both Party A and Party B accordingly.

Key Concepts:

  • Epoch Duration: Each symbol defines a funding epoch (epochDuration), which is the total period between funding rate applications.

  • Window Time: A designated time window (windowTime) within each epoch during which the funding rate can be applied.

  • Price Adjustments: The open price is adjusted by a factor derived from the funding rate. For long positions, a positive rate increases the price (and vice versa for short positions), while a negative rate applies the opposite adjustment.

  • Event Logging: The adjustment process emits a ChargeFundingRate event, capturing the key parameters involved in the funding rate charge.


Overview

The primary function in this facet is chargeFundingRate(). It is called with an array of quote IDs and corresponding funding rates. For each quote, the function:

  1. Verifies the UPnL data using a Muon signature.

  2. Retrieves funding epoch parameters (epochDuration and windowTime) from the symbol settings.

  3. Determines the appropriate funding payment timestamp based on the current block timestamp.

  4. Adjusts the open price of the quote by calculating a price difference based on the funding rate.

  5. Updates the available balances for Party A and Party B.

  6. Increments nonce counters to maintain state consistency.

After processing, the function emits a ChargeFundingRate event.


chargeFundingRate()

The chargeFundingRate function adjusts the open price of one or more quotes for a given Party A, based on an array of funding rates. It ensures that adjustments occur only within a designated time window (derived from the epoch duration and window time settings) and that the resulting balance changes do not render either party insolvent.

Function Signature:

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

Parameters:

  • partyA: The address of Party A whose quotes will be adjusted.

  • quoteIds: An array of quote IDs to be processed.

  • rates: An array of funding rates (as signed integers) corresponding to each quote.

  • upnlSig: A structure containing UPnL signature data for both parties; used for verification.

Example Usage:

// Example: Adjust funding rates for multiple quotes for Party A
address partyA = 0x...;
uint256[] memory quotes = new uint256[](2);
quotes[0] = 101;
quotes[1] = 102;
int256[] memory fundingRates = new int256[](2);
fundingRates[0] = 50000000000000000;  // 0.05 (in 1e18 precision)
fundingRates[1] = -30000000000000000; // -0.03 (in 1e18 precision)
PairUpnlSig memory upnlSig = /* obtain verified signature data */;
fundingRateFacet.chargeFundingRate(partyA, quotes, fundingRates, upnlSig);

Internal Logic:

  • UPnL Verification: The function starts by verifying the provided UPnL data using LibMuonFundingRate.verifyPairUpnl.

  • Funding Epoch Calculation: For each quote, it retrieves:

    • epochDuration from the symbol storage mapping SymbolStorage.layout().symbols[quote.symbolId].fundingRateEpochDuration

    • windowTime from the symbol storage mapping SymbolStorage.layout().symbols[quote.symbolId].fundingRateWindowTime

    It then computes the latestEpochTimestamp as:

    uint256 latestEpochTimestamp = (block.timestamp / epochDuration) * epochDuration;
  • Price Adjustment: A price difference is calculated:

    uint256 priceDiff = (quote.openedPrice * uint256(rates[i])) / 1e18;

    The open price is then adjusted (increased or decreased) based on the position type and the sign of the funding rate. The funding rate charge is embedded into the openedPrice of the quote.

  • Balance Updates: The available balances for Party A and Party B are updated based on the price difference and the open amount of the quote.

  • Final Checks: The function ensures that both parties remain solvent, then increments nonce counters in AccountStorage.


Epoch Timestamps and Window Time

For each quote, the function calculates the funding epoch details:

  • Epoch Duration: Determines how often funding adjustments are applied. Retrieved from the symbol configuration.

  • Window Time: Specifies the time window within an epoch when adjustments are allowed.

  • Latest Epoch Timestamp: Calculated as:

    uint256 latestEpochTimestamp = (block.timestamp / epochDuration) * epochDuration;
  • Paid Timestamp: Depending on the current block time relative to the window, the function determines whether to use the latest epoch timestamp or the next epoch timestamp as the effective payment timestamp.

require(block.timestamp >= nextEpochTimestamp - windowTime, "ChargeFundingFacet: Current timestamp is out of window");
require(nextEpochTimestamp > quote.lastFundingPaymentTimestamp, "ChargeFundingFacet: Funding already paid for this window");

Price Adjustments and Balance Updates

Once the appropriate funding payment timestamp is determined, the function:

Calculates Price Difference: For a positive funding rate:

  • Long positions: quote.openedPrice is increased.

  • Short positions: quote.openedPrice is decreased.

For a negative funding rate, the adjustments are reversed.

Updates Balances: The function deducts or credits the calculated monetary impact from Party A's and Party B's available balances.

Nonce Updates: Nonce counters for Party A and Party B are incremented to prevent replay attacks.


Funding Events

Event Emitted: After processing, the function emits the ChargeFundingRate event, defined as follows:

event ChargeFundingRate(address partyB, address partyA, uint256[] quoteIds, int256[] rates);
  • partyB: The address of the caller (typically Party B).

  • partyA: The address of Party A whose quotes are adjusted.

  • quoteIds: The array of quote IDs for which funding rates were charged.

  • rates: The corresponding array of funding rates applied.

This event provides a transparent log of all funding rate adjustments applied through the chargeFundingRate function.

Contract-Level Code Snippet:

contract FundingRateFacet is Accessibility, Pausable, IFundingRateFacet {
    function chargeFundingRate(
        address partyA,
        uint256[] memory quoteIds,
        int256[] memory rates,
        PairUpnlSig memory upnlSig
    ) external whenNotPartyBActionsPaused notLiquidatedPartyA(partyA) {
        FundingRateFacetImpl.chargeFundingRate(partyA, quoteIds, rates, upnlSig);
        emit ChargeFundingRate(msg.sender, partyA, quoteIds, rates);
    }
}

Last updated