Developers: Migration Guide for Notional V3

Jeff Wu -

Notional V3 is planned to be an in place upgrade to the current Notional V2 proxy contract. For most users and most integrating smart contracts, no action is required. However, there are a few things to be aware of which are outlined below. If you have any questions, please reach out to us in Discord. You can see the code and read the full specification here.

The upgrade is tentatively scheduled for late June 2023, likely after the next quarterly roll on June 21, 2023.

Account Migration

All accounts on Notional will maintain all of their balances before and after the migration. Any deposits held in Notional will be automatically converted to the equivalent value in “Prime Cash”. fCash and nToken balances will also transfer seamlessly.

Accounts that have matured fCash positions (either lending or borrowing) will have their positions settled and converted to cash prior to the upgrade. There is no penalty for accounts with matured lending positions during settlement – it is economically equivalent before and after. Accounts with matured borrow positions have already been settled.

NOTE: there are some accounts with dust matured lending positions (sub $10 value). These accounts WILL NOT be settled as it is not economically viable given gas costs on mainnet. Any accounts with dust balances who want to withdraw must withdraw prior to the upgrade.

Smart Contract Integrations

Notional V3 makes no changes to the existing ABI for smart contract integrations. Most smart contract integrations deal primarily in underlying tokens and therefore should see minimal to no disruption. However, there are a few important changes to note.

  1. depositAssetToken and deposits of asset tokens via BatchAction methods will continue to be supported for legacy cTokens, they will be redeemed immediately to underlying. It is not recommended to continue using these methods but they do exist for backwards compatibility. Note that due to the changes introduced in this fix, the actual "cTokens" Notional holds are non interest bearing wrapped tokens.
  2. redeemToUnderlying in the batchAction and withdraw methods must always be set to true for non-ETH tokens. Notional v3 fully breaks the dependency with Compound V2, accounts will no longer be able to receive cTokens upon withdrawal.
  3. If redeemToUnderlying is set to false for ETH, the account will receive WETH instead of cETH.
  4. The calculateNTokensToMint now takes an amount in underlying tokens, not “asset tokens”. Since Notional no longer accepts “asset tokens” for newly listed currencies, it does not make sense to continue to support legacy functionality for this view function.
  5. The view methods getCurrency, getCurrencyAndRates, getRateStorage, getCashGroupAndAssetRate will continue to return “asset token” and “asset rate” values.
  6. AssetToken will be returned as the deprecated asset token (if it exists) for currencies listed prior to the upgrade. Any currencies after the v3 upgrade will have an asset token of address(0). We recommend any integrating contracts to rely solely on underlying tokens going forward.
  7. AssetRate will return a modified asset rate that matches the current prime cash valuation, so any contracts relying on the asset rate to get a cash valuation will continue to work. However, this will not be supported for newly listed tokens. We recommend that integrating contracts transition to use convertCashBalanceToExternal instead.
  8. Liquidators will no longer deposit “asset tokens” during liquidation, they will need to deposit underlying tokens instead. This will result in a reduction in gas costs.
  9. Leveraged Vault liquidators will see an ABI changes in deleverageVaultAccount and the associated view functions. Liquidators should review the overall Notional V3 contract changes and update their code accordingly.

Wrapped fCash

mintViaAsset and redeemViaAsset will be deprecated on Wrapped fCash and revert when called. This will not affect any of the ERC4626 methods and will not affect mintViaUnderlying.

Off Chain Data

Notional V3 transitions from a bespoke set of events emitted in Notional V3 to more standard ERC20 Transfer and ERC1155 TransferSingle and TransferBatch events to track balance changes off chain. This allows Notional V3 to properly integrate with third party analytics tools and greatly enhances the visibility of Notional V3 assets.

As a consequence, the existing Notional Finance V2 subgraph will cease to update after the migration to Notional V3. A new Notional V3 subgraph will be launched and a subsequent blog post will outline the changes to the event schema and subgraph schemas.

Software License

Notional V3 will be released under a Business Source License (BSL-1.1) with a change date of March 27, 2027 (4 years from publication). Notional V2 was released under a GPL-v3 license. Given the significant effort dedicated to building Notional V3, we believe that this is the right direction to ensure the long term success of the protocol.