Notional contest

Notional Contracts V2

Notional is a fixed rate lending and borrowing platform, built on Ethereum. Fixed rates differ from variable rates or stable rates because the interest rate will not change by for the term of the loan. Fixed rate loans are 25x variable rate loans in traditional financial markets because of the superior guarantees they offer. Notional V1 first introduced our concepts of how to achieve fixed rates on Ethereum and Notional V2 extends upon those concepts to add support for fixed term loans out to 20 years. Notional V2 also introduces many improvements upon Notional V1, including superior capital efficiency, better upgradeability, and on chain governance.

---

Contest scope information

All code in contracts/ is in scope, excluding:

• contracts/mocks
• contracts/proxy (this is just a port from OpenZeppelin for Solidity 0.7)

A full protocol description can be found in the whitepaper. Detailed code walkthroughs can be found at:

• Videos: https://www.youtube.com/watch?v=-8a5kY0QeYY&list=PLnKdM8f8QEJ2lJ59ZjhVCcJvrT056X0Ga
• Blogs: https://blog.notional.finance/tag/deep-dive/

Our primary concern is both the technical and economic security of user funds. We expect that the contracts accurately track user funds and there are no arbitrage conditions present. Notional V2 allows users to gain leverage and collateralize their positions in many ways (a single currency can be used as collateral in four ways: cToken 'asset cash' balances, nToken balances, fCash and liquidity tokens). As a result, free collateral and liquidation is an area of special concern. We must ensure that users can be liquidated in all scenarios where they become undercollateralized.

Notional V2 also makes special use of storage slots, these are accessed directly using assembly and packed manually in the code rather than relying on Solidity's storage packing. This is a suboptimal, however, it does allow for internal libraries to easily access storage locations without requiring the storage slot be passed in from an external contract. It has been suggested by an auditor that we put all the storage slots into a struct and pass them around the contracts but we have not refactored at this point. Obviously care must be taken with this manual approach.

Notional V2 also uses a few different internal decimal precision values. All internal accounting for balances is stored in 8 decimal places regardless of the token's native decimal precision. Interest rates and exchange rates are calculated in 9 decimal precision. Finally, percentages are stored and computed in 2 decimal precision.

Notional V2 contest details

• $150,000 USDC + $50,000 NOTE main award pot
• Join C4 Discord to register
• Submit findings using the C4 form
• Read our guidelines for more details
• Starts August 26, 2021 00:00 UTC
• Ends September 8, 2021 23:59 UTC

---

Codebase

The codebase is broken down into the following modules, each directory has a _README.md file that describes the module. A full protocol description can be found in WHITEPAPER.md.

contracts
|
└── external: all externally deployable contracts
|   └── actions: implementations of externally callable methods
|   └── adapters: adapter contracts used to interface between systems
|   └── governance: on chain governance system, forked from Compound Governor Alpha and COMP token (thanks!)
|
|       FreeCollateralExternal.sol: deployed library for checking account free collateral positions
|       Router.sol: implementation for proxy contract that delegates calls to appropriate action contract
|       SettleAssetsExternal.sol: deployed library for settling matured assets to cash
|       Views.sol: view only methods for inspecting system state
|
└── global: storage, struct and constant definitions
└── internal: shared internal libraries for handling generic system wide functionality
|   └── balances: encapsulates all internal balance and token transfer logic
|   └── liquidation: contains calculations for determining liquidation amounts
|   └── markets: contains logic for defining tradable assets and fCash liquidity curve
|   └── portfolio: handlers for account portfolios and transferring assets between them
|   └── settlement: contains logic for settling matured assets in portfolios
|   └── valuation: calculations for determining account free collateral positions
|
|       AccountContextHandler.sol: manages per account metadata
|       nTokenHandler.sol: manages nToken configuration and metadata
|
└── math: math libraries
└── mocks: mock contracts for testing internal libraries

Statistics

Code Size

These are ported from OpenZeppelin Contracts and do not require audit:

Test Coverage

• Running tests using Ganache can run out of memory, use export NODE_OPTIONS=--max-old-space-size=16000
• debug_traceTransaction can also fail due to string length errors. You will see an error from brownie saying that the environment has crashed. This error is unavoidable, the plan is to test if Hardhat also has this issue.
• Coverage reports are incomplete due to the above string length issue in Ganache.

Gas Costs

Gas costs for various scenarios are in gas_stats.json. This report can be regenerated by running brownie run scripts/gas_stats.py