System Architecture

Design

MegaStrategy is built using a modular architecture that separates core state (Modules) from business logic (Policies). Each module manages a specific set of state variables and access control, while policies define how users and external contracts interact with this state. The entire system is coordinated through a central Kernel contract that manages module installation, policy activation, and access control.

This architecture follows the Default Framework.

Overview

Our implementation consists of four core modules: PRICE (oracle system), ROLES (access control), TOKEN (protocol token), and TRSRY (treasury management). These modules store and manage all protocol state. Seven policies - Banker, Emergency, Issuer, MegaTokenOracle, PriceConfig, RolesAdmin, and TreasuryCustodian - define the business logic for interacting with this state.

Each policy's permissions are explicitly defined and enforced by the Kernel, ensuring that state changes only occur through approved pathways.

This strict separation between state and logic provides several benefits: it makes the codebase more maintainable by isolating concerns, enables granular access control through the Kernel, and allows for selective upgrades of business logic without disrupting core state management. The diagram below illustrates these relationships:

graph TD
    %% User at the top
    User((User))
    Council((Council))
    Morpho((Morpho))
    %% Policies in the middle
    subgraph Policies
        Banker[Banker]
        Emergency[Emergency]
        Issuer[Issuer]
        MegaTokenOracle[MegaTokenOracle]
        PriceConfig[PriceConfig]
        RolesAdmin[RolesAdmin]
        TreasuryCustodian[TreasuryCustodian]
    end
    %% Kernel in the middle
    Kernel[Kernel.sol]
    %% Modules at the bottom
    subgraph Modules
        PRICE["PRICE"]
        ROLES["ROLES"]
        TOKEN["TOKEN"]
        TRSRY["TRSRY"]
    end
    %% Connect user to policies
    User --> Banker
    User --> Issuer
    %% Connect council to policies
    Council --> Banker
    Council --> Emergency
    Council --> Issuer
    Council --> PriceConfig
    Council --> RolesAdmin
    Council --> TreasuryCustodian
    %% Connect morpho to policies
    Morpho --> MegaTokenOracle
    %% Connect policies to kernel
    Banker --> Kernel
    Emergency --> Kernel
    Issuer --> Kernel
    MegaTokenOracle --> Kernel
    PriceConfig --> Kernel
    RolesAdmin --> Kernel
    TreasuryCustodian --> Kernel
    %% Connect kernel to modules
    Kernel --> PRICE
    Kernel --> ROLES
    Kernel --> TOKEN
    Kernel --> TRSRY
    %% Style
    classDef user fill:#fff,stroke:#333,stroke-width:2px,color:#000;
    classDef module fill:#e6f3ff,stroke:#3182ce,stroke-width:2px,color:#000;
    classDef policy fill:#f0fff4,stroke:#38a169,stroke-width:2px,color:#000;
    classDef kernel fill:#fff5f5,stroke:#e53e3e,stroke-width:2px,color:#000;
    class User user;
    class Council user;
    class Morpho user;
    class PRICE,ROLES,TOKEN,TRSRY module;
    class Banker,Emergency,Issuer,MegaTokenOracle,PriceConfig,RolesAdmin,TreasuryCustodian policy;
    class Kernel kernel;
    click Banker "#banker" "Go to Banker policy";
    click Emergency "#emergency" "Go to Emergency policy";
    click Issuer "#issuer" "Go to Issuer policy";
    click MegaTokenOracle "#megatokenoracle" "Go to MegaTokenOracle policy";
    click PriceConfig "#priceconfig" "Go to PriceConfig policy";
    click RolesAdmin "#rolesadmin" "Go to RolesAdmin policy";
    click TreasuryCustodian "#treasurycustodian" "Go to TreasuryCustodian policy";
    click PRICE "#price" "Go to Price module";
    click ROLES "#roles" "Go to Roles module";
    click TOKEN "#token" "Go to Token module";
    click TRSRY "#treasury" "Go to Treasury module";

Permissions

The Default framework uses a permissions model to control access to the protocol. It has the following characteristics:

  • Policies are external-facing, with functions that can be open or gated to particular roles.
  • Modules can gate access to their functions by using the permissioned modifier. This ensures that only Policies can access them.
  • If a policy needs to access a permissioned function in a Module, it must define those functions in the requestPermissions() function. The Kernel will then ensure that the Policy only uses those functions.

The protocol currently has two standard roles that are shared across all policies:

  • manager: Operational management of the protocol, such as creating CV token auctions.
  • admin: Administration of the protocol, including the initialization of Policy parameters and management of the treasury. Typically held by the council multi-sig or on-chain governance.

Policies

Banker

A policy that manages convertible debt token (CV) auctions and the debt lifecycle. It coordinates with the TRSRY and TOKEN modules to handle the issuance, maturation, and conversion of CV tokens.

Certain actions are restricted to the admin and manager roles.

Major Features

Convertible Token Creation

  • Creates new CV tokens using factory pattern
  • Assigns unique series numbers for each underlying asset
  • Stores and tracks created tokens with createdBy mapping

Auction Management

  • Launches Encrypted Marginal Price Auctions (EMPA) for CV tokens
  • Sets minimum price based on configured max discount
  • Controls auction parameters like fill percentage and bid sizes
  • Handles auction callbacks for settlement and cancellation

Token Settlement

  • Manages CV token redemption after maturity
  • Handles conversion of CV tokens to protocol tokens
  • Coordinates withdrawal of collateral from TRSRY
  • Updates approvals and permissions after settlement

Parameter Management

  • Controls auction parameters like max discount and min fill
  • Manages referrer fees for auctions
  • Configures maximum number of bids per auction

Emergency

The Emergency policy enables a caller with the emergency role to pause the protocol in case of an emergency. Specifically, it deactivates the TRSRY and TOKEN modules.

Issuer

The Issuer policy is responsible for issuing the protocol token (MGST) and option tokens.

MegaTokenOracle

The MegaTokenOracle policy is used by Morpho markets to determine the price of a CV token.

PriceConfig

The PriceConfig policy is used by the protocol to configure the price feeds for the assets that are tracked in the treasury.

RolesAdmin

The RolesAdmin policy is used to grant/revoke roles to/from addresses.

TreasuryCustodian

The TreasuryCustodian policy is used by permissioned callers to withdraw assets from the treasury.

Modules

PRICE

The PRICE module contains the configuration required to determine the price of specified assets. Each asset can be configured with 1 or more sources (a Chainlink price feed or Uniswap V3 pool TWAP at the moment) and an aggregation method.

ROLES

The ROLES module stores the defined roles and addresses that have been granted them.

TOKEN

The TOKEN module is the protocol token and an implementation of the ERC20 standard.

TRSRY

The TRSRY module is the protocol's treasury and stores the protocol's assets.