Comments: Add detail description for RPC Method

Author: Wi1l-B0t

src/Plugins/RpcServer/RpcMethodAttribute.cs

@@ -13,6 +13,9 @@
 
 namespace Neo.Plugins.RpcServer
 {
+    /// <summary>
+    /// Indicates that the method is an RPC method.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
     public class RpcMethodAttribute : Attribute
     {

src/Plugins/RpcServer/RpcMethodWithParamsAttribute.cs

@@ -13,6 +13,9 @@
 
 namespace Neo.Plugins.RpcServer
 {
+    /// <summary>
+    /// Indicates that the method is an RPC method with parameters.
+    /// </summary>
     [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
     public class RpcMethodWithParamsAttribute : Attribute
     {

src/Plugins/RpcServer/RpcServer.Blockchain.cs

@@ -26,6 +26,11 @@ partial class RpcServer
 
         /// <summary>
         /// Gets the current number of connections to the node.
+        /// <para>Request format:</para>
+        /// <code>{ "jsonrpc": "2.0", "id": 1,"method": "getconnectioncount"}
+        /// </code>
+        /// <para>Response format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1, "result": 10}</code>
         /// </summary>
         /// <returns>The number of connections as a JToken.</returns>
         [RpcMethodWithParams]
@@ -36,6 +41,19 @@ protected internal virtual JToken GetConnectionCount()
 
         /// <summary>
         /// Gets information about the peers connected to the node.
+        /// <para>Request format:</para>
+        /// <code>{ "jsonrpc": "2.0", "id": 1,"method": "getpeers"}
+        /// </code>
+        /// <para>Response format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "result": {
+        ///     "unconnected": [{"address": "The address", "port": "The port"}],
+        ///     "bad": [],
+        ///     "connected": [{"address": "The address", "port": "The port"}]
+        ///   }
+        /// }</code>
         /// </summary>
         /// <returns>A JObject containing information about unconnected, bad, and connected peers.</returns>
         [RpcMethodWithParams]
@@ -95,6 +113,37 @@ private static JObject GetRelayResult(VerifyResult reason, UInt256 hash)
 
         /// <summary>
         /// Gets version information about the node, including network, protocol, and RPC settings.
+        /// <para>Request format:</para>
+        /// <code>{ "jsonrpc": "2.0", "id": 1,"method": "getversion"}
+        /// </code>
+        /// <para>Response format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "result": {
+        ///     "tcpport": 10333, // The TCP port,
+        ///     "nonce": 1, // The nonce,
+        ///     "useragent": "The user agent",
+        ///     "rpc": {
+        ///       "maxiteratorresultitems": 100, // The maximum number of items in the iterator result,
+        ///       "sessionenabled": false // Whether session is enabled,
+        ///      },
+        ///      "protocol": {
+        ///       "addressversion": 0x35, // The address version,
+        ///       "network": 5195086, // The network,
+        ///       "validatorscount": 0, // The number of validators,
+        ///       "msperblock": 15000, // The time per block in milliseconds,
+        ///       "maxtraceableblocks": 2102400, // The maximum traceable blocks,
+        ///       "maxvaliduntilblockincrement": 86400000 / 15000, // The maximum valid until block increment,
+        ///       "maxtransactionsperblock": 512, // The maximum number of transactions per block,
+        ///       "memorypoolmaxtransactions": 50000, // The maximum number of transactions in the memory pool,
+        ///       "initialgasdistribution": 5200000000000000, // The initial gas distribution,
+        ///       "hardforks": [{"name": "The hardfork name", "blockheight": 0/*The block height*/ }],
+        ///       "standbycommittee": ["The public key"],
+        ///       "seedlist": ["The seed list"]
+        ///     }
+        ///   }
+        /// }</code>
         /// </summary>
         /// <returns>A JObject containing detailed version and configuration information.</returns>
         [RpcMethodWithParams]
@@ -147,6 +196,12 @@ private static string StripPrefix(string s, string prefix)
 
         /// <summary>
         /// Sends a raw transaction to the network.
+        /// <para>Request format:</para>
+        /// <code>
+        /// {"jsonrpc": "2.0", "id": 1,"method": "sendrawtransaction", "params": ["A Base64-encoded transaction"]}
+        /// </code>
+        /// <para>Response format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1, "result": {"hash": "The hash of the transaction"}}</code>
         /// </summary>
         /// <param name="base64Tx">The base64-encoded transaction.</param>
         /// <returns>A JToken containing the result of the transaction relay.</returns>
@@ -160,6 +215,11 @@ protected internal virtual JToken SendRawTransaction(string base64Tx)
 
         /// <summary>
         /// Submits a new block to the network.
+        /// <para>Request format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1,"method": "submitblock", "params": ["A Base64-encoded block"]}
+        /// </code>
+        /// <para>Response format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1, "result": {"hash": "The hash of the block"}}</code>
         /// </summary>
         /// <param name="base64Block">The base64-encoded block.</param>
         /// <returns>A JToken containing the result of the block submission.</returns>

src/Plugins/RpcServer/RpcServer.Node.cs

@@ -212,6 +212,61 @@ private static Witness[] WitnessesFromJson(JArray _params)
             }).ToArray();
         }
 
+        /// <summary>
+        /// Invokes a function on a contract.
+        /// <para>Request format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "method": "invokefunction",
+        ///   "params": [
+        ///     "An UInt160 ScriptHash",  // the contract address
+        ///     "operation",  // the operation to invoke
+        ///     [{"type": "ContractParameterType", "value": "The parameter value"}],  // ContractParameter, the arguments
+        ///     [{
+        ///       "account": "An UInt160 or Base58Check address",
+        ///       "scopes": "WitnessScope", // WitnessScope
+        ///       "allowedcontracts": ["The contract hash(UInt160)"], // optional
+        ///       "allowedgroups": ["PublicKey"], // ECPoint, i.e. ECC PublicKey, optional
+        ///       "rules": [{"action": "WitnessRuleAction", "condition": {A json of WitnessCondition}}] // WitnessRule
+        ///     }], // A Signer array, optional
+        ///     [{"invocation": "A Base64-encoded string","verification": "A Base64-encoded string"}] // A Witness array, optional
+        ///     false // useDiagnostic, a bool value indicating whether to use diagnostic information, optional
+        ///   ]
+        /// }</code>
+        /// <para>Response format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "result": {
+        ///     "script": "A Base64-encoded string",
+        ///     "state": "A string of VMState",
+        ///     "gasconsumed": "An integer number in string",
+        ///     "exception": "The exception message",
+        ///     "stack": [{"type": "The stack item type", "value": "The stack item value"}],
+        ///     "notifications": [
+        ///       {"eventname": "The event name", "contract": "The contract hash", "state": {"interface": "A string", "id": "The GUID string"}}
+        ///     ], // The notifications, optional
+        ///     "diagnostics": {
+        ///       "invokedcontracts": {"hash": "The contract hash","call": [{"hash": "The contract hash"}]},
+        ///       "storagechanges": [{"state": "The state", "key": "The key", "value": "The value"}]
+        ///     }, // The diagnostics, optional, if useDiagnostic is true
+        ///     "session": "A GUID string" // The session id, optional
+        ///   }
+        /// }</code>
+        /// </summary>
+        /// <param name="_params">An array containing the following elements:
+        /// [0]: The script hash of the contract to invoke as a string.
+        /// [1]: The operation to invoke as a string.
+        /// [2]: The arguments to pass to the function as an array of ContractParameter. Optional.
+        /// [3]: The signers as an array of Signer. Optional.
+        /// [4]: The witnesses as an array of Witness. Optional.
+        /// [5]: A boolean value indicating whether to use diagnostic information. Optional.
+        /// </param>
+        /// <returns>The result of the function invocation.</returns>
+        /// <exception cref="RpcException">
+        /// Thrown when the script hash is invalid, the contract is not found, or the verification fails.
+        /// </exception>
         [RpcMethod]
         protected internal virtual JToken InvokeFunction(JArray _params)
         {
@@ -230,6 +285,57 @@ protected internal virtual JToken InvokeFunction(JArray _params)
             return GetInvokeResult(script, signers, witnesses, useDiagnostic);
         }
 
+        /// <summary>
+        /// Invokes a script.
+        /// <para>Request format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "method": "invokescript",
+        ///   "params": [
+        ///     "A Base64-encoded string", // the script to invoke
+        ///     [{
+        ///       "account": "An UInt160 or Base58Check address",
+        ///       "scopes": "WitnessScope", // WitnessScope
+        ///       "allowedcontracts": ["The contract hash(UInt160)"], // optional
+        ///       "allowedgroups": ["PublicKey"], // ECPoint, i.e. ECC PublicKey, optional
+        ///       "rules": [{"action": "WitnessRuleAction", "condition": {A json of WitnessCondition}}] // WitnessRule
+        ///     }], // A Signer array, optional
+        ///     [{"invocation": "A Base64-encoded string","verification": "A Base64-encoded string"}] // A Witness array, optional
+        ///     false // useDiagnostic, a bool value indicating whether to use diagnostic information, optional
+        ///   ]
+        /// }</code>
+        /// <para>Response format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "result": {
+        ///     "script": "A Base64-encoded string",
+        ///     "state": "A string of VMState",
+        ///     "gasconsumed": "An integer number in string",
+        ///     "exception": "The exception message",
+        ///     "stack": [{"type": "The stack item type", "value": "The stack item value"}],
+        ///     "notifications": [
+        ///       {"eventname": "The event name", "contract": "The contract hash", "state": {"interface": "A string", "id": "The GUID string"}}
+        ///     ], // The notifications, optional
+        ///     "diagnostics": {
+        ///       "invokedcontracts": {"hash": "The contract hash","call": [{"hash": "The contract hash"}]},
+        ///       "storagechanges": [{"state": "The state", "key": "The key", "value": "The value"}]
+        ///     }, // The diagnostics, optional, if useDiagnostic is true
+        ///     "session": "A GUID string" // The session id, optional
+        ///   }
+        /// }</code>
+        /// </summary>
+        /// <param name="_params">An array containing the following elements:
+        /// [0]: The script as a Base64-encoded string.
+        /// [1]: The signers as an array of Signer. Optional.
+        /// [2]: The witnesses as an array of Witness. Optional.
+        /// [3]: A boolean value indicating whether to use diagnostic information. Optional.
+        /// </param>
+        /// <returns>The result of the script invocation.</returns>
+        /// <exception cref="RpcException">
+        /// Thrown when the script is invalid, the verification fails, or the script hash is invalid.
+        /// </exception>
         [RpcMethod]
         protected internal virtual JToken InvokeScript(JArray _params)
         {
@@ -240,6 +346,27 @@ protected internal virtual JToken InvokeScript(JArray _params)
             return GetInvokeResult(script, signers, witnesses, useDiagnostic);
         }
 
+        /// <summary>
+        /// <para>Request format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "method": "traverseiterator",
+        ///   "params": [
+        ///     "A GUID string(The session id)",
+        ///     "A GUID string(The iterator id)",
+        ///     "An integer number(The number of items to traverse)"
+        ///   ]
+        /// }</code>
+        /// <para>Response format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "result": [{"type": "The stack item type", "value": "The stack item value"}]
+        /// }</code>
+        /// </summary>
+        /// <param name="_params"></param>
+        /// <returns></returns>
         [RpcMethod]
         protected internal virtual JToken TraverseIterator(JArray _params)
         {
@@ -261,6 +388,21 @@ protected internal virtual JToken TraverseIterator(JArray _params)
             return json;
         }
 
+        /// <summary>
+        /// Terminates a session.
+        /// <para>Request format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "method": "terminatesession",
+        ///   "params": ["A GUID string(The session id)"]
+        /// }</code>
+        /// <para>Response format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1, "result": true}</code>
+        /// </summary>
+        /// <param name="_params">A 1-element array containing the session id as a GUID string.</param>
+        /// <returns>True if the session is terminated successfully, otherwise false.</returns>
+        /// <exception cref="RpcException">Thrown when the session id is invalid.</exception>
         [RpcMethod]
         protected internal virtual JToken TerminateSession(JArray _params)
         {
@@ -277,6 +419,25 @@ protected internal virtual JToken TerminateSession(JArray _params)
             return result;
         }
 
+        /// <summary>
+        /// Gets the unclaimed gas of an address.
+        /// <para>Request format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "method": "getunclaimedgas",
+        ///   "params": ["An UInt160 or Base58Check address"]
+        /// }</code>
+        /// <para>Response format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1, "result": {"unclaimed": "An integer in string", "address": "The address"}}</code>
+        /// </summary>
+        /// <param name="_params">An array containing the following elements:
+        /// [0]: The address as a UInt160 or Base58Check address.
+        /// </param>
+        /// <returns>A JSON object containing the unclaimed gas and the address.</returns>
+        /// <exception cref="RpcException">
+        /// Thrown when the address is invalid.
+        /// </exception>
         [RpcMethod]
         protected internal virtual JToken GetUnclaimedGas(JArray _params)
         {

src/Plugins/RpcServer/RpcServer.SmartContract.cs

@@ -17,6 +17,21 @@ namespace Neo.Plugins.RpcServer
 {
     partial class RpcServer
     {
+        /// <summary>
+        /// Lists all plugins.
+        /// <para>Request format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1, "method": "listplugins"}</code>
+        /// <para>Response format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "result": [
+        ///     {"name": "The plugin name", "version": "The plugin version", "interfaces": ["The plugin method name"]}
+        ///   ]
+        /// }</code>
+        /// </summary>
+        /// <param name="_params">A empty array.</param>
+        /// <returns>A JSON array containing the plugin information.</returns>
         [RpcMethod]
         protected internal virtual JToken ListPlugins(JArray _params)
         {
@@ -33,6 +48,19 @@ protected internal virtual JToken ListPlugins(JArray _params)
                 }));
         }
 
+        /// <summary>
+        /// Validates an address.
+        /// <para>Request format:</para>
+        /// <code>{"jsonrpc": "2.0", "id": 1, "method": "validateaddress", "params": ["The address"]}</code>
+        /// <para>Response format:</para>
+        /// <code>{
+        ///   "jsonrpc": "2.0",
+        ///   "id": 1,
+        ///   "result": {"address": "The address", "isvalid": true}
+        /// }</code>
+        /// </summary>
+        /// <param name="_params">A 1-element array containing the address as a string.</param>
+        /// <returns>A JSON object containing the address and whether it is valid.</returns>
         [RpcMethod]
         protected internal virtual JToken ValidateAddress(JArray _params)
         {