Integrating transaction into chainhead

src/SUMMARY.md

@@ -24,6 +24,7 @@
     - [chainHead_unstable_header](api/chainHead_unstable_header.md)
     - [chainHead_unstable_stopOperation](api/chainHead_unstable_stopOperation.md)
     - [chainHead_unstable_storage](api/chainHead_unstable_storage.md)
+    - [chainHead_unstable_transacion](api/chainHead_unstable_transacion.md)
     - [chainHead_unstable_unfollow](api/chainHead_unstable_unfollow.md)
     - [chainHead_unstable_unpin](api/chainHead_unstable_unpin.md)
   - [chainSpec](api/chainSpec.md)
@@ -38,6 +39,3 @@
     - [sudo_unstable_version](api/sudo_unstable_version.md)
   - [sudo_sessionKeys]()
     - [sudo_sessionKeys_unstable_generate](api/sudo_sessionKeys_unstable_generate.md)
-  - [transaction](api/transaction.md)
-    - [transaction_unstable_submitAndWatch](api/transaction_unstable_submitAndWatch.md)
-    - [transaction_unstable_unwatch](api/transaction_unstable_unwatch.md)

src/api/chainHead_unstable_body.md

@@ -32,10 +32,10 @@ This return value indicates that the request has successfully started.
 
 This return value indicates the request couldn't be started because the server is overloaded, or that the `followSubscription` is invalid or stale.
 
-The JSON-RPC client should try again after an on-going `chainHead_unstable_storage`, `chainHead_unstable_body`, or `chainHead_unstable_call` operation finishes.
+The JSON-RPC client should try again after an on-going `chainHead_unstable_transaction`, `chainHead_unstable_storage`, `chainHead_unstable_body`, or `chainHead_unstable_call` operation finishes.
 
 The JSON-RPC server must accept at least 16 concurrent operations for any given `chainHead_unstable_follow` subscription. In other words, as long as the JSON-RPC client makes sure that no more than 16 operations are in progress at any given item, it is guaranteed that all of its operations will be accepted by the JSON-RPC server.
-For this purpose, each item requested through `chainHead_unstable_storage` counts as one operation, and each call to `chainHead_unstable_body` and `chainHead_unstable_call` counts as one operation.
+For this purpose, each item requested through `chainHead_unstable_storage` counts as one operation, and each call to `chainHead_unstable_transaction`, `chainHead_unstable_body` and `chainHead_unstable_call` counts as one operation.
 
 ## Overview
 

src/api/chainHead_unstable_call.md

@@ -34,10 +34,10 @@ This return value indicates that the request has successfully started.
 
 This return value indicates the call couldn't be started because the server is overloaded, or that the `followSubscription` is invalid or stale.
 
-The JSON-RPC client should try again after an on-going `chainHead_unstable_storage`, `chainHead_unstable_body`, or `chainHead_unstable_call` operation finishes.
+The JSON-RPC client should try again after an on-going `chainHead_unstable_transaction`, `chainHead_unstable_storage`, `chainHead_unstable_body`, or `chainHead_unstable_call` operation finishes.
 
 The JSON-RPC server must accept at least 16 concurrent operations for any given `chainHead_unstable_follow` subscription. In other words, as long as the JSON-RPC client makes sure that no more than 16 operations are in progress at any given item, it is guaranteed that all of its operations will be accepted by the JSON-RPC server.
-For this purpose, each item requested through `chainHead_unstable_storage` counts as one operation, and each call to `chainHead_unstable_body` and `chainHead_unstable_call` counts as one operation.
+For this purpose, each item requested through `chainHead_unstable_storage` counts as one operation, and each call to `chainHead_unstable_transaction`, `chainHead_unstable_body` and `chainHead_unstable_call` counts as one operation.
 
 ## Overview
 

src/api/chainHead_unstable_follow.md

@@ -80,7 +80,12 @@ The format of `finalizedBlockRuntime` is described later down this page.
     "event": "newBlock",
     "blockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
     "parentBlockHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
-    "newRuntime": ...
+    "newRuntime": ...,
+    "submittedTransactions": {
+        "operationIdA": 0,
+        "operationIdB": 3,
+        ...
+    },
 }
 ```
 
@@ -90,6 +95,8 @@ The `newBlock` indicates a new non-finalized block.
 
 `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.
 
