[GraphQL/MovePackage] Paginate by checkpoint

## Description Adds a query, `Query.packages` for fetching all packages that were introduced within a given checkpoint range. Useful for fetching package contents in bulk, to do local analyses. ## Test plan New E2E tests: ``` sui$ cargo nextest run -p sui-graphql-e2e-tests \ --features pg_integration \ -- packages/versioning ``` Also tested for performance against a large read replica (the query planner quotes a high estimate for the query but the actual results do not take very long to run because queries on many sub-partitions are eliminated).
MystenLabs · May 13, 2024 · dd7c07f · dd7c07f
1 parent f480b7a
commit dd7c07f
Show file tree

Hide file tree

Showing 7 changed files with 473 additions and 22 deletions.
diff --git a/crates/sui-graphql-e2e-tests/tests/packages/versioning.exp b/crates/sui-graphql-e2e-tests/tests/packages/versioning.exp
@@ -1,4 +1,4 @@
-processed 14 tasks
+processed 15 tasks
 
 init:
 A: object(0,0)
@@ -11,7 +11,7 @@ gas summary: computation_cost: 1000000, storage_cost: 5076800,  storage_rebate:
 task 2 'create-checkpoint'. lines 11-11:
 Checkpoint created: 1
 
-task 3 'run-graphql'. lines 13-21:
+task 3 'run-graphql'. lines 13-28:
 Response: {
   "data": {
     "latestPackage": {
@@ -25,19 +25,43 @@ Response: {
           ]
         }
       }
+    },
+    "packages": {
+      "nodes": [
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000001",
+          "version": 1
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000002",
+          "version": 1
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000003",
+          "version": 1
+        },
+        {
+          "address": "0x000000000000000000000000000000000000000000000000000000000000dee9",
+          "version": 1
+        },
+        {
+          "address": "0x175ae86f2df1eb652d57fbe9e44c7f2d67870d2b6776a4356f30930221b63b88",
+          "version": 1
+        }
+      ]
     }
   }
 }
 
-task 4 'upgrade'. lines 23-27:
+task 4 'upgrade'. lines 30-34:
 created: object(4,0)
 mutated: object(0,0), object(1,1)
 gas summary: computation_cost: 1000000, storage_cost: 5251600,  storage_rebate: 2595780, non_refundable_storage_fee: 26220
 
-task 5 'create-checkpoint'. lines 29-29:
+task 5 'create-checkpoint'. lines 36-36:
 Checkpoint created: 2
 
-task 6 'run-graphql'. lines 31-39:
+task 6 'run-graphql'. lines 38-53:
 Response: {
   "data": {
     "latestPackage": {
@@ -54,19 +78,47 @@ Response: {
           ]
         }
       }
+    },
+    "packages": {
+      "nodes": [
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000001",
+          "version": 1
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000002",
+          "version": 1
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000003",
+          "version": 1
+        },
+        {
+          "address": "0x000000000000000000000000000000000000000000000000000000000000dee9",
+          "version": 1
+        },
+        {
+          "address": "0x175ae86f2df1eb652d57fbe9e44c7f2d67870d2b6776a4356f30930221b63b88",
+          "version": 1
+        },
+        {
+          "address": "0x351bc614b36f0f522a64334e4c278d4bfe200234958870c084e0a005f041d681",
+          "version": 2
+        }
+      ]
     }
   }
 }
 
-task 7 'upgrade'. lines 41-46:
+task 7 'upgrade'. lines 55-60:
 created: object(7,0)
 mutated: object(0,0), object(1,1)
 gas summary: computation_cost: 1000000, storage_cost: 5426400,  storage_rebate: 2595780, non_refundable_storage_fee: 26220
 
-task 8 'create-checkpoint'. lines 48-48:
+task 8 'create-checkpoint'. lines 62-62:
 Checkpoint created: 3
 
