Skip to content

Commit

Permalink
Mandatory recipients feature - Documentation update (#130)
Browse files Browse the repository at this point in the history 
* Update PrivacyEnhancements.md

* Update PrivacyEnhancements.md

* Update API-Methods.md

* Add files via upload

* Delete PrivacyEnhancements_Contract_Interaction_Matrix.png

* Add files via upload

* Delete PrivacyEnhancements_Contract_Interaction_Matrix.png

* Add files via upload

* Update ContractExtension.md

* Update ContractExtension.md

* Update PrivacyEnhancements.md

* fix lint build

* minor fix

Co-authored-by: Nam Truong <nam.p.truong@outlook.com>
  • Loading branch information
@Krish1979 @namtruong
Krish1979 and namtruong authored Sep 16, 2021
1 parent 1eefe89 commit da35d00
Show file tree
Hide file tree
Showing 4 changed files with 71 additions and 29 deletions.
10 changes: 7 additions & 3 deletions docs/Concepts/Privacy/ContractExtension.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,19 @@ time of extension is shared. This means that there is no history of the contract
to view it will not yield any result, as the new recipient was not party at that time. This
also means that events are not shared either, as the transactions are not shared and no state transitions are calculated.

!!! note

Mandatory recipients are defined at contract creation time and cannnot be amended/extended, however such contracts could still be extended to other nodes in the network.

## Flow

The following diagram describes the flow of contract state extension.
![contract state extension diagram](../../images/ContractStateExtension.png)

For the purpose of the flow description, "**all participants**" in the below description refers to:

- For *"**Standard Private**"* type of contracts, it will be node initiating the extension and the node to which the contract is being extended
- For *"**Party Protection**"* & *"**State Validation**"* type of contracts, it will include all the nodes which are current participant of the contract and the new node to which it is being extended
- For **Standard Private** type of contracts, it will be node initiating the extension and the node to which the contract is being extended
- For **Party Protection**, **Mandatory Party Protection** & **State Validation** type of contracts, it will include all the nodes which are current participant of the contract and the new node to which it is being extended

In this example, an existing private contract deployed between Nodes A and B is being extended to Nodes C from Node A.

Expand Down Expand Up @@ -60,7 +64,7 @@ In this example, an existing private contract deployed between Nodes A and B is
propagated across all nodes

1. Node A & B monitors for state share event
- **5a** - Upon noticing the state share event as a part of block processing, node A & B update the privacy metadata for the contract being extended. *This step will be executed only for party protection or private state validation type of contracts.*
- **5a** - Upon noticing the state share event as a part of block processing, node A & B update the privacy metadata for the contract being extended. *This step will be executed only for party protection, mandatory party protection or private state validation type of contracts.*

1. Node C monitors for state share event
- **6a** - Upon noticing the state share event as a part of block processing, node C fetches the
Expand Down
62 changes: 40 additions & 22 deletions docs/Concepts/Privacy/PrivacyEnhancements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,13 @@ description: Privacy Enhancements feature prevents nodes from modifying contract

# Privacy enhancements

From GoQuorum v20.10.0, two privacy enhancements are included to prevent state divergence:
Three different flavours of privacy enhancements as detailed below:

* Counter party protection
* Counter-party protection
* Mandatory party protection
* Private state validation

## Counter party protection
## Counter Party protection

Counter party protection prevents non-participants sending a transaction to a
private contract. For example, a private contract is deployed between node 1 and 2. Without counter
Expand All @@ -23,7 +24,13 @@ Use the counter party protection instead of access controls on private contract
against other network participants from updating the state. Counter party protection prevents non-participants
from interacting with the private contract without additional access controls.

## Private state validation
## Mandatory Party protection

Inherits all features of Counter party protection (including state divergence) but allows for one or more recipients to be defined as "mandatory" for the contract and to be included in all subsequent transactions to the contract so as to have full private state while normal recipients may only have partial state of the contract.

Use the mandatory party protection if you need "governing" or "central" nodes defined to have full private state view at contract level for all or selective contracts deployed in the network.

## Private State Validation

Private state validation prevents state divergence by ensuring that any private transaction
for the contract is always sent to all participants. For example, a private contract is deployed between node 1 and 2.
Expand Down Expand Up @@ -52,21 +59,25 @@ transaction for the contract.
A new parameter `PrivacyFlag` has been added to all GoQuorum
[`send` API methods](../../Reference/API-Methods.md#privacy-methods), being passed from the client to enable the privacy
enhancements feature.
This flag is an unsigned integer set to 1 for PP and 3 for PSV transactions.
This flag is an unsigned integer set to 1 for PP, 2 for MPP and 3 for PSV transactions.
If the flag is missing or zero, the transaction is assumed to be a "non-privacy enhanced" SP transaction.

### MandatoryFor[]

A new parameter `mandatoryFor` has been added to all GoQuorum [`send` API methods](../../Reference/API-Methods.md#privacy-methods), being passed from the client to define a set of recipients as mandatory for a contract. Different contracts can have different mandatory recipients defined based on use case needs.

### Privacy Metadata and Privacy Metadata Trie

Privacy Metadata is a new structure introduced in GoQuorum. It is stored in the GoQuorum DB in the privacy
metadata trie (which is linked to the private state via root hash mappings). The Privacy Metadata contains
the ACOTH and privacyFlag.
the ACOTH and privacyFlag(and mandatory recipients only for MPP contracts).

Privacy Metadata Trie is a parallel trie that stores the privacy metadata (and whatever extra data we
may need) for the private contracts and is linked to the private state by root hash mappings. The records
in the trie are keyed by the contract address (similarly to how the contract/accounts data is stored
in the state trie).

Each contract(account) that is created as the result of a PP or PSV transaction would have such a structure
Each contract(account) that is created as the result of a PP,MPP or PSV transaction would have such a structure
attached to the privacy metadata trie as it is essential in performing checks on future transactions
affecting those contracts.

Expand All @@ -84,21 +95,21 @@ and attach them to the proposed transaction.
Depending on the complexity of the contracts and the throughput of the network it may happen that the
state at simulation time may differ from the chain state at the time the proposed transaction is minted.
If the state at minting time is sufficiently altered to determine different contract interactions the
corresponding PP/PSV transactions would be marked as failed on all the participants.
Furthermore, since state divergence is expected in PP contracts, it is possible (depending on contract design)
for PP transactions to fail on some of the participants.
corresponding PP/MPP & PSV transactions would be marked as failed on all the participants.
Furthermore, since state divergence is expected in PP/MPP contracts, it is possible (depending on contract design)
for PP/MPP transactions to fail on some of the participants.

Concurrency may also present a problem for PSV contracts. The execution hash calculation is based on
the chain state at simulation time. Submitting multiple transactions to the same PSV contract from multiple
nodes concurrently is likely to result in most of the transactions failing.

Considering the above we expect users to choose PP and PSV contracts/transactions **only** when th
Considering the above we expect users to choose private enhanced contracts/transactions **only** when the
enhanced privacy is necessary (and the extra privacy benefits outweigh the potential shortfalls).

### Contract/transaction interactions

No interactions are allowed between the different types of private contracts/transactions. The only type
of allowed interaction is for private contracts (SP/PP/PSV) to read from public contracts.
of allowed interaction is for private contracts (SP/PP/MPP & PSV) to read from public contracts.

![Contract interaction matrix](../../images/PrivacyEnhancements_Contract_Interaction_Matrix.png)

Expand Down Expand Up @@ -130,7 +141,7 @@ GoQuorum node reports an appropriate error message in the console suggesting use

If a node wants to upgrade it's Tessera to privacy enhancements release (or further) to avail other
features and fixes but not ready to upgrade GoQuorum, it can do so by not enabling `enablePrivacyEnhancements`
in Tessera config. This will allow the node to reject PP and PSV transactions from other nodes until
in Tessera config. This will allow the node to reject PP/MPP and PSV transactions from other nodes until
the node is ready to support privacy enhanced contracts/transactions.

## Backward compatability
Expand All @@ -140,7 +151,7 @@ the node is ready to support privacy enhanced contracts/transactions.
An upgraded GoQuorum node can coexist on a network where other nodes are running on lower version of
GoQuorum and thus supports node by node upgrade. But it cannot support privacy enhanced contracts until
all interested nodes are upgraded and privacy is enabled.
If an upgraded but privacy not "enabled" node receives a PSV or PP transaction the node would log a
If an upgraded but privacy not "enabled" node receives a PP/MPP or PSV transaction the node would log a
`BAD BLOCK` error with “Privacy enhanced transaction received while privacy enhancements are disabled.
Please check your node configuration.” error message. If the consensus algorithm is Raft, the node would stop.
For Istanbul, the node would keep trying to append the problematic block and reprint the above errors and
Expand All @@ -149,8 +160,8 @@ it won't catch up with rest of nodes until restarted and reinitialized with the
### Tessera

On any given node, Tessera can be upgraded to privacy enhanced release at anytime.
Take care when you enable `enablePrivacyEnhancements` flag in Tessera config as it will accept PSV and
PP transactions and can cause the node to crash if GoQuorum node is not privacy enabled.
Take care when you enable `enablePrivacyEnhancements` flag in Tessera config as it will accept PP/MPP and
PSV transactions and can cause the node to crash if GoQuorum node is not privacy enabled.
The upgraded node can continue to communicate on Tessera nodes running on previous versions using SP transactions.
API versioning <!-- TODO: add hyperlink later --> (that will be introduced along with privacy enhancements)
enables the upgraded node to determine if the receiving node supports privacy enhancements and fail the transaction if not.
Expand All @@ -159,14 +170,19 @@ enables the upgraded node to determine if the receiving node supports privacy en

Refer [here](PrivateTransactionLifecycle.md) to refresh about Tessera P2P communication.

### Party protection changes
### Party Protection changes

To prevent a non-party node from interacting with PP contracts new transactions must be submitted with
`ACOTHs` and `PrivacyFlag` from GoQuorum to Tessera. The Tessera node would then generate proofs
(a hash using new transaction ciphertext, original transaction ciphertext and original transaction master key)
for each ACOTH and include a) `PrivacyFlag`, b) ACOTHs and c) ACOTH proofs (secure hashes) in the transaction
payload shared between Tessera nodes.

