From 5bff902bb2fd380086c384fc31cd1149b51e5045 Mon Sep 17 00:00:00 2001 From: Ashok Menon Date: Fri, 13 Sep 2024 14:41:14 +0100 Subject: [PATCH] docs(graphql): [easy] document transaction, event filters ## Description Document the various filter options for transactions and events (and tweak the docs for object filters slightly). ## Test plan :eyes: --- crates/sui-graphql-rpc/schema.graphql | 41 ++++++++++++++++--- .../sui-graphql-rpc/src/types/event/filter.rs | 10 ++--- crates/sui-graphql-rpc/src/types/object.rs | 7 +--- .../src/types/transaction_block/filter.rs | 15 +++++++ .../snapshot_tests__schema_sdl_export.snap | 41 ++++++++++++++++--- 5 files changed, 94 insertions(+), 20 deletions(-) diff --git a/crates/sui-graphql-rpc/schema.graphql b/crates/sui-graphql-rpc/schema.graphql index b848cd8529973c..f6d8946266fdcd 100644 --- a/crates/sui-graphql-rpc/schema.graphql +++ b/crates/sui-graphql-rpc/schema.graphql @@ -1264,7 +1264,13 @@ type EventEdge { } input EventFilter { + """ + Filter down to events from transactions sent by this address. + """ sender: SuiAddress + """ + Filter down to the events from this transaction (given by its transaction digest). + """ transactionDigest: String """ Events emitted by a particular module. An event is emitted by a @@ -2836,11 +2842,8 @@ objects are ones whose """ input ObjectFilter { """ - This field is used to specify the type of objects that should be included in the query - results. - - Objects can be filtered by their type's package, package::module, or their fully qualified - type name. + Filter objects by their type's `package`, `package::module`, or their fully qualified type + name. Generic types can be queried by either the generic type name, e.g. `0x2::coin::Coin`, or by the full type name, such as `0x2::coin::Coin<0x2::sui::SUI>`. @@ -4288,18 +4291,46 @@ type TransactionBlockEffects { } input TransactionBlockFilter { + """ + Filter transactions by move function called. Calls can be filtered by the `package`, + `package::module`, or the `package::module::name` of their function. + """ function: String """ An input filter selecting for either system or programmable transactions. """ kind: TransactionBlockKindInput + """ + Limit to transactions that occured strictly after the given checkpoint. + """ afterCheckpoint: UInt53 + """ + Limit to transactions in the given checkpoint. + """ atCheckpoint: UInt53 + """ + Limit to transaction that occured strictly before the given checkpoint. + """ beforeCheckpoint: UInt53 + """ + Limit to transactions that were signed by the given address. + """ signAddress: SuiAddress + """ + Limit to transactions that sent an object to the given address. + """ recvAddress: SuiAddress + """ + Limit to transactions that accepted the given object as an input. + """ inputObject: SuiAddress + """ + Limit to transactions that output a versioon of this object. + """ changedObject: SuiAddress + """ + Select transactions by their digest. + """ transactionIds: [String!] } diff --git a/crates/sui-graphql-rpc/src/types/event/filter.rs b/crates/sui-graphql-rpc/src/types/event/filter.rs index 0a02a31be89697..10144d5fa8a2f3 100644 --- a/crates/sui-graphql-rpc/src/types/event/filter.rs +++ b/crates/sui-graphql-rpc/src/types/event/filter.rs @@ -10,10 +10,15 @@ use async_graphql::*; #[derive(InputObject, Clone, Default)] pub(crate) struct EventFilter { + /// Filter down to events from transactions sent by this address. pub sender: Option, + + /// Filter down to the events from this transaction (given by its transaction digest). pub transaction_digest: Option, + // Enhancement (post-MVP) // after_checkpoint + // at_checkpoint // before_checkpoint /// Events emitted by a particular module. An event is emitted by a /// particular module if some function in the module is called by a @@ -36,9 +41,4 @@ pub(crate) struct EventFilter { // Enhancement (post-MVP) // pub start_time // pub end_time - - // Enhancement (post-MVP) - // pub any - // pub all - // pub not } diff --git a/crates/sui-graphql-rpc/src/types/object.rs b/crates/sui-graphql-rpc/src/types/object.rs index aa1240cb3f5d6d..2991bc9e83e34e 100644 --- a/crates/sui-graphql-rpc/src/types/object.rs +++ b/crates/sui-graphql-rpc/src/types/object.rs @@ -118,11 +118,8 @@ pub(crate) struct ObjectRef { /// - AND, whose ID is in `objectIds` OR whose ID and version is in `objectKeys`. #[derive(InputObject, Default, Debug, Clone, Eq, PartialEq)] pub(crate) struct ObjectFilter { - /// This field is used to specify the type of objects that should be included in the query - /// results. - /// - /// Objects can be filtered by their type's package, package::module, or their fully qualified - /// type name. + /// Filter objects by their type's `package`, `package::module`, or their fully qualified type + /// name. /// /// Generic types can be queried by either the generic type name, e.g. `0x2::coin::Coin`, or by /// the full type name, such as `0x2::coin::Coin<0x2::sui::SUI>`. diff --git a/crates/sui-graphql-rpc/src/types/transaction_block/filter.rs b/crates/sui-graphql-rpc/src/types/transaction_block/filter.rs index 29c104ac9484cc..2e40d2e63ae48c 100644 --- a/crates/sui-graphql-rpc/src/types/transaction_block/filter.rs +++ b/crates/sui-graphql-rpc/src/types/transaction_block/filter.rs @@ -10,20 +10,35 @@ use sui_types::base_types::SuiAddress as NativeSuiAddress; #[derive(InputObject, Debug, Default, Clone)] pub(crate) struct TransactionBlockFilter { + /// Filter transactions by move function called. Calls can be filtered by the `package`, + /// `package::module`, or the `package::module::name` of their function. pub function: Option, /// An input filter selecting for either system or programmable transactions. pub kind: Option, + + /// Limit to transactions that occured strictly after the given checkpoint. pub after_checkpoint: Option, + + /// Limit to transactions in the given checkpoint. pub at_checkpoint: Option, + + /// Limit to transaction that occured strictly before the given checkpoint. pub before_checkpoint: Option, + /// Limit to transactions that were signed by the given address. pub sign_address: Option, + + /// Limit to transactions that sent an object to the given address. pub recv_address: Option, + /// Limit to transactions that accepted the given object as an input. pub input_object: Option, + + /// Limit to transactions that output a versioon of this object. pub changed_object: Option, + /// Select transactions by their digest. pub transaction_ids: Option>, } diff --git a/crates/sui-graphql-rpc/tests/snapshots/snapshot_tests__schema_sdl_export.snap b/crates/sui-graphql-rpc/tests/snapshots/snapshot_tests__schema_sdl_export.snap index 7b781d6e1de02b..9117563abc0a5b 100644 --- a/crates/sui-graphql-rpc/tests/snapshots/snapshot_tests__schema_sdl_export.snap +++ b/crates/sui-graphql-rpc/tests/snapshots/snapshot_tests__schema_sdl_export.snap @@ -1268,7 +1268,13 @@ type EventEdge { } input EventFilter { + """ + Filter down to events from transactions sent by this address. + """ sender: SuiAddress + """ + Filter down to the events from this transaction (given by its transaction digest). + """ transactionDigest: String """ Events emitted by a particular module. An event is emitted by a @@ -2840,11 +2846,8 @@ objects are ones whose """ input ObjectFilter { """ - This field is used to specify the type of objects that should be included in the query - results. - - Objects can be filtered by their type's package, package::module, or their fully qualified - type name. + Filter objects by their type's `package`, `package::module`, or their fully qualified type + name. Generic types can be queried by either the generic type name, e.g. `0x2::coin::Coin`, or by the full type name, such as `0x2::coin::Coin<0x2::sui::SUI>`. @@ -4292,18 +4295,46 @@ type TransactionBlockEffects { } input TransactionBlockFilter { + """ + Filter transactions by move function called. Calls can be filtered by the `package`, + `package::module`, or the `package::module::name` of their function. + """ function: String """ An input filter selecting for either system or programmable transactions. """ kind: TransactionBlockKindInput + """ + Limit to transactions that occured strictly after the given checkpoint. + """ afterCheckpoint: UInt53 + """ + Limit to transactions in the given checkpoint. + """ atCheckpoint: UInt53 + """ + Limit to transaction that occured strictly before the given checkpoint. + """ beforeCheckpoint: UInt53 + """ + Limit to transactions that were signed by the given address. + """ signAddress: SuiAddress + """ + Limit to transactions that sent an object to the given address. + """ recvAddress: SuiAddress + """ + Limit to transactions that accepted the given object as an input. + """ inputObject: SuiAddress + """ + Limit to transactions that output a versioon of this object. + """ changedObject: SuiAddress + """ + Select transactions by their digest. + """ transactionIds: [String!] }