Rename the existing transaction to transactionWatch and add a new…

… different `transaction` namespace (#107)

* Rename `transaction` to `transactionWatch`

* Add a new different `transaction` namespace

* Add text about validation

---------

Co-authored-by: Josep M Sobrepere <[email protected]>

src/SUMMARY.md

@@ -41,5 +41,8 @@
   - [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)
+    - [transaction_unstable_broadcast](api/transaction_unstable_broadcast.md)
+    - [transaction_unstable_stop](api/transaction_unstable_stop.md)
+  - [transactionWatch](api/transactionWatch.md)
+    - [transactionWatch_unstable_submitAndWatch](api/transactionWatch_unstable_submitAndWatch.md)
+    - [transactionWatch_unstable_unwatch](api/transactionWatch_unstable_unwatch.md)

src/api/transaction.md

@@ -1,3 +1,3 @@
 # Introduction
 
-The `transaction` functions allow submitting a transaction for inclusion in the chain.
+The `transaction` functions allow broadcasting a transaction for inclusion in the chain.

src/api/transactionWatch.md

@@ -0,0 +1,3 @@
+# Introduction
+
+The `transactionWatch` functions allow submitting a transaction for inclusion in the chain.

src/api/transaction_unstable_submitAndWatch.md → src/api/transactionWatch_unstable_submitAndWatch.md

@@ -1,14 +1,14 @@
-# transaction_unstable_submitAndWatch
+# transactionWatch_unstable_submitAndWatch
 
 **Parameters**:
 
 - `transaction`: String containing the hexadecimal-encoded SCALE-encoded transaction to try to include in a block.
 
 **Return value**: String representing the subscription.
 
-The string returned by this function is opaque and its meaning can't be interpreted by the JSON-RPC client. It is only meant to be matched with the `subscription` field of events and potentially passed to `transaction_unstable_unwatch`.
+The string returned by this function is opaque and its meaning can't be interpreted by the JSON-RPC client. It is only meant to be matched with the `subscription` field of events and potentially passed to `transactionWatch_unstable_unwatch`.
 
-Once this function has been called, the server will try to propagate this transaction over the peer-to-peer network and/or include it onto the chain even if `transaction_unstable_unwatch` is called or that the JSON-RPC client disconnects. In other words, it is not possible to cancel submitting a transaction.
+Once this function has been called, the server will try to propagate this transaction over the peer-to-peer network and/or include it onto the chain even if `transactionWatch_unstable_unwatch` is called or that the JSON-RPC client disconnects. In other words, it is not possible to cancel submitting a transaction.
 
 ## Notifications format
 
@@ -17,7 +17,7 @@ This function will later generate one or more notifications in the following for
 ```json
 {
     "jsonrpc": "2.0",
-    "method": "transaction_unstable_watchEvent",
+    "method": "transactionWatch_unstable_watchEvent",
     "params": {
         "subscription": "...",
         "result": ...

src/api/transaction_unstable_unwatch.md → src/api/transactionWatch_unstable_unwatch.md

@@ -1,8 +1,8 @@
-# transaction_unstable_unwatch
+# transactionWatch_unstable_unwatch
 
 **Parameters**:
 
-- `subscription`: Opaque string equal to the value returned by `transaction_unstable_submitAndWatch`
+- `subscription`: Opaque string equal to the value returned by `transactionWatch_unstable_submitAndWatch`
 
 **Return value**: *null*
 

src/api/transaction_unstable_broadcast.md

@@ -0,0 +1,16 @@
+# transaction_unstable_broadcast
+
+**Parameters**:
+
+- `transaction`: String containing the hexadecimal-encoded SCALE-encoded transaction to try to include in a block.
+
+**Return value**: String representing the operation, or `null` if the maximum number of broadcasted transactions has been reached.
+
+The string returned by this function is opaque and its meaning can't be interpreted by the JSON-RPC client.
+
+Once this function has been called, the JSON-RPC server will try to propagate this transaction over the peer-to-peer network until `transaction_unstable_stop` is called.
+
+The JSON-RPC server must allow at least 4 transactions being broadcasted at the same time per JSON-RPC client.
+Any attempt to broadcast more than 4 transactions simultaneously might result in `null` being returned.
+
+The JSON-RPC server might check whether the transaction is valid before broadcasting it. If it does so and if the transaction is invalid, the server should silently do nothing and the JSON-RPC client is not informed of the problem. Invalid transactions should still count towards the limit to the number of simultaneously broadcasted transactions.

src/api/transaction_unstable_stop.md

@@ -0,0 +1,13 @@
+# transaction_unstable_stop
+
+**Parameters**:
+
+- `operationId`: Opaque string equal to the value returned by `transaction_unstable_broadcast`
+
+**Return value**: *null*
+
+The node will no longer try to broadcast the transaction over the peer-to-peer network.
+
+## Possible errors
+
+A JSON-RPC error is generated if the `operationId` doesn't correspond to any active `transaction_unstable_broadcast` operation.

src/dos-attacks-resilience.md

@@ -34,7 +34,7 @@ The events coming from the blockchain node can be seen as a stream. This stream
 
 However, sending a message to a JSON-RPC client might take a long time, in case the client has (intentionally or not) little bandwidth. The threads that are receiving the stream of events should never wait for a client to be ready to accept more data before sending a notification to it. If the client isn't ready, then the notification must either be added to a send queue or simply discarded. Because queues must be bounded, it is unavoidable to sometimes have to discard some notifications.
 
-Consequently, all functions that consist in sending notifications must be designed having in mind that the queue of notifications to send out must be bounded to a certain value. For example, the queue of notifications for `transaction_unstable_submitAndWatch` must have a size of 3. When the queue is full, new notifications must overwrite the notifications already in the queue. The design of all JSON-RPC functions should take into account the fact that this shouldn't result in a loss of important information for the JSON-RPC client.
+Consequently, all functions that consist in sending notifications must be designed having in mind that the queue of notifications to send out must be bounded to a certain value. For example, the queue of notifications for `transactionWatch_unstable_submitAndWatch` must have a size of 3. When the queue is full, new notifications must overwrite the notifications already in the queue. The design of all JSON-RPC functions should take into account the fact that this shouldn't result in a loss of important information for the JSON-RPC client.
 
 ## Distinguishing between light and heavy calls