Control Facet

Control Facet (Options 0.2.1)

Control Facet

The Control Facet handles all administrative functions. It doesn't touch any user positions directly; instead it governs the rules under which everything else operates.

Most functions here are gated behind specific roles (SETTER_ROLE, PAUSER_ROLE, SYMBOL_MANAGER_ROLE, etc.) rather than open to general users.

Key Concepts:

• Roles: The protocol uses a role-based access control system. Different roles gate different operations — SETTER_ROLE for general config, PAUSER_ROLE/UNPAUSER_ROLE for circuit breakers, SYMBOL_MANAGER_ROLE for market listings, ORACLE_MANAGER_ROLE for price feed management, and so on.

• Symbols: Tradeable markets in the options protocol. Each symbol has an option type, an oracle, a collateral token, platform fees, and a symbol type. Symbols must be added and validated before they can be used.

• Oracles: On-chain price feed contracts used for option pricing and settlement. Each symbol references an oracle by ID. Oracles must be registered before a symbol can point to them.

• Pause Granularity: The protocol can be paused at a granular level — globally, or per-operation-type (deposits, withdrawals, transfers, liquidations, PartyA actions, PartyB actions, the instant layer, etc.). This contains issues without shutting down the entire system.

• Emergency Mode: A more aggressive state than a pause — activating emergency mode for PartyB changes the set of actions they're permitted to take. Can be applied system-wide or to a specific PartyB address.

• Instant Layer: A separate execution path for instant settlement operations. It has its own pause toggle and its own role for toggling the callFromInstantLayer flag.

• Release Intervals: Control how frequently PartyBs can release locked balances. Can be configured globally or per PartyB.

• Express Withdraw Providers: Whitelisted third-party providers that can front liquidity for fast withdrawals. Each provider has a config stored per collateral.

---

setAdmin()

Grants DEFAULT_ADMIN_ROLE to an address. This is the bootstrapping function — callable only by the contract owner, typically used once during deployment to hand off administrative control.

Function Signature:

function setAdmin(address _admin) external onlyOwner;

Parameters:

• _admin: The address to grant admin privileges to. Must not be the zero address.

---

grantRole()

Grants an arbitrary role to a user address. Only callable by the DEFAULT_ADMIN_ROLE.

Function Signature:

function grantRole(address _user, bytes32 _role) external onlyRole(LibAccessibility.DEFAULT_ADMIN_ROLE);

Parameters:

• _user: The address to grant the role to. Must not be the zero address.

• _role: The bytes32 role identifier to grant (e.g. LibAccessibility.SETTER_ROLE).

---

revokeRole()

Removes a role from a user. Only callable by DEFAULT_ADMIN_ROLE. Like grantRole().

Function Signature:

function revokeRole(address _user, bytes32 _role) external onlyRole(LibAccessibility.DEFAULT_ADMIN_ROLE);

Parameters:

• _user: The address to revoke the role from.

• _role: The role identifier to revoke.

---

whiteListCollateral()

Adds a collateral token to the protocol's whitelist. Only whitelisted collaterals can be used for deposits and position backing.

Function Signature:

function whiteListCollateral(address _collateral) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _collateral: The ERC-20 token address to whitelist. Must not be the zero address.

---

removeCollateralFromWhitelist()

Removes a collateral token from the whitelist.

Function Signature:

function removeCollateralFromWhitelist(address _collateral) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _collateral: The ERC-20 token address to remove from the whitelist.

---

setMaxCloseOrdersLength()

Sets the maximum number of close orders that can be submitted per trade at one time.

Function Signature:

function setMaxCloseOrdersLength(uint256 _max) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _max: The new maximum. Must be greater than zero.

Internal Logic:

• Zero Check: Reverts with ZeroAmount if _max is 0.

• Storage Write: Updates AppStorage.layout().maxCloseOrdersLength.

• Event: Emits MaxCloseOrdersLengthUpdated.

---

setMaxTradePerPartyA()

Caps the total number of open trades a PartyA can hold at any given time.

Function Signature:

