Subgraph
Voltz Subgraph

API Overview

This section explains the Voltz Protocol Subgraph and how to interact with it through GraphQL queries. Any time a trade position is opened or liquidity is supplied i.e. any time a smart contract is called through the Voltz Protocol the subgraph updates to keep track and organise the data about the transactions over time.

Resources

You can access the Voltz Protocol V1 subgraph here. The repository with the GraphQL schema to the Voltz subgraph can be found here.

Usage

The subgraph tracks the state of the Voltz Protocol and provides historical data about positions traded, liquidity burns, mints and more. To learn more about how to query the Voltz subgraph refer to the documentation on GraphQL.

Entities

Entities define the GraphQL schema of the Voltz subgraph and represents the data structures which can be queried to retrieve information related to each entity. For example, you might be interested in finding out the all time transaction count.

Factory

There is only one Factory entity in the Voltz subgraph.
Field Name
Value Type
Description
id
ID
Factory contract address
owner
ID
Owner address

UnderlyingToken

Stores aggregated information for a specific token across all trades where the token is included.
Field Name
Value Type
Description
id
ID
Underlying token address e.g. for USDC
name
String
Name of the underlying token e.g. USDC
decimals
BigInt
Number of decimal places for the underlying token

RateOracle

The RateOracle entity is responsible for storing the underlying yield bearing token.
Field Name
Value Type
Description
id
ID
Rate Oracle contract address
protocolD
BigInt
Name of the underlying token e.g. USDC
token
UnderlyingToken
Reference to the UnderlyingToken entity.

AMM

The AMM entity stores key information about the current state of a given pool.
Field Name
Value Type
Description
id
ID
vAMM contract address
createdTimestamp
BigInt
When the pool was initiated
fcm
FCM
Reference to the FCM entity of the given pool
marginEngine
MargineEngine
Reference to the MarginEngine entity of the given pool
rateOracle
RateOracle
Reference to the RateOracle entity of the given pool
tickSpacing
BigInt
Granularity of the ticks
termStartTimestamp
BigInt
Time the pool was initiated
termEndTimestamp
BigInt
Maturity date of the pool
updatedTimestamp
BigInt
When the last event from the vAMM smart contract is emitted
tick
BigInt
Current tick of the underlying vAMM of the pool
txCount
BigInt
Number of transactions in the current pool
mints
[Mint]
Derived from the field AMM and represents an array of Mint events within the current pool.
burns
[Burn]
Derived from the field AMM and represents an array of Burn events within the current pool
swaps
[Swap]
Derived from the field AMM and represents an array of Swap events within the current pool
marginUpdates
[MarginUpdate]
Derived from the field AMM and represents an array of marginUpdate events within the current pool.
liquidations
[Liquidations]
Derived from the field AMM and represents an array of liquidation events within the current pool.
settlements
[Settlement]
Derived from the field AMM and represents an array of settlement events within the current pool.

MarginEngine

The MarginEngine entity stores the address of the underlying MarginEngine of the current pool. Used mostly for linking vAMM to it.
Field Name
Value Type
Description
id
ID
Margin Engine contract address
amm
AMM
Reference to the corresponding AMM entity

FCM

The FCM entity stores the stores address of the underlying MarginEngine of the current pool. Used mostly for linking vAMM to it.
Field Name
Value Type
Description
id
ID
Margin Engine contract address
amm
AMM
Reference to the corresponding AMM entity

Wallet

The Wallet entity stores information about the positions and their total count for a given wallet.
Field Name
Value Type
Description
id
ID
Wallet address
positions
[Position]
Derived from field Owner and represents all positions of the specific wallet
positionCount
BigInt
Number of open positions in this specific wallet
fcmPositions
[FCMPositions]
Derived from the field owner and represents an array of the fcm positions within a wallet
fcmPositionCount
BigInt
Number of FCM positions held in a given wallet.

Position

