How sherlock-audit/2023-03-notional works
Main Components to Identify and Represent
• External Contracts:
• Contracts in the “contracts/external” folder (e.g., CalculationViews, Router, SettleAssetsExternal, Views)
• External actions modules (AccountAction, GovernanceAction, LiquidateCurrencyAction, VaultAction, etc.).
– These are entry points for users or external systems and they route calls into internal logic.
• Internal Contracts:
• Modules under “contracts/internal” (e.g., balances, liquidation, markets, nToken, pCash, portfolio, settlement, valuation, vaults).
– Each subdirectory represents a specific domain (e.g., BalanceHandler, LiquidatefCash, Market, PortfolioHandler, VaultAccount) carrying core business logic.
• Proxy & Upgradeable Components:
• Proxy implementations for ERC1155 (fCash and vault tokens) and ERC20/ERC4626 proxies for PrimeCash, nTokens, and Prime Debt.
• These ensure that contract upgrades happen safely (e.g., Notional V3 proxy, PrimeCashProxy).
• Governance & Administration Modules:
• Governance actions and roles embedded in contracts (like the governance routers, pause router, and actions such as GovernanceAction).
• Off-chain roles (Notional Owner, Pause Guardian, Notional Manager, Treasury Manager) that govern how upgrades, emergency actions, and treasury rebalancing occur.
• Scripting and Deployment:
• Deployment and initialization scripts (folder “scripts” and “deployers”) that show how contracts are instantiated, deployed, and configured.
• Testing Infrastructure:
• Extensive test suites in “tests” (stateful, mainnet-fork, unit tests) that simulate protocol behavior and validate interactions.
Relationships and Interactions
• External actions serve as the “front door” for user interactions, aggregating user calls and routing them into the underlying business logic.
• Internal modules perform specific tasks:
• Balance, portfolio, and valuation modules interact to process user funds, determine interest and cash group computations, and maintain collateral balances.
• Liquidation modules listen to risk conditions and interact with both market and balance modules to execute liquidations.
• Proxy contracts abstract the upgradeable architecture, ensuring that user calls are always routed to the correct underlying implementation.
• Off-chain managers (e.g., Treasury Manager, Liquidation Bots) interact with on-chain components via scripted actions (or external calls) to keep the protocol’s state updated.
• External integrations (oracles such as Chainlink, money market adapters like Compound) feed price data and asset information to internal modules.
Architectural Patterns and Design Principles
• Modularity: The code is split into “external” and “internal” components for clear demarcation of concerns (front-facing actions versus core business logic).
• Proxy/Upgradeability: Use of proxy contracts enables upgradability without disrupting user state.
• Separation of Concerns: Distinct modules handle governance, market operations, valuations, liquidations, and treasury functions.
• Testing & Deployment Pipelines: Build scripts and Brownie configuration files illustrate a mature CI/CD/testing strategy.
Relevant Technologies & Frameworks
• Solidity for smart contract programming.
• Brownie as the development and testing framework.
• Integration with Ethereum networks and potentially layer-2 solutions (Arbitrum and Optimism) in the future.
• Use of ERC standards (ERC1155, ERC20, ERC4626) to ensure protocol interoperability.