function setMaxTradePerPartyA(uint256 _max) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _max: The new maximum number of trades per PartyA. Must be greater than zero.

Internal Logic:

• Zero Check: Reverts with ZeroAmount if _max is 0.

• Storage Write: Updates AppStorage.layout().maxTradePerPartyA.

• Event: Emits MaxTradePerPartyAUpdated.

---

setBalanceLimitPerUser()

Sets a per-collateral deposit cap for individual users. Useful for limiting exposure to a specific collateral token on a per-account basis.

Function Signature:

function setBalanceLimitPerUser(address collateral, uint256 _limit) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• collateral: The collateral token address the limit applies to. Must not be the zero address.

• _limit: The maximum balance a user may hold in that collateral.

Internal Logic:

• Storage Write: Updates AppStorage.layout().balanceLimitPerUser[collateral].

• Event: Emits BalanceLimitPerUserUpdated with both the collateral and the new limit.

---

setTimingParameters()

Batch setter for all protocol timing values in a single transaction. Covers deallocation cooldowns, force-cancel timeouts, signature validity windows, the PartyB exclusive action window, the unbinding cooldown, and the instant action mode deactivation cooldown. Useful during initial deployment or when multiple values need to change together atomically.

Function Signature:

function setTimingParameters(
    uint256 _partyADeallocateCooldown,
    uint256 _partyBDeallocateCooldown,
    uint256 _forceCancelOpenTimeout,
    uint256 _forceCancelCloseTimeout,
    uint256 _settlementPriceSigValidTime,
    uint256 _upnlSigValidTime,
    uint256 _partyBExclusiveWindow,
    uint256 _unbindingCooldown,
    uint256 _deactiveInstantActionModeCooldown
) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _partyADeallocateCooldown: How long PartyA must wait between deallocation requests.

• _partyBDeallocateCooldown: How long PartyB must wait between deallocation requests.

• _forceCancelOpenTimeout: Time after which a stuck open intent can be force-cancelled.

• _forceCancelCloseTimeout: Time after which a stuck close intent can be force-cancelled.

• _settlementPriceSigValidTime: The window during which a settlement price signature remains valid.

• _upnlSigValidTime: The window during which a UPnL signature from the oracle remains valid.

• _partyBExclusiveWindow: A time window after a close intent is created during which only the specific PartyB can act on it.

• _unbindingCooldown: How long a party must wait before they can unbind from a counterparty relationship.

• _deactiveInstantActionModeCooldown: The cooldown before instant action mode can be deactivated.

---

setTradeNftAddress()

Sets the address of the NFT contract used to represent trades on-chain.

Function Signature:

function setTradeNftAddress(address _tradeNftAddress) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _tradeNftAddress: The address of the trade NFT contract. Can be set to the zero address to disable.

---

setPartyBReleaseInterval()

Configures a custom release interval for a specific PartyB. The release interval controls how frequently that PartyB can release locked balances.

Function Signature:

function setPartyBReleaseInterval(address _partyB, uint256 _interval) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _partyB: The PartyB address to configure. Must not be the zero address.

• _interval: The release interval in seconds.

---

setDefaultReleaseInterval()

Sets the fallback release interval applied to any PartyB that does not have a custom interval configured.

Function Signature:

function setDefaultReleaseInterval(uint256 _interval) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _interval: The default release interval in seconds.

---

setMaxConnectedCounterParties()

Sets the maximum number of counterparty relationships a single party can have open simultaneously.

Function Signature:

function setMaxConnectedCounterParties(uint256 _max) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _max: The maximum number of connected counterparties. Must be greater than zero.

---

setDefaultFeeCollector()

Sets the default address that receives platform fees when no affiliate-specific collector is configured.

Function Signature:

function setDefaultFeeCollector(address _collector) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _collector: The address to designate as the default fee collector. Must not be the zero address.

---

setAffiliateStatus()

Activates or deactivates an affiliate. Only active affiliates can collect fees routed through their frontend or integration.

Function Signature:

function setAffiliateStatus(address _affiliate, bool _status) external onlyRole(LibAccessibility.AFFILIATE_MANAGER_ROLE);

