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

{% hint style="info" %}
**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.
  {% endhint %}

***

### 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:**

```solidity
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:**

```solidity
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:**

```solidity
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.

```solidity
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.

```solidity
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.

```solidity
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.

```solidity
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.

```solidity
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:**

```solidity
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.

```solidity
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).

```solidity
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.

```solidity
function removeSymbolTypeFromWhitelist(address partyB, uint256 symbolType) external;
```

**Events Emitted:** `RemoveSymbolTypeFromWhitelist(address partyB, uint256 symbolType)`

#### removeSymbolsFromWhitelist()

Removes specific symbols from a PartyB's whitelist.

```solidity
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).

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

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

#### removeSymbolsFromBlacklist()

Removes specific symbols from a PartyB's blacklist.

```solidity
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.