Merge pull request #135 from sablier-labs/chore/envio-updates

chore: envio updates
sablier-labs · Mar 21, 2024 · 11600fa · 11600fa
2 parents eac85e8 + 64df0fc
commit 11600fa
Show file tree

Hide file tree

Showing 5 changed files with 77 additions and 41 deletions.
diff --git 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
@@ -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,33 +26,26 @@ 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
 
 For the 3rd example, querying for a single item vs. a collection will have separate keywords for The Graph. With Envio,
 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 `<name>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 `<name>_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
@@ -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.
+
+<LinkPreview
+  href="https://github.com/sablier-labs/v2-subgraphs"
+  icon="github"
+  subtitle="GitHub"
+  title="Github - sablier-labs/v2-subgraphs: Sablier V2 Indexers"
+/>
+
+## 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
@@ -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
@@ -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
     }