Chaincode API for Private Data Collections

The ChaincodeStub interface provides a number of functions to work with private data collections. The functions are very similar to their regular analogues.

ChaincodeStubInterface defines the following functions for interaction with private data...

• putPrivateData

  putPrivateData(collection: string, key: string, value: Uint8Array): Promise<void>

  putPrivateData puts the (key, value) pair into the transient data store. The corresponding hash of private data is appended to the transaction’s write set. It does not affect collection until a transaction is validated and successfully committed.

• getPrivateData

  getPrivateData(collection: string, key: string): Promise<Uint8Array>

  getPrivateData returns the value associated with the key from collection. The function does not read data from a private write set.

• deletePrivateData

  deletePrivateData(collection: string, key: string): Promise<void>

  deletePrivateData records a specified key to be deleted from collection. key and the value associated with it will be deleted from collection when a transaction is validated and successfully committed.

  🚩Please keep in mind that though you can obtain the history for a key stored in a channel using the getHistoryForKey method, even after the key has been deleted from the channel, such capability does not exist for private data keys.

• getPrivateDataHash

  getPrivateDataHash(collection: string, key: string): Promise<Uint8Array>

  getPrivateDataHash returns the hash of the value associated with a specified key.

• getTransient

  getTransient(): Map<string, Uint8Array>

  getTransient returns the transient field from the transaction proposal. The field is a map containing data that can be used to implement some form of application-level confidentiality. The contents of this field are supposed to always be omitted from a transaction and excluded from a ledger.

• setPrivateDataValidationParameter

  setPrivateDataValidationParameter(collection: string, key: string, ep: Uint8Array): Promise<void>

  setPrivateDataValidationParameter sets the key-level endorsement policy for the private data specified by key. We have discussed the key-level endorsement policy in the Chaincode Specifics chapter.

• getPrivateDataValidationParameter

  getPrivateDataValidationParameter(collection: string, key: string): Promise<Uint8Array>

  getPrivateDataValidationParameter retrieves the key-level endorsement policy for the private data specified by key.

• getPrivateDataByRange

  getPrivateDataByRange(collection: string, startKey: string, endKey: string): Promise<StateQueryIterator>

  getPrivateDataByRange returns a range iterator over a set of keys in a given private collection. The iterator can be used to iterate over all keys between startKey (inclusive) and endKey (exclusive). The keys are returned in a lexical order. getPrivateDataByRange allows startKey and endKey to be empty strings that imply unbounded range queries on a start or an end.

  The query is re-executed during the validation phase to ensure the result set has not changed since transaction endorsement.

• getPrivateDataByPartialCompositeKey

  getPrivateDataByPartialCompositeKey(collection: string, objectType: string, attributes: string[]): Promise<StateQueryIterator>

  getPrivateDataByPartialCompositeKey returns an iterator which can be used to iterate over all composite keys whose prefix matches a given partial composite key.

  The query is re-executed during the validation phase to ensure the result set has not changed since transaction endorsement.

• getPrivateDataQueryResult

  getPrivateDataQueryResult(collection: string, query: string): Promise<StateQueryIterator>

  getPrivateDataQueryResult performs a rich query against a given private data collection. The function returns an iterator which can be used to iterate over all the keys in the query result set.

  The query is not re-executed during the validation phase. In other words, other committed transactions may have added, updated, or removed keys which would impact the result set. Because rich queries are not re-executed, such changes in the result set would not be detected during the validation/commit time. Applications susceptible to this should not use getPrivateDataQueryResult as part of the transactions that update a ledger and should limit the use to read-only chaincode operations.

🚩If a chaincode both queries and updates private data in a single invocation, a proposal request will return an error, as query results cannot be validated on the peers that do not have access to private data or that are missing private data that they have access to. If your application can tolerate result set changes between chaincode execution and validation/commit time, then you could call one chaincode function to perform the query and then call a second chaincode function to make the updates. Note that calls to getPrivateData to retrieve individual keys can be made in the same transaction as putPrivateData calls, since all peers can validate key reads based on a hashed key version.