Hyperledger Fabric private data purging

When Hyperledger Fabric private data collections fit a shared channel

Use private data collections when several organizations share one Fabric channel, but some data, such as pricing terms or personal records, must reach only a defined subset of members. Private data collections keep the payload with the authorized peers, while the channel carries only hashes of that data as evidence that a transaction took place and what its content was. Every member of the channel still sees the same ordered transactions and the same hashes, which is what makes the arrangement useful for shared governance without exposing every record to every member.

This pattern fits a specific situation. A consortium of banks, for example, may need a shared record of trade settlement steps, yet the negotiated price in each trade should be visible only to the two parties involved. The shared channel handles ordering, endorsement and the common view of the ledger, and the collection defines which organizations hold the sensitive values in their own peer state databases. If every organization on the channel is entitled to see all of the data, a plain channel with ordinary state is simpler and easier to operate, and a collection adds configuration without adding protection.

The Fabric private data documentation describes the core behavior. Data in a collection is distributed to peers of the authorized organizations through a gossip-based process, and it is not written into the block that the ordering service delivers to everyone. Collections can also be configured to purge data automatically when it has not been modified for a configurable number of blocks, and a chaincode can explicitly purge private data. Purged data is no longer available to chaincode queries, block events or peers that request it. Before you design around these features, confirm the exact collection configuration keys, the minimum endorsement and member settings, and the upgrade behavior in the Fabric version your network runs, using the current private data documentation for that release.

Decide early whether the collection membership model matches your governance. Membership is set per collection, so a change in who may hold a payload usually means a new collection definition and an agreed process for moving existing data. Ask your consortium governance group to confirm which organizations must be members, who approves changes to a collection definition, and how a departing member's copies are handled. These answers determine whether one collection, several overlapping collections or a separate channel is the right boundary.

Plan for retention and removal before the first transaction. Automatic purging suits data that has a natural expiry, such as a quote that is superseded after a set period, but it also removes data that someone may still need for an audit or dispute. Explicit purges are the mechanism for complete removal, yet they are only useful if the chaincode and the operating procedure call them consistently. Document which records are purged, when, and by which process, and confirm with your legal and compliance owners that the retention rules match your obligations before the design is locked.

Collection settings and purge options, and when each fits

This table compares the collection and purge settings a Fabric designer decides before go-live, with the fit and trade-off for each. Read each row as a choice you make for a specific data type, since settings are usually combined per collection. Confirm exact parameter names and defaults in the Fabric private data documentation for your release before you write the collection configuration.

Setting or option	When it fits	Trade-off to weigh
Collection membership	Data that only a defined subset of organizations should hold, such as a bilateral price or contract term	Every member peer stores the data, so membership changes and onboarding a new member affect who can later hold the records
Endorsement and access policy for the collection	Writes or reads that need a different approval rule than the channel default, such as requiring a specific member to endorse	A stricter policy can block transactions when the required peers are offline, so test endorsement availability under failure
Automatic purge after a block count	Transient or time-limited sensitive data, where the business no longer needs the value after a set period of inactivity	Purged data is gone from chaincode queries and other peers, so any later audit or dispute needs data held elsewhere first
No purge for records that must be kept	Records that must remain available for the full retention period set by your regulator or contract	Data keeps growing on every authorized peer, which increases storage, backup and catch-up load over time
Explicit PurgePrivateData calls	Removal triggered by a business event, such as a contract closing or a consent withdrawal	The application must issue the call on every relevant peer, and the purge must be handled in chaincode logic and tested
Deleting with DelPrivateData only	Ordinary updates where the record is superseded and older versions can remain in history	Deleted private data can still be returned in block events and to peers catching up, so it does not remove data from all authorized peers
Hashes on the shared channel ledger	Keeping proof that a private value existed and was agreed without exposing its content to non-members	Hashes persist even after private data is purged, so confirm with counsel whether hashes alone are acceptable for your retention needs

How Hyperledger Fabric private data collections store hashes and payloads

Private data collections split one transaction into two records. The private payload is delivered only to peers that belong to the organizations authorized by the collection definition. The channel ledger, which every channel member's peers hold, carries only a hash of that payload. This split is the core design decision in the feature: the shared ledger proves that a specific value was agreed without exposing the value itself. Before building anything, your architects should map which organizations must see which data, because that map becomes the collection membership policy and is hard to change later without reworking chaincode and client flows.