-task 9 'run-graphql'. lines 50-58:
+task 9 'run-graphql'. lines 64-79:
 Response: {
   "data": {
     "latestPackage": {
@@ -86,11 +138,43 @@ Response: {
           ]
         }
       }
+    },
+    "packages": {
+      "nodes": [
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000001",
+          "version": 1
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000002",
+          "version": 1
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000003",
+          "version": 1
+        },
+        {
+          "address": "0x000000000000000000000000000000000000000000000000000000000000dee9",
+          "version": 1
+        },
+        {
+          "address": "0x175ae86f2df1eb652d57fbe9e44c7f2d67870d2b6776a4356f30930221b63b88",
+          "version": 1
+        },
+        {
+          "address": "0x351bc614b36f0f522a64334e4c278d4bfe200234958870c084e0a005f041d681",
+          "version": 2
+        },
+        {
+          "address": "0x0eae57b7a07b0548b1f6b0c309f0692828ff994e9159b541334b25582980631c",
+          "version": 3
+        }
+      ]
     }
   }
 }
 
-task 10 'run-graphql'. lines 60-97:
+task 10 'run-graphql'. lines 81-118:
 Response: {
   "data": {
     "v1": {
@@ -189,7 +273,7 @@ Response: {
   }
 }
 
-task 11 'run-graphql'. lines 99-136:
+task 11 'run-graphql'. lines 120-157:
 Response: {
   "data": {
     "v1_from_p1": {
@@ -279,7 +363,7 @@ Response: {
   }
 }
 
-task 12 'run-graphql'. lines 138-193:
+task 12 'run-graphql'. lines 159-214:
 Response: {
   "data": {
     "v1": {
@@ -417,7 +501,7 @@ Response: {
   }
 }
 
-task 13 'run-graphql'. lines 195-223:
+task 13 'run-graphql'. lines 216-244:
 Response: {
   "data": {
     "v0": null,
@@ -428,3 +512,98 @@ Response: {
     "v4": null
   }
 }
+
+task 14 'run-graphql'. lines 246-277:
+Response: {
+  "data": {
+    "before": {
+      "nodes": [
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000001",
+          "version": 1,
+          "previousTransactionBlock": {
+            "effects": {
+              "checkpoint": {
+                "sequenceNumber": 0
+              }
+            }
+          }
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000002",
+          "version": 1,
+          "previousTransactionBlock": {
+            "effects": {
+              "checkpoint": {
+                "sequenceNumber": 0
+              }
+            }
+          }
+        },
+        {
+          "address": "0x0000000000000000000000000000000000000000000000000000000000000003",
+          "version": 1,
+          "previousTransactionBlock": {
+            "effects": {
+              "checkpoint": {
+                "sequenceNumber": 0
+              }
+            }
+          }
+        },
+        {
+          "address": "0x000000000000000000000000000000000000000000000000000000000000dee9",
+          "version": 1,
+          "previousTransactionBlock": {
+            "effects": {
+              "checkpoint": {
+                "sequenceNumber": 0
+              }
+            }
+          }
+        }
+      ]
+    },
+    "after": {
+      "nodes": [
+        {
+          "address": "0x351bc614b36f0f522a64334e4c278d4bfe200234958870c084e0a005f041d681",
+          "version": 2,
+          "previousTransactionBlock": {
+            "effects": {
+              "checkpoint": {
+                "sequenceNumber": 2
+              }
+            }
+          }
+        },
+        {
+          "address": "0x0eae57b7a07b0548b1f6b0c309f0692828ff994e9159b541334b25582980631c",
+          "version": 3,
+          "previousTransactionBlock": {
+            "effects": {
+              "checkpoint": {
+                "sequenceNumber": 3
+              }
+            }
+          }
+        }
+      ]
+    },
+    "between": {
+      "nodes": [
+        {
+          "address": "0x351bc614b36f0f522a64334e4c278d4bfe200234958870c084e0a005f041d681",
+          "version": 2,
+          "previousTransactionBlock": {
+            "effects": {
+              "checkpoint": {
+                "sequenceNumber": 2
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
diff --git a/crates/sui-graphql-e2e-tests/tests/packages/versioning.move b/crates/sui-graphql-e2e-tests/tests/packages/versioning.move
@@ -18,6 +18,13 @@ module P0::m {
             functions { nodes { name } }
         }
     }
+
+    packages(first: 10) {
+        nodes {
+            address
+            version
+        }
+    }
 }
 
 //# upgrade --package P0 --upgrade-capability 1,1 --sender A
@@ -36,6 +43,13 @@ module P1::m {
             functions { nodes { name } }
         }
     }
+
+    packages(first: 10) {
+        nodes {
+            address
+            version
+        }
+    }
 }
 
 //# upgrade --package P1 --upgrade-capability 1,1 --sender A
@@ -55,6 +69,13 @@ module P2::m {
             functions { nodes { name } }
         }
     }
+
+    packages(first: 10) {
+        nodes {
+            address
+            version
+        }
+    }
 }
 
 //# run-graphql
@@ -221,3 +242,36 @@ module P2::m {
         }
     }
 }
+
+//# run-graphql
+{   # Querying packages with checkpoint bounds
+    before: packages(beforeCheckpoint: 1, first: 10) {
+        nodes {
+            address
+            version
+            previousTransactionBlock {
+                effects { checkpoint { sequenceNumber } }
+            }
+        }
+    }
+
+    after: packages(afterCheckpoint: 1, first: 10) {
+        nodes {
+            address
+            version
+            previousTransactionBlock {
+                effects { checkpoint { sequenceNumber } }
+            }
+        }
+    }
+
+    between: packages(afterCheckpoint: 1, beforeCheckpoint: 3, first: 10) {
+        nodes {
+            address
+            version
+            previousTransactionBlock {
+                effects { checkpoint { sequenceNumber } }
+            }
+        }
+    }
+}
diff --git a/crates/sui-graphql-rpc/schema/current_progress_schema.graphql b/crates/sui-graphql-rpc/schema/current_progress_schema.graphql
@@ -2931,6 +2931,14 @@ type Query {
 	"""
 	objects(first: Int, after: String, last: Int, before: String, filter: ObjectFilter): ObjectConnection!
 	"""
+	The Move packages that exist in the network, optionally filtered to be strictly before
+	`beforeCheckpoint` and/or strictly after `afterCheckpoint`.
+	
+	This query will return all versions of a given user package that appear between the
+	specified checkpoints, but only records the latest versions of system packages.
+	"""
+	packages(first: Int, after: String, last: Int, before: String, afterCheckpoint: Int, beforeCheckpoint: Int): MovePackageConnection!
+	"""
 	Fetch the protocol config by protocol version (defaults to the latest protocol
 	version known to the GraphQL service).
 	"""

diff --git a/crates/sui-graphql-rpc/src/types/event.rs b/crates/sui-graphql-rpc/src/types/event.rs
@@ -143,13 +143,13 @@ impl Event {
     /// checkpoint sequence numbers as the cursor to determine the correct page of results. The
     /// query can optionally be further `filter`-ed by the `EventFilter`.
     ///
-    /// The `checkpoint_viewed_at` parameter is represents the checkpoint sequence number at which
-    /// this page was queried for. Each entity returned in the connection will inherit this
-    /// checkpoint, so that when viewing that entity's state, it will be from the reference of this
-    /// checkpoint_viewed_at parameter.
+    /// The `checkpoint_viewed_at` parameter represents the checkpoint sequence number at which this
+    /// page was queried. Each entity returned in the connection will inherit this checkpoint, so
+    /// that when viewing that entity's state, it will be as if it is being viewed at this
+    /// checkpoint.
     ///
-    /// If the `Page<Cursor>` is set, then this function will defer to the `checkpoint_viewed_at` in
-    /// the cursor if they are consistent.
+    /// The cursors in `page` may also include checkpoint viewed at fields. If these are set, they
+    /// take precedence over the checkpoint that pagination is being conducted in.
     pub(crate) async fn paginate(
         db: &Db,
         page: Page<Cursor>,