+`submittedTransactions` when the transactions submitted via `chainHead_unstable_transaction` end up being included in a block, then they will be present in this object. The keys of this object are the `operationId`s and the values are the index where the transaction is present inside the block.
+
 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.
 
 ### bestBlockChanged
@@ -131,6 +138,60 @@ All items in `finalizedBlockHashes` and `prunedBlockHashes` are guaranteed to ha
 
 The current best block, in other words the last block reported through a `bestBlockChanged` event, is guaranteed to either be the last item in `finalizedBlockHashes`, or to not be present in either `finalizedBlockHashes` or `prunedBlockHashes`.
 
+### operationTransactionValid
+
+```json
+{
+    "event": "operationTransactionValid",
+    "operationId": ...,
+}
+```
+
+`operationId` is a string returned by `chainHead_unstable_transaction`.
+
+The `operationTransactionValid` event indicates that this transaction has been checked and is considered as valid by the runtime.
+
+This transaction might still become invalid in the future, for example because a conflicting transaction is included in the chain in-between.
+
+Multiple `operationTransactionValid` events can be generated during the lifetime of a transaction. If multiple `operationTransactionValid` events happen in a row, the JSON-RPC serve
+
+### operationTransactionInvalid
+
+```json
+{
+    "event": "operationTransactionInvalid",
+    "operationId": ...,
+    "error": ...,
+}
+```
+
+The `operationTransactionInvalid` event indicates that the runtime has marked the transaction as invalid.
+
+This can happen for a variety of reasons specific to the chain, such as a bad signature, bad nonce, not enough balance for fees, etc.
+
+`error` is a human-readable error message indicating why the transaction is invalid. This string isn't meant to be shown to end users, but is for developers to understand the problem.
+
+No more event will be generated about this transaction.
+
+### operationTransactionBroadcasted
+
+```json
+{
+    "event": "operationTransactionBroadcasted",
+    "numPeers": ...
+}
+```
+
+The `operationTransactionBroadcasted` event indicates the number of other peers this transaction has been broadcasted to.
+
+`numPeers` is the total number of individual peers this transaction has been broadcasted to.
+
+The JSON-RPC server doesn't (and can't) offer any guarantee that these peers have received the transaction or have saved it in their own transactions pool. In other words, no matter how large the value in `numPeers` is, no guarantee is offered that shutting down the local node will lead to the transaction being included.
+
+**Note**: In principle, a value of `numPeers` equal to 0 guarantees that shutting down the local node will lead to the transaction _not_ being included, assuming that the JSON-RPC server isn't a block producer and that no other node has submitted the same transaction. However, because JSON-RPC servers are allowed to delay or skip events, the JSON-RPC client can never be sure that `numPeers` was still equal to 0 when shutting down the node.
+
+If multiple ``operationTransactionBroadcasted` events happen in a row, the JSON-RPC server is allowed to skip all but the last.
+
 ### operationBodyDone
 
 ```json

src/api/chainHead_unstable_stopOperation.md

@@ -3,11 +3,11 @@
 **Parameters**:
 
 - `followSubscription`: An opaque string that was returned by `chainHead_unstable_follow`.
-- `operationId`: An opaque string that was returned by `chainHead_unstable_body`, `chainHead_unstable_call`, or `chainHead_unstable_storage`.
+- `operationId`: An opaque string that was returned by `chainHead_unstable_transaction`, `chainHead_unstable_body`, `chainHead_unstable_call`, or `chainHead_unstable_storage`.
 
 **Return value**: *null*
 
-Stops an operation started with `chainHead_unstable_body`, `chainHead_unstable_call`, or `chainHead_unstable_storage`. If the operation was still in progress, this interrupts it. If the operation was already finished, this call has no effect.
+Stops an operation started with `chainHead_unstable_transaction`, `chainHead_unstable_body`, `chainHead_unstable_call`, or `chainHead_unstable_storage`. If the operation was still in progress, this interrupts it. If the operation was already finished, this call has no effect.
 
 Has no effect if the `followSubscription` is invalid or stale.
 

src/api/chainHead_unstable_storage.md

@@ -33,10 +33,10 @@ Where:
 - `operationId` is a string containing an opaque value representing the operation.
 - `discardedItems` is an integer indicating the number of items at the back of the array of the `items` parameters that couldn't be processed.
 