Non-member organizations on the channel see only the hash. They can confirm that a transaction happened and that a stored value matches a hash they are given, but they cannot read the underlying data. This matters for evidence and dispute handling. If two parties disagree about the terms they agreed, a member can present the payload, and any party can recompute the hash and compare it with the ledger record. Neither the hash nor the payload alone settles the question, so your process needs a defined way to produce, store and transfer the payload to whoever needs it, with an agreed record of who held it and when.

Hashes on the ledger only help if the payload that produced them is retained somewhere reliable. Members hold the payload in their own peers, but those peers are subject to the purge behavior that the rest of this topic covers. Once a payload is purged, the ledger hash remains, yet the data it proves is no longer available from the network. Decide in advance whether your organization will keep an off-network copy of evidence-relevant payloads under its own retention and access controls, and document who is responsible for that copy. Treat this as a governance decision for the consortium, not an afterthought for the operations team.

Before you rely on this model for disputes, confirm the exact hash computation, the fields included in the record, and the sequence in which payloads are disseminated to authorized peers. The Fabric private data documentation describes this flow in detail, and your engineers should work from it directly rather than from a summary. Test it on a non-production network with at least two member organizations and one non-member, and check that the non-member's peers and client applications receive only the hash and no payload. Record the results as part of your evidence package so auditors can see how the boundary was verified.

Why deleting private data is not the same as purging it

DelPrivateData removes the private data value from the chaincode's view of the ledger, so later chaincode reads of that key no longer return it. The Fabric private data documentation is explicit that this is not full removal. The value can still be returned in block events and to other authorized peers that request it during catch-up, because the data remains in the blocks and transactions that those peers process.

For a designer, this means a delete call is a functional operation for the application, not a data removal control. Plan for these points:

Chaincode queries: the key stops returning the value through normal reads after the delete is committed.
Block events: the earlier value can still appear in block events emitted for historical blocks.
Catch-up peers: an authorized peer joining or catching up can still receive the value.
Compliance evidence: a delete record does not prove that every authorized peer no longer holds the data.
Scope: if the requirement is complete removal, DelPrivateData alone does not meet it.

Before relying on this method, confirm with your application team which reads must stop and whether any downstream consumer of block events stores the payload.

How purging affects peers catching up and backups

Purging decides more than what a peer can query today. It also decides what a peer can obtain later. A purged private data entry is no longer available for chaincode queries, block events, or other peers that request it. A member organization that joins after a purge, or a peer restored after a failure, can therefore receive only the private data that authorized peers still hold for the blocks it missed. Before you set a purge rule, map which peers hold each collection, which of them can serve a catching-up peer, and what each one would return for a block already past its purge window. Write the answer down, because it is the basis for explaining to the business what a late-joining member can see.

Automatic purging is driven by a configurable block count. A collection can be set to purge private data that has not been modified for that number of blocks, so the effective window depends on channel activity as well as the setting. A quiet channel keeps data available for much longer in calendar time than a busy one with the same configuration, which makes the window hard to judge from the policy text alone. Ask the channel team to estimate the block height reached over the period the business cares about and to confirm how long a peer could be offline before the data it needs is no longer served. Explicit removal follows a different path. If a record must be gone from every authorized peer, use PurgePrivateData. DelPrivateData still leaves the data returnable in block events and to peers catching up.

Backups carry the problem forward. A backup of a peer's ledger taken before a purge still holds the private data the purge removed from the live peer. If that backup is restored into the network, the restored peer may present data the business expected to be gone and may serve it to others. The purge policy and backup retention must be designed together as one decision. Decide how long each peer's backups are kept, who may restore them, and whether a restored peer rejoins the channel as it is or only after its private data has been checked against the purge policy. The Fabric upgrade guide already asks operators to back up the ledger and MSPs before upgrading, so that same backup set needs a retention rule that matches your data protection obligations.

