Subgraph
Hungry for data? Hot n' fresh Superfluid subgraphs ready to consume!
The Graph is the indexing layer of our industry. There is an ocean of open data created by blockchain networks, and the Graph will help you query it. You can use the Graph to get data on activity in the Superfluid ecosystem as well as many other types of on-chain data. You can also use the GraphQL Playground to start getting Superfluid specific data on any network.
Click a link to start testing queries in the playground:
Network | URL |
|---|---|
xDAI | |
Matic | |
Avalanche | |
Optimism | |
Arbitrum | |
Avalanche Fuji | |
Optimism Kovan | |
Arbitrum Rinkeby | |
Mumbai | |
Goerli | |
Ropsten | |
Kovan | |
Rinkeby |
- GraphQL Schema for Superfluid - https://github.com/superfluid-finance/protocol-monorepo/blob/dev/packages/subgraph/schema.graphql
If you'd like to help improve the subgraph, there is a complete development guide available in the repo:
- All addresses (
id,underlyingAddress, etc.) are lowercase (i.e. not checksummed). Be sure to convert addresses to lowercase first before making queries.
- The field
totalSubscriptionson theIndex,AccountTokenSnapshotandTokenStatistictypes is nowtotalSubscriptionsWithUnits. - The
Subscriberentity has been changed toSubscription. If you have been using thesubscriberproperty when querying any events, this has been changed tosubscriptionseverywhere. The only place wheresubscriberis still a field is on theSubscriptionentity as a property of typeAccount. - The
createdAtandupdatedAtfields are nowcreatedAtTimestampandupdatedAtTimestampon every type.
The Superfluid Subgraph consists of many entities that can be queried. You can think of entities as similar to tables within a traditional database. We have added significantly more entities in October 2021 - particularly new event entities and aggregate entities. We'll give you an overview of the subgraph's structure in this post, but you can always dive deeper by looking at the schema inside of our repository.
These entities are for the most part 1-to-1 mappings with the raw events from the contract. However for some of them, we have added additional data. This is noted in the
schema.graphql file and will be viewable in the playground as well. These entities are created once and never updated. For example, the FlowUpdatedEvent type will mirror the properties on the FlowUpdated event inside of the Superfluid contracts.Note: Each event entityidis formulated as follows:eventName-transactionHash-logIndex.
Note: event types in our legacy subgraph did not have 'Event' appended onto the end of their name. In our new v1 implementation, every event type is named 'Event Name' + 'Event.' For example,FlowUpdatedis nowFlowUpdatedEventandIndexCreatedis nowIndexCreatedEvent. This schema is applied to every other event type as well.
Higher order level entities (HOL) are an additional abstraction on top of events. They are not ephemeral in the same way the event entities are. They contain data on an entity over its "lifetime" and therefore may be updated over time. Here is an overview of our Higher Order Level Entities:
AccountAn entity created for any address which interacts with the Superfluid protocol.
TokenAn entity created for all 'valid' SuperTokens. Valid tokens are defined as tokens that have set the Superfluid host's value to the correct Superfluid host address within the token contract.
IndexAn entity that represents an
Index within a Superfluid instant distribution agreement (IDA)IndexSubscriptionAn entity that contains subscription data for a
subscriber account of a particular indexStreamAn entity that represents the lifetime of a stream between a
sender and a receiver. An account can create a stream or update its flow rate, but when they delete it, it is considered "dead." The next stream that is created between the same sender and receiver will generate a new stream entity. Therefore, multiple stream entities can be created between the same sender and receiver.StreamPeriodAn entity that represents a period of time in a
Stream with a specific constant flowRate. You can think of it as a portion of a Stream. Each time a Stream's flowRate is updated, a new StreamPeriod will be created.Note: the stream type is a replacement for the previously used Flow type (as of October '21). The below image provides a good visual outline of how theStreamandStreamPeriodtypes compare to the previously usedFlowtype.
A StreamPeriod vs a Stream vs a Flow
Aggregate entities are exactly what the name suggests - they are entities that store aggregate data. More specifically, we do this at an account-token level and also at a global token level. Here is an overview of our two Aggregate Entities:
TokenStatisticAn entity which aggregates all data for a single Token type.
AccountTokenSnapshotAn aggregate entity which aggregates data on an account's interaction with a given
token.There are many different ways to get the same data using GraphQL. Here are some examples to help get you started using the Superfluid subgraphs.
The number of items returned by a query can sometimes be limited. In this example, we are explicitly requesting that up to 100 items should be returned, by using the
first parameterNote: keep in mind that a maximum of 1000 items may be returned in a single query.
{
tokens(first: 100) {
id
symbol
name
underlyingAddress
}
}
List all streams that an account is currently receiving. You can swap receiver for sender to get all streams that an account is currently sending.
//graphql
query MyQuery {
streams(where: {receiver: "YOUR_ADDRESS_HERE"}) {
currentFlowRate
token {
symbol
}
sender {
id
}
receiver {
id
}
}
}
The following query will allow us to answer the following questions for an active stream between Alice ("0x658...") and Bob ("0xd66...")
token will return the token entity type - with the symbol and id in this case.createdAtTimestamp will return the timestamp at which the stream was created.updatedAtTimestamp will return the timestamp of the last time the stream was updated.currentFlowRate will return the current flow rate of the stream.streamedUntilUpdatedAt will return the amount streamed until updatedAtTimestamp/updatedAtBlockNote: to get the current (dynamic) total amount streamed, you can use the following formula: streamedUntilUpdatedAt + ((current time in seconds) - updatedAtTimestamp) * currentFlowRate
{
streams(where:{
sender: "0x658e1b019f2f30c8089a9ae3ae5820f335bd9ce4"
receiver: "0xd66e40b0c30595bec72153b502ac1e0c4785991b"
}
) {
token {
id
symbol
}
createdAtTimestamp
updatedAtTimestamp
currentFlowRate
streamedUntilUpdatedAt
}
}
Here, we can query the FlowUpdatedEvent type and use
first, orderBy and orderDirection to get the 10 most recently updated flows.Note: as explained in the previous higher order level entities section under theStreamtype, it's important to understand the difference between a Flow and a Stream. A Flow represents all streaming activity between 2 addresses for a given token, while a Stream may only represent a portion of that flow. A new stream period is created each time theflowRateis updated, and a new stream is created each time a stream is terminated and restarted again (with the creation happening upon restarting)
oldFlowRate - the flowRate of the previous stream (will return "0" if this is a newly created Flow)flowRate - the flowRate of the current streamstream - the Stream type associated with the flow. In our case, the next few items will come from the Stream type. Several streams may be returned if there have been multiple streams created for this flow.token - the token used in the updated flow. Here we are returning this token's symbolsender - the sender of the updated flow. Here we will return this sender's id (their address)receiver - the receiver of the updated flow. Here we will return this receiver's id (their address){
flowUpdatedEvents(first: 10, orderBy: timestamp, orderDirection: desc) {
oldFlowRate
flowRate
userData
stream {
token {
symbol
}
sender {
id
}
receiver {
id
}
}
}
}
Here, we can query all of the subscriptions a particular account is subscribed to.
subscriptions will return an IndexSubscription type for each Index that this account is subscribed totoken - the Token used in each subscription. Here we display the symbol.id - the ID of the IndexSubscription. This ID is composed of: subscriberAddress-publisherAddress-tokenAddress-IndexIdapproved - a boolean value that represents whether or not the subscription is approved. Approved subscriptions don't require subscribers to claim tokens that are distributed from the publisher.units - the total number of units allocated to this account in the index. If units is 0, it indicates that the subscription is "deleted". They are no longer subscribed to the index.totalAmountReceivedUntilUpdatedAt - the total amount of tokens that this account has received via this IDA index until updatedAtTimestamp/updatedAtBlock.{
accounts(where: {
#your address below
id: "0x..."
}) {
subscriptions{
index {
token{
symbol
}
}
id
approved
units
totalAmountReceivedUntilUpdatedAt
}
}
}
In this example, we can filter by & return data using a combination of an event type and HOL type. Here, we'll get the 10 most recent indexUpdatedEvents where the newIndexValue is greater than 1000 tokens.
We'll return the following from the Index type
indexValue - used to calculate the distribution amount that a user receives when the publisher updates the index value. The distribution amount can be calculated using the following formula:(index.indexValue - subscriber.indexValue) * subscriber.units
totalUnitsPending - he number of units allocated by the Index that are pending. This refers to the current (as of updatedAt) totalUnitsPending - not all that has ever been pending.totalUnitsApproved - he number of units allocated by the Index that have been approved. This refers to the current (as of updatedAt) totalUnitsApproved - not all that has ever been approved.totalUnits - the sum of totalUnitsPending and totalUnitsApproved.token - the type Token used in the index.symbol - the symbol of the Token used in the index{
indexUpdatedEvents (
first: 10,
orderBy: timestamp
orderDirection: desc
where: {
indexValue_gt: "1000000000000000000000"
}) {
index {
indexValue
totalUnitsPending
totalUnitsApproved
totalUnits
token {
symbol
}
}
}
}
As an example of how to use aggregate entities, let's take a look at a query using the Token Statistic type. In this case, we can see aggregate data for Super DAI on Polygon.
totalNumberOfActiveStreams - the total count of active streams using the token.totalNumberOfActiveIndexes - total number of active IDA indexes for the token.totalAmountStreamedUntilUpdatedAt - all-time total amount streamed until the updatedAtTimestamp/updatedAtBlock.totalOutFlowRate - total outflow rate of the token (how much value is being moved).totalAmountDistributedUntilUpdatedAt - all-time total amount distributed until the updatedAtTimestamp/updatedAtBlock.{
tokenStatistics(where: {
#DAIx address on Matic
id: "0x1305f6b6df9dc47159d12eb7ac2804d4a33173c2"
})
{
totalNumberOfActiveStreams
totalNumberOfActiveIndexes
totalAmountStreamedUntilUpdatedAt
totalOutflowRate
totalAmountDistributedUntilUpdatedAt
}
}
To query data on a specific account, we can use both the Account entity and the aggregate AccountTokenSnapshot entity. Note: if you're only interested in seeing an account's activity with a particular token, you can query AccountTokenSnapshot to get that data. Otherwise, the
Account entity will return an AccountTokenSnapshot for every token used for each id (i.e. for each Account's address).On the
Account entity:isSuperApp - returns true if the account is a super app, false if not.inflows - will return all Streams where Account is the sender.outflows - will return all Streams where Account is the receiver.On the
AccountTokenSnapshot entity:token - the address of the token used in streams or subscriptionstotalNumberOfActiveStreams - the total number of streams the account is associated with for the given tokentotalNetFlowRate - the total net flow rate of the account for the given token as of updatedAtTimestamp/updatedAtBlock.{
accounts(where: {
#enter an address below
id: "0x..."
})
{
isSuperApp
inflows {
currentFlowRate
token{
symbol
}
sender {
id
}
}
outflows {
currentFlowRate
token {
symbol
}
receiver {
id
}
}
accountTokenSnapshots{
token {
id
}
totalNumberOfActiveStreams
totalNetFlowRate
}
}
}
If you design a useful query, let us know and we will share it here!
Click a link to start testing queries in the playground:
Network | URL |
|---|---|
xDAI | |
Matic | |
Mumbai | |
Goerli | |
Ropsten | |
Kovan | |
Rinkeby |
The Legacy schema contains fewer entities and some subtle differences in schema. These differences are outlined in the above sections, but you can find the previous schema in full here:
NOTE: Please refer to the above section on Breaking Changes as of October 2021, and the section on Streams vs Flows in the above section on the V1 Subgraph documentation. For example, you'll notice in the below example that theFlowtype is used in a query. This type has been deprecated.
The Subgraph can only return a flow's
sum since the last on-chain event (flowUpdated, flowCreated, or flowDeleted). Therefore, if flowRate is greater than zero, you will need to calculate the tokens flowed since the last event. Use this equation to get the the total sum of tokens flowed:
{
tokens(where: { symbol: "USDCx" }) {
flows(
where: {
owner: "0x658e1b019f2f30c8089a9ae3ae5820f335bd9ce4"
recipient: "0xd66e40b0c30595bec72153b502ac1e0c4785991b"
}
) {
sum
flowRate
lastUpdate
}
}
}
Last modified 28d ago