How to configure a Hyperledger Fabric private data collection

A Hyperledger Fabric private data collection lets selected channel organizations keep sensitive chaincode state in their peer side databases while every channel peer stores only the endorsed private-data hashes. Configuring the collection with the chaincode lifecycle is the point where the channel agrees which organizations may persist, read, write, endorse, and eventually purge that private state.

Fabric reads collection membership from a JSON collection definition that is approved and committed with the chaincode definition. Every organization that approves the lifecycle definition must use the same collection file, because a different file changes the definition and leaves that organization out of readiness.

The sample values use the fabric-samples test network, channel mychannel, chaincode name private, and the asset-transfer private-data contract. Replace the MSP IDs, package ID, sequence, peer endpoints, certificate paths, collection names, and sample asset payload before committing a production chaincode definition.

1. Change to the Fabric channel-admin workspace.

   $ cd fabric-samples/test-network

   The channel and chaincode package must already exist. Deploy the chaincode first when the target package is not installed on the endorsing peers.
   Related: How to deploy Hyperledger Fabric chaincode

2. Add the Fabric binaries and sample config directory to the current shell.

   $ export PATH="$PWD/../bin:$PATH"
   $ export FABRIC_CFG_PATH="$PWD/../config"

3. Set the channel, orderer, and peer certificate values.

   $ export CHANNEL_NAME=mychannel
   $ export ORDERER_ADDRESS=localhost:7050
   $ export ORDERER_HOST=orderer.example.com
   $ export ORDERER_CA="$PWD/organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem"
   $ export ORG1_TLS_ROOTCERT="$PWD/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt"
   $ export ORG2_TLS_ROOTCERT="$PWD/organizations/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt"

4. Load the Org1 admin identity.

   $ export CORE_PEER_TLS_ENABLED=true
   $ export CORE_PEER_LOCALMSPID=Org1MSP
   $ export CORE_PEER_MSPCONFIGPATH="$PWD/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp"
   $ export CORE_PEER_TLS_ROOTCERT_FILE="$ORG1_TLS_ROOTCERT"
   $ export CORE_PEER_ADDRESS=localhost:7051

5. Query the installed private-data chaincode package ID from the Org1 peer.

   $ peer lifecycle chaincode queryinstalled
   Installed chaincodes on peer:
   Package ID: private_1.0:2d0ef0bf48c7d7d39e74c4dfbf0ec9b6e902ae4c1b9f375e5d9a7efb1a6fd3c2, Label: private_1.0

   Use the package ID returned by the peer where the package was installed. A package ID copied from another build can make the lifecycle definition point at code that this peer does not have.

6. Save the lifecycle values for the collection-enabled definition.

   $ export CC_NAME=private
   $ export CC_VERSION=1.0
   $ export CC_SEQUENCE=1
   $ export CC_PACKAGE_ID=private_1.0:2d0ef0bf48c7d7d39e74c4dfbf0ec9b6e902ae4c1b9f375e5d9a7efb1a6fd3c2
   $ export COLLECTION_CONFIG=collections_config.json

   Use the next integer for CC_SEQUENCE when adding or changing collections on an already committed chaincode definition. A collection update is a chaincode definition update even when the package stays the same.
   Related: How to upgrade Hyperledger Fabric chaincode

7. Create the collection definition file.

   collections_config.json

   [
     {
       "name": "assetCollection",
       "policy": "OR('Org1MSP.member', 'Org2MSP.member')",
       "requiredPeerCount": 1,
       "maxPeerCount": 1,
       "blockToLive": 1000000,
       "memberOnlyRead": true,
       "memberOnlyWrite": true
     },
     {
       "name": "Org1MSPPrivateCollection",
       "policy": "OR('Org1MSP.member')",
       "requiredPeerCount": 0,
       "maxPeerCount": 1,
       "blockToLive": 3,
       "memberOnlyRead": true,
       "memberOnlyWrite": false,
       "endorsementPolicy": {
         "signaturePolicy": "OR('Org1MSP.member')"
       }
     },
     {
       "name": "Org2MSPPrivateCollection",
       "policy": "OR('Org2MSP.member')",
       "requiredPeerCount": 0,
       "maxPeerCount": 1,
       "blockToLive": 3,
       "memberOnlyRead": true,
       "memberOnlyWrite": false,
       "endorsementPolicy": {
         "signaturePolicy": "OR('Org2MSP.member')"
       }
     }
   ]

   policy controls which organization peers may persist the collection. requiredPeerCount is the minimum dissemination count before endorsement succeeds, maxPeerCount is the extra dissemination target count, and blockToLive controls private database purge timing. Use 0 for private data that should not expire by block height.

