doc multi-tenancy with flexible privacy groups (#911)

* doc multi-tenancy with flexible privacy groups

Signed-off-by: Alexandra Tran <[email protected]>

* add newline

Signed-off-by: Alexandra Tran <[email protected]>

* integrate feedback

Signed-off-by: Alexandra Tran <[email protected]>

* minor edit

Signed-off-by: Alexandra Tran <[email protected]>

* may > might

Signed-off-by: Alexandra Tran <[email protected]>

docs/Concepts/Privacy/Flexible-PrivacyGroups.md

@@ -10,8 +10,8 @@ description: Flexible privacy groups
     Read our [Orion to Tessera migration guide](https://docs.orion.consensys.net/en/latest/Tutorials/Migrating-from-Orion-to-Tessera/)
     and about all the [new Tessera features](https://consensys.net/blog/quorum/tessera-the-privacy-manager-of-choice-for-consensys-quorum-networks).
 
-Flexible privacy groups use smart contracts to store and maintain the group membership. You can add
-and remove members to and from flexible privacy groups.
+Flexible [privacy groups](Privacy-Groups.md) use smart contracts to store and maintain the group membership.
+You can [add and remove members to and from flexible privacy groups](../../HowTo/Use-Privacy/Use-FlexiblePrivacy.md).
 
 !!! tip
 
@@ -20,23 +20,23 @@ and remove members to and from flexible privacy groups.
 
 !!! important
 
-    Flexible privacy groups are an early access feature. Do not use in production networks.
+    Flexible privacy groups are an early access feature. Don't use in production networks.
 
     The flexible privacy group interfaces might change between releases. There might not be an
     upgrade path from flexible privacy groups created using v1.5 or earlier to enable use of flexible privacy
     group functionality in future versions.
 
-    It's not recommended to create flexible privacy groups in a chain with existing
+    We don't recommended creating flexible privacy groups in a chain with existing
     [offchain privacy groups](Privacy-Groups.md).
 
 ## Group management contracts
 
-The privacy group management contract bytecode is hard-coded into Hyperledger Besu and when you
+The privacy group management contract bytecode is hard-coded into Besu and when you
 create a privacy group, the contract bytecode is part of the genesis state of the privacy group.
 
 !!! caution
 
-    All members of a flexible privacy group must be using the same version of Hyperledger Besu. If
+    All members of a flexible privacy group must be using the same version of Besu. If
     using different versions, the private state within the privacy group may become inconsistent.
 
 In the default implementation of the group management contract, the signer of the private transaction
@@ -60,4 +60,43 @@ group ID and passes the ID to Besu when creating a privacy group.
     participants. If you create a privacy group with an existing privacy group ID, the existing
     privacy group is overwritten.
 
-    To ensure unique privacy group IDs, using 256-bit SecureRandom is recommended.
+    To ensure unique privacy group IDs, we recommend using 256-bit SecureRandom.
+
+## Multi-tenancy
+
+When using [multi-tenancy](Multi-Tenancy.md) with flexible privacy groups, each user provides a JSON Web Token (JWT)
+which allows Besu to check that the user has access to functionality and data associated with a privacy group.
+
+Using multi-tenancy with flexible privacy groups is more complex than with [offchain privacy groups](Privacy-Groups.md)
+because users may be added and removed from flexible privacy groups.
+When a user is added to a privacy group, they get access to all existing data in the privacy group.
+After being removed from a privacy group, a user retains access to already existing data in the privacy group, up to the
+block containing the [privacy marker transaction (PMT)](Private-Transaction-Processing.md) that removed them (the
+removal block).
+A removed user doesn't have access to data in the privacy group that happens after they were removed.
+
+In particular, when multi-tenancy is enabled and a user requests access to a privacy group they were once a member of
+but later removed from, Besu allows the user access to the following functionality and data associated with the privacy
+group:
+
+- Private transactions using `priv_getTransaction` and private transaction receipts using
+  [`priv_getTransactionReceipt`](../../Reference/API-Methods.md#priv_gettransactionreceipt) from blocks up to (and
+  including) the removal block.
+
+    !!! note
+
+        A removed group member may have access to some private transactions after the removal PMT in the same block.
+
+- Using [`priv_call`](../../Reference/API-Methods.md#priv_call) on blocks up to (and including) the removal block.
+
+- Private logs using [`priv_getLogs`](../../Reference/API-Methods.md#priv_getlogs) for blocks up to (and including) the
+  removal block.
+  When the `toBlock` is greater than the removal block, `priv_getLogs` still returns logs up to the removal block.
+
+    !!! note
+
+        When a user is removed from a privacy group, any [log filters](../../HowTo/Interact/Filters#filters-for-private-contracts)
+        they've created are also removed and can't be accessed.
+        A user can only create and access filters for a privacy group they are currently a member of.
+
+All other [`PRIV` API methods](../../Reference/API-Methods.md#priv-methods) fail for the removed group member.

docs/Concepts/Privacy/Multi-Tenancy.md

@@ -32,10 +32,10 @@ is a _tenant_, and the operator is the _owner_ of the Besu and Tessera node.
     including other Besu nodes, might be able to access tenant data.
 
     To secure access, you can [configure TLS between Besu and Tessera](../TLS.md) with the
-    [`whitelist`](https://docs.orion.consensys.net/en/latest/Tutorials/TLS/#clientconnectiontlsservertrust)
+    [`WHITELIST`](https://docs.tessera.consensys.net/en/stable/HowTo/Configure/TLS/#whitelist)
     trust mode.
 
-Multi-tenancy validates that tenants have permission to use the specified HTTP or Websocket
+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.
 Private data is isolated and each tenant uses a JSON Web Token (JWT) for authentication.
 

docs/Concepts/Privacy/Privacy-Groups.md

@@ -98,3 +98,8 @@ transactions sent to the privacy group ID.
     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.
+
+## Multi-tenancy
+
+When using [multi-tenancy](Multi-Tenancy.md) with privacy groups, each user provides a JSON Web Token (JWT) which
+allows Besu to check that the user has access to functionality and data associated with a privacy group.

docs/HowTo/Use-Privacy/Use-FlexiblePrivacy.md

@@ -19,14 +19,15 @@ membership of [flexible privacy groups](../../Concepts/Privacy/Flexible-PrivacyG
     privacy groups are also known as onchain privacy groups.
 
 !!! important
+
     [Flexible privacy groups](../../Concepts/Privacy/Flexible-PrivacyGroups.md) are an early access
-    feature. Do not use in production networks.
+    feature. Don't use in production networks.
 
-    The flexible privacy group interfaces may change between releases. There may not be an
+    The flexible privacy group interfaces may change between releases. There might not be an
     upgrade path from flexible privacy groups created using v1.5 or earlier to enable use of flexible privacy
     group functionality in future versions.
 
-    We do not recommend creating flexible privacy groups in a chain with existing
+    We don't recommend creating flexible privacy groups in a chain with existing
     [offchain privacy groups](../../Concepts/Privacy/Privacy-Groups.md).
 
 ## Enabling flexible privacy groups
@@ -70,5 +71,5 @@ client library.
 !!! note
 
     When adding a member, Besu pushes all existing group transactions to the new member and
-    processes them. If there are a large number of existing transactions, adding the member might
+    processes them. If there are a large number of existing transactions, adding the member may
     take some time.