### Mandatory Party Protection changes

To define a recipient as mandatory for a contract, new transactions must be submitted with
`ACOTHs`, `PrivacyFlag` and `mandatoryFor` from GoQuorum to Tessera. The Tessera node would include a) `PrivacyFlag`, b) ACOTHs , c) ACOTH proofs (secure hashes) and mandatory recipients in the transaction payload shared between Tessera nodes.

### Private State Validation changes

Besides the ACOTH, a PSV transaction has an execution hash (Merkle root) calculated from all the affected
Expand All @@ -183,24 +199,25 @@ In this example we walk through the flow of a private transaction on a "privacy

1. User pushing a private transaction from Node A private for Node B

* The transaction payload will include the `PrivacyFlag` with value `1` for PP and `3` for PSV contract
* The transaction payload will include the `PrivacyFlag` with value `1` for PP, `2` for MPP and `3` for PSV contract (& also `mandatoryFor` for MPP contracts)

1. Node A GoQuorum reading the `PrivacyFlag` runs an EVM transaction simulation to gather all the affected
contracts and the ACOTH(s) associated to contract accounts. For PSV transactions, it also calculates
an execution hash (Merkle root) from all the affected contracts resulting from the transaction simulation.

1. Node A GoQuorum pushes the transaction payload, `PrivacyFlag`, ACOTHs (& the Merkle root for PSV) to Node A Tessera.
1. Node A GoQuorum pushes the transaction payload, `PrivacyFlag`, ACOTHs (& `mandatoryFor` for MPP or the Merkle root for PSV) to Node A Tessera.

