# Control Facet (0.8.4)

## Control Facet (0.8.4)

The **Control Facet** is an administrative interface within the SYMM system. It allows authorized users to perform essential management tasks such as transferring ownership, setting and revoking roles, registering or deregistering Party Bs and affiliates, and configuring various operational parameters. Centralizing these functions ensures that administrative actions are executed securely and efficiently.

***

## Ownership & Role Management

### transferOwnership()

**Description:**\
Transfers Diamond contract ownership to a new address. Only the current owner can call this function.

**Function Signature:**

```solidity
function transferOwnership(address owner) external onlyOwner;
```

**Parameters:**

* `owner`: The address of the new owner (must not be the zero address).

**Example:**

```solidity
diamond.transferOwnership(newOwnerAddress);
```

**Events Emitted:**

* `OwnershipTransferred(previousOwner, _newOwner)`

***

### setAdmin()

**Description:**\
Grants the admin role to a specified user. This function is restricted to the current owner.

**Function Signature:**

```solidity
function setAdmin(address user) external onlyOwner;
```

**Parameters:**

* `user`: The address of the user to be granted admin privileges.

**Example:**

```solidity
diamond.setAdmin(adminUserAddress);
```

**Events Emitted:**

* `RoleGranted(DEFAULT_ADMIN_ROLE, user)`

***

### grantRole()

Grants a specific role to a user. For example, this can be used to assign roles like `LIQUIDATOR_ROLE` or `MUON_SETTER_ROLE`.\
\&#xNAN;*Note: For `LIQUIDATOR_ROLE`, additional checks ensure that a Party A without pending quotes or open positions is assigned.*

**Function Signature:**

```solidity
function grantRole(address user, bytes32 role) external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Parameters:**

* `user`: The address of the user.
* `role`: The role identifier (e.g., LIQUIDATOR\_ROLE).

**Example:**

```solidity
diamond.grantRole(userAddress, LibAccessibility.LIQUIDATOR_ROLE);
```

**Events Emitted:**

* `RoleGranted(role, user)`

***

### revokeRole()

Revokes a specific role from a user.

**Function Signature:**

```solidity
function revokeRole(address user, bytes32 role) external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Parameters:**

* `user`: The address of the user.
* `role`: The role identifier to revoke.

**Example:**

```solidity
diamond.revokeRole(userAddress, LibAccessibility.LIQUIDATOR_ROLE);
```

**Events Emitted:**

* `RoleRevoked(role, user)`

***

## Registration & Affiliate Management

### registerPartyB()

Registers a Party B address in the system. Only callable by an account with the `PARTY_B_MANAGER_ROLE`.

**Function Signature:**

```solidity
function registerPartyB(address partyB) external onlyRole(PARTY_B_MANAGER_ROLE);
```

**Parameters:**

* `partyB`: The address to register (must not be the zero address).

**Example:**

```solidity
diamond.registerPartyB(partyBAddress);
```

**Events Emitted:**

* `RegisterPartyB(partyB)`

***

### deregisterPartyB()

Deregisters a Party B address. Requires the index of the Party B in the stored list.

**Function Signature:**

```solidity
function deregisterPartyB(address partyB, uint256 index) external onlyRole(PARTY_B_MANAGER_ROLE);
```

**Parameters:**

* `partyB`: The address to deregister.
* `index`: The index of the Party B in the partyB list.

**Example:**

```solidity
diamond.deregisterPartyB(partyBAddress, index);
```

**Events Emitted:**

* `DeregisterPartyB(partyB, index)`

***

### registerAffiliate()

Registers an affiliate into the system. Only callable by an account with the `AFFILIATE_MANAGER_ROLE`.

**Function Signature:**

```solidity
function registerAffiliate(address affiliate) external onlyRole(AFFILIATE_MANAGER_ROLE);
```

**Parameters:**

* `affiliate`: The affiliate address to register.

**Example:**

```solidity
diamond.registerAffiliate(affiliateAddress);
```

**Events Emitted:**

* `RegisterAffiliate(affiliate)`

***

### deregisterAffiliate()

Deregisters an affiliate from the system.

**Function Signature:**

```solidity
function deregisterAffiliate(address affiliate) external onlyRole(AFFILIATE_MANAGER_ROLE);
```

**Parameters:**

* `affiliate`: The affiliate address to deregister.

**Example:**

