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:

function transferOwnership(address owner) external onlyOwner;

Parameters:

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

Example:

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:

function setAdmin(address user) external onlyOwner;

Parameters:

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

Example:

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. Note: For LIQUIDATOR_ROLE, additional checks ensure that a Party A without pending quotes or open positions is assigned.

Function Signature:

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:

diamond.grantRole(userAddress, LibAccessibility.LIQUIDATOR_ROLE);

Events Emitted:

• RoleGranted(role, user)

---

revokeRole()

Revokes a specific role from a user.

Function Signature:

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:

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:

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

Parameters:

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

Example:

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:

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:

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:

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

Parameters:

• affiliate: The affiliate address to register.

Example:

diamond.registerAffiliate(affiliateAddress);

Events Emitted:

• RegisterAffiliate(affiliate)

---

deregisterAffiliate()

Deregisters an affiliate from the system.

Function Signature:

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

Parameters:

• affiliate: The affiliate address to deregister.

Example:

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:

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:

diamond.setMuonConfig(300, 300);

Events Emitted:

• SetMuonConfig(upnlValidTime, priceValidTime)

---

setMuonIds()

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

Function Signature:

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:

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:

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

Parameters:

• collateral: The address of the new collateral token.

Example:

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:

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:

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:

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

Parameters:

• feeCollector: The new default fee collector address.

Example:

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:

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

Parameters:

• deallocateDebounceTime: The new debounce time (in seconds).

Example:

diamond.setDeallocateDebounceTime(60);

Events Emitted:

• SetDeallocateDebounceTime(oldDeallocateDebounceTime, deallocateDebounceTime)

---

setInvalidBridgedAmountsPool()

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

Function Signature:

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

Parameters:

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

Example:

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):

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:

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:

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

Parameters:

• symbolId: The ID of the symbol.

• isValid: The new validation state.

Example:

diamond.setSymbolValidationState(1, true);

Events Emitted:

• SetSymbolValidationState(symbolId, oldState, isValid)

---

setSymbolMaxLeverage()

Updates the maximum leverage for a given symbol.

Function Signature:

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

Parameters:

• symbolId: The symbol's ID.

• maxLeverage: The new maximum leverage.

Example:

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:

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:

diamond.setSymbolAcceptableValues(1, 1200, 600);

Events Emitted:

• SetSymbolAcceptableValues(symbolId, oldMinAcceptableQuoteValue, oldMinAcceptablePortionLF, minAcceptableQuoteValue, minAcceptablePortionLF)

---

setSymbolTradingFee()

Updates the trading fee for a specific symbol.

Function Signature:

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

Parameters:

• symbolId: The symbol's ID.

• tradingFee: The new trading fee.

Example:

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:

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

Parameters:

• symbolId: The ID of the symbol.

• forceCloseGapRatio: The new gap ratio.

Example:

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:

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

Parameters:

• deallocateCooldown: New cooldown period (in seconds).

Example:

diamond.setDeallocateCooldown(300);

Events Emitted:

• SetDeallocateCooldown(oldDeallocateCooldown, deallocateCooldown)

---

setForceCancelCooldown()

Description: Configures the cooldown period for force cancellation requests.

Function Signature:

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

Parameters:

• forceCancelCooldown: New cooldown period (in seconds).

Example:

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:

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:

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:

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

Parameters:

• forceClosePricePenalty: The new penalty value.

Example:

diamond.setForceClosePricePenalty(50);

Events Emitted:

• SetForceClosePricePenalty(oldPricePenalty, forceClosePricePenalty)

---

setForceCloseMinSigPeriod()

Sets the minimum signature period required for force closing positions.

Function Signature:

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

Parameters:

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

Example:

diamond.setForceCloseMinSigPeriod(60);

Events Emitted:

• SetForceCloseMinSigPeriod(oldCloseMinSigPeriod, forceCloseMinSigPeriod)

---

setForceCancelCloseCooldown()

Sets the cooldown period for force canceling of close requests.

Function Signature:

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

Parameters:

• forceCancelCloseCooldown: New cooldown period (in seconds).

Example:

diamond.setForceCancelCloseCooldown(90);

Events Emitted:

• SetForceCancelCloseCooldown(oldForceCancelCloseCooldown, forceCancelCloseCooldown)

---

setSettlementCooldown()

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

Function Signature:

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

Parameters:

• settlementCooldown: New cooldown period (in seconds).

Example:

diamond.setSettlementCooldown(120);

Events Emitted:

• SetSettlementCooldown(oldSettlementCooldown, settlementCooldown)

---

setLiquidatorShare()

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

Function Signature:

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

Parameters:

• liquidatorShare: New share percentage.

Example:

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:

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:

function activeEmergencyMode() external onlyRole(DEFAULT_ADMIN_ROLE);

Example:

diamond.activeEmergencyMode();

Events Emitted:

• ActiveEmergencyMode()

---

Unpausing Functions

Description: Functions to resume operations once paused:

• unpauseGlobal()

• unpauseLiquidation()

• unpauseAccounting()

• unpausePartyAActions()

• unpausePartyBActions()

• unpauseInternalTransfer()

Example:

diamond.unpauseGlobal();
diamond.unpauseInternalTransfer();

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

---

Deactivating Emergency Mode

Deactivates emergency mode.

Function Signature:

function deactiveEmergencyMode() external onlyRole(DEFAULT_ADMIN_ROLE);

Example:

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:

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

Parameters:

• liquidationTimeout: New timeout duration (in seconds).

Example:

diamond.setLiquidationTimeout(600);

Events Emitted:

• SetLiquidationTimeout(oldLiquidationTimeout, liquidationTimeout)

---

suspendedAddress() & unsuspendedAddress()

Suspends or unsuspends a user’s address.

Function Signatures:

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:

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:

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:

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:

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

Parameters:

• bridge: The address of the bridge to add.

Example:

diamond.addBridge(bridgeAddress);

Events Emitted:

• AddBridge(bridge)

---

removeBridge()

Removes a bridge address from the system.

Function Signature:

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

Parameters:

• bridge: The address of the bridge to remove.

Example:

diamond.removeBridge(bridgeAddress);

Events Emitted:

• RemoveBridge(bridge)