8. Validate the collection file as strict JSON.

   $ jq empty "$COLLECTION_CONFIG"

   No output means the file parsed successfully. This check does not prove that MSP IDs, policies, or collection names match the chaincode, so keep the lifecycle readiness check as the runtime gate.
   Tool: JSON Validator

9. Review the collection names before approval.

   $ jq -r '.[].name' "$COLLECTION_CONFIG"
   assetCollection
   Org1MSPPrivateCollection
   Org2MSPPrivateCollection

10. Approve the collection-enabled definition for Org1.

    $ peer lifecycle chaincode approveformyorg \
      -o "$ORDERER_ADDRESS" \
      --ordererTLSHostnameOverride "$ORDERER_HOST" \
      --channelID "$CHANNEL_NAME" \
      --name "$CC_NAME" \
      --version "$CC_VERSION" \
      --package-id "$CC_PACKAGE_ID" \
      --sequence "$CC_SEQUENCE" \
      --collections-config "$COLLECTION_CONFIG" \
      --tls \
      --cafile "$ORDERER_CA"
    2026-06-21 08:11:42.084 UTC [chaincodeCmd] ClientWait -> INFO 001 txid [4bb9c5ef4fdfb81d2f4ad59f5d78dd5df4c65e6024d5c4629e9c3a6c938319ad] committed with status (VALID) at localhost:7051

11. Load the Org2 admin identity.

    $ export CORE_PEER_LOCALMSPID=Org2MSP
    $ export CORE_PEER_MSPCONFIGPATH="$PWD/organizations/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp"
    $ export CORE_PEER_TLS_ROOTCERT_FILE="$ORG2_TLS_ROOTCERT"
    $ export CORE_PEER_ADDRESS=localhost:9051

12. Approve the same collection-enabled definition for Org2.

    $ peer lifecycle chaincode approveformyorg \
      -o "$ORDERER_ADDRESS" \
      --ordererTLSHostnameOverride "$ORDERER_HOST" \
      --channelID "$CHANNEL_NAME" \
      --name "$CC_NAME" \
      --version "$CC_VERSION" \
      --package-id "$CC_PACKAGE_ID" \
      --sequence "$CC_SEQUENCE" \
      --collections-config "$COLLECTION_CONFIG" \
      --tls \
      --cafile "$ORDERER_CA"
    2026-06-21 08:12:16.502 UTC [chaincodeCmd] ClientWait -> INFO 001 txid [e94c218da9e088dc6d2a39cd418dd13e6bd39c43d53b96320f5f9886a724f8f6] committed with status (VALID) at localhost:9051

    Do not edit the collection JSON between organization approvals. A whitespace-only JSON formatting change is safe after parsing, but any value change creates a different lifecycle definition.

13. Check whether the channel is ready to commit the definition with the collection file.

    $ peer lifecycle chaincode checkcommitreadiness \
      --channelID "$CHANNEL_NAME" \
      --name "$CC_NAME" \
      --version "$CC_VERSION" \
      --sequence "$CC_SEQUENCE" \
      --collections-config "$COLLECTION_CONFIG" \
      --tls \
      --cafile "$ORDERER_CA" \
      --output json
    {
            "approvals": {
                    "Org1MSP": true,
                    "Org2MSP": true
            }
    }

    A false approval means that organization has not approved the same name, version, sequence, endorsement policy, and collection configuration.

