From 6b2ccce2dc4dd7578d0bc3a9c8cdfb8081cf1479 Mon Sep 17 00:00:00 2001 From: Akamig Date: Thu, 16 Jun 2022 15:04:43 +0900 Subject: [PATCH] Added GraphQL type descriptions (#2074) * Shorten Descriptions (Under 100 char) * Disable lint rule SA1118 for long description. * Update Libplanet.Explorer/GraphTypes/ActionType.cs Co-authored-by: Swen Mun * Fixed Graph Types accordingly. * Added justification. Co-authored-by: Say Cheong Co-authored-by: Swen Mun --- Libplanet.Explorer/GraphTypes/ActionType.cs | 2 + Libplanet.Explorer/GraphTypes/BlockType.cs | 86 +++++++++++++------ .../GraphTypes/TransactionType.cs | 49 ++++++++--- 3 files changed, 100 insertions(+), 37 deletions(-) diff --git a/Libplanet.Explorer/GraphTypes/ActionType.cs b/Libplanet.Explorer/GraphTypes/ActionType.cs index 5c81d60bee5..c17b45532b9 100644 --- a/Libplanet.Explorer/GraphTypes/ActionType.cs +++ b/Libplanet.Explorer/GraphTypes/ActionType.cs @@ -17,6 +17,7 @@ public ActionType() { Field>( name: "Raw", + description: "Raw Action data ('hex' or 'base64' encoding available.)", arguments: new QueryArguments( new QueryArgument { @@ -48,6 +49,7 @@ public ActionType() Field>( name: "Inspection", + description: "A readable representation for debugging.", resolve: ctx => ctx.Source.PlainValue.Inspect(loadAll: true) ); diff --git a/Libplanet.Explorer/GraphTypes/BlockType.cs b/Libplanet.Explorer/GraphTypes/BlockType.cs index ede66eeb65d..3629bf4818f 100644 --- a/Libplanet.Explorer/GraphTypes/BlockType.cs +++ b/Libplanet.Explorer/GraphTypes/BlockType.cs @@ -13,45 +13,79 @@ public class BlockType : ObjectGraphType> { public BlockType() { + #pragma warning disable SA1118 + // We need multiple row of description for clearer, not confusing explanation of field. Field>( - "Hash", - resolve: ctx => ctx.Source.Hash.ToString()); - Field(x => x.Index); - Field(x => x.Difficulty); - Field(x => x.TotalDifficulty); + "Hash", + description: "A block's hash.", + resolve: ctx => ctx.Source.Hash.ToString() + ); + Field>( + name: "Index", + description: "The height of the block.", + resolve: x => x.Source.Index + ); + Field>( + name: "Difficulty", + description: "The mining difficulty that the block's Nonce has to satisfy.", + resolve: x => x.Source.Difficulty); + Field>( + name: "TotalDifficulty", + description: @"The total mining difficulty since the genesis including + the block's Difficulty.", + resolve: x => x.Source.TotalDifficulty); Field>( - "Nonce", - resolve: ctx => ctx.Source.Nonce.ToByteArray() + name: "Nonce", + description: "The proof-of-work nonce which satisfies the required Difficulty.", + resolve: ctx => ctx.Source.Nonce.ToByteArray() + ); + Field( + type: typeof(NonNullGraphType), + name: "Miner", + description: "The address of the miner.", + resolve: x => x.Source.Miner + ); + Field( + type: typeof(PublicKeyType), + name: "PublicKey", + description: "The public key of the Miner.", + resolve: x => x.Source.PublicKey ); - Field(x => x.Miner, type: typeof(NonNullGraphType)); - Field(x => x.PublicKey, type: typeof(PublicKeyType)); Field>( - "PreviousBlock", - resolve: ctx => + name: "PreviousBlock", + description: @"The previous block, If it's a genesis block + (i.e., its Index is 0) this should be null.", + resolve: ctx => + { + if (!(ctx.Source.PreviousHash is BlockHash h)) { - if (!(ctx.Source.PreviousHash is BlockHash h)) - { - return null; - } + return null; + } - // FIXME: (BlockChain) casting does not work - // REF COMMIT HASH: d50c90933c17a70381ad758719144e01bf9c21dc - HashAlgorithmGetter hashAlgorithmGetter = _ => HashAlgorithmType.Of(); - var store = (IStore)ctx.UserContext[nameof(IBlockChainContext.Store)]; - return store.GetBlock(hashAlgorithmGetter, h); - }); + // FIXME: (BlockChain) casting does not work + // REF COMMIT HASH: d50c90933c17a70381ad758719144e01bf9c21dc + HashAlgorithmGetter hashAlgorithmGetter = _ => HashAlgorithmType.Of(); + var store = (IStore)ctx.UserContext[nameof(IBlockChainContext.Store)]; + return store.GetBlock(hashAlgorithmGetter, h); + }); Field(x => x.Timestamp); Field>( - "StateRootHash", - resolve: ctx => ctx.Source.StateRootHash.ToByteArray()); + name: "StateRootHash", + description: @"The Hash of the resulting states after evaluating + transactions and a BlockAction. (if exists)", + resolve: ctx => ctx.Source.StateRootHash.ToByteArray()); Field( - "Signature", - resolve: ctx => ctx.Source.Signature?.ToBuilder()?.ToArray()); + name: "Signature", + description: @"The digital signature of the whole block content + (except for Hash, which is derived from the signature and other contents)", + resolve: ctx => ctx.Source.Signature?.ToBuilder()?.ToArray()); Field>>>>( - "transactions" + name: "transactions", + description: "Transactions belonging to the block." ); Name = "Block"; + #pragma warning restore SA1118 } } } diff --git a/Libplanet.Explorer/GraphTypes/TransactionType.cs b/Libplanet.Explorer/GraphTypes/TransactionType.cs index fe81fecd2ab..359d4eacfd2 100644 --- a/Libplanet.Explorer/GraphTypes/TransactionType.cs +++ b/Libplanet.Explorer/GraphTypes/TransactionType.cs @@ -17,25 +17,52 @@ public class TransactionType : ObjectGraphType> public TransactionType() { Field>( - "Id", - resolve: ctx => ctx.Source.Id.ToString()); - Field(x => x.Nonce); - Field(x => x.Signer, type: typeof(NonNullGraphType)); + name: "Id", + description: "A unique identifier derived from this transaction content.", + resolve: ctx => ctx.Source.Id.ToString()); + Field>( + name: "Nonce", + description: "The number of previous transactions committed by the signer of this tx.", + resolve: x => x.Source.Nonce + ); + Field( + type: typeof(NonNullGraphType), + name: "Signer", + description: "An address of the account who signed this transaction.", + resolve: x => x.Source.Signer + ); Field>( - "PublicKey", - resolve: ctx => ctx.Source.PublicKey.Format(true) + name: "PublicKey", + description: "A PublicKey of the account who signed this transaction.", + resolve: ctx => ctx.Source.PublicKey.Format(true) + ); + Field( + type: typeof(NonNullGraphType>>), + name: "UpdatedAddresses", + description: "Addresses whose states were affected by Actions.", + resolve: x => x.Source.UpdatedAddresses + ); + Field( + type: typeof(NonNullGraphType), + name: "Signature", + description: "A digital signature of the content of this transaction.", + resolve: x => x.Source.Signature ); Field( - x => x.UpdatedAddresses, - type: typeof(NonNullGraphType>>) + type: typeof(NonNullGraphType), + name: "Timestamp", + description: "The time this transaction was created and signed.", + resolve: x => x.Source.Timestamp ); - Field(x => x.Signature, type: typeof(NonNullGraphType)); - Field(x => x.Timestamp); - Field>>>>("Actions"); + Field>>>>( + name: "Actions", + description: "A list of actions in this transaction." + ); // The block including the transaction. - Only RichStore supports. Field>>>( name: "BlockRef", + description: "The block including the transaction.", resolve: ctx => { // FIXME: use context with DI.