refine text in 2 namespace pages

2 years ago · 88357ff1b7
parent 74d3defd9d
commit 88357ff1b7
2 changed files with 102 additions and 82 deletions
--- a/content/docs/interacting_with_geth/RPC/pubsub.md
+++ b/content/docs/interacting_with_geth/RPC/pubsub.md
@ -3,56 +3,54 @@ title: Real-time Events
 sort_key: B
 ---

-Geth v1.4 and later support publish / subscribe using JSON-RPC notifications. This allows
-clients to wait for events instead of polling for them.
+Geth v1.4 and later support publish / subscribe using JSON-RPC notifications. This allows clients to wait for events instead of polling for them.

-It works by subscribing to particular events. The node will return a subscription id. For
-each event that matches the subscription a notification with relevant data is send
-together with the subscription id.
+It works by subscribing to particular events. The node will return a subscription id. For each event that matches the subscription a notification with relevant data is send together with the subscription id.

 Example:

-    // create subscription
-    >> {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
-    << {"jsonrpc":"2.0","id":1,"result":"0xcd0c3e8af590364c09d0fa6a1210faf5"}
-
-    // incoming notifications
-    << {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd9263f42a87",<...>, "uncles":[]}}}
-    << {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd90b1a7ad02", <...>, "uncles":["0x80aacd1ea4c9da32efd8c2cc9ab38f8f70578fcd46a1a4ed73f82f3e0957f936"]}}}
-
-    // cancel subscription
-    >> {"id": 1, "method": "eth_unsubscribe", "params": ["0xcd0c3e8af590364c09d0fa6a1210faf5"]}
-    << {"jsonrpc":"2.0","id":1,"result":true}
-
+```sh
+// create subscription
+{"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
+```
+
+returns
+
+```sh
+{"jsonrpc":"2.0","id":1,"result":"0xcd0c3e8af590364c09d0fa6a1210faf5"}
+// incoming notifications
+{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd9263f42a87",<...>, "uncles":[]}}}
+{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xcd0c3e8af590364c09d0fa6a1210faf5","result":{"difficulty":"0xd90b1a7ad02", <...>, "uncles":["0x80aacd1ea4c9da32efd8c2cc9ab38f8f70578fcd46a1a4ed73f82f3e0957f936"]}}}
+```
+to cancel the subscription:
+
+```sh
+// cancel subscription
+{"id": 1, "method": "eth_unsubscribe", "params": ["0xcd0c3e8af590364c09d0fa6a1210faf5"]}
+{"jsonrpc":"2.0","id":1,"result":true}
+```
 ### Considerations

-1. notifications are sent for current events and not for past events. If your use case
-   requires you not to miss any notifications then subscriptions are probably not the best
-   option.
-2. subscriptions require a full duplex connection. Geth offers such connections in the
-   form of WebSocket and IPC (enabled by default).
-3. subscriptions are coupled to a connection. If the connection is closed all
-   subscriptions that are created over this connection are removed.
-4. notifications are stored in an internal buffer and sent from this buffer to the client.
-   If the client is unable to keep up and the number of buffered notifications reaches a
-   limit (currently 10k) the connection is closed. Keep in mind that subscribing to some
-   events can cause a flood of notifications, e.g. listening for all logs/blocks when the
-   node starts to synchronize.
+1. Notifications are sent for current events and not for past events. For use cases that depend on not to miss any notifications subscriptions are probably not the best option.
+2. Subscriptions require a full duplex connection. Geth offers such connections in the form of WebSocket and IPC (enabled by default).
+3. Subscriptions are coupled to a connection. If the connection is closed all subscriptions that are created over this connection are removed.
+4. Notifications are stored in an internal buffer and sent from this buffer to the client. If the client is unable to keep up and the number of buffered notifications reaches a limit (currently 10k) the connection is closed. Keep in mind that subscribing to some events can cause a flood of notifications, e.g. listening for all logs/blocks when the node starts to synchronize.

 ## Create subscription

-Subscriptions are created with a regular RPC call with `eth_subscribe` as method and the
-subscription name as first parameter. If successful it returns the subscription id.
+Subscriptions are created with a regular RPC call with `eth_subscribe` as method and the subscription name as first parameter. If successful it returns the subscription id.

 ### Parameters

-1. subscription name
-2. optional arguments
+1. Subscription name
+2. Optional arguments

 ### Example

-    >> {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
-    << {"id": 1, "jsonrpc": "2.0", "result": "0x9cef478923ff08bf67fde6c64013158d"}
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
+{"id": 1, "jsonrpc": "2.0", "result": "0x9cef478923ff08bf67fde6c64013158d"}
+```

 ## Cancel subscription

@ -65,8 +63,10 @@ was cancelled successful.

 ### Example

-    >> {"id": 1, "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"]}
-    << {"jsonrpc":"2.0","id":1,"result":true}
+```sh
+{"id": 1, "method": "eth_unsubscribe", "params": ["0x9cef478923ff08bf67fde6c64013158d"]}
+{"jsonrpc":"2.0","id":1,"result":true}
+```

 ## Supported Subscriptions

@ -79,32 +79,39 @@ chain. Therefore the subscription can emit multiple headers on the same height.

 #### Example

-    >> {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
-    << {"jsonrpc":"2.0","id":2,"result":"0x9ce59a13059e417087c02d3236a0b1cc"}
-
-    << {
-           "jsonrpc": "2.0",
-           "method": "eth_subscription",
-           "params": {
-             "result": {
-               "difficulty": "0x15d9223a23aa",
-               "extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
-               "gasLimit": "0x47e7c4",
-               "gasUsed": "0x38658",
-               "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
-               "miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
-               "nonce": "0x084149998194cc5f",
-               "number": "0x1348c9",
-               "parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
-               "receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
-               "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
-               "stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
-               "timestamp": "0x56ffeff8",
-               "transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
-             },
-             "subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
-           }
-         }
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["newHeads"]}
+```
+
+returns
+
+```sh
+{"jsonrpc":"2.0","id":2,"result":"0x9ce59a13059e417087c02d3236a0b1cc"}
+
+{
+        "jsonrpc": "2.0",
+        "method": "eth_subscription",
+        "params": {
+            "result": {
+            "difficulty": "0x15d9223a23aa",
+            "extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
+            "gasLimit": "0x47e7c4",
+            "gasUsed": "0x38658",
+            "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+            "miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
+            "nonce": "0x084149998194cc5f",
+            "number": "0x1348c9",
+            "parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
+            "receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
+            "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
+            "stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
+            "timestamp": "0x56ffeff8",
+            "transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
+            },
+            "subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
+        }
+        }
+```

 ### logs

@ -120,11 +127,15 @@ In case of a chain reorganization previous sent logs that are on the old chain w


 #### Example
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]}]}
+```
+returns
+```sh
+{"jsonrpc":"2.0","id":2,"result":"0x4a8a4c0517381924f9838102c5a4dcb7"}