14. Commit the collection-enabled chaincode definition.

    $ peer lifecycle chaincode commit \
      -o "$ORDERER_ADDRESS" \
      --ordererTLSHostnameOverride "$ORDERER_HOST" \
      --channelID "$CHANNEL_NAME" \
      --name "$CC_NAME" \
      --version "$CC_VERSION" \
      --sequence "$CC_SEQUENCE" \
      --collections-config "$COLLECTION_CONFIG" \
      --tls \
      --cafile "$ORDERER_CA" \
      --peerAddresses localhost:7051 \
      --tlsRootCertFiles "$ORG1_TLS_ROOTCERT" \
      --peerAddresses localhost:9051 \
      --tlsRootCertFiles "$ORG2_TLS_ROOTCERT"
    2026-06-21 08:12:59.771 UTC [chaincodeCmd] ClientWait -> INFO 001 txid [5aab9e413074cf0e77f54f8e93929937144d7e5d018d6c153421e55f7d8575bb] committed with status (VALID) at localhost:7051
    2026-06-21 08:12:59.772 UTC [chaincodeCmd] ClientWait -> INFO 002 txid [5aab9e413074cf0e77f54f8e93929937144d7e5d018d6c153421e55f7d8575bb] committed with status (VALID) at localhost:9051

15. Query the committed chaincode definition.

    $ peer lifecycle chaincode querycommitted --channelID "$CHANNEL_NAME" --name "$CC_NAME"
    Committed chaincode definition for chaincode 'private' on channel 'mychannel':
    Version: 1.0, Sequence: 1, Endorsement Plugin: escc, Validation Plugin: vscc, Approvals: [Org1MSP: true, Org2MSP: true]

16. Invoke the private-data chaincode with a transient asset payload as an authorized Org1 member.

    $ peer chaincode invoke \
      -o "$ORDERER_ADDRESS" \
      --ordererTLSHostnameOverride "$ORDERER_HOST" \
      --tls \
      --cafile "$ORDERER_CA" \
      -C "$CHANNEL_NAME" \
      -n "$CC_NAME" \
      --peerAddresses localhost:7051 \
      --tlsRootCertFiles "$ORG1_TLS_ROOTCERT" \
      -c '{"function":"CreateAsset","Args":[]}' \
      --transient '{"asset_properties":"eyJvYmplY3RUeXBlIjoiYXNzZXQiLCJhc3NldElEIjoiYXNzZXQxIiwiY29sb3IiOiJncmVlbiIsInNpemUiOjIwLCJhcHByYWlzZWRWYWx1ZSI6MTAwfQ=="}'
    2026-06-21 08:13:41.303 UTC [chaincodeCmd] chaincodeInvokeOrQuery -> INFO 001 Chaincode invoke successful. result: status:200

    The transient value is the base64 form of the private asset JSON. Private input belongs in the transient map so the proposal can use it without writing the raw value into the public transaction payload.
    Related: How to invoke Hyperledger Fabric chaincode

17. Query the organization-specific private details as an authorized Org1 member.

    $ peer chaincode query -C "$CHANNEL_NAME" -n "$CC_NAME" -c '{"function":"ReadAssetPrivateDetails","Args":["Org1MSPPrivateCollection","asset1"]}'
    {"assetID":"asset1","appraisedValue":100}

18. Switch to an Org2 member identity.

    $ export CORE_PEER_LOCALMSPID=Org2MSP
    $ export CORE_PEER_MSPCONFIGPATH="$PWD/organizations/peerOrganizations/org2.example.com/users/User1@org2.example.com/msp"
    $ export CORE_PEER_TLS_ROOTCERT_FILE="$ORG2_TLS_ROOTCERT"
    $ export CORE_PEER_ADDRESS=localhost:9051

19. Confirm that Org2 cannot read the Org1-only collection.

    $ peer chaincode query -C "$CHANNEL_NAME" -n "$CC_NAME" -c '{"function":"ReadAssetPrivateDetails","Args":["Org1MSPPrivateCollection","asset1"]}'
    Error: endorsement failure during query. response: status:500 message:"failed to read asset details: GET_STATE failed: tx creator does not have read access permission on privatedata in chaincodeName:private collectionName: Org1MSPPrivateCollection"

    The error is the expected memberOnlyRead boundary for the Org1MSPPrivateCollection. Peers outside the collection can still validate the public private-data hash written to the channel ledger.
    Related: How to query Hyperledger Fabric chaincode