Subgraph Reference

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 directly query on-chain. 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.

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.

Resources & links

Notional subgraphs

Version	Network	Subgraph address
Notional v2	Mainnet	https://thegraph.com/hosted-service/subgraph/notional-finance/mainnet-v2
Notional v2	Kovan	https://thegraph.com/hosted-service/subgraph/notional-finance/kovan-v2?selected=playground
Notional v2	Goerli	https://thegraph.com/hosted-service/subgraph/notional-finance/goerli-v2
Notional v1	Mainnet	https://thegraph.com/hosted-service/subgraph/notional-finance/mainnet
Notional v1	Kovan	https://thegraph.com/explorer/subgraph/notional-finance/kovan

Github repositories

Version	Repository
Notional v2	https://github.com/notional-finance/subgraph-v2
Notional v1	https://github.com/notional-finance/subgraph

How to build and test queries

One can easily build subgraph queries using The Graph’s playground (see links above). The playground works as follows:

• Build your query by modifying the example query on the left side of the screen. You can always refer to the subgraph’s schema on the right side of your screen to explore the subgraph’s data and structure.

• Execute the query by pressing the play button which will display the results in the middle portion of the screen.

Particularities of Notional’s subgraph

• Most variables in Notional’s subgraph are 8 decimals (10^8). This includes the following variables: depositShares, balances, portfolio assets, asset Cash, fCash, TVL and many more.

• Rates variable are all 9 decimals (10^9). This includes the following variables: lastImpliedRates, oracleRates, totalFeeBasisPoints, fCashHaircutBasisPoints, annualizedAnchorRates, leverageThresholds, proportions, settlementPenaltyRateBasisPoints etc.

• When querying a specific account id or set of account ids, they must be in lower case format. Each results 'page' returns 100 entries by default. This can be increased to a maximum of 1000 entries per page by specifying (first:1000, skip:0). The skip variable can be used to iterate through results ex: (first:1000, skip:1000).

• Variables that are labeled as assetCash can be yield baring assets instruments in the underlying currency (ex: cTokens). As an example USDC cash assets in Notional are cUSDC tokens. In order to get the value of cash asset in the underlying currency (ex: convert cUSDC to USDC) one needs to use the historical asset exchange rates (see query example below).

• Notional uses currency ids to identify the different currencies in its system. Here is a list of the underlying currency symbols by currency ids:

  • Currency id #1 = ETH

  • Currency id #2 = DAI

  • Currency id #3 = USDC

  • Currency id #4 = WBTC

• 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, a market index of 1 would be a 3 Month fCash market and a market with an index of 3 would be a 1 Year fCash market.

Querying Notional’s subgraph with python

To run these 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.thegraph.com/subgraphs/name/notional-finance/mainnet-v2", # change to the appropriate endpoint 
verify=True, retries=10, ) client = Client( transport=sample_transport )

#Update the GQL query
query = gql('''
{
    trades(first: 100, skip: 0){
        id
        timestamp
        maturity
        tradeType
        netfCash
        netUnderlyingCash
    }
}''')

response = client.execute(query) 

Examples of common queries

Here are a few example queries to play with in the subgraph playgrounds.

Get account ids

To get a list of all account addresses that used Notional:

{
  accounts(first:1000, skip:0){
    id
  }
}

Get historical trades

To get historical borrow and lend fCash trades:

{
 trades(first: 1000, skip:0){
    id
    timestamp
    tradeType
    maturity
    netfCash
    netUnderlyingCash
    currency{underlyingSymbol}
    market{marketIndex}
    account{id}
  }
}

Get current interest rates

To get the last implied interest rate and oracle rate of different markets:

{
  markets{
    lastImpliedRate
    oracleRate
    currency{underlyingSymbol}
    marketIndex
    maturity
  }
}

Get an account portfolio & balances

To get an account portfolio assets and balances. As mentioned above the account id has to be lower case:

{
 accounts(where:{id:"0x193991827e291599a262e7fa7d212ff1ae31d110"}){
   id
   balances{
    currency{underlyingSymbol}
    assetCashBalance
    nTokenBalance
    }
    portfolio{
      currency{underlyingSymbol}
      maturity
      assetType
      notional
     }
   }
}

Get nToken account portfolios

To get nToken account portfolios:

{
  nTokens{
    name
    account{
    id
    balances{
    currency{underlyingSymbol}
    assetCashBalance
    nTokenBalance
    }
    portfolio{
      currency{underlyingSymbol}
      maturity
      assetType
      notional
    }
  }
}
}

Get nToken governance parameters

To get nToken governance parameters where the depositShares and incentiveEmissionRate are 8 decimals and rates (annualizedAnchorRates, proportions, leverageThresholds) are 9 decimals:

{
  nTokens{
    name
    depositShares
    pvHaircutPercentage
    liquidationHaircutPercentage
    leverageThresholds
    annualizedAnchorRates
    proportions
    incentiveEmissionRate
  }
}

Get cash group governance parameters

To get governance parameters where fCashHaircutBasisPoints, debtBufferBasisPoints, liquidationfCashHaircutBasisPoints, liquidationDebtBufferBasisPoints, settlementPenaltyRateBasisPoints and totalFeeBasisPoints variables are 9 decimals:

{
  cashGroups{
    rateScalars
    rateOracleTimeWindowSeconds
    totalFeeBasisPoints
    reserveFeeSharePercent
    fCashHaircutBasisPoints
    liquidationfCashHaircutBasisPoints
    debtBufferBasisPoints
    liquidationDebtBufferBasisPoints
    settlementPenaltyRateBasisPoints
    liquidityTokenHaircutsPercent
  }
}

Get currency underlying symbols from currency ids

To get the currency underlying symbol per currency id:

{
  currencies(where:{id:1}){
      underlyingSymbol
  }
}

Get Notional current TVL

To get Notional’s total TVL in USD and the TVL breakdown per currency:

{
  tvlHistoricalDatas(first:1, orderBy: timestamp, orderDirection:desc){
    timestamp
    usdTotal
    perCurrencyTvl{
      currency{underlyingSymbol}
      usdValue
    }
  }
}

Get historical asset exchange rates

To get the latest asset exchange rate (ex: the cUSDC to USDC exchange rate):

{
  assetExchangeRateHistoricalDatas(first:1, orderBy:timestamp, orderDirection:desc){
    timestamp
    value
    currency{underlyingSymbol}
  }
}

Get historical ETH exchange rates

To get the latest ETH exchange rate (ex: the USDC to ETH exchange rate):

{
  ethExchangeRateHistoricalDatas(first:1, orderBy:timestamp, orderDirection:desc){
    id
    timestamp
    value
    currency{underlyingSymbol}
  }
}

Get historical liquidations

To get historical Notional liquidations. The netLocalFromLiquidator is the amount of cash asset (ex: cTokens) the liquidator paid in local currency to buy the collateral of fCash currency. If the collateralOrFcashCurrency is null, the collateral currency is the local currency.

{
  liquidations(first:100, skip:0){
    timestamp
    type
    account{id}
    liquidator{id}
    localCurrency{underlyingSymbol}
    collateralOrFcashCurrency{underlyingSymbol}
    netLocalFromLiquidator
    netNTokenTransfer
    netCollateralTransfer
    fCashNotionalTransfer
    fCashMaturities
  }
}