SymbolControl

The SymbolControl Facet manages the creation and configuration of trading symbols (e.g., BTCUSD, ETHUSD) and controls which symbols each PartyB is allowed to trade. It provides admin functions for symbol parameter management and a flexible listing system (whitelist/blacklist) that PartyBs can self-manage.

New in 0.8.5:

• Symbol Types: Symbols can now be assigned a category type (e.g., crypto, forex, lowcap). This is stored in a separate mapping (symbolTypes) rather than modifying the original Symbol struct, preserving backward compatibility. PartyBs can whitelist entire symbol categories rather than individual symbols.

• PartyB Symbol Listing: A comprehensive whitelist/blacklist system allows PartyBs (or admins with PARTY_B_MANAGER_ROLE) to control which symbols they accept quotes for. Whitelisting can operate at both the individual symbol level and the symbol type (category) level. Blacklisting provides explicit exclusions that take priority.

---

Overview

The SymbolControl Facet provides the following key functionalities:

• Add Symbols: Create new trading symbols with their parameters (minimum quote value, trading fee, max leverage, funding rate settings).

• Configure Symbols: Update individual symbol parameters (funding state, validation state, max leverage, acceptable values, trading fee).

• Symbol Types: Assign and update category types for symbols, enabling category-level access control.

• PartyB Whitelisting: PartyBs whitelist specific symbols or entire symbol categories they are willing to trade.

• PartyB Blacklisting: PartyBs blacklist specific symbols they want to exclude, with conflict prevention against whitelisted symbols.

---

Adding Symbols

addSymbol()

Adds a single new trading symbol to the protocol.

Function Signature:

function addSymbol(
    string memory name,
    uint256 minAcceptableQuoteValue,
    uint256 minAcceptablePortionLF,
    uint256 tradingFee,
    uint256 maxLeverage,
    uint256 fundingRateEpochDuration,
    uint256 fundingRateWindowTime
) public onlyRole(SYMBOL_MANAGER_ROLE);

Parameters:

• name: Human-readable symbol name (e.g., "BTCUSD").

• minAcceptableQuoteValue: Minimum notional value required for a quote on this symbol (in collateral units).

• minAcceptablePortionLF: Minimum portion reserved for liquidation fees (in 1e18 precision).

• tradingFee: Base trading fee percentage (in 1e18 precision). Acts as the default when no affiliate-specific fee is set.

• maxLeverage: Maximum leverage multiplier allowed (e.g., 100 for 100x).

• fundingRateEpochDuration: Time interval in seconds between funding rate calculations.

• fundingRateWindowTime: Time window in seconds during which funding rate can be applied. Must be less than epochDuration / 2.

Access: Requires SYMBOL_MANAGER_ROLE.

Events Emitted:

• AddSymbol(uint256 symbolId, string name, uint256 minAcceptableQuoteValue, uint256 minAcceptablePortionLF, uint256 tradingFee, uint256 maxLeverage, uint256 fundingRateEpochDuration, uint256 fundingRateWindowTime)

addSymbolsWithType()

Batch adds multiple symbols, each with an assigned symbol type, in a single transaction.

Function Signature:

function addSymbolsWithType(SymbolWithType[] memory symbolsWithType) external onlyRole(SYMBOL_MANAGER_ROLE);

Parameters:

• symbolsWithType: Array of SymbolWithType structs containing all symbol parameters plus the symbolType category identifier.

Access: Requires SYMBOL_MANAGER_ROLE.

addSymbols()

Batch adds multiple symbols without type assignment.

Function Signature:

function addSymbols(Symbol[] memory symbols) external onlyRole(SYMBOL_MANAGER_ROLE);

Parameters:

• symbols: Array of Symbol structs containing the parameters for each symbol.

Access: Requires SYMBOL_MANAGER_ROLE.

---

Configuring Symbols

All configuration functions require SYMBOL_MANAGER_ROLE.

setSymbolFundingState()

Updates the funding rate timing parameters for a symbol.

function setSymbolFundingState(uint256 symbolId, uint256 fundingRateEpochDuration, uint256 fundingRateWindowTime) external;

Events Emitted: SetSymbolFundingState(uint256 symbolId, uint256 fundingRateEpochDuration, uint256 fundingRateWindowTime)

setSymbolValidationState()

Enables or disables trading for a symbol. Invalid symbols cannot be used for new quotes.