Test a restore against a purged collection before anyone relies on it. Use a non-production copy of the channel. Purge a known private data entry on the live peers with PurgePrivateData, take a backup from before that purge, and restore it into an isolated peer. Query the chaincode for the entry, watch block events from the restored peer, and check whether a second peer that is catching up can obtain the entry from it. Record which steps returned data and which did not. Repeat the test after any change to a collection definition, the purge window, or the backup schedule, and again after each Fabric version upgrade.

Put the restore test in the written scope. Ask for it as a named deliverable with its test cases, the expected result for each case, and the evidence kept for your auditors. Effort depends on how many collections, peers and backup systems are involved, so confirm those counts in your own environment before requesting a quote. Also ask who owns backup retention after handover, because a purge rule that the operations team does not know about can be undone by a routine restore. Agree that owner, and the restore procedure, before the first production purge runs.

Setting up Hyperledger Fabric private data collections in a test channel

This sequence builds a private data collection on a test channel and shows, step by step, who can read the data, what non-members see, and how an explicit purge removes the value from queries and from a catch-up peer. Each step ends with a check so the team can confirm the result before moving to a production design.

Confirm the channel and member organizations
Start by listing the test channel, the organizations joined to it, and the peers each organization runs. Include one member peer that can be taken offline during the write, so it can serve as the catch-up peer later in the sequence. Record the Fabric release line on every peer and orderer, because lifecycle and private data commands can differ between release lines, and the exact commands depend on the release in use. Confirm the channel holds only synthetic test data. Done when each peer reports the channel membership you expect and the release versions are written into the test runbook.
Define the collection and its member policy
Write the collection definition as a JSON file that names the collection, the organizations allowed to hold the private data, the endorsement requirements for writes, and the purge setting that counts blocks without modification. Keep the member list short and state it explicitly, because membership decides which peers store the plaintext. Ask the platform owner to review the file before deployment. Done when the file passes the schema check for your release and the reviewer confirms that only the intended organizations appear as members.
Deploy the collection definition with chaincode
Include the collection definition in the chaincode approval and commit process so that the member organizations approve the same definition as the chaincode. Each organization approves the definition for its own peers, and the chaincode is committed to the channel once the required approvals exist. Confirm the commit with a lifecycle query on a member peer and on a peer outside the collection. Done when both peers report the same chaincode definition and sequence, and the member peer shows the collection as known to it while the non-member peer does not hold the plaintext configuration for it.
Write and read private data from a member client
From a client that belongs to a member organization, invoke a chaincode function that writes a test record into the collection. Pass the value through a transient input so the plaintext stays out of the transaction arguments. Confirm with the chaincode developer that the function reads the transient field. Then call a query function that reads the record back. Done when the transaction commits as valid on the channel and the member client receives the expected test value from a member peer.
Check that non-members see only hashes
Use a client from an organization outside the collection to query the same key through the public chaincode path, and confirm it cannot retrieve the private value. Then inspect the block that holds the write transaction. The collection write should appear only as a hash of the key and value, which serves as on-ledger evidence that the write happened. Done when the non-member client gets no plaintext, the block carries the hash, and the result is recorded in the runbook with the client identity used for the test.
Trigger an explicit purge with PurgePrivateData
Have an authorized member client invoke a chaincode function that calls the PurgePrivateData API for the test key. Use this API rather than relying on a delete call, because a delete leaves the data returnable in block events and to peers that are catching up. The purge transaction is recorded on the ledger, and the hash evidence from the original write remains. Done when the purge transaction commits as valid and the member peer no longer holds the value in its private data store.
Confirm queries and catch-up peer return nothing
Run the chaincode read on each member peer and confirm it returns no value. Then bring the offline peer back so it catches up on the channel, and confirm that it does not return the purged value through queries or block events. If the catch-up peer still returns the value, stop the test and check the purge transaction and the peer's release version before retesting. Done when every member peer tested returns empty results, the catch-up peer shows no value, and the outcome is recorded with the release versions used.

Security and operational considerations for collection data

Private data collections keep sensitive data off the shared ledger for a subset of organizations, but the controls that decide who holds it, what enters it and when it is removed sit with your operations team. The five areas below cover the decisions and checks that connect collection design to day-two operations.

Membership change control

