Skip to main content

CollateralWhitelist

Overview​

The CollateralWhitelist contract (src/CollateralWhitelist.sol) manages the list of approved collateral tokens that can be used within the Citadel Finance protocol. This contract ensures only vetted and secure tokens can serve as collateral for synthetic asset minting.

Purpose​

  • Security: Prevents malicious or unsuitable tokens from being used as collateral
  • Risk Management: Controls protocol exposure to different token types
  • Governance: Provides centralized control over supported collaterals
  • Compliance: Enables compliance with regulatory requirements for supported assets

Contract Details​

  • File: src/CollateralWhitelist.sol
  • Inheritance: ISynthereumCollateralWhitelist, AccessControlEnumerable
  • License: AGPL-3.0-only

Key Functions​

Whitelist Management​

addToWhitelist​

function addToWhitelist(address newCollateral)
    external
    override
    onlyMaintainer

Purpose: Adds a new collateral token to the approved list.

Parameters:

  • newCollateral: Address of the ERC20 token to approve

Access Control: Only maintainer role Requirements: Token not already in whitelist Events: Emits AddedToWhitelist(address indexed addedCollateral)

removeFromWhitelist​

function removeFromWhitelist(address collateralToRemove)
    external
    override
    onlyMaintainer

Purpose: Removes a collateral token from the approved list.

Parameters:

  • collateralToRemove: Address of the token to remove

Access Control: Only maintainer role Requirements: Token must be currently whitelisted Events: Emits RemovedFromWhitelist(address indexed removedCollateral)

Query Functions​

isOnWhitelist​

function isOnWhitelist(address collateralToCheck)
    external
    view
    override
    returns (bool)

Purpose: Checks if a specific token is approved as collateral.

Parameters:

  • collateralToCheck: Address of the token to verify

Returns: true if token is whitelisted, false otherwise Usage: Called by pools and factories before accepting collateral

getWhitelist​

function getWhitelist() external view override returns (address[] memory)

Purpose: Returns all currently approved collateral tokens.

Returns: Array of all whitelisted token addresses Usage: For UI display, governance review, and integration purposes

Storage Structure​

EnumerableSet.AddressSet private collaterals;

Uses OpenZeppelin's EnumerableSet for efficient storage and enumeration:

  • O(1) additions and removals
  • O(1) membership checks
  • Enumerable for getting all elements
  • Prevents duplicate entries

Access Control​

Roles​

bytes32 public constant MAINTAINER_ROLE = keccak256('Maintainer');
  • DEFAULT_ADMIN_ROLE: Can manage role assignments
  • MAINTAINER_ROLE: Can add/remove collaterals from whitelist

Role Structure​

struct Roles {
    address admin;
    address maintainer;
}

Roles are set during contract construction.

Access Modifier​

modifier onlyMaintainer() {
    require(
        hasRole(MAINTAINER_ROLE, msg.sender),
        'Sender must be the maintainer'
    );
    _;
}

Events​

AddedToWhitelist​

event AddedToWhitelist(address indexed addedCollateral);

Emitted when a new collateral is approved.

RemovedFromWhitelist​

event RemovedFromWhitelist(address indexed removedCollateral);

Emitted when a collateral is removed from approval.

Integration Points​

Used By​

  • Pool Factories: Validate collateral before pool creation
  • Liquidity Pools: Verify collateral tokens during operations
  • UIs: Display available collateral options
  • Governance: Review and manage supported assets

Dependencies​

  • OpenZeppelin AccessControlEnumerable: Role management
  • OpenZeppelin EnumerableSet: Efficient set operations

Common Collateral Types​

Stablecoins​

  • USDC: USD Coin
  • USDT: Tether USD
  • DAI: MakerDAO stablecoin
  • FDUSD: First Digital USD

Major Cryptocurrencies​

  • WETH: Wrapped Ethereum
  • WBTC: Wrapped Bitcoin

Protocol Considerations​

Each collateral type brings different risks:

  • Centralized stablecoins: Regulatory risk, freezing risk
  • Decentralized stablecoins: Smart contract risk, depeg risk
  • Volatile assets: Price volatility, liquidation risk

Usage Examples​

Adding USDC as Collateral​

// USDC token address on Ethereum mainnet
address usdc = 0xA0b86a33E6441e94473D3e16fbfE9dB0B2BDdb2E;

// Add to whitelist (only maintainer can call)
collateralWhitelist.addToWhitelist(usdc);

// Verify addition
bool isApproved = collateralWhitelist.isOnWhitelist(usdc); // returns true

Pool Factory Integration​

// In pool factory before creating new pool
require(
    collateralWhitelist.isOnWhitelist(params.collateralToken),
    "Collateral not approved"
);

Getting All Supported Collaterals​

address[] memory supportedCollaterals = collateralWhitelist.getWhitelist();

// Use for UI dropdown or governance review
for (uint i = 0; i < supportedCollaterals.length; i++) {
    address collateral = supportedCollaterals[i];
    // Process each collateral...
}

Security Considerations​

Token Validation​

  • Verify token contracts are legitimate ERC20 implementations
  • Check for unusual behaviors (transfer fees, rebasing, etc.)
  • Validate token decimals and total supply
  • Review token upgrade mechanisms

Risk Assessment​

  • Evaluate counterparty risk for centralized tokens
  • Assess smart contract risk for synthetic tokens
  • Consider liquidity and market depth
  • Review regulatory compliance

Operational Security​

  • Use multisig for maintainer role
  • Implement timelock for critical changes
  • Monitor for governance attacks
  • Regular security audits

Best Practices​

For Governance​

  1. Due Diligence: Thorough review before adding new collaterals
  2. Risk Assessment: Evaluate each token's risk profile
  3. Community Input: Involve community in collateral decisions
  4. Gradual Rollout: Start with small limits for new collaterals

For Integration​

  1. Always Check: Verify whitelist status before operations
  2. Handle Changes: Monitor whitelist events for updates
  3. Graceful Degradation: Handle removed collaterals appropriately
  4. Cache Wisely: Cache whitelist data but refresh periodically

For Risk Management​

  1. Diversification: Avoid over-concentration in single collaterals
  2. Monitoring: Track collateral performance and risks
  3. Emergency Procedures: Prepare for rapid collateral removal
  4. Stress Testing: Test protocol under various collateral scenarios

Upgrade Considerations​

Adding New Collaterals​

  • Verify token contract security
  • Test integration thoroughly
  • Start with conservative parameters
  • Monitor closely after addition

Removing Collaterals​

  • Provide advance notice to users
  • Allow position closure before removal
  • Handle existing positions gracefully
  • Document removal rationale

The CollateralWhitelist contract is a critical risk management component that ensures only suitable and secure tokens can serve as collateral in the Citadel Finance protocol.