```solidity
diamond.deregisterAffiliate(affiliateAddress);
```

**Events Emitted:**

* `DeregisterAffiliate(affiliate)`

***

## Muon & Collateral Configuration

### setMuonConfig()

Sets configuration parameters for the Muon network—specifically, the validity durations for upnl and price data.

**Function Signature:**

```solidity
function setMuonConfig(uint256 upnlValidTime, uint256 priceValidTime) external onlyRole(MUON_SETTER_ROLE);
```

**Parameters:**

* `upnlValidTime`: Duration (in seconds) for which upnl data is considered valid.
* `priceValidTime`: Duration (in seconds) for which price data is valid.

**Example:**

```solidity
diamond.setMuonConfig(300, 300);
```

**Events Emitted:**

* `SetMuonConfig(upnlValidTime, priceValidTime)`

***

### setMuonIds()

Configures the Muon application ID, gateway address, and public key.

**Function Signature:**

```solidity
function setMuonIds(uint256 muonAppId, address validGateway, PublicKey memory publicKey) external onlyRole(MUON_SETTER_ROLE);
```

**Parameters:**

* `muonAppId`: The Muon application ID.
* `validGateway`: The valid gateway address.
* `publicKey`: The Muon public key (structure containing key data).

**Example:**

```solidity
diamond.setMuonIds(12345, gatewayAddress, publicKeyStruct);
```

**Events Emitted:**

* `SetMuonIds(muonAppId, validGateway, publicKey.x, publicKey.parity)`

***

### setCollateral()

Sets the address of the collateral token used by the system. This function ensures that the token has 18 or fewer decimals and that no collateral remains in the contract when switching tokens.

**Function Signature:**

```solidity
function setCollateral(address collateral) external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Parameters:**

* `collateral`: The address of the new collateral token.

**Example:**

```solidity
diamond.setCollateral(newCollateralAddress);
```

**Events Emitted:**

* `SetCollateral(collateral)`

***

## Fee Collector & Debounce Settings

### setFeeCollector()

Sets the fee collector address for a specific affiliate. This function is restricted to the `AFFILIATE_MANAGER_ROLE`.

**Function Signature:**

```solidity
function setFeeCollector(address affiliate, address feeCollector) external onlyRole(AFFILIATE_MANAGER_ROLE);
```

**Parameters:**

* `affiliate`: The affiliate whose fee collector is being set.
* `feeCollector`: The new fee collector address.

**Example:**

```solidity
diamond.setFeeCollector(affiliateAddress, feeCollectorAddress);
```

**Events Emitted:**

* `SetFeeCollector(affiliate, oldFeeCollector, feeCollector)`

***

### setDefaultFeeCollector()

Sets the default fee collector address, which acts as a fallback for affiliates that have not been assigned a custom fee collector.

**Function Signature:**

```solidity
function setDefaultFeeCollector(address feeCollector) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `feeCollector`: The new default fee collector address.

**Example:**

```solidity
diamond.setDefaultFeeCollector(defaultFeeCollectorAddress);
```

**Events Emitted:**

* `SetDefaultFeeCollector(oldDefaultFeeCollector, feeCollector)`

***

### setDeallocateDebounceTime()

Sets the debounce time for deallocation requests. This prevents users from deallocating funds too frequently by enforcing a minimum time window between requests.

**Function Signature:**

```solidity
function setDeallocateDebounceTime(uint256 deallocateDebounceTime) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `deallocateDebounceTime`: The new debounce time (in seconds).

**Example:**

```solidity
diamond.setDeallocateDebounceTime(60);
```

**Events Emitted:**

* `SetDeallocateDebounceTime(oldDeallocateDebounceTime, deallocateDebounceTime)`

***

### setInvalidBridgedAmountsPool()

Sets the address of the pool that will receive any invalid bridged amounts.

**Function Signature:**

```solidity
function setInvalidBridgedAmountsPool(address pool) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `pool`: The new pool address (must not be the zero address).

**Example:**

```solidity
diamond.setInvalidBridgedAmountsPool(poolAddress);
```

**Events Emitted:**

* `SetInvalidBridgedAmountsPool(oldInvalidBridgedAmountsPool, pool)`

***

## Symbol Management

### addSymbol() & addSymbols()

Adds a new trading symbol to the system or adds multiple symbols in one call. Each symbol includes parameters such as minimum acceptable quote value, trading fee, and leverage limits.

