Add purge private data documentation

Add docs for the v2.5 purge private data functionality.

Signed-off-by: David Enyeart <[email protected]>

docs/source/private-data-arch.rst

@@ -380,10 +380,31 @@ Considerations when using private data
 Private data purging
 ~~~~~~~~~~~~~~~~~~~~
 
-Private data in explicitly defined private data collections can be periodically purged from peers.
+Private data can be purged from peers so that it is not available for chaincode queries, not available in block events, and not available for other peers requesting the private data.
+
+**Purging private data in chaincode**
+
+Private data can be deleted from state just like regular state data so that it is not available for query in chaincode for future transactions.
+However, when private data is simply deleted from state, the history of the private data remains in the peer's private database so that it can be returned in block events and returned to other peers that are catching up to the current block height.
+If you need to completely remove the private data from all peers that have access to it, use the chaincode API ``PurgePrivateData`` instead of the ``DelPrivateData`` API.
+
+The ``PurgePrivateData`` chaincode API is available starting in Fabric v2.5. To ensure that all peers are at v2.5 or later, the application capability ``V2_5`` or higher must be set in the channel's configuration before using the feature.
+
+Private data is purged from a peer's private database at the time of block commit.
+For more efficiency, the purge requests can be processed at certain block intervals based on the ``ledger.pvtdataStore.purgeInterval`` setting in the peer ``core.yaml`` configuration, with a default of purging every 100 blocks.
+To process purge requests every block set ``ledger.pvtdataStore.purgeInterval`` to ``1``.
+Regardless of the ``purgeInterval`` setting, the associated private data state will be deleted from the state database upon every block commit so that it is not available for subsequent transaction endorsements or queries.
+Similarly, any purged private data will not be returned in block events or returned to other peers requesting it.
+Only the historical values in the private database will remain until the next ``purgeInterval``.
+
+**Purging private data automatically**
+
+Private data in explicitly defined private data collections can be periodically purged from peers if it has not been modified for a configurable number of blocks.
 For more details, see the ``blockToLive`` collection definition property above.
 
-Additionally, recall that prior to commit, peers store private data in a local
+**Purging uncommitted private data**
+
+Recall that prior to commit, peers store private data in a local
 transient data store. This data automatically gets purged when the transaction
 commits.  But if a transaction was never submitted to the channel and
 therefore never committed, the private data would remain in each peer’s

docs/source/private-data/private-data.md

@@ -118,16 +118,16 @@ For details on transaction flows that don't use private data refer to our
 documentation on [transaction flow](../txflow.html).
 
 1. The client application submits a proposal request to invoke a chaincode
-   function (reading or writing private data) to a target peer, which will manage 
+   function (reading or writing private data) to a target peer, which will manage
    the transaction submission on behalf of the client. The client application can
    [specify which organizations](../gateway.html#targeting-specific-endorsement-peers)
-   should endorse the proposal request, or it can delegate the 
+   should endorse the proposal request, or it can delegate the
    [endorser selection logic](../gateway.html#how-the-gateway-endorses-your-transaction-proposal)
-   to the gateway service in the target peer.  In the latter case, the gateway will 
-   attempt to select a set of endorsing peers which are part of authorized organizations 
-   of the collection(s) affected by the chaincode. The private data, or data used to 
+   to the gateway service in the target peer.  In the latter case, the gateway will
+   attempt to select a set of endorsing peers which are part of authorized organizations
+   of the collection(s) affected by the chaincode. The private data, or data used to
    generate private data in chaincode, is sent in a `transient` field in the proposal.
-   
+
 2. The endorsing peers simulate the transaction and store the private data in
    a `transient data store` (a temporary storage local to the peer). They
    distribute the private data, based on the collection policy, to authorized peers
@@ -372,14 +372,22 @@ For very sensitive data, even the parties sharing the private data might want
 on their peers, leaving behind a hash of the data on the blockchain
 to serve as immutable evidence of the private data.
 
-In some of these cases, the private data only needs to exist on the peer's private
+In some of these cases, the private data only needs to exist in the peer's private
 database until it can be replicated into a database external to the peer's
 blockchain. The data might also only need to exist on the peers until a chaincode business
 process is done with it (trade settled, contract fulfilled, etc).
 
-To support these use cases, private data can be purged if it has not been modified
-for a configurable number of blocks. Purged private data cannot be queried from chaincode,
-and is not available to other requesting peers.
+To support these use cases, private data can be purged so that it is not available for chaincode queries, not available in block events, and not available for other peers requesting the private data.
+
+### Purging private data in chaincode
+
+Private data can be deleted from state just like regular state data so that it is not available for query in chaincode for future transactions.
+However, when private data is simply deleted from state, the history of the private data remains in the peer's private database so that it can be returned in block events and returned to other peers that are catching up to the current block height.
+If you need to completely remove the private data from all peers that have access to it, use the chaincode API `PurgePrivateData` instead of the `DelPrivateData` API.
+
+### Purging private data automatically
+
+Private data collections can be configured to purge private data automatically if it has not been modified for a configurable number of blocks.
 
 ## How a private data collection is defined