Collection membership is defined in a collection configuration that channel members approve, so every change to who may hold a collection's data is a governance event. Record who proposed and approved each change, and confirm which peers receive the new definition. Check how a removed organization's peers handle private data they already hold, and whether that change needs a purge plan or a separate collection. Rehearse membership changes on a non-production channel before you make them on a live one.

Endorsement and chaincode logic

The chaincode decides what enters a collection, so its logic is a control point in its own right. Confirm which functions write to private data, how the sensitive payload reaches them (for example, through the transient field so it is kept out of the transaction proposal), and which endorsing peers can see it. Review the collection-level endorsement policy alongside the chaincode-level policy. Automated tests should cover both the path that writes a value and the path where a caller attempts to write to a collection it should not use.

Key and identity management

Fabric CA issues enrollment certificates, handles renewal and revocation, and generates certificate revocation lists, so your certificate lifecycle depends on how that service is run. It supports PostgreSQL and MySQL backends, and several CA servers can share a database behind a load balancer for high availability. Decide where MSP signing keys live. Fabric can keep peer and orderer MSP keys in an HSM through PKCS#11, but TLS keys must stay file-based and the prebuilt Docker images are not built with PKCS#11, so confirm early whether you need a custom image.

Monitoring peers with mutual TLS

Each peer and orderer exposes an operations service with /healthz, /logspec, /version and a Prometheus /metrics endpoint or StatsD push, and access is secured with mutual TLS client certificates. Decide which monitoring systems hold client certificates, how those certificates are rotated, and who may change log levels in production. Alert on health and metric signals that show a peer is lagging, because a lagging peer is also one that requests private data while it catches up. Keep operations endpoints off public networks.

Documenting purge decisions

Automatic purging after a configured number of unmodified blocks and explicit PurgePrivateData calls both remove data that chaincode queries, block events and catching-up peers would otherwise return. Record each collection's purge policy and block threshold, and log every explicit purge with its reason, approver and channel height. Confirm with your auditors which evidence they expect, since hashes remain on the shared ledger as a record. Document how snapshots and backups taken before a purge are handled, because they may still contain the removed data.

Version and upgrade planning for Fabric 2.5 and 3.x networks

Fabric v2.5 is the long-term support release for production users, and the Fabric GitHub releases page lists v3.1.5 and v2.5.16 as both published on June 18, 2026. Both the 3.x and 2.5 LTS lines therefore receive patch releases in parallel. For a network that stores private data collections, the first planning decision is which line to run. Staying on 2.5 keeps the collection behavior your teams have already tested, while moving to 3.x brings the newer ordering and signing options. Confirm the current patch level for each line with the release notes before you choose a target, because the patch you deploy determines which fixes apply to your collections.

The Fabric upgrade guide describes four steps. First, back up the ledger and the MSP directories for every organization. Second, upgrade orderer binaries in a rolling fashion so the Raft cluster keeps a quorum throughout. Third, upgrade peer binaries in a rolling fashion. Fourth, update the application channel capability levels, which changes network behavior and should be treated as the point of no easy return. Each step is a separate change window with its own rollback plan. Assign a named owner for each organization's peers and orderers so that no member is left running a mixed state without knowing it.

Collection behavior must be retested in the target release before the upgrade and again after each step. Build a test set that covers the collection definitions in use, including member-only read and write policies, endorsement policies, and any collections with automatic purging after a set number of blocks. Confirm that private data written before the upgrade is still readable by authorized peers, that purged keys stay purged, and that hashes on the shared ledger still match what endorsing peers compute. Record the results at each step so that a failed check can be tied to a specific binary change rather than to the whole upgrade.

The Fabric Gateway client API is compatible with both v2.5 and v3.0, according to the Fabric upgrade docs. Client applications can therefore be upgraded on their own schedule, separate from the network, which reduces the number of changes landing in the same window. Confirm the compatibility statement for the exact release you choose, and test your application's transaction flows, including private data reads and writes, against the upgraded network before switching production traffic. Plan this with the teams that own the applications, since a client change that depends on a new collection feature needs its own retest.

