From f00a96312f32dd87a6da2e5cf9c36f50e84f4a96 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 26 Feb 2024 15:45:15 +0200 Subject: [PATCH 1/6] transaction: Stabilize `transaction_v1_broadcast` Signed-off-by: Alexandru Vasile --- src/SUMMARY.md | 2 +- src/api/transaction_unstable_stop.md | 4 ++-- ...tion_unstable_broadcast.md => transaction_v1_broadcast.md} | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) rename src/api/{transaction_unstable_broadcast.md => transaction_v1_broadcast.md} (97%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index f28ca59..7af4e70 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -41,7 +41,7 @@ - [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_v1_broadcast](api/transaction_v1_broadcast.md) - [transaction_unstable_stop](api/transaction_unstable_stop.md) - [transactionWatch](api/transactionWatch.md) - [transactionWatch_unstable_submitAndWatch](api/transactionWatch_unstable_submitAndWatch.md) diff --git a/src/api/transaction_unstable_stop.md b/src/api/transaction_unstable_stop.md index 81364b2..c5053d5 100644 --- a/src/api/transaction_unstable_stop.md +++ b/src/api/transaction_unstable_stop.md @@ -2,7 +2,7 @@ **Parameters**: -- `operationId`: Opaque string equal to the value returned by `transaction_unstable_broadcast` +- `operationId`: Opaque string equal to the value returned by `transaction_v1_broadcast` **Return value**: *null* @@ -10,4 +10,4 @@ The node will no longer try to broadcast the transaction over the peer-to-peer n ## Possible errors -A JSON-RPC error is generated if the `operationId` doesn't correspond to any active `transaction_unstable_broadcast` operation. +A JSON-RPC error is generated if the `operationId` doesn't correspond to any active `transaction_v1_broadcast` operation. diff --git a/src/api/transaction_unstable_broadcast.md b/src/api/transaction_v1_broadcast.md similarity index 97% rename from src/api/transaction_unstable_broadcast.md rename to src/api/transaction_v1_broadcast.md index ad407ba..700f1e9 100644 --- a/src/api/transaction_unstable_broadcast.md +++ b/src/api/transaction_v1_broadcast.md @@ -1,4 +1,4 @@ -# transaction_unstable_broadcast +# transaction_v1_broadcast **Parameters**: From a2856b3acfcb64e8733d12b88946a2f86ddb2671 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 26 Feb 2024 15:45:43 +0200 Subject: [PATCH 2/6] transaction: Stabilize `transaction_v1_stop` Signed-off-by: Alexandru Vasile --- src/SUMMARY.md | 2 +- src/api/transaction_v1_broadcast.md | 2 +- .../{transaction_unstable_stop.md => transaction_v1_stop.md} | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) rename src/api/{transaction_unstable_stop.md => transaction_v1_stop.md} (92%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7af4e70..40f90cd 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -42,7 +42,7 @@ - [sudo_sessionKeys_unstable_generate](api/sudo_sessionKeys_unstable_generate.md) - [transaction](api/transaction.md) - [transaction_v1_broadcast](api/transaction_v1_broadcast.md) - - [transaction_unstable_stop](api/transaction_unstable_stop.md) + - [transaction_v1_stop](api/transaction_v1_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_v1_broadcast.md b/src/api/transaction_v1_broadcast.md index 700f1e9..594704b 100644 --- a/src/api/transaction_v1_broadcast.md +++ b/src/api/transaction_v1_broadcast.md @@ -8,7 +8,7 @@ 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. +Once this function has been called, the JSON-RPC server will try to propagate this transaction over the peer-to-peer network until `transaction_v1_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_v1_stop.md similarity index 92% rename from src/api/transaction_unstable_stop.md rename to src/api/transaction_v1_stop.md index c5053d5..50a3f45 100644 --- a/src/api/transaction_unstable_stop.md +++ b/src/api/transaction_v1_stop.md @@ -1,4 +1,4 @@ -# transaction_unstable_stop +# transaction_v1_stop **Parameters**: From e51c5c99600e58dce76d213fe308f96910fd3d76 Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 26 Feb 2024 15:46:52 +0200 Subject: [PATCH 3/6] transactionWatch: Stabilize `transactionWatch_v1_submitAndWatch` Signed-off-by: Alexandru Vasile --- src/SUMMARY.md | 2 +- src/api/transactionWatch_unstable_unwatch.md | 2 +- ...ubmitAndWatch.md => transactionWatch_v1_submitAndWatch.md} | 4 ++-- src/dos-attacks-resilience.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) rename src/api/{transactionWatch_unstable_submitAndWatch.md => transactionWatch_v1_submitAndWatch.md} (98%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 40f90cd..3954db0 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -44,5 +44,5 @@ - [transaction_v1_broadcast](api/transaction_v1_broadcast.md) - [transaction_v1_stop](api/transaction_v1_stop.md) - [transactionWatch](api/transactionWatch.md) - - [transactionWatch_unstable_submitAndWatch](api/transactionWatch_unstable_submitAndWatch.md) + - [transactionWatch_v1_submitAndWatch](api/transactionWatch_v1_submitAndWatch.md) - [transactionWatch_unstable_unwatch](api/transactionWatch_unstable_unwatch.md) diff --git a/src/api/transactionWatch_unstable_unwatch.md b/src/api/transactionWatch_unstable_unwatch.md index 4c52682..39b1e40 100644 --- a/src/api/transactionWatch_unstable_unwatch.md +++ b/src/api/transactionWatch_unstable_unwatch.md @@ -2,7 +2,7 @@ **Parameters**: -- `subscription`: Opaque string equal to the value returned by `transactionWatch_unstable_submitAndWatch` +- `subscription`: Opaque string equal to the value returned by `transactionWatch_v1_submitAndWatch` **Return value**: *null* diff --git a/src/api/transactionWatch_unstable_submitAndWatch.md b/src/api/transactionWatch_v1_submitAndWatch.md similarity index 98% rename from src/api/transactionWatch_unstable_submitAndWatch.md rename to src/api/transactionWatch_v1_submitAndWatch.md index 91522fb..1eaf569 100644 --- a/src/api/transactionWatch_unstable_submitAndWatch.md +++ b/src/api/transactionWatch_v1_submitAndWatch.md @@ -1,4 +1,4 @@ -# transactionWatch_unstable_submitAndWatch +# transactionWatch_v1_submitAndWatch **Parameters**: @@ -17,7 +17,7 @@ This function will later generate one or more notifications in the following for ```json { "jsonrpc": "2.0", - "method": "transactionWatch_unstable_watchEvent", + "method": "transactionWatch_v1_watchEvent", "params": { "subscription": "...", "result": ... diff --git a/src/dos-attacks-resilience.md b/src/dos-attacks-resilience.md index e5ec034..f895012 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 `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. +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_v1_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 10e0d8e5711acb8644d25fdcc91a28588af4f9da Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Mon, 26 Feb 2024 15:47:58 +0200 Subject: [PATCH 4/6] transactionWatch: Stabilize `transactionWatch_v1_unwatch` Signed-off-by: Alexandru Vasile --- src/SUMMARY.md | 2 +- src/api/transactionWatch_v1_submitAndWatch.md | 4 ++-- ...tch_unstable_unwatch.md => transactionWatch_v1_unwatch.md} | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) rename src/api/{transactionWatch_unstable_unwatch.md => transactionWatch_v1_unwatch.md} (94%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3954db0..59cce61 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -45,4 +45,4 @@ - [transaction_v1_stop](api/transaction_v1_stop.md) - [transactionWatch](api/transactionWatch.md) - [transactionWatch_v1_submitAndWatch](api/transactionWatch_v1_submitAndWatch.md) - - [transactionWatch_unstable_unwatch](api/transactionWatch_unstable_unwatch.md) + - [transactionWatch_v1_unwatch](api/transactionWatch_v1_unwatch.md) diff --git a/src/api/transactionWatch_v1_submitAndWatch.md b/src/api/transactionWatch_v1_submitAndWatch.md index 1eaf569..45e137e 100644 --- a/src/api/transactionWatch_v1_submitAndWatch.md +++ b/src/api/transactionWatch_v1_submitAndWatch.md @@ -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 `transactionWatch_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_v1_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 `transactionWatch_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_v1_unwatch` is called or that the JSON-RPC client disconnects. In other words, it is not possible to cancel submitting a transaction. ## Notifications format diff --git a/src/api/transactionWatch_unstable_unwatch.md b/src/api/transactionWatch_v1_unwatch.md similarity index 94% rename from src/api/transactionWatch_unstable_unwatch.md rename to src/api/transactionWatch_v1_unwatch.md index 39b1e40..1cbf7dc 100644 --- a/src/api/transactionWatch_unstable_unwatch.md +++ b/src/api/transactionWatch_v1_unwatch.md @@ -1,4 +1,4 @@ -# transactionWatch_unstable_unwatch +# transactionWatch_v1_unwatch **Parameters**: From 11551fbc3e3e8210c41d0bd690d05f7a33ffe18c Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 6 Mar 2024 19:10:32 +0200 Subject: [PATCH 5/6] Revert "transactionWatch: Stabilize `transactionWatch_v1_unwatch`" This reverts commit 10e0d8e5711acb8644d25fdcc91a28588af4f9da. --- src/SUMMARY.md | 2 +- ...tch_v1_unwatch.md => transactionWatch_unstable_unwatch.md} | 2 +- src/api/transactionWatch_v1_submitAndWatch.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) rename src/api/{transactionWatch_v1_unwatch.md => transactionWatch_unstable_unwatch.md} (94%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 59cce61..3954db0 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -45,4 +45,4 @@ - [transaction_v1_stop](api/transaction_v1_stop.md) - [transactionWatch](api/transactionWatch.md) - [transactionWatch_v1_submitAndWatch](api/transactionWatch_v1_submitAndWatch.md) - - [transactionWatch_v1_unwatch](api/transactionWatch_v1_unwatch.md) + - [transactionWatch_unstable_unwatch](api/transactionWatch_unstable_unwatch.md) diff --git a/src/api/transactionWatch_v1_unwatch.md b/src/api/transactionWatch_unstable_unwatch.md similarity index 94% rename from src/api/transactionWatch_v1_unwatch.md rename to src/api/transactionWatch_unstable_unwatch.md index 1cbf7dc..39b1e40 100644 --- a/src/api/transactionWatch_v1_unwatch.md +++ b/src/api/transactionWatch_unstable_unwatch.md @@ -1,4 +1,4 @@ -# transactionWatch_v1_unwatch +# transactionWatch_unstable_unwatch **Parameters**: diff --git a/src/api/transactionWatch_v1_submitAndWatch.md b/src/api/transactionWatch_v1_submitAndWatch.md index 45e137e..1eaf569 100644 --- a/src/api/transactionWatch_v1_submitAndWatch.md +++ b/src/api/transactionWatch_v1_submitAndWatch.md @@ -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 `transactionWatch_v1_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 `transactionWatch_v1_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 From f83133a6d4fe4b2680df3aa6b92210c53c8527ed Mon Sep 17 00:00:00 2001 From: Alexandru Vasile Date: Wed, 6 Mar 2024 19:10:34 +0200 Subject: [PATCH 6/6] Revert "transactionWatch: Stabilize `transactionWatch_v1_submitAndWatch`" This reverts commit e51c5c99600e58dce76d213fe308f96910fd3d76. --- src/SUMMARY.md | 2 +- ...ndWatch.md => transactionWatch_unstable_submitAndWatch.md} | 4 ++-- src/api/transactionWatch_unstable_unwatch.md | 2 +- src/dos-attacks-resilience.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) rename src/api/{transactionWatch_v1_submitAndWatch.md => transactionWatch_unstable_submitAndWatch.md} (98%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3954db0..40f90cd 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -44,5 +44,5 @@ - [transaction_v1_broadcast](api/transaction_v1_broadcast.md) - [transaction_v1_stop](api/transaction_v1_stop.md) - [transactionWatch](api/transactionWatch.md) - - [transactionWatch_v1_submitAndWatch](api/transactionWatch_v1_submitAndWatch.md) + - [transactionWatch_unstable_submitAndWatch](api/transactionWatch_unstable_submitAndWatch.md) - [transactionWatch_unstable_unwatch](api/transactionWatch_unstable_unwatch.md) diff --git a/src/api/transactionWatch_v1_submitAndWatch.md b/src/api/transactionWatch_unstable_submitAndWatch.md similarity index 98% rename from src/api/transactionWatch_v1_submitAndWatch.md rename to src/api/transactionWatch_unstable_submitAndWatch.md index 1eaf569..91522fb 100644 --- a/src/api/transactionWatch_v1_submitAndWatch.md +++ b/src/api/transactionWatch_unstable_submitAndWatch.md @@ -1,4 +1,4 @@ -# transactionWatch_v1_submitAndWatch +# transactionWatch_unstable_submitAndWatch **Parameters**: @@ -17,7 +17,7 @@ This function will later generate one or more notifications in the following for ```json { "jsonrpc": "2.0", - "method": "transactionWatch_v1_watchEvent", + "method": "transactionWatch_unstable_watchEvent", "params": { "subscription": "...", "result": ... diff --git a/src/api/transactionWatch_unstable_unwatch.md b/src/api/transactionWatch_unstable_unwatch.md index 39b1e40..4c52682 100644 --- a/src/api/transactionWatch_unstable_unwatch.md +++ b/src/api/transactionWatch_unstable_unwatch.md @@ -2,7 +2,7 @@ **Parameters**: -- `subscription`: Opaque string equal to the value returned by `transactionWatch_v1_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 f895012..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 `transactionWatch_v1_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