**Function Signature (addSymbol):**

```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`: The name of the symbol.
* `minAcceptableQuoteValue`: Minimum quote value.
* `minAcceptablePortionLF`: Minimum liquidation fee portion.
* `tradingFee`: Trading fee for the symbol.
* `maxLeverage`: Maximum leverage allowed.
* `fundingRateEpochDuration`: Duration of each funding epoch.
* `fundingRateWindowTime`: Time window for funding rate calculations (must be less than half the epoch duration).

**Events Emitted:**

* `AddSymbol(symbolId, name, minAcceptableQuoteValue, minAcceptablePortionLF, tradingFee, maxLeverage, fundingRateEpochDuration, fundingRateWindowTime)`

*For multiple symbols, use addSymbols with an array of Symbol structs.*

***

### setSymbolFundingState()

Updates the funding rate parameters for a specific symbol.

**Function Signature:**

```solidity
function setSymbolFundingState(
  uint256 symbolId,
  uint256 fundingRateEpochDuration,
  uint256 fundingRateWindowTime
) external onlyRole(SYMBOL_MANAGER_ROLE);
```

**Parameters:**

* `symbolId`: The ID of the symbol.
* `fundingRateEpochDuration`: New epoch duration.
* `fundingRateWindowTime`: New window time.

**Events Emitted:**

* `SetSymbolFundingState(symbolId, fundingRateEpochDuration, fundingRateWindowTime)`

***

### setSymbolValidationState()

Changes the validation state (active/inactive) of a symbol.

**Function Signature:**

```solidity
function setSymbolValidationState(uint256 symbolId, bool isValid) external onlyRole(SYMBOL_MANAGER_ROLE);
```

**Parameters:**

* `symbolId`: The ID of the symbol.
* `isValid`: The new validation state.

**Example:**

```solidity
diamond.setSymbolValidationState(1, true);
```

**Events Emitted:**

* `SetSymbolValidationState(symbolId, oldState, isValid)`

***

### setSymbolMaxLeverage()

Updates the maximum leverage for a given symbol.

**Function Signature:**

```solidity
function setSymbolMaxLeverage(uint256 symbolId, uint256 maxLeverage) external onlyRole(SYMBOL_MANAGER_ROLE);
```

**Parameters:**

* `symbolId`: The symbol's ID.
* `maxLeverage`: The new maximum leverage.

**Example:**

```solidity
diamond.setSymbolMaxLeverage(1, 20);
```

**Events Emitted:**

* `SetSymbolMaxLeverage(symbolId, oldMaxLeverage, maxLeverage)`

***

### setSymbolAcceptableValues()

Sets the minimum acceptable quote value and liquidation fee portion for a symbol.

**Function Signature:**

```solidity
function setSymbolAcceptableValues(
  uint256 symbolId,
  uint256 minAcceptableQuoteValue,
  uint256 minAcceptablePortionLF
) external onlyRole(SYMBOL_MANAGER_ROLE);
```

**Parameters:**

* `symbolId`: The symbol's ID.
* `minAcceptableQuoteValue`: New minimum quote value.
* `minAcceptablePortionLF`: New minimum liquidation fee portion.

**Example:**

```solidity
diamond.setSymbolAcceptableValues(1, 1200, 600);
```

**Events Emitted:**

* `SetSymbolAcceptableValues(symbolId, oldMinAcceptableQuoteValue, oldMinAcceptablePortionLF, minAcceptableQuoteValue, minAcceptablePortionLF)`

***

### setSymbolTradingFee()

Updates the trading fee for a specific symbol.

**Function Signature:**

```solidity
function setSymbolTradingFee(uint256 symbolId, uint256 tradingFee) external onlyRole(SYMBOL_MANAGER_ROLE);
```

**Parameters:**

* `symbolId`: The symbol's ID.
* `tradingFee`: The new trading fee.

**Example:**

```solidity
diamond.setSymbolTradingFee(1, 1e16);
```

**Events Emitted:**

* `SetSymbolTradingFee(symbolId, oldTradingFee, tradingFee)`

***

### setForceCloseGapRatio()

Sets the force close gap ratio for a specific symbol. Different symbols may require different gap ratios based on volatility.

**Function Signature:**

