Merge pull request #42 from tomaka/fix-30

Rename `runtimeUpdates` to `withRuntime`

src/api/chainHead.md

@@ -12,7 +12,7 @@ _This section contains a small beginner guide destined for JSON-RPC client users
 
 This beginner guide shows how to use the `chainHead` functions in order to know the value of a certain storage item.
 
-1. Call `chainHead_unstable_follow` with `runtimeUpdates: true` to obtain a `followSubscription`. This `followSubscription` will need to be passed when calling most of the other `chainHead`-prefixed functions. If at any point in the future the JSON-RPC server sends back a `{"event": "stop"}` notification, jump back to step 1.
+1. Call `chainHead_unstable_follow` with `withRuntime: true` to obtain a `followSubscription`. This `followSubscription` will need to be passed when calling most of the other `chainHead`-prefixed functions. If at any point in the future the JSON-RPC server sends back a `{"event": "stop"}` notification, jump back to step 1.
 
 2. When the JSON-RPC server sends back a `{"event": "initialized"}` notification with `subscription` equal to your `followSubscription`, store the value of `finalizedBlockHash` found in that notification.
 

src/api/chainHead_unstable_call.md

@@ -2,7 +2,7 @@
 
 **Parameters**:
 
-- `followSubscription`: An opaque string that was returned by `chainHead_unstable_follow`. The `runtimeUpdates` parameter of the call must have been equal to `true`.
+- `followSubscription`: An opaque string that was returned by `chainHead_unstable_follow`. The `withRuntime` parameter of the call must have been equal to `true`.
 - `hash`: String containing the hexadecimal-encoded hash of the header of the block to make the call against.
 - `function`: Name of the runtime entry point to call as a string.
 - `callParameters`: Hexadecimal-encoded SCALE-encoded value to pass as input to the runtime function.
@@ -102,7 +102,7 @@ No more event will be generated with this `subscription`.
 
 - If the networking part of the behaviour fails, then an `{"event": "inaccessible"}` notification is generated (as explained above).
 - If the `followSubscription` is invalid or stale, then a `{"event": "disjoint"}` notification is generated (as explained above).
-- A JSON-RPC error is generated if the `followSubscription` corresponds to a follow where `runtimeUpdates` was `̀false`.
+- A JSON-RPC error is generated if the `followSubscription` corresponds to a follow where `withRuntime` was `̀false`.
 - A JSON-RPC error is generated if the block hash passed as parameter doesn't correspond to any block that has been reported by `chainHead_unstable_follow`.
 - A JSON-RPC error is generated if the `followSubscription` is valid but the block hash passed as parameter has already been unpinned.
 - If the method to call doesn't exist in the Wasm runtime of the chain, then an `{"event": "error"}` notification is generated.

src/api/chainHead_unstable_follow.md

@@ -2,7 +2,7 @@
 
 **Parameters**:
 
-- `runtimeUpdates`: A boolean indicating whether the events should report changes to the runtime.
+- `withRuntime`: A boolean indicating whether the events should report changes to the runtime.
 
 **Return value**: String containing an opaque value representing the subscription.
 
@@ -14,7 +14,7 @@ This function works as follows:
 
 - When called, returns an opaque `followSubscription` that can used to match events and in various other `chainHead`-prefixed functions.
 
-- Later, generates an `initialized` notification (see below) containing the hash of the current finalized block, and, if `runtimeUpdates` is `true`, the runtime specification of the runtime of the current finalized block.
+- Later, generates an `initialized` notification (see below) containing the hash of the current finalized block, and, if `withRuntime` is `true`, the runtime specification of the runtime of the current finalized block.
 
 - Afterwards, generates one `newBlock` notification (see below) for each non-finalized block currently in the node's memory (including all forks), then a `bestBlockChanged` notification. The notifications must be sent in an ordered way such that the parent of each block either can be found in an earlier notification or is the current finalized block.
 
@@ -26,17 +26,17 @@ This function works as follows:
 
 **Note**: This list of notifications makes it very easy for a JSON-RPC client to follow just the best block updates (listening to just `bestBlockChanged` events) or follow just the finalized block updates (listening to just `initialized` and `finalized` events). It is however not possible to easily figure out whether the runtime has been modified when these updates happen. This is not problematic, as anyone using the JSON-RPC interface naively propably doesn't need to account for runtime changes anyway.
 
-## The `runtimeUpdates` parameter
+## The `withRuntime` parameter
 
-If the `runtimeUpdates` parameter is `true`, then blocks shouldn't (and can't) be reported to JSON-RPC clients before the JSON-RPC server has finished obtaining the runtime specification of the blocks that it reports. This includes the finalized block reported in the `initialized` event.
+If the `withRuntime` parameter is `true`, then blocks shouldn't (and can't) be reported to JSON-RPC clients before the JSON-RPC server has finished obtaining the runtime specification of the blocks that it reports. This includes the finalized block reported in the `initialized` event.
 
-If `runtimeUpdates` is `false`, then the `initialized` event must be sent back quickly after the function returns. If `runtimeUpdates` is `true`, then the JSON-RPC server can take as much time as it wants to send back the `initialized` event.
+If `withRuntime` is `false`, then the `initialized` event must be sent back quickly after the function returns. If `withRuntime` is `true`, then the JSON-RPC server can take as much time as it wants to send back the `initialized` event.
 
-For this reason, blocks might be reported more quickly when `runtimeUpdates` is `false`.
+For this reason, blocks might be reported more quickly when `withRuntime` is `false`.
 
 **Note**: It is unlikely that high-level UIs built on top of a JSON-RPC client can do anything before the JSON-RPC server has access to the runtime. Consequently, they should consider the time before the `initialized` event is generated as a loading time. During this loading time, the JSON-RPC server might be performing downloads and CPU-intensive operations. This loading time can be considered as a replacement for the `isSyncing` field of the legacy `system_health` JSON-RPC call.
 
-If a JSON-RPC client wants to be sure to receive an `initialized` event quickly but is also interested in the runtime, it is encouraged to create two subscriptions: one with `runtimeUpdates: true` and one with `runtimeUpdates: false`.
+If a JSON-RPC client wants to be sure to receive an `initialized` event quickly but is also interested in the runtime, it is encouraged to create two subscriptions: one with `withRuntime: true` and one with `withRuntime: false`.
 
 ## Notifications format
 
@@ -67,7 +67,7 @@ Where `subscription` is the value returned by this function, and `result` can be
 
 The `initialized` event is always the first event to be sent back, and is only ever sent back once per subscription.
 
-`finalizedBlockRuntime` is present if and only if `runtimeUpdates`, the parameter to this function, is `true`.
+`finalizedBlockRuntime` is present if and only if `withRuntime`, the parameter to this function, is `true`.
 
 The format of `finalizedBlockRuntime` is described later down this page.
 
@@ -86,7 +86,7 @@ The `newBlock` indicates a new non-finalized block.
 
 `parentBlockHash` is guaranteed to be equal either to the current finalized block hash, or to a block reported in an earlier `newBlock` event.
 
-`newRuntime` must not be present if `runtimeUpdates`, the parameter to this function, is `false`. `newRuntime` must be `null` if the runtime hasn't changed compared to its parent.
+`newRuntime` must not be present if `withRuntime`, the parameter to this function, is `false`. `newRuntime` must be `null` if the runtime hasn't changed compared to its parent.
 
 If present and non-null, the format of `newRuntime` is the same as the `finalizedBlockRuntime` field in the `initialized` event and is explained later down this page.