-    >> {"id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]}]}
-    << {"jsonrpc":"2.0","id":2,"result":"0x4a8a4c0517381924f9838102c5a4dcb7"}
-
-    << {"jsonrpc":"2.0","method":"eth_subscription","params": {"subscription":"0x4a8a4c0517381924f9838102c5a4dcb7","result":{"address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd","blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04","blockNumber":"0x29e87","data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003","logIndex":"0x0","topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],"transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4","transactionIndex":"0x0"}}}
+{"jsonrpc":"2.0","method":"eth_subscription","params": {"subscription":"0x4a8a4c0517381924f9838102c5a4dcb7","result":{"address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd","blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04","blockNumber":"0x29e87","data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003","logIndex":"0x0","topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],"transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4","transactionIndex":"0x0"}}}
+```

 ### newPendingTransactions

@ -138,16 +149,23 @@ none

 #### Example

-    >> {"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions"]}
-    << {"jsonrpc":"2.0","id":2,"result":"0xc3b33aa549fb9a60e95d21862596617c"}
-    << {
-            "jsonrpc":"2.0",
-            "method":"eth_subscription",
-            "params":{
-                "subscription":"0xc3b33aa549fb9a60e95d21862596617c",
-                "result":"0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
-            }
-       }
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions"]}
+```
+
+returns
+
+```sh
+{"jsonrpc":"2.0","id":2,"result":"0xc3b33aa549fb9a60e95d21862596617c"}
+{
+        "jsonrpc":"2.0",
+        "method":"eth_subscription",
+        "params":{
+            "subscription":"0xc3b33aa549fb9a60e95d21862596617c",
+            "result":"0xd6fdc5cc41a9959e922f30cb772a9aef46f4daea279307bc5f7024edc4ccd7fa"
+        }
+    }
+```

 ### syncing

@ -161,8 +179,9 @@ none

 #### Example

-    >> {"id": 1, "method": "eth_subscribe", "params": ["syncing"]}
-    << {"jsonrpc":"2.0","id":2,"result":"0xe2ffeb2703bcf602d42922385829ce96"}
-
-    << {"subscription":"0xe2ffeb2703bcf602d42922385829ce96","result":{"syncing":true,"status":{"startingBlock":674427,"currentBlock":67400,"highestBlock":674432,"pulledStates":0,"knownStates":0}}}}
+```sh
+{"id": 1, "method": "eth_subscribe", "params": ["syncing"]}

+{"jsonrpc":"2.0","id":2,"result":"0xe2ffeb2703bcf602d42922385829ce96"}
+{"subscription":"0xe2ffeb2703bcf602d42922385829ce96","result":{"syncing":true,"status":{"startingBlock":674427,"currentBlock":67400,"highestBlock":674432,"pulledStates":0,"knownStates":0}}}}
+```
--- a/content/docs/tools/Clef/apis.md
+++ b/content/docs/tools/Clef/apis.md
@ -7,7 +7,7 @@ sort_key: E

 Clef listens to HTTP requests on `http.addr`:`http.port` (or to IPC on `ipcpath`), with the same JSON-RPC standard as Geth. The messages are expected to be [JSON-RPC 2.0 standard](https://www.jsonrpc.org/specification).

-Some of these calls can require user interaction. Clients must be aware that responses may be delayed significantly or may never be received if a user decides to ignore the confirmation request.
+Some of these calls can require user interaction in the Clef terminal. Responses may be delayed significantly or may never be received if a user decides to ignore the confirmation request.

 The External API is **untrusted**: it does not accept credentials, nor does it expect that requests have any authority.

@ -41,6 +41,7 @@ See the [external API changelog](https://github.com/ethereum/go-ethereum/blob/ma


 ### Encoding
+
 - number: positive integers that are hex encoded
 - data: hex encoded data
 - string: ASCII string