```solidity
function setForceCloseGapRatio(uint256 symbolId, uint256 forceCloseGapRatio) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `symbolId`: The ID of the symbol.
* `forceCloseGapRatio`: The new gap ratio.

**Example:**

```solidity
diamond.setForceCloseGapRatio(1, 150);
```

**Events Emitted:**

* `SetForceCloseGapRatio(symbolId, oldForceCloseGapRatio, forceCloseGapRatio)`

***

## Cooldown & Penalty Settings

### setDeallocateCooldown()

Sets the cooldown period required after deallocation before withdrawals can proceed.

**Function Signature:**

```solidity
function setDeallocateCooldown(uint256 deallocateCooldown) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `deallocateCooldown`: New cooldown period (in seconds).

**Example:**

```solidity
diamond.setDeallocateCooldown(300);
```

**Events Emitted:**

* `SetDeallocateCooldown(oldDeallocateCooldown, deallocateCooldown)`

***

### setForceCancelCooldown()

**Description:**\
Configures the cooldown period for force cancellation requests.

**Function Signature:**

```solidity
function setForceCancelCooldown(uint256 forceCancelCooldown) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `forceCancelCooldown`: New cooldown period (in seconds).

**Example:**

```solidity
diamond.setForceCancelCooldown(120);
```

**Events Emitted:**

* `SetForceCancelCooldown(oldForceCancelCooldown, forceCancelCooldown)`

***

### setForceCloseCooldowns()

**Description:**\
Sets two cooldown periods for force closing positions: one for before the target price is reached and one for after.

**Function Signature:**

```solidity
function setForceCloseCooldowns(uint256 forceCloseFirstCooldown, uint256 forceCloseSecondCooldown) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `forceCloseFirstCooldown`: The first cooldown period (in seconds).
* `forceCloseSecondCooldown`: The second cooldown period (in seconds).

**Example:**

```solidity
diamond.setForceCloseCooldowns(180, 300);
```

**Events Emitted:**

* `SetForceCloseCooldowns(oldForceCloseFirstCooldown, forceCloseFirstCooldown, oldForceCloseSecondCooldown, forceCloseSecondCooldown)`

***

### setForceClosePricePenalty()

Sets the penalty applied to Party B during force closing based on price deviations.

**Function Signature:**

```solidity
function setForceClosePricePenalty(uint256 forceClosePricePenalty) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `forceClosePricePenalty`: The new penalty value.

**Example:**

```solidity
diamond.setForceClosePricePenalty(50);
```

**Events Emitted:**

* `SetForceClosePricePenalty(oldPricePenalty, forceClosePricePenalty)`

***

### setForceCloseMinSigPeriod()

Sets the minimum signature period required for force closing positions.

**Function Signature:**

```solidity
function setForceCloseMinSigPeriod(uint256 forceCloseMinSigPeriod) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `forceCloseMinSigPeriod`: The new minimum signature period (in seconds).

**Example:**

```solidity
diamond.setForceCloseMinSigPeriod(60);
```

**Events Emitted:**

* `SetForceCloseMinSigPeriod(oldCloseMinSigPeriod, forceCloseMinSigPeriod)`

***

### setForceCancelCloseCooldown()

Sets the cooldown period for force canceling of close requests.

**Function Signature:**

```solidity
function setForceCancelCloseCooldown(uint256 forceCancelCloseCooldown) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `forceCancelCloseCooldown`: New cooldown period (in seconds).

**Example:**

```solidity
diamond.setForceCancelCloseCooldown(90);
```

**Events Emitted:**

* `SetForceCancelCloseCooldown(oldForceCancelCloseCooldown, forceCancelCloseCooldown)`

***

### setSettlementCooldown()

Sets the cooldown period for settling upnl (unrealized profit and loss) for positions.

**Function Signature:**

```solidity
function setSettlementCooldown(uint256 settlementCooldown) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `settlementCooldown`: New cooldown period (in seconds).

**Example:**

```solidity
diamond.setSettlementCooldown(120);
```

**Events Emitted:**

* `SetSettlementCooldown(oldSettlementCooldown, settlementCooldown)`

***

### setLiquidatorShare()

Sets the percentage of funds distributed to liquidators from liquidated positions.

**Function Signature:**

