diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 45c5065121be..f28ca59a82e1 100644 --- a/src/SUMMARY.md +++ b/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) diff --git a/src/api/transaction.md b/src/api/transaction.md index 4b7bcbcf5869..7554ceae19b7 100644 --- a/src/api/transaction.md +++ b/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. diff --git a/src/api/transactionWatch.md b/src/api/transactionWatch.md new file mode 100644 index 000000000000..c0578d9d04fd --- /dev/null +++ b/src/api/transactionWatch.md @@ -0,0 +1,3 @@ +# Introduction + +The `transactionWatch` functions allow submitting a transaction for inclusion in the chain. diff --git a/src/api/transaction_unstable_submitAndWatch.md b/src/api/transactionWatch_unstable_submitAndWatch.md similarity index 96% rename from src/api/transaction_unstable_submitAndWatch.md rename to src/api/transactionWatch_unstable_submitAndWatch.md index 2a1d06c87824..333adbfaf57e 100644 --- a/src/api/transaction_unstable_submitAndWatch.md +++ b/src/api/transactionWatch_unstable_submitAndWatch.md @@ -1,4 +1,4 @@ -# transaction_unstable_submitAndWatch +# transactionWatch_unstable_submitAndWatch **Parameters**: @@ -6,9 +6,9 @@ **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": ... diff --git a/src/api/transaction_unstable_unwatch.md b/src/api/transactionWatch_unstable_unwatch.md similarity index 87% rename from src/api/transaction_unstable_unwatch.md rename to src/api/transactionWatch_unstable_unwatch.md index 7ccc1d46f5ce..4c52682cc7bd 100644 --- a/src/api/transaction_unstable_unwatch.md +++ b/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* diff --git a/src/api/transaction_unstable_broadcast.md b/src/api/transaction_unstable_broadcast.md new file mode 100644 index 000000000000..ad407ba76a08 --- /dev/null +++ b/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. diff --git a/src/api/transaction_unstable_stop.md b/src/api/transaction_unstable_stop.md new file mode 100644 index 000000000000..81364b26154c --- /dev/null +++ b/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. diff --git a/src/dos-attacks-resilience.md b/src/dos-attacks-resilience.md index 527d39222b66..e5ec034abe10 100644 --- a/src/dos-attacks-resilience.md +++ b/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