The Position entity gives the information on the position at the current time.
Field Name
Value Type
Description
id
ID
Unique identifier for the position
createdTimestamp
BigInt
Time when position was opened
amm
AMM
Reference to the corresponding AMM entity
owner
Wallet
Owner of the wallet address
tickLower
Tick
Lower bound of fixed rate range
tickUpper
Tick
Upper bound of fixed rate range
updatedTimestamp
BigInt
Time when position was updated/changed
liquidity
BigInt
Amount of liquidity deposited in the specific position
margin
BigInt
Amount of margin deposited in the specific position
fixedTokenBalance
BigInt
Number of fixed rate tokens of this position.
variableTokenBalance
BigInt
Number of variable rate tokens of this position
accumulatedFees
BigInt
The running total of the fees associated with a position??
isLiquidityProvider
Boolean
Is the position owner a liquidity provider?
isSettled
Boolean
Has the position been settled?
mints
[Mint]
Derived from the field Position and represents an array of Mint events within the position
burns
[Burn]
Derived from the field Position and represents an array of Burn events within the position
swaps
[Swap]
Derived from the field Position and represents an array of Swap events within the position
marginUpdates
[MarginUpdates]
Derived from the field AMM and represents an array of marginUpdate events within the current position.
liquidations
[Liquidations]
Derived from the field AMM and represents an array of liquidations events within the current position.
settlements
[Settlement]
Derived from the field AMM and represents an array of settlement events within the current position.

PositionSnapshot

The PositionSnapshot entity gives the position information at a specific time in the past.
Field Name
Value Type
Description
id
ID
Unique identifier for the position snapshot
createdTimestamp
BigInt
Time when position snapshot was created
position
Position
Reference to the corresponding Position entity
liquidity
BigInt
Amount of liquidity deposited in this position
margin
BigInt
Amount of margin deposited in this position
fixedTokenBalance
BigInt
Number of fixed rate tokens of this position.
variableTokenBalance
BigInt
Number of variable rate tokens of this position
accumulatedFees
BigInt
The running total of the fees associated with a position??
isLiquidityProvider
Boolean
Is the position owner a liquidity provider?
isSettled
Boolean
Has the position been settled?

Transaction

The Transaction entity gives information about a transaction in the past.
Field Name
Value Type
Description
id
ID
Unique identifier for the transaction
amm
AMM
Reference to the corresponding AMM
blockNumber
BigInt
Block transaction was mined in
createdTimestamp
BigInt
Creation timestamp of the transaction
gasPrice
BigInt
Gas price associated with the transaction
mints
[Mint]
Derived from the field Transaction and represents an array of Mint events within the transaction.
burns
[Burn]
Derived from the field Transaction and represents an array of Burn events within the transaction.
swaps
[Swap]
Derived from the field Transaction and represents an array of Swap events within the transaction.
marginUpdates
[MaginUpdates]
Derived from the field Transaction and represents an array of marginUpdate events within the current transaction.
liquidations
[Liquidations]
Derived from the field Transaction and represents an array of liquidations events within the current transaction.
settlements
[Settlements]
Derived from the field Transaction and represents an array of settlements events within the current transaction.

Mint

Any time a minting event is emitted by the smart contracts a corresponding mint entity is created to store key data like timestamp, gasPrice and more.
Field Name
Value Type
Description
id
ID
Unique identifier for the mint
transaction
Transaction
Reference to the transaction the Mint was included in
amm
AMM
Reference to the corresponding AMM entity
position
Position
Reference to corresponding Position entity
sender
String
Address of the sender initiating the mint
amount
BigInt
Amount of tokens to be minted based on the underlying asset e.g. USDC

Burn

Any time a burn event is emitted by the smart contracts a corresponding burn entity is created to store key data like who burned the position, the position itself and the amount burned.
Field Name
Value Type
Description
id
ID
Unique identifier of the burn
transaction
Transaction
Reference to Transaction entity
amm
AMM
Reference to corresponding AMM entity
position
Position
Reference to corresponding Position entity
sender
String
Address which initiated the burn event
amount
BigInt
Amount of tokens to be burned based on the underlying asset e.g. USDC

Swap

