From 64df0fca0f5b357f70126639e8620ca68f31fd23 Mon Sep 17 00:00:00 2001 From: Razvan Gabriel Date: Thu, 21 Mar 2024 14:54:07 +0200 Subject: [PATCH] chore: update envio indexers endpoints feat: add testing section for envio fix: remove entityObject references --- docs/api/indexers/01-endpoints.mdx | 23 +++++--------- docs/api/indexers/02-differences.mdx | 39 ++++++++++++----------- docs/api/indexers/06-testing.mdx | 40 ++++++++++++++++++++++++ docs/api/indexers/merkle/02-queries.md | 12 ++++--- docs/api/indexers/protocol/04-queries.md | 4 +-- 5 files changed, 77 insertions(+), 41 deletions(-) create mode 100644 docs/api/indexers/06-testing.mdx diff --git a/docs/api/indexers/01-endpoints.mdx b/docs/api/indexers/01-endpoints.mdx index 371ddaab..a9e33630 100644 --- a/docs/api/indexers/01-endpoints.mdx +++ b/docs/api/indexers/01-endpoints.mdx @@ -20,18 +20,11 @@ The `protocol-envio` indexer tracks events mainly emitted by the [`@sablier/v2-core`](/contracts/v2/reference/overview#core) contracts. It deals with core protocol actions like creating, withdrawing or transferring streams. -:::warning Note - -The Sablier Envio indexers are still under development so links may change in time. Please reach out if the endpoints -don't work any more. This warning will be removed once indexers are deployed in production and endpoints are stable. - -::: - ### Endpoints -| Chain | Endpoint (Hosted Network) | -| ---------------- | ------------------------------------------------------------------------- | -| All-Networks[^1] | [https://indexer.bigdevenergy.link/[...]/v1/graphql]([endpoint-protocol]) | +| Chain | Endpoint (Hosted Network) | +| ---------------- | ----------------------------------------------------------------------- | +| All-Networks[^1] | [https://indexer.bigdevenergy.link/[...]/v1/graphql][endpoint-protocol] | Use [Hasura's online explorer](https://cloud.hasura.io/public/graphiql?) to view the entities and query API. @@ -52,17 +45,17 @@ contracts, specifically the specific actions like the factory creating a campaign, admin clawbacks or users claiming streams as defined in the attached Merkle tree. -[endpoint-protocol]: https://indexer.bigdevenergy.link/be2052e/v1/graphql +[endpoint-protocol]: https://indexer.bigdevenergy.link/9e37ca4/v1/graphql ### Endpoints -| Chain | Endpoint (Hosted Network) | -| ------------ | ----------------------------------------------------------------------- | -| All-Networks | [https://indexer.bigdevenergy.link/[...]/v1/graphql]([endpoint-merkle]) | +| Chain | Endpoint (Hosted Network) | +| ------------ | --------------------------------------------------------------------- | +| All-Networks | [https://indexer.bigdevenergy.link/[...]/v1/graphql][endpoint-merkle] | Use [Hasura's online explorer](https://cloud.hasura.io/public/graphiql?) to view the entities and query API. -[endpoint-merkle]: https://indexer.bigdevenergy.link/61cf6be/v1/graphql +[endpoint-merkle]: https://indexer.bigdevenergy.link/508d217/v1/graphql ### Code diff --git a/docs/api/indexers/02-differences.mdx b/docs/api/indexers/02-differences.mdx index fd2516fe..949c8588 100644 --- a/docs/api/indexers/02-differences.mdx +++ b/docs/api/indexers/02-differences.mdx @@ -6,10 +6,11 @@ title: "Differences" # Differences (The Graph vs. Envio) -:::info +:::warning If you're looking to support both subgraphs (The Graph) and indexers (Envio) into your apps, please make sure to scroll -down to the "Different Results" section to understand how results from both APIs may differ for the same entities. +down to the "Different Results (\*)" 📌 section to understand how results from both APIs may differ for the same +entities. ::: @@ -25,13 +26,13 @@ Both solutions create a **GraphQL** API for consumers to read data from. It is i customized subset of GraphQL operations, which makes is impossible to use the same queries between both indexers and subgraphs, whereas Envio deploys a GraphQL API over a Postgres DB. Some examples: -| Example | The Graph | Envio | -| -------------------- | ------------------------------------- | --------------------------------------------- | -| Pagination | `first`, `skip` | `limit`, `offset` | -| Filter by id | `stream(id)` | `Stream(where: {id: {_eq: 1}})` | -| Single vs. Plural | `stream(id){}`, `streams{}` | `Stream(where...){}` for both | -| Nested items | `campaigns{ id, asset: {id, symbol}}` | `Campaign{ asset, assetObject: {id, symbol}}` | -| Filter similar items | `assets(id: $id)` | `Asset(where: {id: {_iregex: $id}})` | +| Example | The Graph | Envio | +| -------------------- | ------------------------------------- | ------------------------------------------ | +| Pagination | `first`, `skip` | `limit`, `offset` | +| Filter by id | `stream(id)` | `Stream(where: {id: {_eq: 1}})` | +| Single vs. Plural | `stream(id){}`, `streams{}` | `Stream(where...){}` for both | +| Nested items | `campaigns{ id, asset: {id, symbol}}` | `Campaign{ asset_id, asset: {id, symbol}}` | +| Filter similar items | `assets(id: $id)` | `Asset(where: {id: {_iregex: $id}})` | #### Important Notes @@ -39,19 +40,12 @@ For the 3rd example, querying for a single item vs. a collection will have separ you'll have to identify within the app itself if the query is supposed to yield one or multiple items. As you may tell, with Envio you'll query for `Stream` (capitalized) while with The Graph you'll query for `stream` or `streams`. -For the 4th example, in Envio indexers the name of an object will yield its `id`, while the `Object` label will -ask for the object itself (e.g. `asset` vs `assetObject`). - -:::warning - -This `asset` vs `assetObject` discrepancy may change in future versions of Envio. Please checks the docs accordingly -before developing features on top of the Sablier V2 indexers. - -::: +For the 4th example, in Envio Indexers the `name` of an object will yield its contents (`{}`), while the `_id` +label will ask for the identifier of the object (e.g. `asset` vs `asset_id`). Keep this in mind for "where" filtering. ### Handler Language -- The Graph: uses Assembly script +- The Graph: uses Assembly Script - Envio: we've chosen Typescript, but you can use JS, TS or Rescript For Envio, one important mental model is in the concept of loaders vs. handlers. To optimize querying speeds, Envio will @@ -106,6 +100,13 @@ contracts by flavor. └── event: CreateLockupLinearStreamV21 ``` +## Contract Calls + +Outside of data provided directly by the event arguments, one can access additional information through contract calls. +While The Graph provides a dedicated API (binding an ABI to an address, calling `contract.try_method()`), Envio is less +opinionated. A good example of contract calls can be found in our `helpers/asset.ts` where we use `viem` and a custom +caching mechanism to search for asset details. + ## Different Results (\*) Due to the cross-chain indexing aspect, entities in Envio will need to have a chainId suffix attached to them to ensure diff --git a/docs/api/indexers/06-testing.mdx b/docs/api/indexers/06-testing.mdx new file mode 100644 index 00000000..64a211ab --- /dev/null +++ b/docs/api/indexers/06-testing.mdx @@ -0,0 +1,40 @@ +--- +id: "testing" +sidebar_position: 6 +title: "Testing" +--- + +import LinkPreview from "@site/src/components/LinkPreview"; + +## Integrating + +To ensure Envio indexers are delivering the same set of data as The Graph's subgraphs we've implemented a set of +differentials tests over both `merkle` and `protocol` configurations. + +Check them out inside the `apps/[...]/test/` folders. + + + +## Running + +The differentials tests are powered by Jest. Inside `test/setup/constants.ts` you will find the full configuration for +these tests. This is where you'll also be able to toggle between using the local endpoint (see +[development](/api/indexers/development) to bootstrap a project locally) and the hosted-service one, using the `REMOTE` +flag. + +```bash +pnpm run test +``` + +:::info + +As the set of streams or campaigns grows, the final tests (full-coverage over the entire list of elements) may start +timing out. We suggest either splitting them chunks or simply adding a manual limit to the number of iterations the loop +can cover at once. Alternatively, one can also increase the timeout of those tests. + +::: diff --git a/docs/api/indexers/merkle/02-queries.md b/docs/api/indexers/merkle/02-queries.md index f89551dd..b61b555c 100644 --- a/docs/api/indexers/merkle/02-queries.md +++ b/docs/api/indexers/merkle/02-queries.md @@ -67,7 +67,7 @@ query getAirstreams_ByAsset($first: Int!, $skip: Int!, $asset: String!, $subgrap order_by: {subgraphId: desc} where: { _and: [ - { asset: {_eq: $asset} } + { asset_id: {_eq: $asset} } { subgraphId: {_lt: $subgraphId}} { chainId: {_eq: $chainId}} ] @@ -103,10 +103,12 @@ const CampaignFragment = gql(/* GraphQL */ ` claimedAmount claimedCount version - assetObject { + asset_id + asset { ...AssetFragment } - factoryObject { + factory_id + factory { ...FactoryFragment } } @@ -121,8 +123,8 @@ on behalf of that user. If the query yields a result, it means the uses has alre ```graphql title="Claim action of a user on a certain campaign" query getClaim($campaignId: ID!, $user: String!) { - Action(where: { campaign: { _eq: $campaignId }, category: { _eq: "Claim" }, claimRecipient: { _eq: $uer } }) { - campaignObject { + Action(where: { campaign_id: { _eq: $campaignId }, category: { _eq: "Claim" }, claimRecipient: { _eq: $uer } }) { + campaign { id lockup } diff --git a/docs/api/indexers/protocol/04-queries.md b/docs/api/indexers/protocol/04-queries.md index 0bafb5ae..00ce567f 100644 --- a/docs/api/indexers/protocol/04-queries.md +++ b/docs/api/indexers/protocol/04-queries.md @@ -15,7 +15,7 @@ query getStreams { id alias category - assetObject { + asset { id symbol } @@ -41,7 +41,7 @@ query getStreams($first: Int!, $subgraphId: numeric!) { id alias category - assetObject { + asset { id symbol }