-If the list the JSON-RPC server is overloaded, it might refuse to accept new storage requests. In that situation, the JSON-RPC server will discard some or all the `items` passed as parameter. The number of items discarded is indicated in `discardedItems`. When that happens, the JSON-RPC client should try again after an on-going `chainHead_unstable_storage`, `chainHead_unstable_body`, or `chainHead_unstable_call` operation finishes.
+If the list the JSON-RPC server is overloaded, it might refuse to accept new storage requests. In that situation, the JSON-RPC server will discard some or all the `items` passed as parameter. The number of items discarded is indicated in `discardedItems`. When that happens, the JSON-RPC client should try again after an on-going `chainHead_unstable_transaction`, `chainHead_unstable_storage`, `chainHead_unstable_body`, or `chainHead_unstable_call` operation finishes.
 
 The JSON-RPC server must accept at least 16 concurrent operations for any given `chainHead_unstable_follow` subscription. In other words, as long as the JSON-RPC client makes sure that no more than 16 operations are in progress at any given item, it is guaranteed that all of its operations will be accepted by the JSON-RPC server.
-For this purpose, each item requested through `chainHead_unstable_storage` counts as one operation, and each call to `chainHead_unstable_body` and `chainHead_unstable_call` counts as one operation.
+For this purpose, each item requested through `chainHead_unstable_storage` counts as one operation, and each call to `chainHead_unstable_transaction`, `chainHead_unstable_body` and `chainHead_unstable_call` counts as one operation.
 
 ### LimitReached
 

src/api/chainHead_unstable_transaction.md

@@ -0,0 +1,57 @@
+# chainHead_unstable_transaction
+
+**Parameters**:
+
+- `followSubscription`: An opaque string that was returned by `chainHead_unstable_follow`.
+- `transaction`: String containing the hexadecimal-encoded SCALE-encoded transaction to try to include in a block.
+
+**Return value**: A JSON object.
+
+The JSON object returned by this function has one the following formats:
+
+### Started
+
+```
+{
+    "result": "started",
+    "operationId": ...
+}
+```
+
+This return value indicates that the request has successfully started.
+
+`operationId` is a string containing an opaque value representing the operation.
+
+### LimitReached
+
+```
+{
+    "result": "limitReached"
+}
+```
+
+This return value indicates the request couldn't be started because the server is overloaded, or that the `followSubscription` is invalid or stale.
+
+The JSON-RPC client should try again after an on-going `chainHead_unstable_transaction`, `chainHead_unstable_storage`, `chainHead_unstable_body`, or `chainHead_unstable_call` operation finishes.
+
+The JSON-RPC server must accept at least 16 concurrent operations for any given `chainHead_unstable_follow` subscription. In other words, as long as the JSON-RPC client makes sure that no more than 16 operations are in progress at any given item, it is guaranteed that all of its operations will be accepted by the JSON-RPC server.
+For this purpose, each item requested through `chainHead_unstable_transaction` counts as one operation, and each call to `chainHead_unstable_storage`, `chainHead_unstable_body` and `chainHead_unstable_call` counts as one operation.
+
+## Overview
+
+One can build a mental model in order to understand which events can be generated. While a transaction is being watched, it has the following properties:
+
+- `isValidated`: `yes` or `not-yet`. A transaction is initially `not-yet` validated. A `validated` event indicates that the transaction has now been validated. After a certain number of blocks or in case of retractation, a transaction automatically becomes `not-yet` validated and needs to be validated again. No event is generated to indicate that a transaction is no longer validated, however a `validated` event will be generated again when a transaction is validated again.
+
+- `numBroadcastedPeers`: _integer_. A transaction is initially broadcasted to 0 other peers. After a transaction is in the `isValidated: yes`, the number of broadcaster peers can increase. This number never decreases and is never reset to 0, even if a transaction becomes `isValidated: not-yet`. The `broadcasted` event is used to report about updates to this value.
+
+- `blockIncluded`: A transaction is included in a block, or blocks, one of which should eventually become the `finalized` block of the chain.
+
+JSON-RPC servers are allowed to skip sending events as long as it properly keeps the JSON-RPC client up to date with the state of the transaction.
+
+## Possible errors
+
+- If the networking part of the behaviour fails, then a `{"event": "operationInaccessible"}` notification is generated (as explained above).
+- If the `followSubscription` is invalid or stale, then `"result": "limitReached"` is returned (as explained above).
+- 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.