A swap entity is created when a swap takes place on the Voltz Protocol. It stores key information about the swap like the liquidity, the rate of the swap, and who initiated the swap.
Field Name
Value Type
Description
id
ID
Unique identifier for the swap
transaction
Transaction
Reference to corresponding Transaction entity
amm
AMM
Reference to corresponding AMM entity
position
Position
Reference to corresponding Position entity
sender
String
Address which initiated the swap
desiredNotional
BigInt
Desired notional amount of tokens to be traded e.g. USDC
sqrtPriceLimitX96
BigInt
Price of the underlying pool square rooted multiplied by 2^96 for scaling purposes
cumulativeFeeIncurred
BigInt
Running total of fees incurred for a swap ???
fixedTokenDelta
BigInt
Delta in fixed token balance induced by the swap
variableTokenDelta
BigInt
Delta in variable token balance induced by the swap
fixedTokenDeltaUnbalanced
BigInt
Unnormalised difference in fixed token balance

Liquidations

The liquidations entity stores information about the transactions which were liquidated, the liquidator, their reward, and the amount of notional unwound in the liquidation.
Field Name
Value Type
Description
id
ID
Unique identifier of the liquidation
transaction
Transaction
Reference to the Transaction entity corresponding to this liquidation
amm
AMM
Reference to the AMM entity corresponding to this liquidation
position
Position
Reference to the Position entity corresponding to this liquidation
liquidator
String
Address of the liquidator
reward
BigInt
Reward value for the liquidator
notionalUnwound
BigInt
Amount of notional liquidated

Settlement

Field Name
Value Type
Description
id
ID
Unique identifier of the settlement
transaction
Transaction
Reference to the Transaction entity corresponding to this settlement
amm
AMM
Reference to the AMM entity corresponding to this settlement
position
Position
Reference to the Position entity corresponding to this settlement
settlementCashflow
BigInt
Cashflow owed to the position owner at maturity

MarginUpdate

The MarginUpdate entity stores information on the positions where the margin was updated by the position owner.
Field Name
Value Type
Description
id
ID
Unique identifier for the MarginUpdate
transaction
Transaction
Reference to the Transaction entity corresponding to this margin update.
amm
AMM
Reference to the AMM entity corresponding to this margin update.
position
Position
Reference to the position entity corresponding to this margin update.
depositer
String
Address of the owner depositing extra margin
marginDelta
BigInt
Amount of margin the user deposited in the margin update operation

FCMPosition

The FCMPosition entity stores key information about FCM position at the current time.
Field Names
Value Types
Description
id
ID
Unique identifier for the FCM position
createdTimestamp
BigInt
Time when the FCM position was created
amm
AMM
Reference to the corresponding AMM
owner
Wallet
Reference to the corresponding Wallet of the owner
updatedTimeStamp
BigInt
Time when the FCM position was updated
fixedTokenBalance
BigInt
The amount of fixed rate tokens based on an underlying yield-bearing asset
variableTokenBalance
BigInt
The amount of variable rate tokens based on an underlying yield-bearing asset
marginScaledYieldBearingTokens
BigInt
Position margin converted into yield bearing tokens
isSettled
Boolean
Has the position been settled?
fcmSwaps
[FCMSwap]
Derived from FCM position and represents an array of FCM swaps in the current FCM position.
fcmUnwinds
[FCMUnwind]
Derived from FCM position and represents an array of FCM unwinds in the current FCM position.
fcmSettlements
[FCMSettlement]
Derived from FCM position and represents an array of FCM settlements in the current FCM position.
snapshots
[FCMPositionSnapshot]
Derived from FCM position and represents an array of FCM position snapshots in the current FCM position.
snapshotCount
BigInt
The number of snapshots for a given FCM position.

FCMPositionSnapshot

The FCMPositionSnapshot entity contains the FCM position information at a specific time in the past.
Field Name
Value Type
Description
id
ID
Unique identifier for the position snapshot
createdTimestamp
BigInt
Time when position snapshot was created
fcmPosition
Position
Reference to the corresponding Position entity
fixedTokenBalance
BigInt
Number of fixed rate tokens of this position.
variableTokenBalance
BigInt
Number of variable rate tokens of this position
marginScaledYieldBearingTokens
BigInt
Position margin converted into yield bearing tokens
isSettled
Boolean
Has the position been settled?

