sui-graphql-client: add some more doc comments (#50)

crates/sui-graphql-client/src/lib.rs

@@ -6,7 +6,6 @@
 pub mod faucet;
 pub mod query_types;
 
-use base64ct::Encoding;
 use query_types::ActiveValidatorsArgs;
 use query_types::ActiveValidatorsQuery;
 use query_types::BalanceArgs;
@@ -53,12 +52,11 @@ use query_types::TransactionMetadata;
 use query_types::TransactionsFilter;
 use query_types::Validator;
 
-use serde::de::DeserializeOwned;
-use serde::Serialize;
 use sui_types::types::framework::Coin;
 use sui_types::types::Address;
 use sui_types::types::CheckpointSequenceNumber;
 use sui_types::types::CheckpointSummary;
+use sui_types::types::Digest;
 use sui_types::types::Event;
 use sui_types::types::Object;
 use sui_types::types::SignedTransaction;
@@ -72,13 +70,16 @@ use anyhow::anyhow;
 use anyhow::ensure;
 use anyhow::Error;
 use anyhow::Result;
+use base64ct::Encoding;
 use cynic::serde;
 use cynic::GraphQlResponse;
 use cynic::MutationBuilder;
 use cynic::Operation;
 use cynic::QueryBuilder;
 use futures::Stream;
 use reqwest::Url;
+use serde::de::DeserializeOwned;
+use serde::Serialize;
 use std::pin::Pin;
 
 const MAINNET_HOST: &str = "https://sui-mainnet.mystenlabs.com/graphql";
@@ -91,12 +92,15 @@ static USER_AGENT: &str = concat!(env!("CARGO_PKG_NAME"), "/", env!("CARGO_PKG_V
 // Output Types
 // ===========================================================================
 
+/// The result of a dry run, which includes the effects of the transaction and any errors that may
+/// have occurred.
 #[derive(Debug)]
 pub struct DryRunResult {
     pub effects: Option<TransactionEffects>,
     pub error: Option<String>,
 }
 
+/// The name part of a dynamic field, including its type, bcs, and json representation.
 #[derive(Debug)]
 pub struct DynamicFieldName {
     /// The type name of this dynamic field name
@@ -107,6 +111,8 @@ pub struct DynamicFieldName {
     pub json: Option<serde_json::Value>,
 }
 
+/// The output of a dynamic field query, that includes the name, value, and value's json
+/// representation.
 #[derive(Debug)]
 pub struct DynamicFieldOutput {
     /// The name of the dynamic field
@@ -171,8 +177,11 @@ pub enum Direction {
 /// GraphQL server's default items per page limit.
 #[derive(Default)]
 pub struct PaginationFilter<'a> {
+    /// The direction of pagination.
     direction: Direction,
+    /// An opaque cursor used for pagination.
     cursor: Option<&'a str>,
+    /// The maximum number of items to return. Use `service_config` to find the limit.
     limit: Option<i32>,
 }
 
@@ -816,6 +825,7 @@ impl Client {
     // Events API
     // ===========================================================================
 
+    /// Return a page of events based on the provided filters.
     pub async fn events(
         &self,
         filter: Option<EventFilter>,
@@ -1124,9 +1134,8 @@ impl Client {
     // Transaction API
     // ===========================================================================
 
-    // TODO: From Brandon: this fails due to SignedTransaction in Sui core type being technically inaccurate but it is fixed in this SDK here. in particular core incorrectly appends the signing intent when it shouldn't so my guess is that's whats wrong
     /// Get a transaction by its digest.
-    pub async fn transaction(&self, digest: &str) -> Result<Option<SignedTransaction>, Error> {
+    pub async fn transaction(&self, digest: Digest) -> Result<Option<SignedTransaction>, Error> {
         let operation = TransactionBlockQuery::build(TransactionBlockArgs {
             digest: digest.to_string(),
         });

crates/sui-graphql-client/src/query_types/active_validators.rs

@@ -57,6 +57,7 @@ pub struct ValidatorConnection {
     pub nodes: Vec<Validator>,
 }
 
+/// Represents a validator in the system.
 #[derive(cynic::QueryFragment, Debug)]
 #[cynic(schema = "rpc", graphql_type = "Validator")]
 pub struct Validator {
@@ -114,10 +115,10 @@ pub struct Validator {
     pub voting_power: Option<i32>,
 }
 
+/// The credentials related fields associated with a validator.
 #[derive(cynic::QueryFragment, Debug)]
 #[cynic(schema = "rpc", graphql_type = "ValidatorCredentials")]
 #[allow(non_snake_case)]
-/// The credentials related fields associated with a validator.
 pub struct ValidatorCredentials {
     pub protocol_pub_key: Option<Base64>,
     pub network_pub_key: Option<Base64>,

crates/sui-graphql-client/src/query_types/coin.rs

@@ -28,14 +28,22 @@ pub struct CoinMetadataArgs<'a> {
 use crate::query_types::schema;
 use crate::query_types::BigInt;
 
+/// The coin metadata associated with the given coin type.
 #[derive(cynic::QueryFragment, Debug)]
 #[cynic(schema = "rpc", graphql_type = "CoinMetadata")]
 pub struct CoinMetadata {
+    /// The number of decimal places used to represent the token.
     pub decimals: Option<i32>,
+    /// Optional description of the token, provided by the creator of the token.
     pub description: Option<String>,
+    /// Icon URL of the coin.
     pub icon_url: Option<String>,
+    /// Full, official name of the token.
     pub name: Option<String>,
+    /// The token's identifying abbreviation.
     pub symbol: Option<String>,
+    /// The overall quantity of tokens that will be issued.
     pub supply: Option<BigInt>,
+    /// Version of the token.
     pub version: u64,
 }

crates/sui-graphql-client/src/query_types/epoch.rs

@@ -26,12 +26,17 @@ pub struct EpochSummaryArgs {
     pub id: Option<u64>,
 }
 
+/// A summary of the epoch.
 #[derive(cynic::QueryFragment, Debug)]
 #[cynic(schema = "rpc", graphql_type = "Epoch")]
 pub struct EpochSummary {
+    /// The epoch number.
     pub epoch_id: u64,
+    /// The reference gas price throughout this epoch.
     pub reference_gas_price: Option<BigInt>,
+    /// The total number of checkpoints in this epoch.
     pub total_checkpoints: Option<u64>,
+    /// The total number of transactions in this epoch.
     pub total_transactions: Option<u64>,
 }
 

crates/sui-graphql-client/src/query_types/protocol_config.rs

@@ -32,21 +32,33 @@ pub struct ProtocolVersionArgs {
 // ===========================================================================
 
 /// Information about the configuration of the protocol.
+/// Constants that control how the chain operates.
+/// These can only change during protocol upgrades which happen on epoch boundaries.
 #[derive(cynic::QueryFragment, Debug)]
 #[cynic(schema = "rpc", graphql_type = "ProtocolConfigs")]
 pub struct ProtocolConfigs {
+    /// The protocol is not required to change on every epoch boundary, so the protocol version
+    /// tracks which change to the protocol these configs are from.
     pub protocol_version: u64,
+    /// List all available feature flags and their values. Feature flags are a form of boolean
+    /// configuration that are usually used to gate features while they are in development. Once a
+    /// flag has been enabled, it is rare for it to be disabled.
     pub feature_flags: Vec<ProtocolConfigFeatureFlag>,
+    /// List all available configurations and their values. These configurations can take any value
+    /// (but they will all be represented in string form), and do not include feature flags.
     pub configs: Vec<ProtocolConfigAttr>,
 }
 
+/// Feature flags are a form of boolean configuration that are usually used to gate features while
+/// they are in development. Once a lag has been enabled, it is rare for it to be disabled.
 #[derive(cynic::QueryFragment, Debug)]
 #[cynic(schema = "rpc", graphql_type = "ProtocolConfigFeatureFlag")]
 pub struct ProtocolConfigFeatureFlag {
     pub key: String,
     pub value: bool,
 }
 
+/// A key-value protocol configuration attribute.
 #[derive(cynic::QueryFragment, Debug)]
 #[cynic(schema = "rpc", graphql_type = "ProtocolConfigAttr")]
 pub struct ProtocolConfigAttr {