Skip to main content

Finder

Overview​

The Finder contract (src/Finder.sol) serves as the central service registry for the Citadel Finance protocol. It maps interface names to implementation addresses, enabling the protocol to discover and interact with different components dynamically.

Purpose​

  • Service Discovery: Provides a centralized way to locate contract addresses
  • Upgradability: Enables protocol upgrades by updating implementation addresses
  • Decoupling: Reduces tight coupling between contracts by using interface names instead of hardcoded addresses

Contract Details​

  • File: src/Finder.sol
  • Inheritance: ISynthereumFinder, AccessControlEnumerable
  • License: AGPL-3.0-only

Key Functions​

changeImplementationAddress​

function changeImplementationAddress(
    bytes32 interfaceName,
    address implementationAddress
) external override onlyMaintainer

Purpose: Updates the address of the contract that implements a specific interface.

Parameters:

  • interfaceName: bytes32 identifier of the interface (e.g., keccak256("PoolRegistry"))
  • implementationAddress: New contract address implementing the interface

Access Control: Only maintainer role Events: Emits InterfaceImplementationChanged

getImplementationAddress​

function getImplementationAddress(bytes32 interfaceName)
    external
    view
    override
    returns (address)

Purpose: Retrieves the current implementation address for a given interface.

Parameters:

  • interfaceName: bytes32 identifier of the interface to query

Returns: Address of the implementation contract Reverts: If implementation not found (address(0x0))

Storage Structure​

mapping(bytes32 => address) public interfacesImplemented;

Maps interface names (as bytes32) to their implementation addresses.

Access Control​

Roles​

  • DEFAULT_ADMIN_ROLE: Can manage role assignments
  • MAINTAINER_ROLE: Can update implementation addresses

Role Management​

struct Roles {
    address admin;
    address maintainer;
}

Roles are set during contract construction and can be modified by admin.

Events​

InterfaceImplementationChanged​

event InterfaceImplementationChanged(
    bytes32 indexed interfaceName,
    address indexed newImplementationAddress
);

Emitted when an interface implementation is updated.

Common Interface Names​

The protocol uses these standard interface names:

  • SynthereumInterfaces.PoolRegistry
  • SynthereumInterfaces.Manager
  • SynthereumInterfaces.PriceFeed
  • SynthereumInterfaces.CollateralWhitelist
  • SynthereumInterfaces.IdentifierWhitelist
  • SynthereumInterfaces.LendingManager
  • SynthereumInterfaces.Deployer

Usage Examples​

Getting a Contract Address​

address poolRegistry = finder.getImplementationAddress(
    SynthereumInterfaces.PoolRegistry
);

Updating an Implementation​

// Only maintainer can call this
finder.changeImplementationAddress(
    SynthereumInterfaces.PriceFeed,
    newPriceFeedAddress
);

Integration Points​

Used By​

  • All protocol contracts that need to discover other contracts
  • Pool contracts for accessing registries and managers
  • Oracle contracts for validation
  • Factory contracts for deployment coordination

Dependencies​

  • OpenZeppelin's AccessControlEnumerable for role management

Security Considerations​

Access Control​

  • Critical function changeImplementationAddress is restricted to maintainer role
  • Role hierarchy ensures only admin can grant/revoke maintainer role

Validation​

  • Reverts when querying non-existent implementations
  • Prevents setting zero addresses for critical interfaces

Upgrade Safety​

  • Changes to implementations should be coordinated across the protocol
  • Consider time delays for critical address changes
  • Validate new implementations before updating

Implementation Notes​

Gas Optimization​

  • Uses storage mapping for O(1) address lookups
  • Minimal gas overhead for service discovery

Error Handling​

  • Clear error messages for missing implementations
  • Validates against zero addresses

Best Practices​

For Protocol Developers​

  1. Always use Finder for service discovery instead of hardcoded addresses
  2. Validate retrieved addresses before use
  3. Handle potential revert cases when addresses might not be set

For Maintainers​

  1. Coordinate implementation updates across the protocol
  2. Test new implementations thoroughly before updating
  3. Consider using timelock for critical address changes
  4. Monitor events for address changes

The Finder contract is critical infrastructure that enables the modular and upgradeable nature of the Citadel Finance protocol.