Subgraph
Voltz Subgraph
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.
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 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.
There is only one Factory entity in the Voltz subgraph.
Field Name | Value Type | Description |
|---|---|---|
id | ID | Factory contract address |
owner | ID | Owner address |
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 |
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. |
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 |
totalNotionalTraded | BigInt | Total notional traded for the given pool. |
totalLiquidity | BigInt | Total liquidity available for a given 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. |
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 |
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 |
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. |
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?? |
totalNotionalTraded | BigInt | Total notional traded in a specific position. |
sumOfWeightedFixedRate | BigInt | Sum of unbalancedFixedTokenDelta for all swaps in 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. |
snapshots | [PositionSnapshot] | Derived from the field Position and represents an array of Position Snapshots within the position. |
snapshotCount | BigInt | The total number of snapshots in a position |
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?? |
totalNotionalTraded | BigInt | Total notional traded in this position |
sumOfWeightedFixedRate | BigInt | Sum of unbalancedFixedTokenDelta for all swaps in a position. |
positionType | BigInt | Is it a fixed or variable rate position. Costin |
isSettled | Boolean | Has the position been settled? |
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. |
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 |
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 |
​
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 |
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 |
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 |
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 |
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 |
totalNotionalTraded | BigInt | Total notional traded in an FCM position. |
sumOfWeightedFixedRate | BigInt | Sum of unbalancedFixedTokenDelta for all swaps in an FCM position. |
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. |
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 |
totalNotionalTraded | BigInt | Total notional traded in a given FCM position. |
sumOfWeightedFixedRate | BigInt | Sum of unbalancedFixedTokenDelta for all swaps in an FCM position. |
isSettled | Boolean | Has the position been settled? |
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 |
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 |
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 |
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.
You can query the information for an underlying token using:
{
underlyingTokens {
id
name
decimals
}
}
Here we receive the sender address and amount minted by the sender address by passing the minting ID of the mint we are querying.
{
mint {
id: transaction hash + "#" + index in mints Transaction array
sender
amount
}
}
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.
{
positionSnapshot {
id: <position>#<index>
createdTimestamp
position {
id
}
liquidity
margin
fixedTokenBalance
variableTokenBalance
isSettled
isEmpty
}
}
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:
amms(first: 100, orderBy: $orderBy, orderDirection: asc) {
id
createdTimestamp
updatedTimestamp
fcmAddress
marginEngineAddress
rateOracle {
id
protocolId
token {
id
name
decimals
}
}
termStartTimestamp
termEndTimestamp
tickSpacing
sqrtPriceX96
liquidity
tick
txCount
}
Last modified 8mo ago