Building on Hyperledger Fabric
A comprehensive developer's guide to the permissioned blockchain framework
Learn how to leverage Hyperledger Fabric to build secure, scalable, and transparent blockchain solutions for enterprise use cases.
In This Guide
What is Hyperledger Fabric?
A permissioned blockchain framework for enterprise applications
Permissioned Blockchain
Hyperledger Fabric is a permissioned blockchain, meaning that participants are known and authorized to join the network. This contrasts with public blockchains like Bitcoin and Ethereum, where anyone can participate anonymously. Permissioned blockchains are well-suited for enterprise use cases where identity and access control are important.
Why Build on Fabric?
Developers choose Fabric for its modular architecture, support for multiple programming languages (Go, Java, Node.js), its strong focus on privacy and confidentiality (channels and private data), and its robust identity management features. Fabric is designed for scalability and performance in enterprise environments.
Architecture & Components
Key components include: *Peers:* Nodes that execute chaincode, maintain the ledger, and endorse transactions. *Orderers:* Nodes that order transactions into blocks and ensure consensus. *Clients:* Applications that submit transactions to the network. *Chaincode:* Smart contracts that define the business logic. *Channels:* Private communication channels between a subset of network participants. *Fabric CA:* Certificate Authority for managing identities.
Open Source & Community
Fabric is an open-source project under the Hyperledger umbrella, governed by a strong community. This ensures transparency, collaboration, and continuous development. Contributions and feedback are welcome.
Understanding Fabric's Architecture
The technical components of Hyperledger Fabric
Development Environment Setup
Setting up your local environment for Fabric development
Prerequisites
Before setting up your Fabric development environment, you need: *Operating System:* Linux, macOS, or Windows (with WSL2 for some features). *Docker and Docker Compose:* Essential for running Fabric components in containers. *Go (for Go chaincode):* Version 1.18 or later. *Java (for Java chaincode):* Version 8 or 11. *Node.js (for Node.js chaincode):* Version 14 or later. *npm or yarn:* Package managers for Node.js. *Git:* For version control.
Download Fabric Samples
Clone the `fabric-samples` repository from GitHub. This repository contains sample applications, scripts, and configurations that are useful for learning and development. `git clone https://github.com/hyperledger/fabric-samples.git`
Install Fabric Binaries and Docker Images
The `fabric-samples` repository includes a script (`bootstrap.sh`) that downloads the Fabric binaries (e.g., `peer`, `orderer`, `configtxgen`) and the required Docker images. Run the script within the `fabric-samples` directory: `./scripts/bootstrap.sh` This script makes the necessary tools available.
Install Fabric SDKs (Optional)
If you plan to develop applications that interact with Fabric, you'll need to install the appropriate Fabric SDK. The SDKs are available for Go, Java, Node.js, and Python. For example, for Node.js, you would use: `npm install fabric-network fabric-ca-client`
Text Editor or IDE
Choose a text editor or IDE for writing code. Popular choices include: *Visual Studio Code (with Go, Java, or Node.js extensions).* *GoLand (for Go development).* *IntelliJ IDEA (for Java development).* *Any text editor with syntax highlighting for your chosen language.
Test Network (fabric-samples)
The `fabric-samples` repository includes a basic test network (`test-network`) that you can use for development and testing. You can start the network using scripts provided in the `test-network` directory. This network provides a simple environment for deploying and testing chaincode.
Verify Installation
After setting up, it's recommended to verify the installation. This may involve starting the `test-network` from the fabric-samples and running a simple chaincode to ensure everything works.
Fabric Network Configuration
Defining and configuring your Hyperledger Fabric network
Organizations
A Fabric network is typically composed of multiple organizations, each with its own peers, users, and certificate authority. Organizations represent real-world entities that participate in the blockchain network. Each organization has its own MSP (Membership Service Provider).
Configuration Files
Fabric networks are configured using a set of configuration files: *`configtx.yaml`:* Defines the network configuration, including organizations, orderers, and channel profiles. *`crypto-config.yaml`:* Defines the cryptographic material (certificates and keys) for network entities. *`core.yaml`:* Configuration file for peers. *`orderer.yaml`:* Configuration file for orderers.
configtxgen
`configtxgen` is a command-line tool that generates the genesis block for the ordering service and channel configuration transactions based on the `configtx.yaml` file. It's a crucial tool for setting up a Fabric network. You use it to create the initial configuration artifacts.
cryptogen
`cryptogen` is a command-line tool that generates the cryptographic material (certificates and keys) for network entities based on the `crypto-config.yaml` file. It's used for development and testing, but in production, you would typically use Fabric CA. It's a convenient way to quickly generate identities for a test network.
Genesis Block
The genesis block is the first block of a blockchain. In Fabric, the ordering service uses a genesis block that contains the initial network configuration. The genesis block is created using the `configtxgen` tool.
Channel Configuration
Channels are created and managed using configuration transactions. A channel configuration transaction defines the members of the channel, the policies (e.g., endorsement policies), and other channel-specific settings. The `configtxgen` tool is used to create channel configuration transactions.
Network Topology
The network topology defines the structure of the network, including the number of organizations, peers, orderers, and channels. You need to design your network topology based on your application's requirements, considering factors like performance, scalability, and privacy.
Consortium Definition
In a multi-organization network (consortium), you need to define the consortium in the `configtx.yaml` file. The consortium defines the set of organizations that can create channels on the network. This ensures that only authorized organizations can participate in the network.
Chaincode Development
Writing smart contracts for Hyperledger Fabric
Application Development with Fabric SDKs
Building client applications that interact with your Fabric network
Available SDKs
Hyperledger Fabric provides SDKs for multiple programming languages, allowing you to choose the language that best suits your needs: *Node.js SDK:* Well-suited for building web applications and server-side applications. *Java SDK:* Ideal for enterprise environments where Java is widely used. *Go SDK:* Provides high performance and is often used for building command-line tools and system-level applications. *Python SDK:* Useful for scripting and rapid prototyping.
Connecting to the Network
To connect to a Fabric network, your application needs: *A connection profile:* A configuration file (typically in JSON or YAML format) that describes the network topology, including peers, orderers, and CAs. *User credentials:* An identity (certificate and private key) that allows the application to authenticate with the network. The SDK uses the connection profile and user credentials to establish a connection to the network.
Submitting Transactions
To submit a transaction, your application uses the SDK to: *Create a transaction proposal.* *Send the proposal to endorsing peers.*(Peers simulate the transaction by running chaincode) *Collect endorsements from the peers.* *Send the endorsed transaction to the ordering service.* *Wait for the transaction to be committed to the ledger. The SDK handles the communication with peers and orderers, simplifying the transaction submission process.
Querying the Ledger
Your application can use the SDK to query the ledger and retrieve data. You can: *Query the world state to get the current value of a key.* *Query the blockchain to get the history of changes for a key.* *Use rich queries (with CouchDB as the state database) to retrieve data based on complex criteria. The SDK provides functions for making these queries and processing the results.
Event Handling
Your application can listen for events emitted by chaincode or by the Fabric network. This allows your application to react to changes in the ledger in real time. The SDK provides event listeners for: *Chaincode events:* Custom events emitted by chaincode during transaction execution. *Block events:* Notifications when new blocks are added to the ledger. *Transaction events:* Notifications when transactions are committed or rejected.
Gateway (Fabric 2.x+)
The Fabric Gateway simplifies application development by providing a higher-level abstraction for interacting with the network. It handles connection management, transaction submission, and other common tasks, reducing the amount of boilerplate code you need to write. The Gateway is recommended for new application development.
Identity and Wallet
The SDK provides APIs for managing user identities and storing credentials (certificates and private keys). The Wallet is an abstraction that stores and manages identities. You can use different wallet implementations, such as file system wallets, in-memory wallets, or cloud-based wallets.
Asynchronous Operations
Many SDK operations are asynchronous, meaning that they return immediately and complete in the background using Promises (js) or Channels(go). You need to handle the asynchronous nature of these operations in your application code.
Channels and Private Data
Implementing privacy and confidentiality in your Fabric network
What are Channels?
Channels are a key feature of Hyperledger Fabric that provide a mechanism for private communication and data isolation. A channel is a separate ledger shared by a subset of network participants. Only members of a channel can see the transactions and data on that channel. This allows organizations to share data selectively with specific partners without exposing it to the entire network.
Channel Creation
Channels are created using configuration transactions. The `configtxgen` tool is used to create the initial channel configuration transaction. The configuration transaction defines the members of the channel, the policies (e.g., endorsement policies), and other channel-specific settings. Creating a channel requires the consent of the organizations involved.
Channel Membership
Channel membership is managed through MSPs (Membership Service Providers). Each organization participating in a channel has its own MSP defined for that channel. This allows for fine-grained control over access to channel data. Organizations can be added or removed from a channel through configuration updates.
Private Data Collections
Private data collections allow you to share data with a subset of organizations *within* a channel. Data in a private data collection is stored in a separate private state database on the peers of authorized organizations. Only authorized organizations can read and write to the private data collection. This provides an additional layer of confidentiality, even within a channel.
Defining Private Data Collections
Private data collections are defined in a `collections_config.json` file that is specified when the chaincode is installed. The collection definition specifies: *The name of the collection.* *The endorsement policy for the collection.* *The list of organizations that are members of the collection.* *The maximum number of peers that will disseminate the private data.* *Configuration of how long the private data will remain on peers via the `blockToLive` and `timeToLive` fields.
Using Private Data in Chaincode
Chaincode can access private data using the Chaincode API. Functions like `PutPrivateData`, `GetPrivateData`, and `DelPrivateData` are used to interact with private data collections. Access to private data is controlled by the collection's endorsement policy and membership definition.
Implicit Private Data Collections
Fabric 2.x introduced implicit private data collections, which are created automatically for each organization on a channel. This simplifies the management of private data, as you don't need to explicitly define collections for every organization. Implicit collection names begin with `_implicit_org_` + MSP ID.
Use Cases for Channels and Private Data
Channels and private data are essential for implementing many enterprise blockchain use cases, such as: *Supply chain management:* Sharing data with specific suppliers or customers without exposing it to the entire network. *Financial transactions:* Keeping transaction details confidential between the parties involved. *Healthcare:* Sharing patient data securely between authorized providers. *Multi-party data sharing:* Enabling secure and selective data sharing among multiple organizations.
Identity Management in Fabric
Using Fabric CA and MSPs to manage identities and access control
Chaincode Lifecycle (Fabric 2.x+)
Managing the lifecycle of chaincode on your Fabric network
Packaging Chaincode
Before chaincode can be installed on peers, it needs to be packaged. In Fabric 2.x, the packaging format is a tar file (`.tar.gz`). The package contains the chaincode source code, dependencies, and metadata.
Installing Chaincode
Chaincode needs to be installed on each peer that will execute it. The installation process copies the chaincode package to the peer's file system. Each organization's peers need to install the chaincode package. The `peer chaincode install` command is used for installation.
Approving Chaincode Definition
After installing the chaincode, organizations need to *approve* a chaincode definition for their organization. The chaincode definition includes: *The chaincode name.* *The version.* *The endorsement policy.* *Private data collection configuration (if any).* *Initialization policy* Approval signifies that the organization agrees with the chaincode definition. The `peer chaincode approveformyorg` command is used for approval.
Committing Chaincode Definition
Once a sufficient number of organizations have approved the chaincode definition (according to the lifecycle endorsement policy), the definition can be *committed* to the channel. Committing the definition makes the chaincode available for invocation on the channel. The `peer chaincode commit` command is used for committing.
Invoking Chaincode
After the chaincode definition is committed, client applications can invoke the chaincode functions using the Fabric SDKs. Invocation involves sending a transaction proposal to endorsing peers, collecting endorsements, and submitting the endorsed transaction to the ordering service.
Upgrading Chaincode
To upgrade chaincode, you follow a similar process: package, install, approve, and commit a new chaincode definition with a higher version number. The upgrade process ensures that all organizations agree on the new chaincode version before it becomes active.
Lifecycle Endorsement Policy
The lifecycle endorsement policy specifies which organizations need to approve a chaincode definition before it can be committed to the channel. This policy is defined at the channel level and is enforced by the peers. By default the policy is MAJORITY, meaning a majority of organizations.
Chaincode Endorsement Policy
The chaincode endorsement policy specifies which peers need to endorse a transaction before it can be considered valid. This policy is specified in the chaincode definition and is enforced by the committing peers. Policies are typically defined using a combination of organizations and roles (e.g., `AND('Org1.member', 'Org2.member')`).
Initialization Policy
The initialization policy specifies which identities are allowed to invoke the chaincode's `Init` function. This policy can be distinct from the regular chaincode endorsement policy.
Testing & Deployment
Best practices for validating and deploying Fabric applications
Monitoring and Logging
Tracking the health and performance of your Fabric network
Peer and Orderer Logs
Peers and orderers generate logs that provide information about their operation. You can configure the logging level (e.g., DEBUG, INFO, WARN, ERROR) and the output destination (e.g., console, file). Regularly review the logs to identify and troubleshoot issues. Log analysis tools can help with log management.
Chaincode Logs
Metrics
Prometheus and Grafana
Prometheus is a popular open-source monitoring system that can be used to collect Fabric metrics. Grafana is a data visualization and dashboarding tool that can be used to create dashboards for Fabric metrics. Together, Prometheus and Grafana provide a powerful monitoring solution for Fabric networks. You configure the `metrics` section of the `core.yaml` (peer) or `orderer.yaml` (orderer) files for Prometheus integration.
Operations Service
Fabric components expose a RESTful operations service that can be used to monitor their health and status. The operations service provides endpoints for: *Checking the health of the component.* *Retrieving metrics.* *Retrieving log levels.* You can use the operations service to build custom monitoring tools or integrate Fabric with existing monitoring systems.
Event Monitoring
Blockchain Explorers
Blockchain explorers (such as Hyperledger Explorer) allow you to view transactions, blocks, and other data on the Fabric network. Explorers provide a user-friendly interface for inspecting the ledger and understanding the state of the network. They are useful for debugging and monitoring.
Alerting
Based on metrics collected, alert rules can be created to send notifcations when a threshold is reached, e.g. high CPU usage, disk usage, or low peer count. This helps identify and react to problems faster.
Security Best Practices
Protecting your Fabric network and applications
Secure Your Network Configuration
Carefully configure your Fabric network to ensure its security. Use strong passwords, restrict access to network components, and use TLS for all communication. Regularly review and update your network configuration.
Manage Identities Securely
Use Fabric CA to manage identities and issue digital certificates. Follow best practices for key management, such as storing private keys securely and regularly rotating certificates. Enforce strong password policies for user registration.
Chaincode Security
When writing chaincode, follow secure coding practices. Validate all inputs, handle errors properly, and avoid common vulnerabilities (e.g., integer overflows, incorrect access control). Thoroughly test your chaincode and consider conducting security audits.
Endorsement Policies
Carefully design your endorsement policies to ensure that transactions are properly validated. Use appropriate policies based on the sensitivity of the data and the trust model of your network. Avoid overly permissive endorsement policies.
Channel and Private Data Security
Use channels and private data collections to protect sensitive data. Ensure that only authorized organizations have access to confidential information. Carefully configure the membership and policies for channels and private data collections.
Network Monitoring
Regularly monitor your Fabric network for any suspicious activity or security breaches. Use monitoring tools to track key metrics and set up alerts for potential issues. Review logs regularly to identify any errors or warnings.
Keep Software Updated
Keep your Fabric components (peers, orderers, CAs) and SDKs updated to the latest versions. New releases often include security patches and bug fixes. Subscribe to the Hyperledger Fabric security announcements to stay informed about security updates.
Secure Your Infrastructure
Ensure that the infrastructure on which your Fabric network runs is secure. This includes securing the operating systems, networks, and physical servers. Follow security best practices for your infrastructure environment.
TLS Encryption
Use TLS (Transport Layer Security) encryption for all communication between Fabric components (peers, orderers, clients, CAs). TLS ensures that data is encrypted in transit, protecting it from eavesdropping and tampering. Configure TLS certificates for all network entities.
Real-World Examples
Use cases and deployments of Hyperledger Fabric
Supply Chain Management
Fabric is widely used in supply chain management solutions to track goods and materials as they move through the supply chain. Channels and private data can be used to share data selectively with different participants (suppliers, manufacturers, distributors, retailers). Examples include IBM Food Trust and Walmart's food traceability initiative.
Trade Finance
Fabric is used in trade finance applications to streamline the process of financing international trade. This includes applications for letters of credit, bills of lading, and other trade documents. Channels and private data ensure that sensitive financial information is shared only with authorized parties. We.trade is a prominent example.
Digital Identity
Fabric can be used to build decentralized digital identity solutions. This allows individuals and organizations to control their own digital identities and share them securely with others. Fabric CA provides the infrastructure for managing identities and issuing certificates. Examples include Sovrin and the National Strategy for Trusted Identities in Cyberspace (NSTIC).
Healthcare
Fabric is being used in healthcare applications to securely share patient data between healthcare providers, insurers, and patients. Channels and private data ensure that sensitive patient information is protected. Examples include initiatives for managing medical records, tracking pharmaceuticals, and streamlining insurance claims.
Government
Fabric is used in government applications for managing land registries, voting systems, and supply chain solutions that provide transparency, security, and auditability. This can improve efficiency, reduce fraud, and increase trust in government services.
Loyalty Programs
Hyperledger Fabric enables the creation of multi-party loyalty programs. Airlines and associated businesses could use Fabric to share customer loyalty points in a transparent and secure way.
Future of Fabric
Upcoming developments and roadmap for the project
Frequently Asked Questions
Common questions about developing with Hyperledger Fabric
Additional Resources
Essential links and tools for Hyperledger Fabric developers
Hyperledger Fabric Documentation
Official documentation for Hyperledger Fabric.
Hyperledger Fabric GitHub
Source code repository for Hyperledger Fabric.
Fabric Samples
Repository containing sample applications, scripts, and configurations.
Hyperledger Wiki
Wiki pages for Hyperledger projects, including Fabric.
Hyperledger Discord
Discord server for Hyperledger projects, including channels for Fabric.
Hyperledger Fabric SDK for Node.js
Node.js SDK for building Fabric applications.
Hyperledger Fabric SDK for Java
Java SDK for building Fabric applications
Hyperledger Fabric SDK for Go
Go SDK for building Fabric applications.
Hyperledger Fabric CA Documentation
Documentation for Fabric CA.
Ready to Build on Hyperledger Fabric?
Take the next steps in your enterprise blockchain development journey