FCMSwap

An FCM swap entity is created when an FCM swap takes place on the Voltz Protocol. It stores key information about the FCM swap.
Field Name
Value Type
Description
id
ID
Unique identifier for the position FCM swap
transaction
Transaction
Reference to the corresponding Transaction entity
amm
AMM
Reference to the corresponding AMM entity
fcmPosition
Position
Reference to the corresponding Position entity
desiredNotional
BigInt
Desired notional amount of tokens to be traded by the swap initiator e.g. USDC
sqrtPriceLimitX96
BigInt
Price of the underlying pool square rooted multiplied by 2^96 for scaling purposes
cumulativeFeeIncurred
BigInt
Running total of fees paid by the FCM swap initiator
fixedTokenDelta
BigInt
Difference between the upper and lower range of fixed tokens
variableTokenDelta
BigInt
Difference between the upper and lower range of variable tokens
fixedTokenDeltaUnbalanced
BigInt
Unnormalised difference in fixed token balance

FCMUnwind

An FCM unwind entity is created when an unwind or liquidation takes place on the Voltz Protocol.
Field Name
Value Type
Description
id
ID
Unique identifier for the position FCM swap
transaction
Transaction
Reference to the corresponding Transaction entity
amm
AMM
Reference to the corresponding AMM entity
fcmPosition
Position
Reference to the corresponding Position entity
desiredNotional
BigInt
Desired notional amount of tokens to be traded by the swap initiator e.g. USDC
sqrtPriceLimitX96
BigInt
Price of the underlying pool square rooted multiplied by 2^96 for scaling purposes
cumulativeFeeIncurred
BigInt
Running total of fees paid by the FCM swap initiator
fixedTokenDelta
BigInt
Difference between the upper and lower range of fixed tokens
variableTokenDelta
BigInt
Difference between the upper and lower range of variable tokens
fixedTokenDeltaUnbalanced
BigInt
Unnormalised difference in fixed token balance

FCMSettlement

An FCM settlement entity is created when an FCM settlement takes place on the Voltz Protocol.
Field Name
Value Type
Description
id
ID
Unique identifier for the position FCM swap
transaction
Transaction
Reference to the corresponding Transaction entity
amm
AMM
Reference to the corresponding AMM entity
fcmPosition
Position
Reference to the corresponding Position entity
settlementCashflow
BigInt
Cashflow owed to the position owner at maturity

Example Queries

The Voltz subgraph can be queried to retrieve key information about the state of the Voltz Protocol. This section will provide examples of common queries that you might use. To try these queries you need to visit the interactive sandbox for Voltz Subgraph.

Get information on an underlying token

You can query the information for an underlying token using:
1
{
2
underlyingTokens {
3
id
4
name
5
decimals
6
}
7
}
Copied!

Get information on a specific minting transaction

Here we receive the sender address and amount minted by the sender address by passing the minting ID of the mint we are querying.
1
{
2
mint {
3
id: transaction hash + "#" + index in mints Transaction array
4
sender
5
amount
6
}
7
}
Copied!

Get the snapshot of a position

To get a snapshot of a specific trade position you can pass the ID of that trade position and observe details like margin, fixedTokenBalance and whether the position is settled.
1
{
2
positionSnapshot {
3
id: <position>#<index>
4
createdTimestamp
5
position {
6
id
7
}
8
liquidity
9
margin
10
fixedTokenBalance
11
variableTokenBalance
12
isSettled
13
isEmpty
14
}
15
}
Copied!

Get AMM information

You can query the AMM information from the subgraph and pass arguments to order the results and limit the returned results such as the below example:
1
amms(first: 100, orderBy: $orderBy, orderDirection: asc) {
2
id
3
createdTimestamp
4
updatedTimestamp
5
fcmAddress
6
marginEngineAddress
7
rateOracle {
8
id
9
protocolId
10
token {
11
id
12
name
13
decimals
14
}
15
}
16
termStartTimestamp
17
termEndTimestamp
18
tickSpacing
19
sqrtPriceX96
20
liquidity
21
tick
22
txCount
23
}
Copied!