Parameters:

• _affiliate: The affiliate address to configure.

• _status: true to activate, false to deactivate.

---

setAffiliateFeesCollector()

Sets the address that receives fees on behalf of a specific affiliate. Allows affiliates to route their fee revenue to a different address (e.g. a multisig or treasury).

Function Signature:

function setAffiliateFeesCollector(address _affiliate, address _collector) external onlyRole(LibAccessibility.AFFILIATE_MANAGER_ROLE);

Parameters:

• _affiliate: The affiliate whose collector is being set.

• _collector: The address that will receive this affiliate's fees. Must not be the zero address.

---

setAffiliateFees()

Sets per-symbol fee structures for an affiliate in batch. Each symbol can have its own fee configuration for a given affiliate.

Function Signature:

function setAffiliateFees(
    address _affiliate,
    uint256[] calldata _symbolIds,
    Fee[] calldata _fees
) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _affiliate: The affiliate address whose fee schedule is being configured.

• _symbolIds: Array of symbol IDs to apply fees to.

• _fees: A parallel array of Fee structs corresponding to each symbol ID.

---

setPartyBConfig()

Configures a PartyB's operational parameters — whether they're active, which oracle they use, and other solver-specific settings. When activating a PartyB, the referenced oracle is validated to exist.

Function Signature:

function setPartyBConfig(
    address _partyB,
    PartyBConfig calldata _config
) external onlyRole(LibAccessibility.PARTY_B_MANAGER_ROLE);

Parameters:

• _partyB: The PartyB address being configured. Must not be the zero address.

• _config: A PartyBConfig struct containing the PartyB's operational settings, including their active status and oracle assignment.

---

setPartyBSupportedSymbolTypes()

Sets which symbol types a given PartyB is willing to trade, in batch. A PartyB will only accept intents for symbol types they have marked as supported.

Function Signature:

function setPartyBSupportedSymbolTypes(
    address _partyB,
    uint256[] calldata _symbolTypes,
    bool[] calldata _statuses
) external onlyRole(LibAccessibility.PARTY_B_MANAGER_ROLE);

Parameters:

• _partyB: The PartyB address being configured.

• _symbolTypes: Array of symbol type identifiers.

• _statuses: Parallel array of booleans — true means supported, false means not supported.

---

Pause & Unpause Functions

The Control Facet provides granular pause controls across eleven separate operation types. Each has a matching pause and unpause function. Pausing requires PAUSER_ROLE; unpausing requires UNPAUSER_ROLE — these are intentionally separate so that a pauser cannot unilaterally lift their own pause.

Function	State flag set
pauseGlobal() / unpauseGlobal()	globalPaused
pauseDeposit() / unpauseDeposit()	depositingPaused
pauseWithdraw() / unpauseWithdraw()	withdrawingPaused
pauseExpressWithdraw() / unpauseExpressWithdraw()	expressWithdrawPaused
pauseInternalTransfer() / unpauseInternalTransfer()	internalTransferPaused
pauseExternalTransfer() / unpauseExternalTransfer()	externalTransferPaused
pausePartyBActions() / unpausePartyBActions()	partyBActionsPaused
pausePartyAActions() / unpausePartyAActions()	partyAActionsPaused
pauseLiquidating() / unpauseLiquidating()	liquidatingPaused
pauseThirdPartyActions() / unpauseThirdPartyActions()	thirdPartyActionsPaused
pauseInstantLayer() / unpauseInstantLayer()	instantLayerPaused

All state flags are stored in StateControlStorage. Each function emits a corresponding event (e.g. GlobalPaused, DepositUnpaused, etc.).

---

activePartyBsEmergencyMode() / deactivePartyBsEmergencyMode()

Activates or deactivates emergency mode for all PartyBs simultaneously. In emergency mode, PartyBs gain access to a restricted set of actions to allow them to close out positions and wind down safely.

Function Signatures:

function activePartyBsEmergencyMode() external onlyRole(LibAccessibility.PAUSER_ROLE);
function deactivePartyBsEmergencyMode() external onlyRole(LibAccessibility.UNPAUSER_ROLE);

