From 113cb0fac303d0bf3f8b566b68f527b8ba3cb8cd Mon Sep 17 00:00:00 2001
From: Roman Khimov <roman@nspcc.ru>
Date: Thu, 7 Jul 2022 18:33:23 +0300
Subject: [PATCH] rpc: rename RawParams to Params in Raw, add comments

We've got parameters here and usually we name them Raw when they're
represented by json.RawMessage which is not the case here, so make it a bit
more friendly (the type itself is only used in client internals, so rename is
not a huge problem).
---
 pkg/rpc/client/client.go   |  8 ++++----
 pkg/rpc/client/wsclient.go |  2 +-
 pkg/rpc/request/types.go   | 28 ++++++++++++++++++++--------
 3 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/pkg/rpc/client/client.go b/pkg/rpc/client/client.go
index a837e5238..b904c82b8 100644
--- a/pkg/rpc/client/client.go
+++ b/pkg/rpc/client/client.go
@@ -174,10 +174,10 @@ func (c *Client) Close() {
 
 func (c *Client) performRequest(method string, p request.RawParams, v interface{}) error {
 	var r = request.Raw{
-		JSONRPC:   request.JSONRPCVersion,
-		Method:    method,
-		RawParams: p.Values,
-		ID:        c.getNextRequestID(),
+		JSONRPC: request.JSONRPCVersion,
+		Method:  method,
+		Params:  p.Values,
+		ID:      c.getNextRequestID(),
 	}
 
 	raw, err := c.requestF(&r)
diff --git a/pkg/rpc/client/wsclient.go b/pkg/rpc/client/wsclient.go
index 5d3d00439..adcfdede8 100644
--- a/pkg/rpc/client/wsclient.go
+++ b/pkg/rpc/client/wsclient.go
@@ -256,7 +256,7 @@ writeloop:
 				break writeloop
 			}
 			if err := c.ws.WriteJSON(req); err != nil {
-				connCloseErr = fmt.Errorf("failed to write JSON request (%s / %d): %w", req.Method, len(req.RawParams), err)
+				connCloseErr = fmt.Errorf("failed to write JSON request (%s / %d): %w", req.Method, len(req.Params), err)
 				break writeloop
 			}
 		case <-pingTicker.C:
diff --git a/pkg/rpc/request/types.go b/pkg/rpc/request/types.go
index 7ef644862..866f91926 100644
--- a/pkg/rpc/request/types.go
+++ b/pkg/rpc/request/types.go
@@ -32,15 +32,27 @@ func NewRawParams(vals ...interface{}) RawParams {
 	return p
 }
 
-// Raw represents JSON-RPC request on the Client side.
-type Raw struct {
-	JSONRPC   string        `json:"jsonrpc"`
-	Method    string        `json:"method"`
-	RawParams []interface{} `json:"params"`
-	ID        uint64        `json:"id"`
-}
-
 type (
+	// Raw represents JSON-RPC request. It's generic enough to be used in many
+	// generic JSON-RPC communication scenarios, yet at the same time it's
+	// tailored for NeoGo RPC Client needs.
+	Raw struct {
+		// JSONRPC is the protocol version, only valid when it contains JSONRPCVersion.
+		JSONRPC string `json:"jsonrpc"`
+		// Method is the method being called.
+		Method string `json:"method"`
+		// Params is a set of method-specific parameters passed to the call. They
+		// can be anything as long as they can be marshaled to JSON correctly and
+		// used by the method implementation on the server side. While JSON-RPC
+		// technically allows it to be an object, all Neo calls expect params
+		// to be an array.
+		Params []interface{} `json:"params"`
+		// ID is an identifier associated with this request. JSON-RPC itself allows
+		// any strings to be used for it as well, but NeoGo RPC client uses numeric
+		// identifiers.
+		ID uint64 `json:"id"`
+	}
+
 	// BlockFilter is a wrapper structure for the block event filter. The only
 	// allowed filter is primary index.
 	BlockFilter struct {