clarify sending concurrent private txns (#903)

* clarify sending concurrent private txns Signed-off-by: Alexandra Tran <[email protected]> * more changes Signed-off-by: Alexandra Tran <[email protected]> * address reviewer feedback Signed-off-by: Alexandra Tran <[email protected]> * reviewer suggestions Signed-off-by: Alexandra Tran <[email protected]>
hyperledger · Dec 16, 2021 · c1ec894 · c1ec894
1 parent a60dc8a
commit c1ec894
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 43 deletions.
diff --git a/docs/Concepts/Privacy/Private-Transactions.md b/docs/Concepts/Privacy/Private-Transactions.md
@@ -108,13 +108,19 @@ You can manage private nonces in multiple ways:
     You must wait until the private transaction's corresponding PMT is included in a block.
 
 * Manage the nonce yourself, by keeping track of and providing the nonce at each call.
-  We recommend this if you're sending many transactions that are independent of each other.
+  We recommend this if you're [sending many transactions that are independent of each other](../../HowTo/Send-Transactions/Concurrent-Private-Transactions.md).
+
+    !!! note
+
+        You can use [`priv_getTransactionCount`](../../Reference/API-Methods.md#priv_gettransactioncount) or
+        [`priv_getEeaTransactionCount`](../../Reference/API-Methods.md#priv_geteeatransactioncount) to get the nonce for
+        an account for the specified privacy group or participants.
 
 * Use [Orchestrate](https://docs.orchestrate.consensys.net/en/stable/) for nonce management.
   We recommend this for enterprise use.
 
 !!! tip
 
     The [web3js-quorum library includes an example](https://github.com/ConsenSys/web3js-quorum/blob/master/example/concurrentPrivateTransactions/concurrentPrivateTransactions.js)
-    of nonce management when sending multiple private transactions.
+    of nonce management when [sending concurrent private transactions](../../HowTo/Send-Transactions/Concurrent-Private-Transactions.md).
     The example calculates the correct nonces for the private transactions and PMTs outside of Besu.
diff --git a/docs/HowTo/Send-Transactions/Concurrent-Private-Transactions.md b/docs/HowTo/Send-Transactions/Concurrent-Private-Transactions.md
@@ -4,26 +4,39 @@ description: Creating and sending concurrent private transactions with Hyperledg
 
 # Sending concurrent private transactions
 
-Private transaction processing involves two transactions, the private transaction and the [privacy marker transaction].
-The private transaction and the [privacy marker transaction] each have their [own nonce].
+Private transaction processing involves two transactions, the private transaction and the
+[privacy marker transaction (PMT)](../../Concepts/Privacy/Private-Transaction-Processing.md).
+The private transaction and the PMT each have their own [nonce](../../Concepts/Privacy/Private-Transactions.md#nonces).
 
 If your private transaction rate requires sending private transactions without waiting for the previous
-private transaction to be mined, you must use [`priv_distributeRawTransaction`](../../Reference/API-Methods.md#priv_distributerawtransaction)
-instead of [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction). When
-using [`priv_distributeRawTransaction`](../../Reference/API-Methods.md#priv_distributerawtransaction)
-you create and send the privacy marker transaction yourself rather than [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction)
-handling the privacy marker transaction.
+private transaction to be mined, using [`eth_getTransactionCount`](../../Reference/API-Methods.md#eth_gettransactioncount)
+and [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction) may result in
+[incorrect nonces](../../Concepts/Privacy/Private-Transactions.md#private-nonce-management).
 
-The [web3js-quorum library](https://github.com/ConsenSys/web3js-quorum/tree/master/example/concurrentPrivateTransactions)
-includes an example of how to send concurrent private transactions.
+In this case, use [`priv_distributeRawTransaction`](Creating-Sending-Private-Transactions.md#priv_distributerawtransaction)
+instead of [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction).
 
-!!! tip
-    [The example](https://github.com/ConsenSys/web3js-quorum/blob/master/example/concurrentPrivateTransactions/concurrentPrivateTransactions.js)
-    uses [off-chain privacy groups](../../Concepts/Privacy/Privacy-Groups.md).
-    Use [`priv_getPrivacyPrecompileAddress`](../../Reference/API-Methods.md#priv_getprivacyprecompileaddress)
-    to get the precompile address to specify in the `to` field when creating the [privacy marker transaction].
+!!! note
 
-<!-- links ---->
+    You can use [`priv_getTransactionCount`](../../Reference/API-Methods.md#priv_gettransactioncount) or
+    [`priv_getEeaTransactionCount`](../../Reference/API-Methods.md#priv_geteeatransactioncount) to get the nonce for
+    an account for the specified privacy group or participants.
 
-[privacy marker transaction]: ../../Concepts/Privacy/Private-Transaction-Processing.md
-[own nonce]: ../../Concepts/Privacy/Private-Transactions.md#nonces
+Send the corresponding PMT using [`eth_sendRawTransaction`](../../Reference/API-Methods.md#eth_sendrawtransaction),
+specifying the public PMT nonce.
+This method allows you to create and send the PMT yourself rather than
+[`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction) handling the PMT.
+
+!!! important
+
+    When using `priv_distributeRawTransaction` to distribute transactions with consecutive nonces for the same account,
+    the corresponding PMTs must use one account with the nonces in the same order as the private transactions.
+    This is to ensure that the private transactions are executed in the correct order.
+
+!!! example
+
+    The [web3js-quorum library](https://github.com/ConsenSys/web3js-quorum/tree/master/example/concurrentPrivateTransactions)
+    includes an example of how to send concurrent private transactions.
+    The example uses [offchain privacy groups](../../Concepts/Privacy/Privacy-Groups.md).
+    Use [`priv_getPrivacyPrecompileAddress`](../../Reference/API-Methods.md#priv_getprivacyprecompileaddress) to get the
+    precompile address to specify in the `to` field when creating the PMT.
diff --git a/docs/HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md b/docs/HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md
@@ -17,7 +17,7 @@ distributed. If any participants are offline when submitting the private transac
 transaction is not attempted and you must resubmit the transaction.
 
 The `gas` and `gasPrice` specified when sending a private transaction are used by the
-[privacy marker transaction] not the private transaction itself.
+[privacy marker transaction (PMT)](../../Concepts/Privacy/Private-Transaction-Processing.md), not the private transaction itself.
 
 !!! note
 
@@ -27,27 +27,23 @@ The `gas` and `gasPrice` specified when sending a private transaction are used b
 ## `eea_sendRawTransaction`
 
 [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction) distributes the
-private transaction to the participating nodes, and signs and submits the
-[privacy marker transaction], as described in
+private transaction to the participating nodes, and signs and submits the PMT, as described in
 [Private transaction processing](../../Concepts/Privacy/Private-Transaction-Processing.md).
 
 !!! note
-    If sending more than one transaction for mining in the same block (that is, you are not waiting
-    for the transaction receipt), you must calculate the private transaction nonce outside Besu.
 
-    Use
-    [`priv_getTransactionCount`](../../Reference/API-Methods.md#priv_gettransactioncount) or
-    [`priv_getEeaTransactionCount`](../../Reference/API-Methods.md#priv_geteeatransactioncount) to get
-    the nonce for an account for the specified privacy group or participants.
+    If [sending concurrent transactions](Concurrent-Private-Transactions.md), you must use
+    [`priv_distributeRawTransaction`](#priv_distributerawtransaction) instead of
+    [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction).
 
 ## `priv_distributeRawTransaction`
 
+Use [`priv_distributeRawTransaction`](../../Reference/API-Methods.md#priv_distributerawtransaction) instead of
+[`eea_sendRawTransaction`](#eea_sendrawtransaction) when sending [concurrent private transactions](Concurrent-Private-Transactions.md).
+
 [`priv_distributeRawTransaction`](../../Reference/API-Methods.md#priv_distributerawtransaction)
-distributes the private transaction to the participating nodes but does not sign and submit the
-[privacy marker transaction]. That is,
-[`priv_distributeRawTransaction`](../../Reference/API-Methods.md#priv_distributerawtransaction)
-performs steps 1 to 5 of
-[Private Transaction Processing](../../Concepts/Privacy/Private-Transaction-Processing.md).
+distributes the private transaction to the participating nodes but does not sign and submit the PMT.
+That is, it performs steps 1 to 5 of [Private Transaction Processing](../../Concepts/Privacy/Private-Transaction-Processing.md).
 
 If using
 [`priv_distributeRawTransaction`](../../Reference/API-Methods.md#priv_distributerawtransaction)
@@ -64,17 +60,12 @@ field of the call.
 
 By using the [public Ethereum transaction](Transactions.md),
 [`eth_sendRawTransaction`](../../Reference/API-Methods.md#eth_sendrawtransaction), you are signing
-and submitting the
-[privacy marker transaction] yourself instead of having it signed by the Besu node, giving you
-greater control over the [privacy marker transaction].
-
-Use [`priv_distributeRawTransaction`](../../Reference/API-Methods.md#priv_distributerawtransaction)
-to send [concurrent private transactions](Concurrent-Private-Transactions.md).
+and submitting the PMT yourself instead of having it signed by the Besu node, giving you greater control over the PMT.
 
 !!! warning
 
-    If the [privacy marker transaction] is not sent after distributing the private transaction, the
-    distributed private transaction is not executed and the private states are not updated.
+    If the PMT is not sent after distributing the private transaction, the distributed private transaction is not
+    executed and the private states are not updated.
 
 !!! example
 
@@ -172,6 +163,5 @@ private transactions to create a contract.
 
 <!-- links ---->
 
-[privacy marker transaction]: ../../Concepts/Privacy/Private-Transaction-Processing.md
 [EEA-compliant private transaction]: ../../Concepts/Privacy/Privacy-Groups.md#enterprise-ethereum-alliance-privacy
 [Besu-extended private transaction]: ../../Concepts/Privacy/Privacy-Groups.md#besu-extended-privacy
diff --git a/docs/Reference/API-Methods.md b/docs/Reference/API-Methods.md
@@ -5957,7 +5957,7 @@ Distributes a signed, RLP encoded
 
 !!! tip
 
-    If you want to sign the Privacy Marker Transaction outside of Besu,
+    If you want to sign the [privacy marker transaction](../Concepts/Privacy/Private-Transaction-Processing.md) outside of Besu,
     use [`priv_distributeRawTransaction`](..//HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md#priv_distributerawtransaction)
     instead of [`eea_sendRawTransaction`](#eea_sendrawtransaction).