function setSymbolValidationState(uint256 symbolId, bool isValid) external;

Events Emitted: SetSymbolValidationState(uint256 symbolId, bool oldState, bool newState)

setSymbolMaxLeverage()

Updates the maximum leverage allowed for a symbol.

function setSymbolMaxLeverage(uint256 symbolId, uint256 maxLeverage) external;

Events Emitted: SetSymbolMaxLeverage(uint256 symbolId, uint256 oldMaxLeverage, uint256 newMaxLeverage)

setSymbolAcceptableValues()

Updates minimum quote value and liquidation fee requirements for a symbol.

function setSymbolAcceptableValues(uint256 symbolId, uint256 minAcceptableQuoteValue, uint256 minAcceptablePortionLF) external;

Events Emitted: SetSymbolAcceptableValues(uint256 symbolId, uint256 oldMinQuoteValue, uint256 oldMinPortionLF, uint256 newMinQuoteValue, uint256 newMinPortionLF)

setSymbolTradingFee()

Updates the base trading fee for a symbol. This fee applies when no affiliate-specific fee is configured.

function setSymbolTradingFee(uint256 symbolId, uint256 tradingFee) external;

Events Emitted: SetSymbolTradingFee(uint256 symbolId, uint256 oldTradingFee, uint256 newTradingFee)

---

Symbol Types

Symbol types allow categorizing symbols (e.g., type 1 = major crypto, type 2 = lowcap, type 3 = forex) and controlling PartyB access at the category level. Types are stored in a separate symbolTypes mapping for backward compatibility.

setSymbolTypes()

Batch updates category types for multiple symbols.

Function Signature:

function setSymbolTypes(uint256[] calldata symbolIds, uint256[] calldata symbolTypes) external onlyRole(SYMBOL_MANAGER_ROLE);

Parameters:

• symbolIds: Array of symbol IDs to update.

• symbolTypes: Array of category identifiers corresponding to each symbol.

Access: Requires SYMBOL_MANAGER_ROLE.

Events Emitted: SetSymbolType(uint256 symbolId, uint256 symbolType) — per symbol

---

PartyB Symbol Listing

PartyBs control which symbols they accept quotes for through a whitelist/blacklist system. These functions can be called either by the PartyB itself or by an admin with PARTY_B_MANAGER_ROLE.

whitelistSymbolType()

Whitelists an entire category of symbols for a PartyB, allowing them to accept quotes for all symbols in that category.

function whitelistSymbolType(address partyB, uint256 symbolType) external;

Events Emitted: WhitelistSymbolType(address partyB, uint256 symbolType)

whitelistSymbols()

Whitelists specific individual symbols for a PartyB. Cannot whitelist a symbol that is currently blacklisted (conflict prevention).

function whitelistSymbols(address partyB, uint256[] calldata symbolIds) external;

Events Emitted: WhitelistSymbols(address partyB, uint256[] symbolIds)

removeSymbolTypeFromWhitelist()

Removes a symbol category from a PartyB's whitelist.

function removeSymbolTypeFromWhitelist(address partyB, uint256 symbolType) external;

Events Emitted: RemoveSymbolTypeFromWhitelist(address partyB, uint256 symbolType)

removeSymbolsFromWhitelist()

Removes specific symbols from a PartyB's whitelist.

function removeSymbolsFromWhitelist(address partyB, uint256[] calldata symbolIds) external;

Events Emitted: RemoveSymbolsFromWhitelist(address partyB, uint256[] symbolIds)

blacklistSymbols()

Blacklists specific symbols for a PartyB, explicitly preventing them from accepting quotes for those symbols. Cannot blacklist a symbol that is currently whitelisted (conflict prevention).

function blacklistSymbols(address partyB, uint256[] calldata symbolIds) external;

Events Emitted: BlacklistSymbols(address partyB, uint256[] symbolIds)

removeSymbolsFromBlacklist()

Removes specific symbols from a PartyB's blacklist.

function removeSymbolsFromBlacklist(address partyB, uint256[] calldata symbolIds) external;

Events Emitted: RemoveSymbolsFromBlacklist(address partyB, uint256[] symbolIds)

---

Access Control for Listing Functions

All whitelist and blacklist functions use a shared authorization check: the caller must either be the PartyB itself or hold the PARTY_B_MANAGER_ROLE. This allows PartyBs to self-manage their symbol preferences while retaining admin override capability.