Before scheduling any upgrade to 3.x, check prerequisites that the Fabric docs call out. Version 3.0 removed Solo and Kafka consensus and the v1.x legacy chaincode lifecycle, so Kafka ordering must already be migrated to Raft and every channel must use the v2.x lifecycle. Ask each member organization to confirm these conditions in writing, and ask your vendor or integrator for a written upgrade runbook that names the rollback point for each step. Any scope or timeline for the upgrade should come from that written plan, not from an estimate made before the prerequisites are verified.

Limits to confirm before you design around collections

Private data collections and purging solve a confidentiality problem, but they also create rules about who can read what, what survives a restore, and how much work purges create over time. The cards below list the limits to confirm for your Fabric release, each to be checked in the Fabric documentation and in a test channel before the design is locked.

Exact purge semantics for your release

Confirm precisely when a purge takes effect on each peer, including automatic purges after a configured number of blocks without modification and explicit purges through the PurgePrivateData API. The Fabric private data documentation says purged data is no longer returned to chaincode queries, block events or peers requesting it, but you should verify this behavior for the exact release you run. Test it with a deletion that a catching-up peer would otherwise request.

Interaction with backups and snapshots

Determine whether purged private data reappears when you restore a peer from a ledger backup, a snapshot or a copy of its state database. Ask how your backup schedule, retention window and restore runbook handle data that was purged after the backup was taken. Write this down as a restore test with a purged key, because a backup that resurrects sensitive data can undo the purge you designed for.

What chaincode and clients can read

Map which chaincode functions, client applications and off-chain consumers can still read private data after a purge, and which can only see the on-chain hash. The hash remains on the shared ledger as evidence by design, so confirm that no application logic depends on the hash returning the original value. Verify these results in a test channel using the same chaincode version and client code you plan to deploy.

Operational load of purge-driven changes

Estimate how often purges happen in your workload and who runs them. Automatic purges run as data ages, but explicit purges need a transaction from an authorized organization and a process for approving them. Confirm the effect of frequent purges on peer storage, state database compaction and transaction throughput by running your expected purge volume in a test channel and recording the peer resource use before you commit to a design.

Identity, HSM and collection membership

Check whether your MSP layout, certificate lifecycle and HSM setup change which organizations can join or be added to a collection, and whether they affect the peers that hold private data. The Fabric HSM documentation notes that peer and orderer MSP keys can sit in an HSM through PKCS#11, while TLS keys stay file-based and prebuilt images lack PKCS#11 support. Confirm each of these points against your own identity provider and certificate authority setup.

What Hyperledger Fabric private data collections cost and take to implement

What drives the cost of a Hyperledger Fabric private data collections project?

The cost rises with the number of organizations, the number of collections, the complexity of your purge rules, the chaincode that reads and writes private data, the backup and snapshot design, and the amount of testing you need before go-live. Each collection needs a defined member list, endorsement behavior, and purge settings, and each one adds design, build and test work. One-time costs include design, chaincode changes, integration and acceptance testing. Recurring costs include operations, backup verification, upgrades and any retainer for ongoing support. Ask for a written quote that itemizes these phases separately, lists the number of collections and organizations in scope, states what is excluded, and names which costs fall to your team and which to the implementation partner. DeployOpen does not publish a price list, so the quote follows from the written scope.

How long does a Fabric private data collections engagement take?

The duration depends on the scope you agree in writing, so there is no fixed timeline that applies to every network. The main variables are how many channels and collections are involved, how settled your channel governance decisions are when the work starts, how quickly your identity and HSM details are available, and whether test environments already exist. Purge rules that need sign-off from several business owners often take longer than the technical build. Ask for a schedule with milestones, the decisions and inputs each milestone depends on, the acceptance tests for each phase, and the client actions that could delay it. A quote that states its assumptions in this way is easier to check than one that gives only an end date.

What does our team need to provide before private data collection work starts?

The work depends on several client decisions and inputs that should be settled before the build begins. On the governance side, you need to decide which organizations belong to each collection, how endorsement applies to private data, and who approves changes to membership. On the identity side, you need your certificate authority design and, if you use an HSM, the PKCS#11 details for peer and orderer MSP keys. TLS keys must remain file-based, and the prebuilt Fabric Docker images are not built with PKCS#11, so custom images may be needed. You also need test environments that match production topology, and named business owners who can approve purge windows for each data type. Ask the partner to list these inputs with owners and due dates in the written scope.