1. Node A Tessera generates proofs (secure hashes) for the ACOTHs and use them to validate that the
originating party has access to all relevant transactions.
In addition for PSV it would also verify the participants list against the list in each of the ACOTH
In addition for MPP it verifies mandatory recipients against the list in each of ACOTH(the list should at the minimum include all mandatory recipients against each ACOTH).
For PSV it would verify the participants list against the list in each of the ACOTH
transactions (as in PSV transactions the recipient list is shared across all nodes party to the transaction).
If the list doesn't match it will return failure on `/send` to Node A GoQuorum.

1. Node A Tessera pushes to Node B Tessera the encrypted payload, ACOTH <-> proofs (secure hash) mappings
(for PSV transaction it will also push the `privateFor` list and Merkle root).
(for MPP it will also push `mandatoryFor` and for PSV transaction it will also push the `privateFor` list and Merkle root).

1. Node B Tessera computes and compares proofs (secure hash) from Node A Tessera (for PSV it also verifies
1. Node B Tessera computes and compares proofs (secure hash) from Node A Tessera (for MPP it also verifies mandatory recipients & for PSV it also verifies
participants list of ACOTHs against the `privateFor` list).

1. Node B Tessera returns a SUCCESS response to Node A Tessera - even if the compute and compare mismatched
Expand All @@ -224,6 +241,7 @@ the transaction receipt accordingly to mark transaction execution completion.
proofs (secure hash) for each ACOTH.**

*[PP]: Counter Party Protection
*[MPP]: Mandatory Party Protection
*[PSV]: Private State Validation
*[ACOTH]: Affected Contract's Original Transaction's encrypted payload Hash
*[SP]: Standard Private
Expand Down
28 changes: 24 additions & 4 deletions docs/Reference/API-Methods.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2488,7 +2488,8 @@ sent to participants with this API, and the resulting hash set as the PMT's `dat
* object - private data to send, with the following fields:
* `privateFor`: `List<String>` - an array of the recipients' base64-encoded public keys.
* `privateFrom`: `String` - (optional) the sending party’s base64-encoded public key to use (Privacy Manager default if not provided).
* `privacyFlag`: `Number` - (optional) `0` for SP (default if not provided), `1` for PP, `3` for PSV
* `privacyFlag`: `Number` - (optional) `0` for SP (default if not provided), `1` for PP, `2` for MPP & `3` for PSV
* `mandatoryFor`: `List<String>` - an array of the recipients' base64-encoded public keys.

#### Returns

Expand Down Expand Up @@ -2628,7 +2629,9 @@ Queries the privacy metadata for the specified contract account address.

* `creationTxHash`: *data* - affected contract's original transaction's encrypted payload hash

* `privacyFlag`: *number* - unsigned integer with 1 for counterparty protection and 3 for private state validation contracts
* `privacyFlag`: *number* - unsigned integer with 1 for counterparty protection, 2 for mandatory party protection and 3 for private state validation contracts

* `mandatoryFor`: *string* - an array of the recipients' base64-encoded public keys.

!!! example

Expand All @@ -2646,7 +2649,8 @@ Queries the privacy metadata for the specified contract account address.
"id":15,
"result": {
"creationTxHash":"0xf67c748bbed92110cb66510d413af99144b4434fa325771b6323f7f00c35192d2f861076f68061ed2d324f614edd2f0159Ba5ee2408bb42402a876c4b295598b7",
"privacyFlag":3
"mandatoryFor":["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]
"privacyFlag":2
}
}
```
Expand All @@ -2662,7 +2666,8 @@ Queries the privacy metadata for the specified contract account address.
```json
{
"creationTxHash":"0xf67c748bbed92110cb66510d413af99144b4434fa325771b6323f7f00c35192d2f861076f68061ed2d324f614edd2f0159Ba5ee2408bb42402a876c4b295598b7",
"privacyFlag":3
"mandatoryFor":["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="],
"privacyFlag":2
}
```

Expand Down Expand Up @@ -2886,8 +2891,13 @@ the contract address after the transaction is mined.

* 1 - for counterparty protection

* 2 - for mandatory party protection

* 3 - for private state validation

* `mandatoryFor`: *array* of *strings* - when sending a private transaction, an array of the recipients' base64-encoded
public keys

* `callback`: *function* - (optional) callback function; if you pass a callback, the HTTP request is made asynchronous.

#### Returns
Expand Down Expand Up @@ -2975,8 +2985,13 @@ If the transaction is a contract creation, use

* 1 - for counterparty protection

* 2 - for mandatory party protection

* 3 - for private state validation

* `mandatoryFor`: *array* of *strings* - (optional) when sending a private transaction, an array of the recipients'
base64-encoded public keys

* `callback`: *function* - (optional) callback function; if you pass a callback, the HTTP request is made asynchronous.

!!! note
Expand Down Expand Up @@ -3066,8 +3081,13 @@ the contract address after the transaction is mined.

* 1 - for counterparty protection

* 2 - for mandatory party protection

* 3 - for private state validation

* `mandatoryFor`: *array* of *strings* - (optional) when sending a private transaction, an array of the recipients'
base64-encoded public keys

* `callbackUrl`: *string* - (optional) URL to perform a POST request to post the result of submitting the transaction

!!! note
Expand Down
Binary file modified docs/images/PrivacyEnhancements_Contract_Interaction_Matrix.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit da35d00

Please sign in to comment.