Internal Logic:

• Storage Write: Sets StateControlStorage.layout().partyBsEmergencyMode to true or false.

• Events: Emits PartyBsEmergencyModeActivated or PartyBsEmergencyModeDeactivated.

---

activePartyBEmergencyMode() / deactivePartyBEmergencyMode()

Same as the system-wide emergency mode, but scoped to a single PartyB address. Useful for isolating a specific solver that is experiencing issues without affecting the rest of the market makers.

Function Signatures:

function activePartyBEmergencyMode(address _partyB) external onlyRole(LibAccessibility.PAUSER_ROLE);
function deactivePartyBEmergencyMode(address _partyB) external onlyRole(LibAccessibility.UNPAUSER_ROLE);

Parameters:

• _partyB: The specific PartyB address to affect. Must not be the zero address.

---

suspendAddress()

Suspends or unsuspends a single user address. Suspended addresses cannot deposit, withdraw, or participate in trading actions.

Function Signature:

function suspendAddress(address _user, bool _status) external onlyRole(LibAccessibility.SUSPENDER_ROLE);

Parameters:

• _user: The address to suspend or unsuspend. Must not be the zero address.

• _status: true to suspend, false to unsuspend.

---

suspendWithdrawal()

Suspends or unsuspends a specific pending withdrawal by ID. A suspended withdrawal cannot be completed or cancelled until unsuspended.

Function Signature:

function suspendWithdrawal(uint256 _withdrawId, bool _status) external onlyRole(LibAccessibility.SUSPENDER_ROLE);

Parameters:

• _withdrawId: The withdrawal ID to act on. Must not be zero.

• _status: true to suspend, false to unsuspend.

---

suspendAddresses()

Batch version of suspendAddress(). Applies suspension statuses to multiple addresses in a single transaction.

Function Signature:

function suspendAddresses(
    address[] calldata users,
    bool[] calldata statuses
) external onlyRole(LibAccessibility.SUSPENDER_ROLE);

Parameters:

• users: Array of addresses to suspend or unsuspend.

• statuses: Parallel array of booleans corresponding to each address.

---

addOracle()

Registers a new price oracle with the protocol. Each oracle gets a unique auto-incremented ID and is referenced by symbols and PartyB configs.

Function Signature:

function addOracle(
    string calldata _name,
    address _contractAddress
) external onlyRole(LibAccessibility.ORACLE_MANAGER_ROLE);

Parameters:

• _name: A human-readable name for the oracle (e.g. "Chainlink ETH/USD"). Must not be empty.

• _contractAddress: The on-chain address of the oracle contract. Must not be the zero address.

---

updateOracle()

Updates the contract address of an existing oracle. Useful when a price feed migrates to a new contract.

Function Signature:

function updateOracle(
    uint256 _oracleId,
    address _contractAddress
) external onlyRole(LibAccessibility.ORACLE_MANAGER_ROLE);

Parameters:

• _oracleId: The ID of the oracle to update. Must already exist.

• _contractAddress: The new contract address. Must not be the zero address.

---

setPriceOracleAddress()

Sets the address of the primary price oracle used by the protocol for settlement price lookups.

Function Signature:

function setPriceOracleAddress(address _oracle) external onlyRole(LibAccessibility.ORACLE_MANAGER_ROLE);

Parameters:

• _oracle: The oracle contract address. Must not be the zero address.

---

addSymbol()

Lists a new tradeable options symbol on the protocol. Each symbol is assigned a unique auto-incremented ID and is immediately marked as valid.

Function Signature:

function addSymbol(
    string memory _name,
    OptionType _optionType,
    uint256 _oracleId,
    address _collateral,
    Fee memory _platformFee,
    uint256 _symbolType
) public onlyRole(LibAccessibility.SYMBOL_MANAGER_ROLE);

Parameters:

• _name: A human-readable name for the symbol (e.g. "ETH-CALL-3500-2024Q1"). Must not be empty.

• _optionType: An enum value specifying whether this is a call or put option.

• _oracleId: The ID of the oracle that will provide pricing for this symbol. Must already be registered.

