From c157ec59e4b9a0331c3a1fb19733bd2db9a167b3 Mon Sep 17 00:00:00 2001
From: Razvan Gabriel <razvan.gabriel.apostu@gmail.com>
Date: Sat, 18 Jan 2025 14:00:33 +0200
Subject: [PATCH] feat(api): tips and tricks with stream contracts

---
 docs/api/lockup/01-overview.mdx         | 38 +++++++++++++++++++++++++
 docs/api/lockup/the-graph/04-queries.md | 16 ++++++++++-
 2 files changed, 53 insertions(+), 1 deletion(-)

diff --git a/docs/api/lockup/01-overview.mdx b/docs/api/lockup/01-overview.mdx
index b603dfa..fc7547c 100644
--- a/docs/api/lockup/01-overview.mdx
+++ b/docs/api/lockup/01-overview.mdx
@@ -27,3 +27,41 @@ Lockup-native functionality is powered by:
 
 As per our endpoint [naming convention](/api/overview#endpoints--slugs), subgraph deployments of Sablier Lockup will
 follow the `sablier-v2-*` structure (e.g. `sablier-v2` for Mainnet, `sablier-v2-base` for Base).
+
+#### Tips and tricks
+
+:::tip
+
+To avoid writing the same entity definitions over and over again, check out
+[Fragments](https://graphql.org/learn/queries/#fragments).
+
+```graphql
+
+fragment StreamFragment on Stream {
+  id
+  sender
+  recipient
+  contract {
+    id
+    address
+  }
+}
+
+query getStreams(...){
+  streams(...){
+    ...StreamFragment
+  }
+}
+
+```
+
+:::
+
+:::note
+
+Since Sablier uses multiple immutable contract versions and deployments (e.g.
+[lockup's variants](/guides/lockup/deployments#previous-versions)), if you're going to perform onchain actions on
+queried streams (e.g. getting the `streamedAmountOf`) make sure you call those methods on the right contract. For
+subgraphs/indexers, we store the source contract under `stream.contract.address`.
+
+:::
diff --git a/docs/api/lockup/the-graph/04-queries.md b/docs/api/lockup/the-graph/04-queries.md
index ea65c1f..7905c60 100644
--- a/docs/api/lockup/the-graph/04-queries.md
+++ b/docs/api/lockup/the-graph/04-queries.md
@@ -160,7 +160,8 @@ query getStreams_ByCampaignId($campaignId: String!) {
 
 :::tip
 
-To avoid writing the same entity definitions over and over again, check out Fragments.
+To avoid writing the same entity definitions over and over again, check out
+[Fragments](https://graphql.org/learn/queries/#fragments).
 
 ```graphql
 
@@ -168,6 +169,10 @@ fragment StreamFragment on Stream {
   id
   sender
   recipient
+  contract {
+    id
+    address
+  }
 }
 
 query getStreams(...){
@@ -180,6 +185,15 @@ query getStreams(...){
 
 :::
 
+:::note
+
+Since Sablier uses multiple immutable contract versions and deployments (e.g.
+[lockup's variants](/guides/lockup/deployments#previous-versions)), if you're going to perform onchain actions on these
+streams (e.g. getting the `streamedAmountOf` for each one) make sure you call those methods on the right contract. For
+subgraphs/indexers, we store the source contract under `stream.contract.address`.
+
+:::
+
 ## Actions
 
 ### Actions by stream