Lens

The Lens.sol contract defines the Lens as a diamond-pattern-based contract. It serves as a modular and extensible component for retrieving and managing protocol-related data. The implementation is divided into the following facets:

1. LensConfigFacet - Handles configuration settings for the Lens.
2. LensProtocolFacet - Manages protocol-related data and interactions.
3. LensUserFacet - Provides user-specific data access and management.
4. LensDataStructs - Defines the shared data structures used across the Lens.

The Lens contract aggregates functionality from its facets and exposes public methods through the ILens interface. Next, I'll analyze the ILens.sol file to document its public-facing functions.

The ILens.sol interface aggregates functionality from the following components:

1. IDiamond - Provides modularity through the diamond pattern.
2. ILensConfig - Manages configuration-related functionalities.
3. ILensProtocol - Handles protocol-specific data operations.
4. ILensUser - Manages user-specific data retrieval and interaction.

To document the Lens contract comprehensively, I'll explore the ILensProtocol.sol, ILensConfig.sol, and ILensUser.sol files to extract the public methods exposed by each of these facets.

The ILensProtocol.sol interface defines the public functions for protocol-specific data operations. Here is an overview of its primary methods:

Public Functions

1. protocolData

• Description: Retrieves general protocol data, including controller and Soul details.
• Returns:
  • ControllerData: Information about the controller.
  • SoulData: Information about the Soul contracts.
• Example:

  (ControllerData memory controller, SoulData memory soul) = lens.protocolData();
   

2. controllerData

• Description: Fetches data specific to the Controller.
• Returns:
  • ControllerData: A struct containing details about the Controller.
• Example:

  ControllerData memory controller = lens.controllerData();
   

3. controllerSouls

• Description: Retrieves a list of Souls associated with the Controller.
• Returns:
  • ControllerSoul[]: Array of Soul-related data structs.
• Example:

  ControllerSoul[] memory souls = lens.controllerSouls();
   

4. sTokensData

• Description: Returns data for all SToken contracts in the protocol.
• Returns:
  • STokenData[]: Array of data for each SToken.
• Example:

  STokenData[] memory sTokenData = lens.sTokensData();
   

5. sTokenData

• Description: Fetches specific data for a given SToken.
• Parameters:
  • ISToken sToken: Address of the SToken to query.
• Returns:
  • STokenData: Data structure containing SToken details.
• Example:

  STokenData memory tokenData = lens.sTokenData(sTokenAddress);
   

6. sTokenState

• Description: Retrieves the current state of a given SToken.
• Parameters:
  • ISToken sToken: Address of the SToken.
• Returns:
  • STokenState: A struct containing the state of the SToken.
• Example:

  STokenState memory state = lens.sTokenState(sTokenAddress);
   

7. underlying

• Description: Fetches details about an underlying asset.
• Parameters:
  • IERC20 underlying: Address of the ERC20 token.
  • bool isNative: Indicates whether the token is native to the blockchain.
• Returns:
  • Underlying: A struct containing details about the underlying asset.
• Example:

  Underlying memory assetDetails = lens.underlying(underlyingToken, false);
   

8. baseData

• Description: Retrieves base data for a specific SToken.
• Parameters:
  • ISToken sToken: Address of the SToken.
• Returns:
  • BaseData: A struct with basic SToken information.
• Example:

  BaseData memory base = lens.baseData(sTokenAddress);
   

9. soulData

• Description: Fetches data related to Soul contracts.
• Returns:
  • SoulData[]: Array of Soul-related data structs.
• Example:

  SoulData[] memory soulDetails = lens.soulData();
   

Summary of Protocol Functions

The LensProtocol interface provides a comprehensive set of tools for:

1. Accessing controller-related data (e.g., Souls, STokens).
2. Retrieving detailed information about assets and their states.
3. Interfacing with protocol-level components like Souls and STokens.

Next, I will analyze ILensConfig.sol and ILensUser.sol to complete the documentation for the Lens contract.

The ILensConfig.sol interface defines configuration-related functions for the Lens contract. Here's a summary of its public methods:

Public Functions

Getters

1. network
   • Description: Retrieves the name of the current network.
   • Returns:
     • string memory: Name of the network.
   • Example:

     string memory networkName = lens.network();
      
2. currentChainId
   • Description: Fetches the chain ID of the current network.
   • Returns:
     • uint96: Chain ID of the network.
   • Example:

     uint96 chainId = lens.currentChainId();
      
