From 0fda391668db54a18123c459fdfdb30ea6b868e5 Mon Sep 17 00:00:00 2001 From: Razvan Gabriel Date: Sat, 18 Jan 2025 13:44:05 +0200 Subject: [PATCH] feat(api): add example queries for streams and campaigns --- docs/api/01-overview.mdx | 2 +- docs/api/airdrops/the-graph/02-queries.md | 54 +++++++++++++++++++++-- docs/api/lockup/the-graph/04-queries.md | 39 +++++++++++++++- 3 files changed, 89 insertions(+), 6 deletions(-) diff --git a/docs/api/01-overview.mdx b/docs/api/01-overview.mdx index 17238ef..df74637 100644 --- a/docs/api/01-overview.mdx +++ b/docs/api/01-overview.mdx @@ -45,7 +45,7 @@ using The Graph since we launched Sablier Legacy in 2019. For our current apps, feature-oriented subgraphs used internally and by third-party services (e.g., Snapshot) and integrators. These subgraphs are hosted on The Graph Network, as well as on the The Graph Hosted Service. They can be used to query -Sablier data from the official [endpoints](/api/lockup/endpoints). EAch network has its own subgraph endpoints. +Sablier data from the official [endpoints](/api/lockup/endpoints). Each network has its own subgraph endpoints. - [Lockup endpoints](/api/lockup/endpoints) - [Lockup subgraph](https://github.com/sablier-labs/subgraphs/apps/lockup) (Vesting) diff --git a/docs/api/airdrops/the-graph/02-queries.md b/docs/api/airdrops/the-graph/02-queries.md index b27d419..4232010 100644 --- a/docs/api/airdrops/the-graph/02-queries.md +++ b/docs/api/airdrops/the-graph/02-queries.md @@ -7,7 +7,9 @@ title: "Queries" Building on top of the [entity structure](/api/airdrops/the-graph/entities) defined earlier, here are some common GraphQL queries for fetching data from the Sablier subgraph. -### Recent streams +## Campaigns + +### Recent campaigns ```graphql title="The 10 most recent campaigns" campaigns( @@ -52,7 +54,7 @@ a simple GraphQL description of what a certain entity (here the campaign) looks ::: ```graphql title="The next campaigns created by an address with a certain asset" -query getAirstreams_ByAsset($first: Int!, $skip: Int!, $asset: String!, $subgraphId: BigInt!, $chainId: BigInt!) { +query getCampaigns_ByAsset($first: Int!, $skip: Int!, $asset: String!, $subgraphId: BigInt!, $chainId: BigInt!) { campaigns( first: $first skip: $skip @@ -101,13 +103,15 @@ const CampaignFragment = gql(/* GraphQL */ ` ``` +## Actions (e.g. Claim) + ### Claim actions of a user on a certain campaign To check if a user has claimed their share from a distribution campaign we can look for a "Claim" action performed by or on behalf of that user. If the query yields a result, it means the uses has already claimed from the Airstream. -```graphql title="Claim action of a user on a certain campaign" -query getClaim($campaignId: ID!, $user: String!) { +```graphql title="Claim actions of a user on a certain campaign" +query getClaim_ByUserByCampaign($campaignId: String!, $user: String!) { actions(where: { campaign: $campaignId, category: Claim, claimRecipient: $user }) { campaign { id @@ -120,3 +124,45 @@ query getClaim($campaignId: ID!, $user: String!) { } } ``` + +### Claim actions for campaigns with a certain asset + +This query yields all "Claim" actions for a given asset / token. These actions can be sourced from multiple airdrop +campaigns, for all users. + +```graphql title="Claim actions for campaigns with a certain token" +query getClaims_ByAsset($asset: String!) { + actions(where: { campaign_: { asset: $asset, category: "Claim" } }) { + campaign { + id + lockup + } + claimStreamId + claimTokenId + claimRecipient + category + } +} +``` + +## Streams + +### Stream identifiers for a campaign's claims (airstream) + +This query yields all the IDs of the streams claimed as part of a certain campaign (airstream). + +```graphql title="Claim actions for campaigns with a certain token" +query getStreamIds_ByCampaign($campaignId: String!) { + actions(where: { campaign: $campaignId, category: "Claim" }) { + claimStreamId + } +} +``` + +:::tip + +To source more details regarding these streams you can head over to the `Lockup` subgraph and look for streams where the +`stream.funder` is the address of your airdrop campaign. +[Here's an example query](/api/lockup/the-graph/queries/#streams-by-campaign). + +::: diff --git a/docs/api/lockup/the-graph/04-queries.md b/docs/api/lockup/the-graph/04-queries.md index 38aec8e..ea65c1f 100644 --- a/docs/api/lockup/the-graph/04-queries.md +++ b/docs/api/lockup/the-graph/04-queries.md @@ -7,6 +7,8 @@ title: "Queries" Building on top of the [entity structure](/api/lockup/the-graph/structure) defined earlier, here are some common GraphQL queries for fetching data from the Sablier subgraph. +## Streams (All) + ### Recent streams ```graphql title="The 10 most recent streams" @@ -44,6 +46,8 @@ query getStreams($first: Int!, $subgraphId: numeric!) { } ``` +## Streams (Filtered) + ### Streams by sender (with support for the old V2.0) To support both [proxy senders](/api/lockup/the-graph/structure) (case 3) and @@ -139,14 +143,47 @@ where: { } ``` -### Actions by stream +## Streams ( + Airdrop 🪂) + +### Streams by campaign + +This query yields data about all streams generated by a specific airdrop campaign. It makes use of the fact that +`stream.funder` will be set to the campaign's address (since assets funding the streams are coming from that contract). + +```graphql title="Streams by campaign" +query getStreams_ByCampaignId($campaignId: String!) { + streams(where: { funder: $campaignId }) { + ...StreamFragment + } +} +``` :::tip To avoid writing the same entity definitions over and over again, check out Fragments. +```graphql + +fragment StreamFragment on Stream { + id + sender + recipient +} + +query getStreams(...){ + streams(...){ + ...StreamFragment + } +} + +``` + ::: +## Actions + +### Actions by stream + ```graphql title="Most recent 100 stream actions such as withdrawals or transfers" actions( first: 100