```solidity
function setLiquidatorShare(uint256 liquidatorShare) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `liquidatorShare`: New share percentage.

**Example:**

```solidity
diamond.setLiquidatorShare(10);
```

**Events Emitted:**

* `SetLiquidatorShare(oldLiquidatorShare, liquidatorShare)`

***

## Pause & Emergency Operations

### Pausing Functions

Multiple functions exist to pause various system operations. For example:

* **pauseGlobal()** pauses all global operations.
* **pauseLiquidation()** pauses liquidation activities.
* **pauseAccounting()** pauses accounting operations.
* **pausePartyAActions()** and **pausePartyBActions()** pause Party A or Party B specific actions.
* **pauseInternalTransfer()** pauses internal transfers.

**Example:**

```solidity
diamond.pauseGlobal();
diamond.pausePartyAActions();
```

**Events Emitted:**\
Corresponding events such as `PauseGlobal()`, `PausePartyAActions()`, etc.

***

#### Emergency Mode

Activates emergency mode for the protocol. This is used to when hedgers must close positions without requiring any action on the partyA's part.

**Function Signature:**

```solidity
function activeEmergencyMode() external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Example:**

```solidity
diamond.activeEmergencyMode();
```

**Events Emitted:**

* `ActiveEmergencyMode()`

***

### Unpausing Functions

**Description:**\
Functions to resume operations once paused:

* **unpauseGlobal()**
* **unpauseLiquidation()**
* **unpauseAccounting()**
* **unpausePartyAActions()**
* **unpausePartyBActions()**
* **unpauseInternalTransfer()**

**Example:**

```solidity
diamond.unpauseGlobal();
diamond.unpauseInternalTransfer();
```

**Events Emitted:**\
Events such as `UnpauseGlobal()`, `UnpauseInternalTransfer()`, etc.

***

### Deactivating Emergency Mode

Deactivates emergency mode.

**Function Signature:**

```solidity
function deactiveEmergencyMode() external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Example:**

```solidity
diamond.deactiveEmergencyMode();
```

**Events Emitted:**

* `DeactiveEmergencyMode()`

***

## Liquidation & Suspension Controls

### setLiquidationTimeout()

Sets the timeout duration for liquidation of partyBs between their initial liquidation and when all their positions are liquidated.

**Function Signature:**

```solidity
function setLiquidationTimeout(uint256 liquidationTimeout) external onlyRole(SETTER_ROLE);
```

**Parameters:**

* `liquidationTimeout`: New timeout duration (in seconds).

**Example:**

```solidity
diamond.setLiquidationTimeout(600);
```

**Events Emitted:**

* `SetLiquidationTimeout(oldLiquidationTimeout, liquidationTimeout)`

***

### suspendedAddress() & unsuspendedAddress()

Suspends or unsuspends a user’s address.

**Function Signatures:**

```solidity
function suspendedAddress(address user) external onlyRole(SUSPENDER_ROLE);
function unsuspendedAddress(address user) external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Parameters:**

* `user`: The address to (un)suspend.

**Example:**

```solidity
diamond.suspendedAddress(userAddress);
diamond.unsuspendedAddress(userAddress);
```

**Events Emitted:**

* `SetSuspendedAddress(user, true)` and `SetSuspendedAddress(user, false)`

***

### setPartyBEmergencyStatus()

Sets the emergency status for multiple Party B addresses.

**Function Signature:**

```solidity
function setPartyBEmergencyStatus(address[] memory partyBs, bool status) external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Parameters:**

* `partyBs`: Array of Party B addresses.
* `status`: Emergency status to set (true or false).

**Example:**

```solidity
address[] memory partyBList = new address[](2);
partyBList[0] = partyBAddress1;
partyBList[1] = partyBAddress2;
diamond.setPartyBEmergencyStatus(partyBList, true);
```

**Events Emitted:**

* `SetPartyBEmergencyStatus(partyB, status)` for each address.

***

## Bridge Management

### addBridge()

Adds a new bridge address to the system.

**Function Signature:**

```solidity
function addBridge(address bridge) external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Parameters:**

* `bridge`: The address of the bridge to add.

**Example:**

```solidity
diamond.addBridge(bridgeAddress);
```

**Events Emitted:**

* `AddBridge(bridge)`

***

### removeBridge()

Removes a bridge address from the system.

**Function Signature:**

```solidity
function removeBridge(address bridge) external onlyRole(DEFAULT_ADMIN_ROLE);
```

**Parameters:**

* `bridge`: The address of the bridge to remove.

**Example:**

```solidity
diamond.removeBridge(bridgeAddress);
```

**Events Emitted:**

* `RemoveBridge(bridge)`