3. nativeSymbol
   • Description: Retrieves the symbol of the native token for the network.
   • Returns:
     • string memory: Symbol of the native token (e.g., "ETH", "BNB").
   • Example:

     string memory symbol = lens.nativeSymbol();
      
4. nativeName
   • Description: Retrieves the name of the native token for the network.
   • Returns:
     • string memory: Name of the native token (e.g., "Ether", "Binance Coin").
   • Example:

     string memory tokenName = lens.nativeName();
      
5. controller
   • Description: Returns the address of the associated Controller contract.
   • Returns:
     • IController: Address of the Controller.
   • Example:

     IController controllerAddress = lens.controller();
      
6. chainIdToNetworkName
   • Description: Maps a chain ID to its corresponding network name.
   • Parameters:
     • uint96 chainId: The chain ID to query.
   • Returns:
     • string memory: The name of the network associated with the chain ID.
   • Example:

     string memory networkName = lens.chainIdToNetworkName(1001);
      

These functions provide essential configuration data for interacting with the protocol, ensuring that Lens can dynamically adapt to different networks and settings.

Next, I'll analyze ILensUser.sol to extract its user-specific functionalities.

The ILensUser.sol interface defines user-specific data retrieval functions, allowing seamless access to information related to user accounts and their protocol interactions. Here's a summary of its key public functions:

Public Functions

User Data Retrieval

1. userData
   • Description: Fetches general user data across markets and Souls.
   • Parameters:
     • address user: The address of the user to query.
   • Returns:
     • MarketUser: Struct containing user data in markets.
     • SoulUser: Struct containing user data in Souls.
   • Example:

     (MarketUser memory marketUser, SoulUser memory soulUser) = lens.userData(userAddress);
      
2. userAndProtocolData
   • Description: Retrieves user data alongside protocol data.
   • Parameters:
     • address user: The address of the user.
   • Returns:
     • MarketUser: Market data for the user.
     • SoulUser: Soul-specific data for the user.
     • ControllerData: General Controller information.
     • SoulData: Protocol-level Soul data.
   • Example:

     (MarketUser memory marketUser, SoulUser memory soulUser, ControllerData memory controllerData, SoulData memory soulData) = lens.userAndProtocolData(userAddress);
      

Market-Specific Functions

1. marketUser
   • Description: Fetches user-specific market data.
   • Parameters:
     • address userAddress: The user's address.
   • Returns:
     • MarketUser: Struct containing the user's market data.
   • Example:

     MarketUser memory marketUser = lens.marketUser(userAddress);
      
2. marketAccounts
   • Description: Returns all market accounts associated with a user.
   • Parameters:
     • address userAddress: The user's address.
   • Returns:
     • MarketAccount[]: Array of MarketAccount structs.
   • Example:

     MarketAccount[] memory accounts = lens.marketAccounts(userAddress);
      
3. marketAccount
   • Description: Retrieves data for a specific market account.
   • Parameters:
     • ISToken sToken: Address of the SToken representing the market.
     • address userAddress: The user's address.
   • Returns:
     • MarketAccount: Struct containing account details.
   • Example:

     MarketAccount memory account = lens.marketAccount(sTokenAddress, userAddress);
      

Soul-Specific Functions

1. soulUser
   • Description: Retrieves data related to the user's Soul interactions.
   • Parameters:
     • address userAddress: The user's address.
   • Returns:
     • SoulUser: Struct containing Soul-specific user data.
   • Example:

     SoulUser memory soulData = lens.soulUser(userAddress);
      
2. soulUserNetworks
   • Description: Returns Soul-related data across networks for a user.
   • Parameters:
     • address userAddress: The user's address.
   • Returns:
     • SoulUserNetwork[]: Array of SoulUserNetwork structs.
   • Example:

     SoulUserNetwork[] memory networks = lens.soulUserNetworks(userAddress);
      
3. soulUserNetwork
   • Description: Retrieves user-specific Soul data for a specific network.
   • Parameters:
     • uint96 chainId: The chain ID to query.
     • address userAddress: The user's address.
   • Returns:
     • SoulUserNetwork: Struct containing Soul data for the user on that network.
   • Example:

     SoulUserNetwork memory networkData = lens.soulUserNetwork(1001, userAddress);
      

Summary of User Functions

The LensUser interface provides a rich set of tools for:

1. Fetching user-specific data across markets and Souls.
2. Accessing account-level and network-specific details for users.
3. Combining user and protocol data for comprehensive insights.