From 4e61760952c35a316d52f4dbae78bdcf4e8e414c Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Wed, 9 Aug 2023 16:55:43 +0200 Subject: [PATCH 1/3] Rename `transaction` to `transactionWatch` --- src/SUMMARY.md | 6 +++--- src/api/transaction.md | 3 --- src/api/transactionWatch.md | 3 +++ ...tch.md => transactionWatch_unstable_submitAndWatch.md} | 8 ++++---- ...le_unwatch.md => transactionWatch_unstable_unwatch.md} | 4 ++-- src/dos-attacks-resilience.md | 2 +- 6 files changed, 13 insertions(+), 13 deletions(-) delete mode 100644 src/api/transaction.md create mode 100644 src/api/transactionWatch.md rename src/api/{transaction_unstable_submitAndWatch.md => transactionWatch_unstable_submitAndWatch.md} (96%) rename src/api/{transaction_unstable_unwatch.md => transactionWatch_unstable_unwatch.md} (87%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 5f4652e..0154792 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -39,6 +39,6 @@ - [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) + - [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 deleted file mode 100644 index 4b7bcbc..0000000 --- a/src/api/transaction.md +++ /dev/null @@ -1,3 +0,0 @@ -# Introduction - -The `transaction` functions allow submitting a transaction for inclusion in the chain. diff --git a/src/api/transactionWatch.md b/src/api/transactionWatch.md new file mode 100644 index 0000000..c0578d9 --- /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 bfd57b5..9d2b83a 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 7ccc1d4..4c52682 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/dos-attacks-resilience.md b/src/dos-attacks-resilience.md index 527d392..e5ec034 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 From a094cf0ad9b382b85059ea0292c043aaa0edcf57 Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Wed, 9 Aug 2023 17:01:06 +0200 Subject: [PATCH 2/3] Add a new different `transaction` namespace --- src/SUMMARY.md | 3 +++ src/api/transaction.md | 3 +++ src/api/transaction_unstable_broadcast.md | 14 ++++++++++++++ src/api/transaction_unstable_stop.md | 13 +++++++++++++ 4 files changed, 33 insertions(+) create mode 100644 src/api/transaction.md create mode 100644 src/api/transaction_unstable_broadcast.md create mode 100644 src/api/transaction_unstable_stop.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0154792..710b82a 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -39,6 +39,9 @@ - [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_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 new file mode 100644 index 0000000..7554cea --- /dev/null +++ b/src/api/transaction.md @@ -0,0 +1,3 @@ +# Introduction + +The `transaction` functions allow broadcasting a transaction for inclusion in the chain. diff --git a/src/api/transaction_unstable_broadcast.md b/src/api/transaction_unstable_broadcast.md new file mode 100644 index 0000000..d6a6d17 --- /dev/null +++ b/src/api/transaction_unstable_broadcast.md @@ -0,0 +1,14 @@ +# 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. diff --git a/src/api/transaction_unstable_stop.md b/src/api/transaction_unstable_stop.md new file mode 100644 index 0000000..81364b2 --- /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. From 79728c826cd153ffc4495d2310f05033c513edb2 Mon Sep 17 00:00:00 2001 From: Pierre Krieger Date: Thu, 10 Aug 2023 09:31:29 +0200 Subject: [PATCH 3/3] Add text about validation --- src/api/transaction_unstable_broadcast.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/api/transaction_unstable_broadcast.md b/src/api/transaction_unstable_broadcast.md index d6a6d17..ad407ba 100644 --- a/src/api/transaction_unstable_broadcast.md +++ b/src/api/transaction_unstable_broadcast.md @@ -12,3 +12,5 @@ Once this function has been called, the JSON-RPC server will try to propagate th 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.