Protocol (V2) Contract Architecture

This section of the Sommelier docs outlines the Smart Contract Architecture and its details. The docs are under continuous revision, so some sections are not published yet.

A list of useful links is provided below depending on what information you are seeking. For all paths, read this page, the next page first ("Smart Contract Architecture Walk-Through"), and the "Roles & Permissions" page outlining different actors for Cellars.

  1. Developers looking to understand the architecture: read the rest of this page and the next page.

  2. Developers looking to deeply understand the core contracts: go to the "Advanced Smart Contracts" section, and check out the detailed subpages and APIs (and some fun schematics). Also, feel free to check out the deployed versions of this code after reading over this first page. Of course, all code can be found in the github repository.

  3. Developers looking to create an Adaptor: Skip to the "External Protocol Integration" section with "Building Adaptors" for a tutorial (still in progress).

  4. Developers looking to create a PriceExtension: Skip to the "External Protocol Integration" section with "Building Price Extensions."

  5. Developers only seeking actual, in-prod deployments: See "Smart Contract Addresses."

Now, onto the core smart contracts architecture currently adopted by the Sommelier protocol.

Core Architecture

The V2 Cellars infrastructure contains a number of smart contracts that contribute to the continued operation of each cellar and the Sommelier Cellars protocol.

The following four concepts categorize the scope of smart contract functionality in Cellars V2:

  • Registry - contains global configuration applicable across Cellars, including references to other smart contracts and permissions layers for adaptors and Cellars.

  • PriceRouter - global Cellars pricing contract, typically using Chainlink. Built to price complex multi-token Cellar positions (e.g. LP positions). Price Router upgrades now allow for alternative price sources other than Chainlink where deemed appropriate (see "Building Pricing Extensions").

  • Cellars - user-facing ERC4626 vaults where strategists deploy assets to earn yield. Each Cellar is run by a single strategist, implementing various independent methods of earning yield. Each Strategist can make adjustments to the respective Cellar they're managing, via Sommelier governance and Gravity Bridge-approved strategist functions.

    • Note: Sommelier Cellars depart from the ERC4626 standard in their implementation of totalAssets. According to the standard, totalAssets must not revert. For Sommelier Cellars, totalAssets may revert. Integrators should take care to note and handle this difference.

  • Adaptors - integration contracts that allow Cellars to interact with an external DeFi protocol. Adaptors should be case-specific, and a Cellar may use multiple adaptors in the course of complex DeFi operations.

There have been iterations on the above concepts throughout the lifetime of the Sommelier protocol. These are noted in each of their detailed subsections. A full V3 architecture upgrade is being currently discussed but not in the immediate development timeline.

Please see the next page for a general walk-through of the setup of a Cellar and its parts.

Last updated