Merge pull request #84 from casper-network/feat/article/029-rpc-compa…

…rison Feat/article/029 rpc comparison
casper-network · Jul 29, 2024 · 2cb6cf3 · 2cb6cf3
2 parents fb41a79 + 59cca25
commit 2cb6cf3
Show file tree

Hide file tree

Showing 318 changed files with 24,954 additions and 89 deletions.
diff --git a/articles/024-jsonrpc-comp.md b/articles/024-jsonrpc-comp.md
@@ -0,0 +1,68 @@
+# Casper 1.X -> Casper 2.0 :: JSON-RPC API changes  
+
+## Introduction
+
+This article is intended for developers consuming the Casper 2.0 (AKA Condor) JSON RPC, such as dApp developers, SDK developers, or others relying on the JSON-RPC API. In this article we examine the JSON-RPC  and break down the [differences between v1.5.6 and v2.0.0](#differences-between-v15-and-v20).
+
+Since the network's inception, the Casper node has exposed an API over HTTP, using JSON, which is known as the JSON-RPC. This API allows client software such as dApps and SDKs to communicate and interact with the node, giving access to query node state, chain state, balance details and other information, as well as to write information to the chain by submitting transactions.  
+
+## Changes for v2.0
+
+### Casper Sidecar
+
+One of the major changes in the Condor upgrade is the new [casper-sidecar](https://github.com/casper-network/casper-sidecar). The sidecar runs in a **dedicated** process and and is bound to a node's binary port and/or SSE port.  The sidecar assumes **all** responsibility for running the JSON-RPC server and exposing the JSON-RPC endpoints to the internet, i.e. the node software itself no longer exposes a JSON RPC API to the consumer - <u>this job is now done by the sidecar</u>.  
+
+Because the sidecar runs in a dedicated process, it is possible to run a sidecar upon a different machine to the node.  However in practice, most node operators will likely operate a sidecar process on the same machine as the node.  Furthermore an operator's deployment setup is opaque to to a DApp that interacts with the JSON-RPC API via an SDK.  
+
+There are several benefits to moving the JSON-RPC API to a sidecar:  
+- The JSON-RPC API can now evolve independently of the node  
+- A node operator now has a finer degree of control over their operational setup
+- The sidecar reduces the amount of work that the node itself has to do, thereby simplifying the deployment of alternative node implementations (e.g. mojo, go, zig, c++)
+
+### Node Binary Port
+
+The Casper 2.0 Node now exposes a pure Binary Port API, which allows connection over TCP/IP and pure binary serialization for your remote procedure calls.  Depending on your use case, you may be interested in considering this option for interacting with Casper Condor. In general, the binary port offers better performance and features compared to the JSON RPC.  A detailed discussion of the Binary Port will be contained in a future article.  It is anticipated that all SDKs will be updated so as to support the new Binary Port API.
+
+#### JSON-RPC Differences  
+
+The biggest immediately obvious change in the RPC is the change in name from deploy to transaction.  Casper 1.X used the name "deploy" for a unit of work submitted to the blockchain, in Condor a unit of work is now renamed as "Transaction". 
+
+### JSON-RPC Schema Definitions
+
+See [here](./024-jsonrpc-comp/rpc-1.5/schema.json) for Casper 1.5 node JSON-RPC.
+
+See [here](./024-jsonrpc-comp/rpc-2.0/schema.json) for Casper 2.0 node JSON-RPC.
+
+## Table of v1.5 & v2.0 JSON-RPC API differences
+
+| Function in v1.5                      | Function in v2.0                      |Remarks|
+| ---                                   | ---                                   | --- |
+| [account_put_deploy](./024-jsonrpc-comp/rpc-1.5/account_put_deploy.json)                                      | [account_put_transaction](./024-jsonrpc-comp/rpc-2.0/account_put_transaction.json)                            | [Renamed](./024-jsonrpc-comp/account_put_transaction.md)     |  
+| [chain_get_block_transfers](./024-jsonrpc-comp/rpc-1.5/chain_get_block_transfers.json)                        | [chain_get_block_transfers](./024-jsonrpc-comp/rpc-2.0/chain_get_block_transfers.json)                        | Unchanged     |
+| [chain_get_block](./024-jsonrpc-comp/rpc-1.5/chain_get_block.json)                                            | [chain_get_block](./024-jsonrpc-comp/rpc-2.0/chain_get_block.json)                                            | [Now returns Block with Signatures](./024-jsonrpc-comp/chain_get_block.md)         |
+| [chain_get_era_info_by_switch_block](./024-jsonrpc-comp/rpc-1.5/chain_get_era_info_by_switch_block.json)      | [chain_get_era_info_by_switch_block](./024-jsonrpc-comp/rpc-2.0/chain_get_era_info_by_switch_block.json)      | Unchanged     |
+| [chain_get_era_summary](./024-jsonrpc-comp/rpc-1.5/chain_get_era_summary.json)                                | [chain_get_era_summary](./024-jsonrpc-comp/rpc-2.0/chain_get_era_summary.json)                                | Unchanged     |
+| [chain_get_state_root_hash](./024-jsonrpc-comp/rpc-1.5/chain_get_state_root_hash.json)                        | [chain_get_state_root_hash](./024-jsonrpc-comp/rpc-2.0/chain_get_state_root_hash.json)                        | Unchanged     |
+| [info_get_chainspec](./024-jsonrpc-comp/rpc-1.5/info_get_chainspec.json)                                      | [info_get_chainspec](./024-jsonrpc-comp/rpc-2.0/info_get_chainspec.json)                                      | Unchanged     |
+| [info_get_deploy](./024-jsonrpc-comp/rpc-1.5/info_get_deploy.json)                                            | [info_get_transaction](./024-jsonrpc-comp/rpc-2.0/info_get_transaction.json)                                  | [Renamed](./024-jsonrpc-comp/info_get_transaction.md)    |
+| [info_get_peers](./024-jsonrpc-comp/rpc-1.5/info_get_peers.json)                                              | [info_get_peers](./024-jsonrpc-comp/rpc-2.0/info_get_peers.json)                                              | Unchanged     |
+| [info_get_status](./024-jsonrpc-comp/rpc-1.5/info_get_status.json)                                            | [info_get_status](./024-jsonrpc-comp/rpc-2.0/info_get_status.json)                                            | Latest [switch block hash](./024-jsonrpc-comp/rpc-2.0/components/BlockHash.json) included in result     |
+| [info_get_validator_changes](./024-jsonrpc-comp/rpc-1.5/info_get_validator_changes.json)                      | [info_get_validator_changes](./024-jsonrpc-comp/rpc-2.0/info_get_validator_changes.json)                      | Unchanged     |
+| [query_balance](./024-jsonrpc-comp/rpc-1.5/query_balance.json)                                                | [query_balance](./024-jsonrpc-comp/rpc-2.0/query_balance.json)                                                | Unchanged     |
+|                                                                                                               | [query_balance_details](./024-jsonrpc-comp/rpc-2.0/query_balance_details.json)                                | Added         |
+| [query_global_state](./024-jsonrpc-comp/rpc-1.5/query_global_state.json)                                      | [query_global_state](./024-jsonrpc-comp/rpc-2.0/query_global_state.json)                                      | Unchanged     |
+| [state_get_account_info](./024-jsonrpc-comp/rpc-1.5/state_get_account_info.json)                              | [state_get_account_info](./024-jsonrpc-comp/rpc-2.0/state_get_account_info.json)                              | Unchanged     |
+| [state_get_auction_info](./024-jsonrpc-comp/rpc-1.5/state_get_auction_info.json)                              | [state_get_auction_info](./024-jsonrpc-comp/rpc-2.0/state_get_auction_info.json)                              | Unchanged     |
+| [state_get_balance](./024-jsonrpc-comp/rpc-1.5/state_get_balance.json)                                        | [state_get_balance](./024-jsonrpc-comp/rpc-2.0/state_get_balance.json)                                        | [Balance now reflects all active holds](./024-jsonrpc-comp/state_get_balance.md)     |
+| [state_get_dictionary_item](./024-jsonrpc-comp/rpc-1.5/state_get_dictionary_item.json)                        | [state_get_dictionary_item](./024-jsonrpc-comp/rpc-2.0/state_get_dictionary_item.json)                        | Unchanged     |
+| [state_get_item](./024-jsonrpc-comp/rpc-1.5/state_get_item.json)                                              | [state_get_entity](./024-jsonrpc-comp/rpc-2.0/state_get_entity.json)                                          | Renamed    |
+
+
+---
+## Summary
+
+The major changes in the JSON-RPC between v1.5.6 and v2.0.0 are:
+
+- The [casper-sidecar](https://github.com/casper-network/casper-sidecar) is now responsible for serving the JSON-RPC API.
+- The sidecar may also expose the Server Side Events API, this is of some relevance to developers relying upon the Casper Event Standard (CES).
+- Deploys are now called Transactions as per the industry norm.  There are differences in the representation of these data structures.
diff --git a/articles/024-jsonrpc-comp/account_put_transaction.md b/articles/024-jsonrpc-comp/account_put_transaction.md
@@ -0,0 +1,7 @@
+## account_put_transaction
+The [account_put_transaction](./rpc-2.0/account_put_transaction.json) method replaces the pre-existing [account_put_deploy](./rpc-1.5/account_put_deploy.json) method. To some extent, it simply mirrors the pre-existing method. However, the new Transaction datatype is used instead of the legacy Deploy.
+
+- Parameters
+  - Accepts a [Transaction](./rpc-2.0/components/Transaction.json) instead of a [Deploy](./rpc-1.5/components/Deploy.json)   
+- Results
+  - Returns a [TransactionHash](./rpc-2.0/components/TransactionHash.json) instead of a [DeployHash](./rpc-1.5/components/DeployHash.json)
diff --git a/articles/024-jsonrpc-comp/chain_get_block.md b/articles/024-jsonrpc-comp/chain_get_block.md
@@ -0,0 +1,3 @@
+## chain_get_clock
+The [chain_get_block](./rpc-2.0/chain_get_block.json) method now returns a [block with signatures](rpc-2.0/components/JsonBlockWithSignatures.json).
+
diff --git a/articles/024-jsonrpc-comp/info_get_transaction.md b/articles/024-jsonrpc-comp/info_get_transaction.md
@@ -0,0 +1,8 @@
+## info_get_transaction
+The [info_get_transaction](./rpc-2.0/info_get_transaction.json) method replaces the pre-existing [info_get_deploy](./rpc-1.5/info_get_deploy.json) method. to some extent, it simply mirrors the pre-existing method. 
+
+- Parameters
+  - Accepts a [TransactionHash](./rpc-2.0/components/TransactionHash.json) instead of a [DeployHash](./rpc-1.5/components/DeployHash.json)   
+- Results
+  - Returns a [Transaction](./rpc-2.0/components/Transaction.json) instead of a [Deploy](./rpc-1.5/components/Deploy.json)
+  - Returns an [ExecutionInfo](./rpc-2.0/components/ExecutionInfo.json) instead of [ExecutionResult](./rpc-1.5/components/JsonExecutionResult.json)  
diff --git a/articles/024-jsonrpc-comp/rpc-1.5/account_put_deploy.json b/articles/024-jsonrpc-comp/rpc-1.5/account_put_deploy.json
@@ -0,0 +1,103 @@
+{
+  "name": "account_put_deploy",
+  "summary": "receives a Deploy to be executed by the network",
+  "params": [
+    {
+      "name": "deploy",
+      "schema": {
+        "description": "The `Deploy`.",
+        "$ref": "#/components/schemas/Deploy"
+      },
+      "required": true
+    }
+  ],
+  "result": {
+    "name": "account_put_deploy_result",
+    "schema": {
+      "description": "Result for \"account_put_deploy\" RPC response.",
+      "type": "object",
+      "required": [
+        "api_version",
+        "deploy_hash"
+      ],
+      "properties": {
+        "api_version": {
+          "description": "The RPC API version.",
+          "type": "string"
+        },
+        "deploy_hash": {
+          "description": "The deploy hash.",
+          "$ref": "#/components/schemas/DeployHash"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "name": "account_put_deploy_example",
+      "params": [
+        {
+          "name": "deploy",
+          "value": {
+            "hash": "5c9b3b099c1378aa8e4a5f07f59ff1fcdc69a83179427c7e67ae0377d94d93fa",
+            "header": {
+              "account": "01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c",
+              "timestamp": "2020-11-17T00:39:24.072Z",
+              "ttl": "1h",
+              "gas_price": 1,
+              "body_hash": "d53cf72d17278fd47d399013ca389c50d589352f1a12593c0b8e01872a641b50",
+              "dependencies": [
+                "0101010101010101010101010101010101010101010101010101010101010101"
+              ],
+              "chain_name": "casper-example"
+            },
+            "payment": {
+              "StoredContractByName": {
+                "name": "casper-example",
+                "entry_point": "example-entry-point",
+                "args": [
+                  [
+                    "amount",
+                    {
+                      "cl_type": "I32",
+                      "bytes": "e8030000",
+                      "parsed": 1000
+                    }
+                  ]
+                ]
+              }
+            },
+            "session": {
+              "Transfer": {
+                "args": [
+                  [
+                    "amount",
+                    {
+                      "cl_type": "I32",
+                      "bytes": "e8030000",
+                      "parsed": 1000
+                    }
+                  ]
+                ]
+              }
+            },
+            "approvals": [
+              {
+                "signer": "01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c",
+                "signature": "014c1a89f92e29dd74fc648f741137d9caf4edba97c5f9799ce0c9aa6b0c9b58db368c64098603dbecef645774c05dff057cb1f91f2cf390bbacce78aa6f084007"
+              }
+            ]
+          }
+        }
+      ],
+      "result": {
+        "name": "account_put_deploy_example_result",
+        "value": {
+          "api_version": "1.5.6",
+          "deploy_hash": "5c9b3b099c1378aa8e4a5f07f59ff1fcdc69a83179427c7e67ae0377d94d93fa"
+        }
+      }
+    }
+  ]
+}
diff --git a/articles/024-jsonrpc-comp/rpc-1.5/chain_get_block.json b/articles/024-jsonrpc-comp/rpc-1.5/chain_get_block.json
@@ -0,0 +1,118 @@
+{
+  "name": "chain_get_block",
+  "summary": "returns a Block from the network",
+  "params": [
+    {
+      "name": "block_identifier",
+      "schema": {
+        "description": "The block identifier.",
+        "$ref": "#/components/schemas/BlockIdentifier"
+      },
+      "required": false
+    }
+  ],
+  "result": {
+    "name": "chain_get_block_result",
+    "schema": {
+      "description": "Result for \"chain_get_block\" RPC response.",
+      "type": "object",
+      "required": [
+        "api_version"
+      ],
+      "properties": {
+        "api_version": {
+          "description": "The RPC API version.",
+          "type": "string"
+        },
+        "block": {
+          "description": "The block, if found.",
+          "anyOf": [
+            {
+              "$ref": "#/components/schemas/JsonBlock"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "name": "chain_get_block_example",
+      "params": [
+        {
+          "name": "block_identifier",
+          "value": {
+            "Hash": "13c2d7a68ecdd4b74bf4393c88915c836c863fc4bf11d7f2bd930a1bbccacdcb"
+          }
+        }
+      ],
+      "result": {
+        "name": "chain_get_block_example_result",
+        "value": {
+          "api_version": "1.5.6",
+          "block": {
+            "hash": "13c2d7a68ecdd4b74bf4393c88915c836c863fc4bf11d7f2bd930a1bbccacdcb",
+            "header": {
+              "parent_hash": "0707070707070707070707070707070707070707070707070707070707070707",
+              "state_root_hash": "0808080808080808080808080808080808080808080808080808080808080808",
+              "body_hash": "cd502c5393a3c8b66d6979ad7857507c9baf5a8ba16ba99c28378d3a970fff42",
+              "random_bit": true,
+              "accumulated_seed": "ac979f51525cfd979b14aa7dc0737c5154eabe0db9280eceaa8dc8d2905b20d5",
+              "era_end": {
+                "era_report": {
+                  "equivocators": [
+                    "013b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29"
+                  ],
+                  "rewards": [
+                    {
+                      "validator": "018a88e3dd7409f195fd52db2d3cba5d72ca6709bf1d94121bf3748801b40f6f5c",
+                      "amount": 1000
+                    }
+                  ],
+                  "inactive_validators": [
+                    "018139770ea87d175f56a35466c34c7ecccb8d8a91b4ee37a25df60f5b8fc9b394"
+                  ]
+                },
+                "next_era_validator_weights": [
+                  {
+                    "validator": "016e7a1cdd29b0b78fd13af4c5598feff4ef2a97166e3ca6f2e4fbfccd80505bf1",
+                    "weight": "456"
+                  },
+                  {
+                    "validator": "018a875fff1eb38451577acd5afee405456568dd7c89e090863a0557bc7af49f17",
+                    "weight": "789"
+                  },
+                  {
+                    "validator": "01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c",
+                    "weight": "123"
+                  }
+                ]
+              },
+              "timestamp": "2020-11-17T00:39:24.072Z",
+              "era_id": 1,
+              "height": 10,
+              "protocol_version": "1.0.0"
+            },
+            "body": {
+              "proposer": "01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c",
+              "deploy_hashes": [],
+              "transfer_hashes": [
+                "5c9b3b099c1378aa8e4a5f07f59ff1fcdc69a83179427c7e67ae0377d94d93fa"
+              ]
+            },
+            "proofs": [
+              {
+                "public_key": "01d9bf2148748a85c89da5aad8ee0b0fc2d105fd39d41a4c796536354f0ae2900c",
+                "signature": "016291a7b2689e2edcc6e79030be50edd02f9bd7d809921ae2654012f808c7b9a0f125bc32d6aa610cbd012395a9832ccfaa9262023339f1db71ca073a13bb9707"
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		## chain_get_clock
		The [chain_get_block](./rpc-2.0/chain_get_block.json) method now returns a [block with signatures](rpc-2.0/components/JsonBlockWithSignatures.json).