• _collateral: The ERC-20 token used as collateral for this symbol. Must not be the zero address.

• _platformFee: A Fee struct defining the platform fee charged on trades for this symbol.

• _symbolType: A numeric type identifier for categorizing symbols.

---

addSymbols()

Batch version of addSymbol(). Accepts an array of Symbol structs and calls addSymbol() for each.

Function Signature:

function addSymbols(Symbol[] calldata symbols) external onlyRole(LibAccessibility.SYMBOL_MANAGER_ROLE);

Parameters:

• symbols: An array of Symbol structs to add. Each must pass the same validations as a single addSymbol() call.

---

Symbol Management Functions

These batch functions allow existing symbols to be updated. All follow the same pattern: a SYMBOL_MANAGER_ROLE check, a length validation between the two parallel arrays, a loop over the pairs, a storage write, and one event per symbol.

setSymbolsPlatformFees(uint256[] _symbolIds, Fee[] _fees) Updates the platform fee struct for each specified symbol. Emits SymbolPlatformFeeUpdated with the old and new fee per symbol.

setSymbolsValidationState(uint256[] _symbolIds, bool[] _states) Enables or disables each symbol. A symbol with isValid = false cannot be used for new intents. Emits SymbolStateUpdated.

setSymbolsNames(uint256[] _symbolIds, string[] _names) Updates the human-readable name of each symbol. Names must not be empty. Emits SymbolNameUpdated.

setSymbolsTypes(uint256[] _symbolIds, uint256[] _types) Updates the symbolType classification of each symbol. Emits SymbolTypeUpdated.

All four functions validate that the symbol ID exists (lastSymbolId < _symbolIds[i] check) and revert with InvalidSymbol if not.

---

setSignatureVerifier()

Sets the address of the contract responsible for verifying option-related signatures (UPnL, settlement price, etc.).

Function Signature:

function setSignatureVerifier(address _verifier) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _verifier: The address of the signature verifier contract. Must not be the zero address.

---

setExpressWithdrawProviderConfig()

Configures a whitelisted express withdrawal provider for a specific collateral. Providers can front liquidity for users who want to skip the standard withdrawal cooldown.

Function Signature:

function setExpressWithdrawProviderConfig(
    address _provider,
    address _collateral,
    ExpressWithdrawProviderConfig memory _config
) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _provider: The address of the express withdrawal provider. Must not be the zero address.

• _collateral: The collateral token this config applies to.

• _config: An ExpressWithdrawProviderConfig struct defining the provider's operational parameters for this collateral.

---

setInvalidWithdrawalsAmountsPool()

Sets the address that receives any collateral from withdrawals that fail validation (e.g. amounts that can't be reconciled). Ensures those funds don't sit stranded.

Function Signature:

function setInvalidWithdrawalsAmountsPool(address _pool) external onlyRole(LibAccessibility.SETTER_ROLE);

Parameters:

• _pool: The address of the pool that receives invalid withdrawal amounts. Must not be the zero address.

---

setExternalTransferTargetValidationStatus()

Whitelists or de-whitelists a specific target contract for a given collateral token, controlling which external contracts can receive funds via externalTransfer().

Function Signature:

function setExternalTransferTargetValidationStatus(
    address _target,
    address _collateral,
    bool _status
) external onlyRole(LibAccessibility.EXTERNAL_TRANSFER_TARGET_MANAGER_ROLE);

Parameters:

• _target: The external contract to whitelist or remove. Must not be the zero address.

• _collateral: The collateral token this status applies to. Must not be the zero address.

• _status: true to whitelist, false to remove.

---

setCallFromInstantLayer()

Toggles a flag that marks the current execution context as originating from the instant layer. Used internally by the instant layer contract to signal to the rest of the protocol that it should apply instant-layer-specific logic.

Function Signature:

function setCallFromInstantLayer(bool _callFromInstantLayer) external onlyRole(LibAccessibility.INSTANT_LAYER_ROLE);

Parameters:

• _callFromInstantLayer: true to mark the context as an instant layer call, false to clear it.