Can our own engineers build private data collections and purge rules in-house?

Your team can build them if it already operates Fabric peers and orderers, writes chaincode, and has tested backup and recovery practice. The harder parts are usually not the collection configuration itself. They are the purge semantics, the behavior of peers that are catching up, the interaction with backups and snapshots, and the testing needed to prove that data is gone where it should be. Ask yourself whether you have engineers who can own those areas after handover, and whether you have time to learn them while also running the network. Many teams compare the two options by scoping a small pilot collection first, measuring the effort and defects it produces, and then deciding how much of the rollout to keep in-house. A written scope from a partner can serve as a reference point for that comparison.

How do automatic purge settings affect peers that catch up and backups?

Collections can purge private data automatically if it has not been modified for a configurable number of blocks. Once purged, the data is no longer available to chaincode queries, block events, or other peers that request it. The effect on operations is less obvious. Backups and snapshots taken before a purge still contain the data, and a peer that restores from an older state may hold data the rest of the network has already purged. Your design should decide the block threshold for each collection with the business owner, define how backups of private data are retained and access-controlled, and test how a lagging peer behaves after a purge. Confirm the exact behavior for your Fabric version against the private data documentation before you finalize the design.

Why does deleting private data in Fabric not remove it from every peer?

Deleting private data with DelPrivateData does not remove it everywhere. According to the Fabric private data documentation, deleted data can still be returned in block events and to peers that are catching up. If you need complete removal from all authorized peers, the design needs the PurgePrivateData API instead. Your chaincode, application logic and operating procedures must call the right API for each case, and your test plan should check block events and a catching-up peer after each purge type. Business owners should decide which data needs full removal and which only needs automatic expiry, because those decisions determine the chaincode work and the test cases. Confirm the exact semantics against the version of Fabric you run before you write the purge specification.

What should a written quote for Fabric private data work include?

A useful quote states the scope in terms of the number of organizations, channels, collections and purge rules, and lists the deliverables for each phase. It should separate one-time build work from recurring operations, upgrades and any retainer for continuous testing or support. It should name the client inputs the work depends on, such as governance decisions, HSM details, test environments and business owner approvals, and state what happens if those inputs arrive late. It should list exclusions, including decisions the partner will not make for you, such as the legal basis for retention. Acceptance criteria should describe the tests that prove purge behavior, backup restoration and catching-up peers. DeployOpen works from fixed scopes agreed in writing before work starts, and ongoing support is available as a retainer, so ask how changes to scope are priced and approved.

How DeployOpen scopes and delivers Fabric private data work

DeployOpen plans and implements Hyperledger Fabric private data collections and purging inside infrastructure you control. We start with a written scope that fixes which organizations hold which data, how long it lives on peers, and how removal is proven before any chaincode or peer configuration changes.

How we scope

Map each sensitive data set to a named collection and list the member organizations allowed to hold it.
Record the block-count purge settings per collection and which data needs explicit PurgePrivateData calls.
Agree how hashes on the shared channel ledger will serve as evidence and who reviews those records.
Engagements are fixed-scope, so deliverables, timelines and acceptance tests are agreed in writing first.

How we build

Write collection definitions, endorsement policies and chaincode logic that call the purge API where required.
Test that purged values are absent from chaincode queries, block events and peer-to-peer private data pulls.
Rehearse a peer catching up from an earlier block to confirm how purged and deleted data behave in practice.
Plan backup content for private data stores and document the restore steps each member organization must follow.

How we hand over

Deliver the collection register, purge runbook and test evidence as documents your team can audit.
Walk your engineers through how deletion differs from purging so operators do not rely on the wrong call.
Document the upgrade and snapshot constraints that affect private data on each peer in your network.
Confirm with your auditors which evidence they need before handover, since DeployOpen prepares evidence but does not issue attestations.

How we support

Review collection changes and new member onboarding against the written purge and retention design.
Keep patch levels for the Fabric 3.x and 2.5 LTS lines current under a retainer if you choose one.
Repeat purge and catch-up tests after each binary upgrade or channel capability change.
Scope retainer support and continuous testing separately in writing, with pricing provided only through a quote.

Hyperledger Fabric private data collections and purging