.
# Currency Ids
Each currency listed on Notional is associated with a unique Currency Id. The Currency Id of a given asset can vary on different Notional deployments.
| Currency Id | Ethereum Mainnet | Arbitrum |
| ----------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 1 | [ETH](https://www.youtube.com/watch?v=rlM7gsUY9Gw) | [ETH](https://www.youtube.com/watch?v=rlM7gsUY9Gw) |
| 2 | [DAI](https://etherscan.io/token/0x6b175474e89094c44da98b954eedeac495271d0f) | [DAI](https://arbiscan.io/address/0xda10009cbd5d07dd0cecc66161fc93d7c9000da1) |
| 3 | [USDC](https://etherscan.io/token/0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48) | [USDC.e](https://arbiscan.io/token/0xff970a61a04b1ca14834a43f5de4533ebddb5cc8) |
| 4 | [WBTC](https://etherscan.io/token/0x2260fac5e5542a773aa44fbcfedf7c193bc2c599) | [WBTC](https://arbiscan.io/address/0x2f2a2543b76a4166549f7aab2e75bef0aefc5b0f) |
| 5 | [wstETH](https://etherscan.io/token/0x7f39c581f595b53c5cb19bd0b3f8da6c935e2ca0) | [wstETH](https://arbiscan.io/address/0x5979D7b546E38E414F7E9822514be443A4800529) |
| 6 | [FRAX](https://etherscan.io/token/0x853d955acef822db058eb8505911ed77f175b99e) | [FRAX](https://arbiscan.io/address/0x17fc002b466eec40dae837fc4be5c67993ddbd6f) |
| 7 | [rETH](https://etherscan.io/token/0xae78736cd615f374d3085123a210448e74fc6393) | [rETH](https://arbiscan.io/token/0xec70dcb4a1efa46b8f2d97c310c9c4790ba5ffa8) |
| 8 | [USDT](https://etherscan.io/token/0xdac17f958d2ee523a2206206994597c13d831ec7) | [USDT](https://arbiscan.io/token/0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9) |
| 9 | [cbETH](https://etherscan.io/token/0xbe9895146f7af43049ca1c1ae358b0541ea49704) | [cbETH](https://arbiscan.io/token/0x1debd73e752beaf79865fd6446b0c970eae7732f?a=0x7235a73bd38f26e16bc146b1d5173f4ca5172a42) |
| 10 | [sDAI](https://etherscan.io/token/0x83f20f44975d03b1b09e64809b757c47f942beea) | [GMX](https://arbiscan.io/token/0xfc5a1a6eb076a2c7ad06ed22c90d7e710e35ad0a) |
| 11 | [GHO](https://etherscan.io/token/0x40d16fc0246ad3160ccc09b8d0d3a2cd28ae6c2f) | [ARB](https://arbiscan.io/token/0x912ce59144191c1204e64559fe8253a0e49e6548) |
| 12 | [tBTC](https://etherscan.io/token/0x18084fba666a33d37592fa2633fd49a74dd93a88) | [RDNT](https://arbiscan.io/token/0x3082cc23568ea640225c2467653db90e9250aaa0) |
| 13 | N/A | [UNI](https://arbiscan.io/token/0xfa7f8980b0f1e64a2062791cc3b0871572f1f7f0) |
| 14 | N/A | [LINK](https://arbiscan.io/token/0xf97f4df75117a78c1a5a0dbb814af92458539fb4) |
| 15 | N/A | [LDO](https://arbiscan.io/token/0x13ad51ed4f1b7e9dc168d8a00cb3f4ddd85efa60) |
| 16 | N/A | [tBTC](https://arbiscan.io/token/0x6c84a8f1c29108F47a79964b5Fe888D4f4D0dE40) |
# Market Indexes
fCash markets of a given currency are identified by Market Indexes. Market Indexes identify the tenor of active markets using a predefined tenor cadence:
* 3 month (market index = 1)
* 6 month (market index = 2)
* 1 year (market index = 3)
* 2 year (market index = 4)
* 5 year (market index = 5)
* 10 year (market index = 6)
* 20 year (market index = 7)
As an example, using a market index of 1 would refer to a 3 Month fCash market and a market with an index of 3 would refer to a 1 Year fCash market.
# Notional Internal Precision
## Balances
Notional's internal balance precision is 8 decimals. For example, here is a non-exhaustive list of balance related variables with 1e8 precision:
* User Prime Cash and Prime Debt balances
* User nToken balances
* User fCash balances
* nToken liquidity token balances
* User Vault Share Balances
* User Free Collateral balances
* fCash markets total Prime Cash and total fCash balances
* Prime Cash totalUnderlyingSupply balances
* maxUnderlyingSupply parameters
* Leveraged Vaults minAccountBorrowSize parameters
## Rates
Notional's internal rate precision is 9 decimals. For example, here is a non-exhaustive list of rates related variables with 1e9 precision:
* `fCashOracleRates`
* `fCashLastImpliedRates`
* `oracleSupplyRate`
* Leveraged Vaults `minCollateralRatio`, `maxRequiredAccountCollateralRatio`, `maxDeleverageCollateralRatio`, `liquidationRate`, and `feeRate` parameters
## Scalars
Prime Cash scalars are 1e18 precision. For example, the precision of the following variables is 1e18:
* `debtScalar`
* `supplyScalar`
* `underlyingScalar`
## Prime factors
The Prime Cash `debtFactor`and `supplyFactor` precision is 1e36.
# Intro
This section will cover how to interact with Notional V3 contracts using [ETH brownie](https://eth-brownie.readthedocs.io/en/stable/install.html) a Python-based development and testing framework.
## Contract Github repository
Notional's V3 smart contracts repository can be found [here](https://github.com/notional-finance/).
## Setup
Here is a simple setup to start interacting with Notional V3 using ETH brownie:
```
import json
from brownie import (
accounts,
interface
)
from brownie.network.state import Chain
import eth_abi
class V3Environment:
def __init__(self):
self.notional = interface.NotionalProxy("0x1344A36A1B56144C3Bc62E7757377D288fDE0369")
self.owner = self.notional.owner()
def main():
env = V3Environment()
env.chain = Chain()
env.notional.address
```
## Contract approval
To interact with the protocol using ERC-20 tokens, accounts must approve Notional's Proxy.
```
# Approve sending an unlimited amount of DAI to the Notional Proxy.
interface.ERC20(currencyAddress).approve(notional.address, 2**255, {'from': account})
```
# Trading guide
In this section we will cover how one can:
* Deposit
* Lend at the Prime Variable Rate
* Borrow at the Prime Borrow Rate
* Buy fCash (Lend Fixed)
* Sell fCash (Borrow Fixed)
* Mint nTokens (Provide Liquidity)
* Redeem nTokens (Redeem Liquidity)
* Enter a leveraged vault
* Exit a leveraged vault
We will also explore how to submit multiple actions in one trade and how to set slippage limits when trading fCash.
## Helper functions
Here are some helper functions that can be useful when interacting with Notional balance and trading functions:
```
from eth_abi.packed import encode_abi_packed
DEPOSIT_ACTION_TYPE = {
"None": 0,
"DepositAsset": 1,
"DepositUnderlying": 2,
"DepositAssetAndMintNToken": 3,
"DepositUnderlyingAndMintNToken": 4,
"RedeemNToken": 5,
"ConvertCashToNToken": 6,
}
TRADE_ACTION_TYPE = {
"Lend": 0,
"Borrow": 1,
"AddLiquidity": 2,
"RemoveLiquidity": 3,
"PurchaseNTokenResidual": 4,
"SettleCashDebt": 5,
}
def get_balance_action(currencyId, depositActionType, **kwargs):
depositActionAmount = (
0 if "depositActionAmount" not in kwargs else kwargs["depositActionAmount"]
)
withdrawAmountInternalPrecision = (
0
if "withdrawAmountInternalPrecision" not in kwargs
else kwargs["withdrawAmountInternalPrecision"]
)
withdrawEntireCashBalance = (
False if "withdrawEntireCashBalance" not in kwargs else kwargs["withdrawEntireCashBalance"]
)
redeemToUnderlying = (
True if "redeemToUnderlying" not in kwargs else kwargs["redeemToUnderlying"]
)
return (
DEPOSIT_ACTION_TYPE[depositActionType],
currencyId,
int(depositActionAmount),
int(withdrawAmountInternalPrecision),
withdrawEntireCashBalance,
redeemToUnderlying,
)
def get_balance_trade_action(currencyId, depositActionType, tradeActionData, **kwargs):
tradeActions = [get_trade_action(**t) for t in tradeActionData]
balanceAction = list(get_balance_action(currencyId, depositActionType, **kwargs))
balanceAction.append(tradeActions)
return tuple(balanceAction)
def get_lend_action(currencyId, tradeActionData, depositUnderlying):
tradeActions = [get_trade_action(**t) for t in tradeActionData]
return (currencyId, depositUnderlying, tradeActions)
def get_trade_action(**kwargs):
tradeActionType = kwargs["tradeActionType"]
if tradeActionType == "Lend":
return encode_abi_packed(
["uint8", "uint8", "uint88", "uint32", "uint120"],
[
TRADE_ACTION_TYPE[tradeActionType],
kwargs["marketIndex"],
int(kwargs["notional"]),
int(kwargs["minSlippage"]),
0,
],
)
elif tradeActionType == "Borrow":
return encode_abi_packed(
["uint8", "uint8", "uint88", "uint32", "uint120"],
[
TRADE_ACTION_TYPE[tradeActionType],
kwargs["marketIndex"],
int(kwargs["notional"]),
int(kwargs["maxSlippage"]),
0,
],
)
elif tradeActionType == "AddLiquidity":
return encode_abi_packed(
["uint8", "uint8", "uint88", "uint32", "uint32", "uint88"],
[
TRADE_ACTION_TYPE[tradeActionType],
kwargs["marketIndex"],
int(kwargs["notional"]),
int(kwargs["minSlippage"]),
int(kwargs["maxSlippage"]),
0,
],
)
elif tradeActionType == "RemoveLiquidity":
return encode_abi_packed(
["uint8", "uint8", "uint88", "uint32", "uint32", "uint88"],
[
TRADE_ACTION_TYPE[tradeActionType],
kwargs["marketIndex"],
int(kwargs["notional"]),
int(kwargs["minSlippage"]),
int(kwargs["maxSlippage"]),
0,
],
)
elif tradeActionType == "PurchaseNTokenResidual":
return encode_abi_packed(
["uint8", "uint32", "int88", "uint128"],
[
TRADE_ACTION_TYPE[tradeActionType],
kwargs["maturity"],
int(kwargs["fCashAmountToPurchase"]),
0,
],
)
elif tradeActionType == "SettleCashDebt":
return encode_abi_packed(
["uint8", "address", "uint88"],
[
TRADE_ACTION_TYPE[tradeActionType],
kwargs["counterparty"],
int(kwargs["amountToSettle"]),
],
)
```
# Deposit (Prime Lend)
## Deposit a single Currency to a Notional account
To deposit underlying tokens to Notional, users can use the `depositUnderlyingToken` method:
# Deposit DAI on Notional. DAI external precision is 1e18.
notional.depositUnderlyingToken(account.address, 2, 10e18, {'from': account})
# Deposit 100 USDC on Notional. USDC external precision is 1e6.
notional.depositUnderlyingToken(account.address, 2, 100e6, {'from': account})
# Deposit 1 ETH on Notional
notional.depositUnderlyingToken(account.address, 1, 1e18, {'from': account, 'value':1e18})
## Deposit Prime Cash to a Notional Account
To deposit Prime Cash to Notional, users can use the `depositAssetToken` method:
```
# Deposit 10 pDAI to a Notional Account. pCash external precision is 1e8.
notional.depositAssetToken(account.address, 2, 10e8, {'from': account})
# Deposit 100 pUSDC to a Notional Account. pCash external precision is 1e8.
notional.depositAssetToken(account.address, 3, 100e8, {'from': account})
# Deposit 1 pETH to a Notional Account. pCash external precision is 1e8.
notional.depositAssetToken(account.address, 1, 1e8, {'from': account})
```
## Batch deposit to a Notional Account
To deposit multiple tokens to Notional at once, users can use the `batchBalanceAction` method:
```
from helpers import get_balance_action
# Deposit 100 DAI & 10 USDC
depositActionDAI = get_balance_action(2, "DepositUnderlying", depositActionAmount=100e18)
depositActionUSDC = get_balance_action(3, "DepositUnderlying", depositActionAmount=10e6)
tx = notional.batchBalanceAction(account.address, [depositActionDAI, depositActionUSDC], {'from': account})
```
*Note that the array of actions must be sorted by currency ids when using batch functions.*
# Trade fCash (Borrow & Lend Fixed)
## Deposit and Lend Fixed
To lend fixed on Notional, users need to trade Prime Cash in exchange for fCash:
```
from helpers import get_balance_trade_action
# Deposit 10 DAI to Notional as Prime Dai and lend 5 fDAI fixed in the 3M maturity (marketIndex = 1).
lendActionDai = get_balance_trade_action(2, "DepositUnderlying", [
{"tradeActionType": "Lend", "marketIndex": 1, "notional": 5 * 1e8, "minSlippage": 0.03*1e9}
], depositActionAmount = 10e18)
tx = notional.batchBalanceAndTradeAction(account.address, [lendActionDai], {"from": account})
```
Note that the `minSlippage` limit sets the minimum fixed rate at which the user will lend. The transaction will revert if the trade implied fixed rate is lower than the minimum slippage limit.
The `depositActionAmount` uses the external currency precision. The `notional` amount precision is 1e8. The slippage limit rate precision is 1e9.
## Deposit and Lend Fixed in multiple maturities
Users can use the `batchBalanceAndTradeAction` method to lend across multiple maturities:
```
from helpers import get_balance_trade_action
# Deposit 10 DAI to Notional as Prime Dai,
# Lend 5 fDAI fixed in the 3M maturity (marketIndex = 1), and
# Lend 3 fDAI fixed in the 6M maturity (marketIndex = 2).
lendActionDai = get_balance_trade_action(2, "DepositUnderlying", [
{"tradeActionType": "Lend", "marketIndex": 1, "notional": 5 * 1e8, "minSlippage": 0.03*1e9},
{"tradeActionType": "Lend", "marketIndex": 2, "notional": 3 * 1e8, "minSlippage": 0.02*1e9}
], depositActionAmount = 10e18)
tx = notional.batchBalanceAndTradeAction(account.address, [lendActionDai], {"from": account})
```
## Deposit and Lend Fixed in multiple currencies
Users can use the `batchBalanceAndTradeAction` method to lend across multiple currencies:
```
from helpers import get_balance_trade_action
# Deposit 10 DAI to Notional as Prime DAI and lend 5 fDAI fixed in the 3M maturity (marketIndex = 1).
# Deposit 100 USDC to Notional as Prime USDC and lend 100 fUSDC fixed in the 6M maturity (marketIndex = 2).
lendActionDai = get_balance_trade_action(2, "DepositUnderlying", [
{"tradeActionType": "Lend", "marketIndex": 1, "notional": 5 * 1e8, "minSlippage": 0.03*1e9}
], depositActionAmount = 10e18)
lendActionUsdc = get_balance_trade_action(3, "DepositUnderlying", [
{"tradeActionType": "Lend", "marketIndex": 2, "notional": 100 * 1e8, "minSlippage": 0.02*1e9}
], depositActionAmount = 100e6)
tx = notional.batchBalanceAndTradeAction(account.address, [lendActionDai, lendActionUsdc], {"from": account})
```
Note that when using batch functions the array of actions needs to be sorted by Currency Ids.
## Deposit, lend fixed in the 3M maturity and borrow in the 6M maturity
Users can use the `batchBalanceAndTradeAction` method to lend and borrow across different maturities:
```
from helpers import get_balance_trade_action
# Deposit 10 DAI to Notional as Prime Dai,
# Lend 1,000 fDAI fixed in the 3M maturity (marketIndex = 1), and
# Borrow 1,000 fDAI fixed in the 6M maturity (marketIndex = 2).
actionDai = get_balance_trade_action(2, "DepositUnderlying", [
{"tradeActionType": "Lend," "marketIndex": 1, "notional": 1_000 * 1e8, "minSlippage": 0.03*1e9},
{"tradeActionType": "Borrow", "marketIndex": 2, "notional": 1_000 * 1e8, "maxSlippage": 0.05*1e9}
], depositActionAmount = 10e18)
tx = notional.batchBalanceAndTradeAction(account.address, [actionDai], {"from": account})
```
Note that the maxSlippage limit sets the maximum fixed rate at which user will borrow. If the trade implied fixed rate is lower than the minimum slippage limit, the transaction will revert.
## Deposit Prime Cash in one currency and borrow fixed in another currency
Users can use the `batchBalanceAndTradeAction` method to borrow at a fixed rate:
```
from helpers import get_balance_trade_action
# Deposit 10 DAI to Notional as Prime Dai,
# Borrow 5 fUSDC fixed in the 6M maturity (marketIndex = 2).
actionDai = get_balance_trade_action(2, "DepositUnderlying", [], depositActionAmount = 10e18)
actionUsdc = get_balance_trade_action(3, "None", [
{"tradeActionType": "Borrow", "marketIndex": 2, "notional": 5 * 1e8, "maxSlippage": 0.05*1e9}
], withdrawEntireCashBalance=True)
tx = notional.batchBalanceAndTradeAction(account.address, [actionDai, actionUsdc], {"from": account})
```
Note that we can set `withdrawEntireCashBalance` to True in order to withdraw the borrowed USDC to the user's wallet.
# Add liquidity (Mint nTokens)
## Deposit from wallet and Mint nTokens
Users can use the `batchBalanceAction` method to mint nTokens across multiple maturities:
```
# Deposit 100 DAI and 1 WBTC and Mint nDAI and nWBTC LP tokens.
mintNDaiAction = get_balance_action(2, "DepositUnderlyingAndMintNToken", depositActionAmount=10e18)
mintNWbtcAction = get_balance_action(4, "DepositUnderlyingAndMintNToken", depositActionAmount=1e8)
notional.batchBalanceAction(account.address, [mintNDaiAction, mintNWbtcAction], {"from": account})
```
# Withdraw liquidity (Redeem nTokens)
## Redeem nTokens (sell asset and don't accept residuals)
```
# Redeem 100 nDAI. Sell fDAI residuals to Prime DAI and don't accept fDAI residuals.
notional.nTokenRedeem(account.address, 2, 100e8, True, False, {'from': account})
```
Note that by setting `sellTokenAssets` to True and `acceptResidualAssets` to False, the nToken redeemer will only receive Prime DAI in exchange for his nDAI. If the nDAI account has accrued any fDAI residuals, they will be sold for Prime Cash during the redeem action. Trading fCash for Prime Cash is subject to fCash trading fees. A large nToken redemption might therefore lead the redeemer to face slippage when redeeming.
## Redeem nTokens (don't sell asset and accept residuals)
```
# Redeem 100 nDAI. Don't sell fDAI residuals to Prime DAI and accept fDAI residuals.
notional.nTokenRedeem(account.address, 2, 100e8, False, True, {'from': account})
```
Note that by setting `sellTokenAssets` to False and `acceptResidualAssets` to True, the nToken redeemer will likely receive fDAI in all maturities and some Prime DAI.
## Redeem nTokens (sell asset and accept residuals)
```
# Redeem 100 nDAI. Sell fDAI residuals to Prime DAI and accept fDAI residuals.
notional.nTokenRedeem(account.address, 2, 100e8, True, True, {'from': account})
```
Note that by setting `sellTokenAssets` to True and `acceptResidualAssets` to True, the nToken redeemer will trade fDAI residuals for Prime DAI. If selling residuals is impossible due to low fCash liquidity, the redeemer will receive the fCash residuals assets to his portfolio.
# Withdraw (Prime Cash)
## Withdraw a Prime Cash Balance from Notional
Users can use the `withdraw` method to redeem their Prime Cash balances from Notional:
```
# Redeem 100 Prime USDC from Notional to a user's wallet in USDC.
tx = notional.withdraw(3, 100e8, True, {'from': account})
# Withdraw 100 Prime USDC from Notional to a user's wallet in Prime USDC.
tx = notional.withdraw(3, 100e8, False, {'from': account})
```
Note that the Prime Cash balance precision is 1e8.
## Withdraw Prime Cash from Notional (Borrow Prime)
Users can use the `withdraw` method to borrow Prime Debts from Notional:
```
# Deposit 100 USDC on Notional. USDC external precision is 1e6.
notional.depositUnderlyingToken(account.address, 2, 100e6, {'from': account})
# In order to Borrow Prime Cash the user needs to enable Prime Borrow.
notional.enablePrimeBorrow(True, {'from': account})
# Borrow 50 Prime DAI from Notional to the user's wallet in DAI.
tx = notional.withdraw(3, 50e8, True, {'from': account})
```
# Settle Account
## Settle Account
Users can settle Notional accounts using the settleAccount function. If a user trades after a settlement, it will also automatically settle his account.
```
# Accounts holding fCash balances (positive or negative) in the 3M maturity need to
be settled after the fCash maturity has passed and markets have been initialized.
notional.settleAccount(settledAccount, {'from': account})
```
# Enter Leveraged Vaults
## Enter Leveraged Vault
Notional users can use the `enterVault` method to initiate or update a vault position:
```
def get_deposit_params(minPoolClaim=0, trade=bytes()):
return eth_abi.encode_abi(
['(uint256, bytes)'],
[[minPoolClaim, trade]]
)
depositParams = get_deposit_params()
# Enter a vault by depositing 10 USDC, borrowing 20 fUSDC from Notional in the December 18, 2023 (1702944000) maturity with a max borrow interest rate limit of 5%.
notional.enterVault(account.address, vaultAddress, 10e6, 1702944000, 25e8, 0.05 * 1e9, depositParams, {'from':account})
```
A user can enter a vault at a specific leverage ratio by selecting the amount of Prime Cash he borrows and the deposit amount.
# Exit Leveraged Vaults
## Exit Leveraged Vault
Notional users can use the `exitVault` method to exit or update a vault position:
```
# Exit a vault (USDC borrow) by redeeming the account's vault shares and repaying its fCash debt.
vaultShares = notional.getVaultAccount(account.address, vaultAddress)["vaultShares"]
fCash = abs(notional.getVaultAccount(account.address, vaultAddress)["accountDebtUnderlying"])
tx = notional.exitVault(account.address, vaultAddress, account.address, vaultShares, fCash, 0, "", {'from': account})
```
A user could increase his leverage ratio by partially redeeming his vault shares without repaying his debt position.
# Accounts
To get a list of Notional users, one can use this [subgraph query](/v3-technical-docs/subgraph-guides/notional-v3-subgraphs/fetch-notional-accounts) or use this [Dune query](https://dune.com/queries/2759293).
## Get an account's balances
```
account = notional.getAccount(accountAddress)
```
## Fetch an account's positions in readable format
The following function can be used to make an account's balances more readable. This is especially useful when comparing an account's state before and after trading.
from datetime import datetime
# CurrencyId to Symbol Mapping
CURRENCY_ID_TO_SYMBOL = {
1: "ETH",
2: "DAI",
3: "USDC",
4: "WBTC",
5: "wstETH",
6: "FRAX",
7: "rETH",
8: "USDT",
}
# This function can be used to make an account's positions readable.
def getAccountPositions(address):
account = notional.getAccount(address)
dict = {}
dict['Account Address'] = address
dict['Free collateral (ETH)'] = notional.getFreeCollateral(address)[0] / 1e8
for i in account[1]:
if i[0] != 0:
symbol = CURRENCY_ID_TO_SYMBOL[i[0]]
dict[symbol] = {
'p{} Balance'.format(symbol): i[1]/1e8,
'n{} Balance'.format(symbol): i[2]/1e8}
for j in account[2]:
symbol = CURRENCY_ID_TO_SYMBOL[j[0]]
if j[2] == 1:
dict[symbol].update({'f{} {} {}'.format(symbol, j[1], datetime.fromtimestamp(j[1]).date()): j[3] / 1e8})
return dict
## Get an account's free collateral
If a user's free collateral is negative, then the user is eligible to get liquidated. If the user's free collateral figure is positive the account is sufficiently collateralized.
```
notional.getFreeCollateral(accountAddress)
```
## Get an account's Leveraged Vaults positions
Users can use the `getVaultAccount` methord to fetch an account's leveraged vault positions:
leveragedVaultAccount = notional.getVaultAccount(accountAddress, vaultAdderes)
accountVaultShares = leveragedVaultAccount["vaultShares"]/1e8
accountDebtInUnderlying = leveragedVaultAccount["accountDebtUnderlying"]/1e8
# Prime Cash Markets
## Fetch Prime Cash and Prime Debt Addresses
```
# Fetch the Prime Cash and Prime debt addresses for a given currencyId
pCashAddress = notional.pCashAddress(currrencyId)
pDebtAddress = notional.pDebtAddress(currrencyId)
```
## Fetch a market's total pCash and total pDebt supply
```
from brownie.network.state import Chain
chain = Chain()
primeFactors = notional.getPrimeFactorsStored(currencyId, chain.time())
totalPrimeSupply = primeFactors['factors']["totalPrimeSupply"]/1e8
totalPrimeDebt = primeFactors['factors']["totalPrimeDebt"]/1e8
```
## Get a market's pCash and pDebt Supply in Underlying
In order to convert Prime Cash to underlying we need to use the underlyingScalar and the supplyScalar. To convert Prime Debt to underlying we need to use the underlyingScalar and the debtScalar:
```
from brownie.network.state import Chain
chain = Chain()
primeFactors = notional.getPrimeFactorsStored(currencyId, chain.time())
totalPrimeSupply = primeFactors['factors']["totalPrimeSupply"]/1e8
totalPrimeDebt = primeFactors['factors']["totalPrimeDebt"]/1e8
supplyScalar = primeFactors["factors"]["supplyScalar"]/1e18
debtScalar = primeFactors["factors"]["debtScalar"]/1e18
underlyingScalar = primeFactors["factors"]["underlyingScalar"]/1e18
# Total Prime Supply in underlying
totalPrimeSupplyInUnderlying = totalPrimeSupply * underlyingScalar * supplyScalar
totalPrimeDebtInUnderlying = totalPrimeDebt * underlyingScalar * debtScalar
```
## Calculate a Prime Cash Market's utilization
Prime Cash Market utilization is defined as a market's `debt / supply` in underlying terms:
```
from brownie.network.state import Chain
chain = Chain()
primeFactors = notional.getPrimeFactorsStored(currencyId, chain.time())
totalPrimeSupply = primeFactors["factors"]["totalPrimeSupply"]
totalPrimeDebt = primeFactors["factors"]["totalPrimeDebt"]
supplyScalar = primeFactors["factors"]["supplyScalar"]
debtScalar = primeFactors["factors"]["debtScalar"]
# Utilization is calculated in underlying terms.
# Utilization = accruedDebtUnderlying / accruedSupplyUnderlying
# Utilization = (totalPrimeDebt * underlyingScalar * debtScalar) / (totalPrimeSupply * underlyingScalar * supplyScalar)
# Note that the underlyingScalar cancels out in both numerator and denominator
utilization = (totalPrimeDebt * debtScalar) / (totalPrimeSupply * supplyScalar)
```
## Fetch Prime Cash markets Supply Rates and Borrowing Rates
from brownie.network.state import Chain
chain = Chain()
primeFactors = notional.getPrimeFactors(currencyId, chain.time())
# Prime Cash Supply Rate
oracleSupplyRate = primeFactors["primeRate"]["oracleSupplyRate"]/1e9
# Prime Cash Borrow Rate
TODO after contract upgrade
# fCash Markets
## Get active fCash Markets
We can use the `getActiveMarkets` method to get a list of the current active markets in a given currency:
```
activeMarkets = notional.getActiveMarkets(currencyId)
```
## Get a market's total fCash and total Prime Cash holdings
```
market3Months = activeMarkets[0]
market6Months = activeMarkets[1]
# Get the maturity of the 3 Month market
maturity = market3Months[1]
# Get the 3 Month market total Prime Cash balance
primeCashBalance3MonthMarket = market3Months[3]/1e8
# Get the 3 Month market total fCash balance
fCashBalance3MonthMarket = market3Months[2]/1e8
```
## Get a market's utilization
An fCash market's utilization is defined as total `fCash/ (total fCash + total Prime Cash in underlying)`:
from brownie.network.state import Chain
chain = Chain()
primeFactors = notional.getPrimeFactorsStored(currencyId, chain.time())
supplyScalar = primeFactors["factors"]["supplyScalar"]/1e18
underlyingScalar = primeFactors["factors"]["underlyingScalar"]/1e18
marketPrimeCashSupply = primeCashBalance3MonthMarket * underlyingScalar * supplyScalar
fCashMarketUtilization = fCashBalance3MonthMarket / (fCashBalance3MonthMarket + marketPrimeCashSupply)
## Get fCash rates
```
# Last Implied Rate 3 Month Market
lastImpliedRate = market3Months[5]
# Oracle Rate 3 Month Market
oracleRate = market3Months[6]
```
# nTokens
## Get nToken Address
```
nTokenAddress = notional.nTokenAddress(currencyId)
```
## Get nToken Total Supply
```
nTokenSupply = notional.nTokenTotalSupply(nTokenAddress)
```
## Get nToken PV
```
nTokenPV = notional.nTokenPresentValueUnderlyingDenominated(currencyId)
```
## Get the underlying value of one nToken
```
nTokenValue = nTokenPV / nTokenSupply
```
## Get nToken Portfolio
An nToken portfolio can hold multiple positions (Prime Cash, fCash, Liquitity tokens):
nTokenPrimeCashBalance = notional.getNTokenAccount(nTokenAddress)["cashBalance"]
nTokenFCashPortfolio = notional.getNTokenPortfolio(nTokenAddress)["netfCashAssets"]
nToken3MFCashMaturity = notional.getNTokenPortfolio(nTokenAddress)["netfCashAssets"][0][1]
nToken3MFCashBalance = notional.getNTokenPortfolio(nTokenAddress)["netfCashAssets"][0][3]
nTokenLiquidityTokenPortfolio = notional.getNTokenPortfolio(nTokenAddress)["liquidityTokens"]
nToken3MLiquidityTokenMaturity = notional.getNTokenPortfolio(nTokenAddress)["liquidityTokens"][0][1]
nToken3MLiquidityTokenBalance = notional.getNTokenPortfolio(nTokenAddress)["liquidityTokens"][0][3]
## nToken Annual Incentive Rate
The nToken annual incentive rate defines the number of NOTE tokens that are given as incentives annually to nToken holders:
```
incentiveAnnualRate = notional.getNTokenAccount(nTokenAddress)["incentiveAnnualEmissionRate"]
```
# Leveraged Vaults
## Get Leveraged Vault Configuration Parameters
The `getVaultConfig` method can be used to get a Leverage Vault's parameters:
```
vaultConfigs = notional.getVaultConfig(vaultAddress)
vaultFeeRate = vaultConfigs["feeRate"]/1e9
liquidationRate = vaultConfigs["liquidationRate"]/1e9 - 1
reserveFeeShare = vaultConfigs["reserveFeeShare"]/100
minAccountBorrowSize = vaultConfigs["minAccountBorrowSize"]/1e8
maxRequiredAccountCollateralRatio = vaultConfigs["maxRequiredAccountCollateralRatio"]/1e9
maxDeleverageCollateralRatio = vaultConfigs["maxDeleverageCollateralRatio"]/1e9
minCollateralRatio = vaultConfigs["minCollateralRatio"]/1e9
```
## Fetch a Leveraged Vault State
The `getVaultState` method can be called to get the total amount of vault shares and debts of a given leveraged vault strategy:
```
vaultState = notional.getVaultState(accountAddress, maturityTimestamp)
totalVaultShares = vaultState["totalVaultShares"]
totalDebtUnderlying = vaultState["totalDebtUnderlying"]
```
# Oracles
## Fetch the Price Oracle Address for a given currency
The `getRateStorage` method can be used to fetch the addresses of price oracles used by the Notional protocol:
```
# Fetch the DAI/ETH price oracle address.
DaiEthOracleAddress = notional.getRateStorage(2)["ethRate"]["rateOracle"]
# Fetch the USDC/ETH price oracle address.
UsdcEthOracleAddress = notional.getRateStorage(3)["ethRate"]["rateOracle"]
```
## ETH Price Oracle Exchange Rates
The `getCurrencyAndRates` method can be used to fetch the current ETH price oracles used to value accounts in the Notional system:
```
# Fetch the DAI/ETH price oracle exchange rate.
notional.getCurrencyAndRates(2)["ethRate"]["rate"]/notional.getCurrencyAndRates(2)["ethRate"]["rateDecimals"]
# Fetch the USDC/ETH price oracle exchange rate.
notional.getCurrencyAndRates(3)["ethRate"]["rate"]/notional.getCurrencyAndRates(3)["ethRate"]["rateDecimals"]
```
# Governance parameters
## fCash Interest Rate Models
# Fetch Notional's fDAI Interest Rate Models.
fCashInterestRateCurves = notional.getInterestRateCurve(1)['activeInterestRateCurve']
interestRateCurve3M = fCashInterestRateCurves[0]
interestRateCurve6M = fCashInterestRateCurves[1]
## Collateral Haircut & Buffers
```
# Fetch Notional's USDC collateral haircut.
usdcCollateralHaircut = notional.getRateStorage(3)["ethRate"]["haircut"]/100
# Fetch Notional's USDC debt buffer.
usdcDebtBuffer = notional.getRateStorage(3)["ethRate"]["buffer"]/100
```
## Liquidation Discount Parameters
```
# Fetch Notional's USDC Liquidation Discount.
notional.getRateStorage(3)["ethRate"]["liquidationDiscount"]/100 - 1
```
## fCash Risk Adjustments Parameters
```
# Fetch the fcash haircuts and debt buffers rate adjustment that are made to the oracles rates:
notional.getCashGroup(currencyId)["debtBuffer25BPS"]
notional.getCashGroup(currencyId)["fCashHaircut25BPS"]
# Fetch the fCash liquidation discounts given to fCash liquidators.
notional.getCashGroup(currencyId)["liquidationDebtBuffer25BPS"]
notional.getCashGroup(currencyId)["liquidationfCashHaircut25BPS"]
# Fetch the minimum oracle rate at which negative fCash can be discounted
# and the maximum oracle rate at which positive fCash can be discounted.
notional.getCashGroup(currencyId)["minOracleRate25BPS"]
notional.getCashGroup(currencyId)["maxOracleRate25BPS"]
# Fetch the maximum fCash discount factor. 1 - maxDiscountFactor is the min fCash PV of positive fCash assets.
notional.getCashGroup(currencyId)["maxDiscountFactor5BPS"]
```
# Notional V3 Subgraphs
## The Graph & subgraphs
The Graph is a decentralized protocol for indexing and querying data from blockchains. Anyone can build and publish open APIs, called subgraphs, making data easily accessible in a decentralized and reliable way. Subgraphs make it possible for anyone to query data that would otherwise be difficult to query on-chain directly. Each subgraph pays attention to events of a project’s contracts and maps that event data to data that The Graph stores in its database. Learn more about The Graph [here](https://thegraph.com/docs/en/about/introduction/).
### GraphQL
GraphQL is the underlying query language utilized in The Graph. GraphQL is especially useful for calls requiring lots of information where instead of making multiple API calls one only needs to do one subgraph call to get all of the information needed. Learn more about GraphQL [here](https://graphql.org/learn/).
## Notional Subgraphs
| Version | Network | Subgraph Endpoint |
| ----------- | -------- | --------------------------------------------------------------------------------------- |
| Notional V3 | Mainnet | [Link](https://api.studio.thegraph.com/query/60626/notional-v3-mainnet/v0.0.9) |
| Notional V3 | Arbitrum | [Link](https://api.studio.thegraph.com/query/60626/notional-v3-arbitrum/version/latest) |
## Query Notional’s subgraph with python
To run subgraph queries through python one can use the following script and modify the url to the appropriate endpoint and modify the GQL query:
```
from gql import gql, Client from gql.transport.requests
import RequestsHTTPTransport
#Connect with theGraph
sample_transport = RequestsHTTPTransport( url="https://api.studio.thegraph.com/proxy/33671/notional-finance-v3-arbitrum/v0.0.135/", # change to the appropriate endpoint
verify=True, retries=10, ) client = Client( transport=sample_transport )
#Update the GQL query
query = gql('''
{
accounts(first: 1000, where:{ systemAccountType: None}) {
id
}
}
''')
response = client.execute(query)
```
We will go over a few example queries to explore Notional's V3 subgraph.
# Fetch Notional Accounts
## Get a list of account Ids
This query can be used to get a list of Notional account addresses:
```
{
accounts(first: 1000, where:{ systemAccountType: None}) {
id
}
}
```
## Get an Account current positions and balances
This query can be used to get the current balances of a given Notional account:
```
{
accounts(where:{id:"0x4e8014ff5bace498dab1a9e2b5c3f4240bc059b6"}) {
id
balances {
token{symbol}
snapshots(first:1, orderBy:blockNumber, orderDirection:desc) {
currentBalance
}
}
}
}
```
# Fetch Notional's reserves
## Get Notional's Reserve balances
This query can be used to fetch the protocol's Prime Cash reserves:
```
{
accounts(where:{ systemAccountType: FeeReserve}) {
id
balances {
token{symbol}
snapshots(first:1, orderBy:blockNumber, orderDirection:desc) {
currentBalance
}
}
}
}
```
# Fetch Notional nToken accounts
## Get Notional's nToken accounts balances
This query can be used to fetch nToken accounts positions:
```
{
accounts(where:{ systemAccountType: nToken}) {
id
balances {
token{symbol}
snapshots(first:1, orderBy:blockNumber, orderDirection:desc) {
currentBalance
}
}
}
}
```
# Fetch Historical Trades
## Get all fCash historical trades
This query can be used to fetch historical fCash trades. This includes fCash trades occurring upon nToken redemptions and nToken mints above the leverage threshold.
```
{
transferBundles(orderBy:timestamp, where:{bundleName_in:["Buy fCash","Sell fCash"], transfers_:{tokenType:"fCash"}}){
bundleName
timestamp
transfers{
from{id}
to{id}
token{symbol}
value
valueInUnderlying
}
}
}
```
# Fetch an Account's P\&L
## Fetch the historical P\&L of a given account
This query can be used to fetch the historical per position P\&L of a Notional user:
```
{
accounts(where:{id: "0x4e8014ff5bace498dab1a9e2b5c3f4240bc059b6"}) {
id
balances {
id
token { symbol }
snapshots(orderBy:blockNumber, orderDirection:desc) {
id
currentBalance
_accumulatedBalance
_accumulatedCostRealized
_accumulatedCostAdjustedBasis
adjustedCostBasis
currentProfitAndLossAtSnapshot
totalILAndFeesAtSnapshot
totalProfitAndLossAtSnapshot
totalInterestAccrualAtSnapshot
profitLossLineItems {
id
tokenAmount
bundle {bundleName}
underlyingAmountRealized
underlyingAmountSpot
realizedPrice
spotPrice
}
}
}
}
}
```
# Fetch current fCash and Prime Cash Rates
## Get current Prime Cash lending rates
This query can be used to get current Prime Cash variable lending rates:
```
{
oracles(where:{oracleType: "PrimeCashSpotInterestRate"}){
base{symbol}
latestRate
}
}
```
## Get current Prime Cash borrowing rates
This query can be used to get current Prime Cash variable borrowing rates:
```
{
oracles(where:{oracleType: "PrimeDebtSpotInterestRate"}){
base{symbol}
latestRate
}
}
```
## Get current fCash rates
This query can be used to get current fCash fixed last implied rates:
```
{
oracles(where:{oracleType: "fCashSpotRate"}){
base{
symbol
}
quote{
symbol
maturity
}
latestRate
}
}
```
# Fetch Historical Prime Cash & Prime Debt Exchange Rates
## Get Prime Cash to Underlying exchange rates
This query can be used to fetch the underlying exchange rate between Prime Cash and the underlying currency:
```
{
primeCashMarkets{
snapshots(orderBy: timestamp, orderDirection:desc){
market{
id
}
timestamp
underlyingScalar
supplyScalar
}
}
}
```
## Get Prime Debt to Underlying exchange rates
This query can be used to fetch the underlying exchange rate between Prime Debts and the underlying currency:
```
{
primeCashMarkets{
snapshots(orderBy: timestamp, orderDirection:desc){
market{
id
}
timestamp
underlyingScalar
debtScalar
}
}
}
```
# Fetch Prime Cash Market Balances
## Get Prime Cash Market Balances
This query can be used to fetch Prime Cash market balances and a Prime Cash markets total debt outstanding:
```
{
primeCashMarkets{
snapshots(first: 1, orderBy: timestamp, orderDirection:desc){
market{
id
}
timestamp
underlyingScalar
supplyScalar
debtScalar
totalUnderlyingHeld
totalPrimeCashInUnderlying
totalPrimeDebtInUnderlying
totalPrimeCash
totalPrimeDebt
}
}
}
```
# Fetch fCash Market Balances
## Get fCash Market balances
This query can be used to fetch fCash market total balances and a fCash markets total debt outstanding:
```
{
fCashMarkets{
snapshots(first: 1, orderBy: timestamp, orderDirection:desc){
market{id}
totalPrimeCash
totalfCash
totalPrimeCashInUnderlying
totalfCashPresentValue
totalfCashDebtOutstanding
totalfCashDebtOutstandingPresentValue
}
}
}
```
# Fetch Outstanding Debt
## Get Prime Cash and fCash Markets Outstanding Debts
This query can be used to fetch Notional outstanding variable and fixed debts:
```
{
primeCashMarkets{
snapshots(first: 1, orderBy: timestamp, orderDirection:desc){
market{id}
totalPrimeDebtInUnderlying
}
}
fCashMarkets{
snapshots(first: 1, orderBy: timestamp, orderDirection:desc){
market{id}
totalfCashDebtOutstandingPresentValue
}
}
}
```
# Fetch Historical nToken Exchange Rates
## Get nToken to underlying historical exchange rates
This query can be used to get the historical exchange rates between an underlying currency and an nToken PV:
```
{
oracles(where:{oracleType:"nTokenToUnderlyingExchangeRate"}){
base{symbol}
latestRate
}
}
```
# Fetch ETH Oracle Exchange Rates
## Get Historical Price Oracle Exchange Rates
This query can be used to get historical Chainlink oracle prices for all listed base currencies:
```
{
oracles(where:{oracleType:"Chainlink"}){
base{symbol}
quote{symbol}
latestRate
}
}
```
# Fetch Annual Incentive Rates
## Get nToken Annual NOTE Incentive Rates
This query can be used to fetch the annual NOTE incentive rates for all nTokens:
```
{
currencyConfigurations{
underlying{symbol}
incentiveEmissionRate
}
}
```
# Fetch Interest Rate Models
## Get Prime Cash and fCash Interest Rate Models
This query can be used to fetch Prime Cash and fCash interest rate models. Ids reference the currency, the market index and if the model is the current Interest rate model or the next interest rate model. For example, the id "3:0:current" identifies the Prime Cash Market for currency id 3 (USDC). Id "6:2:current" identifies the 6 month fCash market (market index = 2) interest rate model for currency id 6 (FRAX).
```
{
interestRateCurves{
id
kinkRate1
kinkRate2
kinkUtilization1
kinkUtilization2
maxRate
maxFeeRate
minFeeRate
feeRatePercent
}
}
```
# Fetch Governance Parameters
## Get Governance Parameters and Configurations
This query can be used to fetch Notional's governance parameters per currency:
```
{
currencyConfigurations {
underlying {
symbol
}
collateralHaircut
debtBuffer
proportions
depositShares
residualPurchaseTimeBufferSeconds
residualPurchaseIncentiveBasisPoints
fCashMinOracleRate
fCashMaxOracleRate
fCashMaxDiscountFactor
fCashHaircutBasisPoints
fCashDebtBufferBasisPoints
fCashReserveFeeSharePercent
fCashRateOracleTimeWindowSeconds
fCashLiquidationDebtBufferBasisPoints
pvHaircutPercentage
primeDebtAllowed
leverageThresholds
rebalancingTargets
rebalancingCooldown
liquidationDiscount
liquidationHaircutPercentage
maxUnderlyingSupply
primeCashRateOracleTimeWindowSeconds
treasuryReserveBuffer
}
}
```
