Where Fabric fits
Hyperledger Fabric is a permissioned distributed ledger licensed under Apache-2.0 and a graduated project of LF Decentralized Trust. Every participant has a certificate-based identity issued by Fabric CA or an existing PKI and recognized through an organization's membership service provider (MSP). Transactions follow an execute, order, validate flow: endorsing peers run chaincode and sign the results, the ordering service sequences transactions into blocks, and every peer checks the endorsement policy before committing.
Fabric suits known organizations that share a ledger, for example for trade finance documents, asset registries or interbank workflows, and need control over who sees which data. The demanding parts are governance, data visibility, certificate management and upgrades across nodes that different organizations run. LF Decentralized Trust also lists Fabric-x, a separate implementation aimed at regulated digital assets; this page covers classic Fabric.
Consortium governance as a workstream
Fabric encodes many governance decisions in channel configuration and policies, so members must agree them before the network is built.
| Decision | What to agree | Where it lands |
|---|---|---|
| Membership | How organizations join and leave, who approves, and what happens to their nodes and data on exit. | Consortium agreement and a channel configuration update procedure. |
| Channel policies | Who may update channel configuration, read the ledger and submit transactions on each channel. | Channel configuration and policy definitions. |
| Chaincode governance | Who writes and reviews chaincode, how many organizations must approve a definition (the default LifecycleEndorsement policy is a majority) and how upgrades are scheduled. | LifecycleEndorsement policy and the chaincode release process. |
| Ordering service | Which organizations run orderer nodes, how many each, and whether Raft or BFT consensus fits the trust model. | Orderer plan and consenter set per channel. |
| Certificate authorities | Each organization's CA hierarchy, intermediate CAs, and who issues admin, node and client identities. | MSP and CA design. |
Network building blocks
Each organization runs its own components. Shared components need agreed owners.
Peers
Hold the ledger and world state, endorse transactions by running chaincode, and serve the Fabric Gateway for client applications. World state lives in LevelDB or CouchDB; CouchDB adds JSON rich queries and another database to run.
Ordering service
Raft is crash fault tolerant and fits members that trust orderer operators. Fabric 3.0 added BFT ordering based on SmartBFT, for cases where up to, but not including, a third of orderer operators may not be trusted. BFT needs the V3_0 channel capability.
Channels
Each channel is a separate ledger with its own members, policies and chaincode, managed through the channel participation API. Fabric 3.0 removed the ordering system channel.
Private data collections
Private data goes peer to peer only to authorized organizations, with a hash on the channel ledger. Collections can purge data after a set number of blocks, and PurgePrivateData removes it on request.
Chaincode
Written in Go, Java or Node.js and deployed through the lifecycle: package, install, approve per organization, commit. External builders control how chaincode is built and run in production.
Chaincode and application design
Design keys, composite keys and indexes around the queries the business needs. Rich queries on CouchDB are not re-executed during validation, so they do not detect phantom reads; keep them out of transactions that update state. Plan for MVCC conflicts on frequently updated keys.
Chaincode-level policies set which organizations must endorse, state-based endorsement sets policies on individual keys, and collections can carry their own policy. Model who must sign each kind of change, such as a transfer that needs both the sender's and the registrar's endorsement.
Applications use the Fabric Gateway client API for Go, Node or Java. The legacy SDKs are no longer maintained and do not support v3.0 features such as SmartBFT, so plan their replacement. Event listeners with checkpoints let integrations resume after an outage.
Unit test chaincode against a mocked stub, then run integration tests on a multi-organization network with production policies, collections and certificates. Include hot-key concurrency, policy failures and a full lifecycle upgrade.
Integration with core systems and HSMs
Each organization usually runs a gateway service between its internal systems and Fabric that submits transactions with the organization's identity, consumes events and updates core banking, ERP or document systems. Decide which system holds the authoritative copy of each data item, and reconcile ledger state against internal records on a schedule.
Fabric can keep peer and orderer MSP signing keys in an HSM over PKCS#11, configured in the bccsp section of the node configuration. Prebuilt Fabric Docker images do not include PKCS#11 support, so images must be built with the pkcs11 build tag and the vendor library. TLS keys remain file based. Fabric CA can also keep its own signing key in an HSM.
Decide how people and systems map to certificates: end users may hold their own identities, or applications may sign on their behalf. The choice affects onboarding, KYC record linkage, revocation and audit trails.
Hosting, certificates and recovery
Fabric nodes run in each member's infrastructure, on Kubernetes or virtual machines. Build every environment from code.
| Area | Approach | Check |
|---|---|---|
| Orderer availability | Spread orderer nodes across organizations and failure domains. Add or remove Raft nodes one at a time, only while the cluster has quorum. | Stopping one orderer leaves ordering running on every channel. |
| Certificate lifecycle | Track expiry for every node, admin and client certificate. Rotating a Raft orderer's TLS certificate to a new key means updating every channel the node serves, replacing the files and restarting, while all consenters are healthy. | Expiry alerts fire well ahead, and a rotation has been rehearsed. |
| Backups | Back up ledgers, MSP folders, CA databases and keys, and channel configuration. Peers can catch up on blocks from the network, but a lost CA database or admin key cannot be recreated. | A CA restore and a peer rebuild have both been rehearsed. |
| Monitoring | Peers and orderers expose an operations service with health checks and Prometheus or StatsD metrics, protected by mutual TLS with certificates from a dedicated CA. | Alerts cover block height divergence, endorsement failures, Raft leader changes and certificate expiry. |
Security hardening and access
Use mutual TLS between all nodes, keep each organization's root CA offline and issue from intermediates, and use node organizational units so certificates carry admin, peer, orderer or client roles. Keep organization admin identities in an HSM or under tight custody, since they can change channel configuration and approve chaincode.
Fabric has no single sign-on of its own. Staff sign in to the applications and consoles around it through your identity provider, and those applications use Fabric identities with only the rights they need. Restrict operations endpoints and CouchDB to the node's network, and review chaincode for nondeterminism and access checks before every approval. DeployOpen's infrastructure and application testing can cover the gateway services, nodes and chaincode.
Versions, upgrades and common questions
Which Fabric version should we run?
The project README names 2.5 as the current LTS release, and it still receives patch releases. The 3.x line adds BFT ordering, Ed25519 support and, in 3.1, batched chaincode reads and writes. Networks that need BFT start on 3.x; others weigh the LTS designation against newer features.
What must change before moving to 3.x?
Fabric 3.0 removed the system channel, Solo and Kafka consensus, and the legacy chaincode lifecycle. Move channels to the channel participation API, Kafka ordering to Raft and chaincode to the current lifecycle first. With the V3_0 capability, replace global OrdererAddresses with per-organization orderer endpoints.
How does an upgrade run?
Back up ledgers and MSPs, upgrade orderers one at a time, then peers, and update channel capability levels only after every node runs the new version. Each organization upgrades its own nodes, so agree the schedule and rollback point across members.
Is gossip still used for block distribution?
Fabric 3.0 deprecated block dissemination through gossip, and peers can receive blocks directly from orderers. Review peer delivery settings during upgrade planning.
Which licenses apply?
Fabric source code is Apache-2.0 and its documentation is CC-BY-4.0. Fabric CA is also Apache-2.0. CouchDB, HSM client libraries and any commercial tooling have their own terms.
Fabric operating ownership
Every member operates part of the network, and some duties are shared. Write down who does each.
Member node operators
- Run peers, CouchDB and gateway services.
- Apply upgrades on the agreed schedule.
- Monitor endorsement and commit health.
Ordering service operators
- Run orderer nodes and watch consensus.
- Change consenters one node at a time.
- Coordinate certificate rotation.
CA and identity owners
- Operate CAs and protect admin identities.
- Track expiry and revoke certificates.
- Map staff and systems to Fabric roles.
Consortium governance
- Approves members, channel changes and chaincode.
- Owns the upgrade calendar.
- Commissions security testing.
Scope and handover
Effort depends on the number of organizations and channels, chaincode complexity, private data needs, the ordering trust model, HSM use, integrations with internal systems and whether an existing network needs to move to 3.x.
DeployOpen runs governance and design workshops with members, designs channels, policies and the CA structure, writes and tests chaincode, builds network configuration as code, deploys and hardens nodes in each member's infrastructure, integrates internal systems and plans upgrades. Handover includes the governance and channel design, MSP and CA procedures, chaincode source and tests, a certificate inventory with expiry tracking, monitoring setup and runbooks.
