diff --git a/docs/Concepts/Privacy/Multi-Tenancy.md b/docs/Concepts/Privacy/Multi-Tenancy.md index 9ea7b07e68f..6337e114ed7 100644 --- a/docs/Concepts/Privacy/Multi-Tenancy.md +++ b/docs/Concepts/Privacy/Multi-Tenancy.md @@ -1,32 +1,37 @@ +--- description: Multi-tenancy - +--- # Multi-tenancy -By default, each participant in a privacy network uses its own Besu and Orion -node. +By default, each participant in a privacy network uses its own Besu and Orion node. -Multi-tenancy allows multiple participants to use the same Besu and -Orion node. Each participant is called a Tenant, and the Operator is the -owner of the Besu and Orion node. +Multi-tenancy allows multiple participants to use the same Besu and Orion node. Each participant is +a _tenant_, and the operator is the _owner_ of the Besu and Orion node. !!! important - The Operator is responsible for [configuring multi-tenancy](../../Tutorials/Privacy/Configuring-Multi-Tenancy.md), and has + + The operator is responsible for + [configuring multi-tenancy](../../Tutorials/Privacy/Configuring-Multi-Tenancy.md), and has access to all tenant data. - + ![Multi-tenancy](../../images/Multi-tenancy.png) !!! important - Ensure the multi-tenant Orion node client API is configured to allow access only by the multi-tenant Besu node. Access to your data is secured through Besu using multi-tenancy mode. - If not configured to allow access only by the multi-tenant Besu node, other - Orion clients including other Besu nodes may be able to access tenant data. + Ensure the multi-tenant Orion node client API is configured to allow access only by the + multi-tenant Besu node. Access to your data is secured through Besu using multi-tenancy mode. + + If not configured to allow access only by the multi-tenant Besu node, other Orion clients, + including other Besu nodes, might be able to access tenant data. - You can [configure TLS between Besu and Orion](../TLS.md) with the [`whitelist`](https://docs.orion.pegasys.tech/en/latest/Tutorials/TLS/#clientconnectiontlsservertrust) trust mode to secure access. + To secure access, you can [configure TLS between Besu and Orion](../TLS.md) with the + [`whitelist`](https://docs.orion.pegasys.tech/en/latest/Tutorials/TLS/#clientconnectiontlsservertrust) + trust mode. -Multi-tenancy validates that tenants are permitted to use the specified HTTP or -Websocket JSON-RPC requests, and the tenant has access to the requested privacy -data. Private data is segregated, and each tenant uses a JWT token for -authentication. +Multi-tenancy validates that tenants have permission to use the specified HTTP or Websocket +JSON-RPC requests, and the tenant has access to the requested privacy data. There is segregation of +private data, and each tenant uses a JWT token for authentication. -The JWT token can be created [externally or internally](../../HowTo/Interact/APIs/Authentication.md). \ No newline at end of file +You can create the JWT token either +[externally or internally](../../HowTo/Interact/APIs/Authentication.md). \ No newline at end of file diff --git a/docs/Concepts/Privacy/Privacy-Groups.md b/docs/Concepts/Privacy/Privacy-Groups.md index 166875b21e6..b800d5556c3 100644 --- a/docs/Concepts/Privacy/Privacy-Groups.md +++ b/docs/Concepts/Privacy/Privacy-Groups.md @@ -1,76 +1,88 @@ -description: Privacy - +--- +description: Privacy groups +--- -# Privacy Groups +# Privacy groups -A privacy group is a group of nodes identified by a unique privacy group ID by Orion. Each private transaction is -stored in Orion with the privacy group ID. +A privacy group is a group of nodes identified by a unique privacy group ID by Orion. Each private +transaction is stored in Orion with the privacy group ID. -The Besu nodes maintain the public world state for the blockchain and a private state for each privacy group. -The private states contain data that is not shared in the globally replicated world state. +The Besu nodes maintain the public world state for the blockchain and a private state for each +privacy group. The private states contain data that is not shared in the globally replicated world +state. -## Privacy Types +## Privacy types -Besu implements two types of privacy: +Besu implements two types of privacy: -* EEA-compliant privacy - private transactions include `privateFor` as the recipient. -* Besu-extended privacy - private transactions include `privacyGroupId` as the recipient. +* Enterprise Ethereum Alliance (EEA) privacy, where private transactions include `privateFor` as +the recipient. +* Besu-extended privacy, where private transactions include `privacyGroupId` as the recipient. -Both privacy types create privacy groups and store private transactions with their privacy group in Orion. +Both privacy types create privacy groups and store private transactions with their privacy group in +Orion. ![Privacy Groups](../../images/PrivacyGroups.png) !!! note - The Orion nodes are not shown above for clarity only. To send private transactions, - each Besu node must have an associated Orion node. -### Access between States + For clarity, the Orion nodes are not shown in the previous diagram. To send private + transactions, each Besu node must have an associated Orion node. + +### Access between states A contract in a privacy group: * Can read or write to a contract in the same privacy group. -* Can read from the public state including public contracts. -* Cannot access contracts from a different privacy group. +* Can read from the public state including public contracts. +* Cannot access contracts from a different privacy group. A public contract cannot access a private contract. -### EEA-compliant Privacy +### Enterprise Ethereum Alliance privacy + +In the privacy implementation complying with the +[EEA Client Specification](https://entethalliance.org/technical-documents/) the group of nodes +specified by `privateFrom` and `privateFor` form a privacy group with a unique privacy group ID +provided by Orion. -In our privacy implementation complying with the [EEA Client Specification](https://entethalliance.org/technical-documents/) -the group of nodes specified by `privateFrom`and `privateFor` form a privacy group and are given a unique -privacy group ID by Orion. +!!! example -!!! example - The diagram above illustrates two privacy groups enabling: + The previous diagram illustrates two privacy groups enabling: - * A, B, and C to send transactions that are private from D - * A, C, and D to send transactions that are private from B + * A, B, and C to send transactions that are private from D. + * A, C, and D to send transactions that are private from B. - Using EEA-compliant privacy, to send private transactions between A, B, and C, A initialises a contract in a private transaction with - B and C specified as the `privateFor` and A specified as the `privateFrom`. Initialising the contract - creates a privacy group consisting of A, B, and C. For the ABC private state to remain consistent, - A, B, and C must be included on transactions (as either `privateFrom` or `privateFor`) even if they are - between two of the three parties. + Using EEA-compliant privacy, to send private transactions between A, B, and C, A initializes a + contract in a private transaction with B and C specified as the `privateFor` and A specified as + the `privateFrom`. Initializing the contract creates a privacy group consisting of A, B, and C. + For the ABC private state to remain consistent, A, B, and C must be included on transactions + (as either `privateFrom` or `privateFor`) even if they are between only two of the three + parties. - To send private transactions between A, C, and D, C initialises a different contract in a private transaction with - A and D specified as the `privateFor` and C specified as the `privateFrom`. Initialising the contract - creates a privacy group consisting of A, C, and D. For the ACD private state to remain consistent, - A, C, and D must be included on transactions (as either `privateFrom` or `privateFor`) even if they are - between two of the three parties. + To send private transactions between A, C, and D, C initializes a different contract in a + private transaction with A and D specified as the `privateFor` and C specified as the + `privateFrom`. Initializing the contract creates a privacy group consisting of A, C, and D. + For the ACD private state to remain consistent, A, C, and D must be included on transactions + (as either `privateFrom` or `privateFor`) even if they are between only two of the three + parties. -### Besu-extended Privacy +### Besu-extended privacy -In our extended privacy implementation, a privacy group is created using [`priv_createPrivacyGroup`](../../Reference/API-Methods.md#priv_createprivacygroup) -and private transactions sent to the privacy group ID. +The Besu-extended privacy implementation creates a privacy group using +[`priv_createPrivacyGroup`](../../Reference/API-Methods.md#priv_createprivacygroup) with private +transactions sent to the privacy group ID. + +!!! example -!!! example - Using the same privacy groups as above. + Using the same privacy groups as in the previous example. - Using Besu-extended privacy, to send private transactions between A, B, and C, A creates a privacy - group consisting of A, B, and C. The privacy group ID is specified when sending private transactions and - A, B, and C are recipients of all private transactions sent to the privacy group. + Using Besu-extended privacy, to send private transactions between A, B, and C, A creates a + privacy group consisting of A, B, and C. The privacy group ID is specified when sending private + transactions and A, B, and C are recipients of all private transactions sent to the privacy + group. - To send private transactions between A, C, and D, A creates a privacy group consisting of A, C, and D. - The privacy group ID of this group is specified when sending private transactions with A, C, and D - as recipients. \ No newline at end of file + To send private transactions between A, C, and D, A creates a privacy group consisting of A, C, + and D. The privacy group ID of this group is specified when sending private transactions with A, + C, and D as recipients. \ No newline at end of file diff --git a/docs/Concepts/Privacy/Privacy-Overview.md b/docs/Concepts/Privacy/Privacy-Overview.md index 4013f939939..53a91d8165b 100644 --- a/docs/Concepts/Privacy/Privacy-Overview.md +++ b/docs/Concepts/Privacy/Privacy-Overview.md @@ -1,35 +1,44 @@ +--- description: Privacy - +--- # Privacy -Privacy in Besu refers to the ability to keep transactions private between the involved participants. -Other participants cannot access the transaction content or list of participants. +In Besu, privacy refers to the ability to keep transactions private between the involved +participants. Other participants cannot access the transaction content or list of participants. !!! important - For production systems requiring private transactions: - - * We recommend using a network with a consensus mechanism supporting transaction finality. For example, - [IBFT 2.0](../../HowTo/Configure/Consensus-Protocols/IBFT.md). - * Orion must be [highly available and run in a separate instance to Besu](../../HowTo/Use-Privacy/Run-Orion-With-Besu.md). - -!!! important + + For production systems requiring private transactions: + + * It is recommended you use a network with a consensus mechanism supporting transaction + finality, such as [IBFT 2.0](../../HowTo/Configure/Consensus-Protocols/IBFT.md). + * Orion must be [highly available and run in a separate instance to Besu]. + Using private transactions with [pruning](../Pruning.md) is not supported. -## Private Transaction Manager +## Private transaction manager -Besu uses a Private Transaction Manager to implement privacy. For example, [Orion](http://docs.orion.pegasys.tech). -Each Besu node that sends or receives private transactions requires an associated Orion node. +Besu uses a private transaction manager, [Orion](http://docs.orion.pegasys.tech), to implement +privacy. Each Besu node sending or receiving private transactions requires an associated Orion +node. ![Orion Nodes](../../images/OrionNodes.png) -Private transactions are passed from the Besu node to the associated Orion node. The Orion node -encrypts and directly distributes (that is, point to point) the private transaction to Orion nodes -participating in the transaction. +Private transactions pass from the Besu node to the associated Orion node. The Orion node +encrypts and directly distributes (that is, point-to-point) the private transaction to the Orion +nodes participating in the transaction. + +By default, each participant in a privacy network uses its own Besu and Orion node. +[Multi-tenancy](Multi-Tenancy.md) allows multiple participants to use the same Besu and Orion node. By default, each participant in a privacy network uses its own Besu and Orion node. [Multi-tenancy](Multi-Tenancy.md) allows multiple participants to use the same Besu and Orion node. !!! tip - Private Transaction Managers are also known as Enclaves. + + Private Transaction Managers are also refered to as Enclaves. + + +[highly available and run in a separate instance to Besu]: ../../HowTo/Use-Privacy/Run-Orion-With-Besu.md \ No newline at end of file diff --git a/docs/Concepts/Privacy/Private-Transaction-Processing.md b/docs/Concepts/Privacy/Private-Transaction-Processing.md index 62716e155df..c14fffdb79f 100644 --- a/docs/Concepts/Privacy/Private-Transaction-Processing.md +++ b/docs/Concepts/Privacy/Private-Transaction-Processing.md @@ -1,69 +1,84 @@ -description: Private Transaction Processing - +--- +description: Private transaction processing +--- -# Processing Private Transactions +# Processing private transactions Processing private transactions involves the following: -- **Precompiled Contract**: Smart contract compiled from the source language to EVM bytecode and stored by an -Ethereum node for later execution. +- **Precompiled Contract**: A smart contract compiled from the source language to EVM bytecode and +stored by an Ethereum node for later execution. -- **Privacy Marker Transaction**: Public Ethereum transaction with a payload of the enclave key. The enclave key -is a pointer to the private transaction in Orion. The `to` attribute of the Privacy Marker Transaction is the address -of the privacy precompiled contract. +- **Privacy Marker Transaction**: A public Ethereum transaction with a payload of the enclave key. +The enclave key is a pointer to the private transaction in Orion. The `to` attribute of the Privacy +Marker Transaction is the address of the privacy precompiled contract. - The Privacy Marker Transaction is [signed with a random key or the key specified on the command line](../../HowTo/Use-Privacy/Sign-Privacy-Marker-Transactions.md). + The Privacy Marker Transaction is + [signed with a random key or the key specified on the command line]. -Private transactions are processed as illustrated and described below. +Private transaction processing is illustrated and described in the following diagram. ![Processing Private Transctions](../../images/PrivateTransactionProcessing.png) -1. A private transaction is submitted using [eea_sendRawTransaction](../../Reference/API-Methods.md#eea_sendrawtransaction). -The signed transaction includes transaction attributes that are specific to private transactions: +1. Submit a private transaction using +[eea_sendRawTransaction](../../Reference/API-Methods.md#eea_sendrawtransaction). The signed +transaction includes transaction attributes specific to private transactions, including: * `privateFor` or `privacyGroupId` specifies the list of recipients * `privateFrom` specifies the sender - * `restriction` specifies the transaction is of type [_restricted_](../Privacy/Privacy-Overview.md#private-transactions) - + * `restriction` specifies the transaction is of type + [_restricted_](../Privacy/Privacy-Overview.md#private-transactions). + 1. The JSON-RPC endpoint passes the private transaction to the Private Transaction Handler. -1. The Private Transaction Handler sends the private transaction to Orion. +1. The Private Transaction Handler sends the private transaction to Orion. -1. Orion distributes the private transaction directly (that is, point-to-point) to the Orion nodes specified -in `privateFor` or belonging to the privacy group identified by `privacyGroupId`. All recipient Orion nodes store the transaction. -The stored transaction is associated with the transaction hash and privacy group ID. +1. Orion distributes the private transaction directly (that is, point-to-point) to the Orion nodes +specified in `privateFor` or belonging to the privacy group identified by `privacyGroupId`. All +recipient Orion nodes store the transaction. Orion associates the stored transaction with the +transaction hash and privacy group ID. 1. Orion returns the transaction hash to the Private Transaction Handler. - -1. The Private Transaction Handler creates a Privacy Marker Transaction for the private -transaction. The Privacy Marker Transaction is propagated using devP2P in the same way as a public Ethereum transaction. - !!! tip - If you want to sign the Privacy Marker Transaction outside of Besu, use [`priv_distributeRawTransaction`](../../HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md#priv_distributerawtransaction) - instead of [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction). +1. The Private Transaction Handler creates a Privacy Marker Transaction for the private +transaction. The Private Transaction Handler propagates the Privacy Marker Transaction using devP2P +in the same way as a public Ethereum transaction. + + !!! tip + If you want to sign the Privacy Marker Transaction outside of Besu, use + [`priv_distributeRawTransaction`](../../HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md#priv_distributerawtransaction) + instead of + [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction). -1. The Privacy Marker Transaction is mined into a block and distributed to all Ethereum nodes in the network. +1. Besu mines the Privacy Marker Transaction into a block and the Privacy Marker Transaction is +distributed to all Ethereum nodes in the network. -1. The Mainnet Transaction Processor processes the Privacy Marker Transaction in the same way as any other public transaction. -On nodes that contain the privacy precompile contract specified in the `to` attribute of the Privacy Marker Transaction, -the Privacy Marker Transaction is passed to the privacy precompile contract. +1. The Mainnet Transaction Processor processes the Privacy Marker Transaction in the same way as +any other public transaction. On nodes containing the privacy precompile contract specified in the +`to` attribute of the Privacy Marker Transaction, the Mainnet Transaction Processor passes the +Privacy Marker Transaction to the privacy precompile contract. !!! note - Nodes receiving the Privacy Marker Transaction that do not contain the privacy precompile contract - specified in the Privacy Marker Transaction ignore the Privacy Marker Transaction. + Nodes receiving the Privacy Marker Transaction that do not contain the privacy precompile + contract specified in the Privacy Marker Transaction ignore the Privacy Marker Transaction. -1. The privacy precompile contract queries Orion for the private transaction and privacy group ID using the -transaction hash. +1. The privacy precompile contract queries Orion for the private transaction and privacy group ID +using the transaction hash. -1. The privacy precompile contract passes the private transaction to the Private Transaction Processor. -The privacy group ID specifies the private world state to use. +1. The privacy precompile contract passes the private transaction to the Private Transaction +Processor. The privacy group ID specifies the private world state to use. -1. The Private Transaction Processor executes the transaction. The Private Transaction Processor can read and write to -the private world state, and read from the public world state. +1. The Private Transaction Processor executes the transaction. The Private Transaction Processor +can read and write to the private world state, and read from the public world state. !!! important - For production systems requiring private transactions: - * We recommend using a network with a consensus mechanism supporting transaction finality. For example, - [IBFT 2.0](../../HowTo/Configure/Consensus-Protocols/IBFT.md). - * Orion must be [highly available and run in a separate instance to Besu](../../HowTo/Use-Privacy/Run-Orion-With-Besu.md). + For production systems requiring private transactions: + + * It is recommended you use a network with a consensus mechanism supporting transaction + finality, such as [IBFT 2.0](../../HowTo/Configure/Consensus-Protocols/IBFT.md). + * Orion must be [highly available and run in a separate instance to Besu]. + + +[signed with a random key or the key specified on the command line]: ../../HowTo/Use-Privacy/Sign-Privacy-Marker-Transactions.md +[highly available and run in a separate instance to Besu]: ../../HowTo/Use-Privacy/Run-Orion-With-Besu.md diff --git a/docs/Concepts/Privacy/Private-Transactions.md b/docs/Concepts/Privacy/Private-Transactions.md index 25b592a8701..d7005fe8e1b 100644 --- a/docs/Concepts/Privacy/Private-Transactions.md +++ b/docs/Concepts/Privacy/Private-Transactions.md @@ -1,35 +1,36 @@ -description: Private Transaction Overview - +--- +description: Private transaction overview +--- -# Private Transactions +# Private transactions -Private transactions have additional attributes to public Ethereum transactions: +Private transactions have additional attributes to public Ethereum transactions: -* `privateFrom` - Orion public key of transaction sender +* `privateFrom` - The Orion public key of the transaction sender +* `privateFor` - The Orion public keys of the transaction recipients, or +* `privacyGroupId` - [The privacy group to receive the transaction](Privacy-Groups.md) +* `restriction` - Whether the private transaction is `restricted` or `unrestricted`. In: + - `restricted` private transactions, only the nodes participating in the transaction receive + and store the payload of the private transaction. + - `unrestricted` private transactions, all nodes in the network receive the payload of the + private transaction, but only the nodes participating in the transaction can read the + transaction. -* `privateFor` - Orion public keys of transaction recipients or `privacyGroupId` - [Privacy group to receive transaction](Privacy-Groups.md) - -* `restriction` - Private transactions are `restricted` or `unrestricted`: - - - In `restricted` private transactions the payload of the private transaction is received and stored only by - the nodes participating in the transaction. - - - In `unrestricted` private transactions the payload of the private transaction is transmitted to all nodes - in the network but is readable only by nodes participating in the transaction. - - !!! important + !!! important Besu implements `restricted` private transactions only. -For details on creating and sending private transactions, refer to our [How To documentation](../../HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md). +For more information about creating and sending private transactions, see the +[How To documentation](../../HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md). -## Besu and Orion Keys +## Besu and Orion keys -Besu and Orion nodes both have public/private key pairs identifying them. The private transaction -submitted from the Besu node to the Orion node is signed with the Besu node private key. The +Besu and Orion nodes both have public/private key pairs identifying them. A Besu node sending a +private transaction to an Orion node signs the transaction with the Besu node private key. The `privateFrom` and `privateFor` attributes specified in the RLP-encoded transaction string for -[`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction) are the public keys -of the Orion nodes sending and receiving the transaction. +[`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction) are the public +keys of the Orion nodes sending and receiving the transaction. + +!!! important -!!! important - The mapping of Besu node addresses to Orion node public keys is off-chain. That is, the - sender of a private transaction must know the Orion node public key of the recipient. \ No newline at end of file + The mapping of Besu node addresses to Orion node public keys is off-chain. That is, the sender + of a private transaction must know the Orion node public key of the recipient. \ No newline at end of file diff --git a/docs/HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md b/docs/HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md index 24a3c8eb5eb..be9271fadff 100644 --- a/docs/HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md +++ b/docs/HowTo/Send-Transactions/Creating-Sending-Private-Transactions.md @@ -93,7 +93,7 @@ the nonce for an account for the specified privacy group. ## EEA-compliant or Besu-extended Privacy -To create an [EEA-compliant private transaction](../../Concepts/Privacy/Privacy-Groups.md#eea-compliant-privacy), +To create an [EEA-compliant private transaction](../../Concepts/Privacy/Privacy-Groups.md#enterprise-ethereum-alliance-privacy), specify `privateFor` when creating the signed transaction passed as an input parameter to [`eea_sendRawTransaction`](../../Reference/API-Methods.md#eea_sendrawtransaction). diff --git a/docs/Reference/API-Methods.md b/docs/Reference/API-Methods.md index 8fccdc9e19b..7bd33c98503 100644 --- a/docs/Reference/API-Methods.md +++ b/docs/Reference/API-Methods.md @@ -4242,7 +4242,7 @@ Distributes a signed, RLP encoded [private transaction](../HowTo/Send-Transactio ### priv_getEeaTransactionCount -Returns the private transaction count for the specified account and [group of sender and recipients](../Concepts/Privacy/Privacy-Groups.md#eea-compliant-privacy). +Returns the private transaction count for the specified account and [group of sender and recipients](../Concepts/Privacy/Privacy-Groups.md#enterprise-ethereum-alliance-privacy). !!! important If sending more than 1 transaction to be mined in the same block (that is, you're not waiting for @@ -4424,7 +4424,7 @@ are A and B, a privacy group containing A, B, and C is not returned. **Returns** -Privacy groups containing only the specified members. Privacy groups are [EEA-compliant](../Concepts/Privacy/Privacy-Groups.md#eea-compliant-privacy) +Privacy groups containing only the specified members. Privacy groups are [EEA-compliant](../Concepts/Privacy/Privacy-Groups.md#enterprise-ethereum-alliance-privacy) or [Besu-extended](../Concepts/Privacy/Privacy-Groups.md#besu-extended-privacy) with types: * `LEGACY` for EEA-compliant groups diff --git a/docs/Reference/web3js-eea-Methods.md b/docs/Reference/web3js-eea-Methods.md index 6d3c372c49c..6f265c7ec67 100644 --- a/docs/Reference/web3js-eea-Methods.md +++ b/docs/Reference/web3js-eea-Methods.md @@ -100,7 +100,7 @@ Finds privacy groups containing only the specified members. ## generatePrivacyGroup -Generates the privacy group ID for [EEA privacy](../Concepts/Privacy/Privacy-Groups.md#eea-compliant-privacy). +Generates the privacy group ID for [EEA privacy](../Concepts/Privacy/Privacy-Groups.md#enterprise-ethereum-alliance-privacy). The privacy group ID is the RLP-encoded `privateFor` and `privateFrom` keys. **Parameters**