clarify sending concurrent private txns (#903)

* clarify sending concurrent private txns

Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>

* more changes

Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>

* address reviewer feedback

Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>

* reviewer suggestions

Signed-off-by: Alexandra Tran <alexandra.tran@consensys.net>
pull/907/head 21.10.5
Alexandra Tran 3 years ago committed by GitHub
parent a60dc8ad12
commit c1ec894578
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 10
      docs/Concepts/Privacy/Private-Transactions.md
  2. 47
      docs/HowTo/Send-Transactions/Concurrent-Private-Transactions.md
  3. 36
      docs/HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md
  4. 2
      docs/Reference/API-Methods.md

@ -108,7 +108,13 @@ 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.
@ -116,5 +122,5 @@ You can manage private nonces in multiple ways:
!!! 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.

@ -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.

@ -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

@ -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).

Loading…
Cancel
Save