Creating and Understanding `configtx.yaml` in Hyperledger Fabric

Published in

Novai-Hyperledger Fabric 101

7 min readJun 3, 2024

The configtx.yaml file in Hyperledger Fabric is essential for defining the network configuration, creating the genesis block, and configuring channels. This article provides a comprehensive guide to understanding and creating the configtx.yaml file.

Introduction to `configtx.yaml`

configtx.yaml is a configuration file that defines the organizational structure, policies, and other settings for the Hyperledger Fabric network. It plays a crucial role in generating configuration transactions and the genesis block for the blockchain network.

Key Sections of `configtx.yaml`

The configtx.yaml file is structured into several key sections:

Organizations
Capabilities
Application
Orderer
Channel
Profiles

1. Organizations

This section defines the organizations that participate in the network. Each organization has an MSP (Membership Service Provider) configuration.

Organizations:
  - &OrdererOrg
    Name: OrdererOrg
    ID: OrdererMSP
    MSPDir: crypto-config/ordererOrganizations/example.com/msp
    Policies:
      Readers:
        Type: Signature
        Rule: "OR('OrdererMSP.member')"
      Writers:
        Type: Signature
        Rule: "OR('OrdererMSP.member')"
      Admins:
        Type: Signature
        Rule: "OR('OrdererMSP.admin')"
  
  - &Org1
    Name: Org1MSP
    ID: Org1MSP
    MSPDir: crypto-config/peerOrganizations/org1.example.com/msp
    Policies:
      Readers:
        Type: Signature
        Rule: "OR('Org1MSP.admin', 'Org1MSP.peer', 'Org1MSP.client')"
      Writers:
        Type: Signature
        Rule: "OR('Org1MSP.admin', 'Org1MSP.client')"
      Admins:
        Type: Signature
        Rule: "OR('Org1MSP.admin')"
    AnchorPeers:
      - Host: peer0.org1.example.com
        Port: 7051

OrdererOrg
Policies: This section defines the policies for the organization.

Readers: Policy for readers. It specifies who can read the data.
Type: Signature: The type of policy, which in this case is a signature-based policy.
Rule: “OR(‘OrdererMSP.member’)”: The rule defines that any member of the OrdererMSP can read.
Writers: Policy for writers. It specifies who can write the data.
Type: Signature
Rule: “OR(‘OrdererMSP.member’)”: The rule defines that any member of the OrdererMSP can write.
Admins: Policy for admins. It specifies who can perform administrative tasks.
Type: Signature
Rule: “OR(‘OrdererMSP.admin’)”: The rule defines that only admins of the OrdererMSP can perform administrative tasks.

Other Possible Example for rule:

AND

Rule: "AND('Org1MSP.admin', 'Org1MSP.client')"

Meaning: Both the admin and the client from Org1MSP must sign.

Out Of (n, …)

Rule: "OutOf(2, 'Org1MSP.admin', 'Org1MSP.client', 'Org1MSP.peer')"

Meaning: Any 2 out of the 3 specified identities (admin, client, peer from Org1MSP) must sign.

Combining OR and AND

Rule: "OR('Org1MSP.admin', AND('Org1MSP.client', 'Org1MSP.peer'))"

Meaning: Either an admin from Org1MSP must sign, or both a client and a peer from Org1MSP must sign.

2. Capabilities

Capabilities specify the features enabled in the network, application, and orderer.

Capabilities:
  Channel: &ChannelCapabilities
    V2_0: true
  Orderer: &OrdererCapabilities
    V2_0: true
  Application: &ApplicationCapabilities
    V2_0: true

ChannelCapabilities: This indicates that the network supports features and functionalities introduced in version 2.0 of Hyperledger Fabric.
OrdererCapabilities: Similar to ChannelCapabilities, it's defined that the capabilities for the orderer are set to version 2.0 (V2_0: true), indicating support for features introduced in version 2.0.
ApplicationCapabilities: Again, it’s defined that the capabilities for applications are set to version 2.0 (V2_0: true), indicating support for features introduced in version 2.0.

3. Application

The Application section defines policies and organizations for the application layer. It includes settings related to organizations, policies, and capabilities that govern how applications interact with the blockchain network.

Application: &ApplicationDefaults
  Organizations:
  Policies:
    Readers:
      Type: ImplicitMeta
      Rule: "ANY Readers"
    Writers:
      Type: ImplicitMeta
      Rule: "ANY Writers"
    Admins:
      Type: ImplicitMeta
      Rule: "MAJORITY Admins"
  Capabilities:
    <<: *ApplicationCapabilities

Policies: This subsection defines the default access control policies for the application layer. In the provided snippet:

Here, we define three types of policies:

Readers: Who can read data from the blockchain.
Writers: Who can write data to the blockchain.
Admins: Who has administrative control over the network.

ImplicitMeta: This is a type of policy that allows for more complex rules. In this case, it’s saying:

ANY Readers: Any member of any organization can read data.
ANY Writers: Any member of any organization can write data.
MAJORITY Admins: Administrative tasks require the approval of the majority of admins from all organizations in the network.

4. Orderer

The Orderer section configures the ordering service.

Orderer: &OrdererDefaults
  OrdererType: solo
  Addresses:
    - orderer.example.com:7050
  BatchTimeout: 2s
  BatchSize:
    MaxMessageCount: 10
    AbsoluteMaxBytes: 99 MB
    PreferredMaxBytes: 512 KB
  Policies:
    Readers:
      Type: ImplicitMeta
      Rule: "ANY Readers"
    Writers:
      Type: ImplicitMeta
      Rule: "ANY Writers"
    Admins:
      Type: ImplicitMeta
      Rule: "MAJORITY Admins"
  Organizations:

OrdererDefaults: This section defines default settings for the orderer component of the Hyperledger Fabric network.
OrdererType: solo: This specifies that the network is using a solo orderer type, which means there is only one orderer node managing the ordering service.
Addresses: This specifies the network address and port where the orderer node is accessible. In this case, it’s orderer.example.com on port 7050.
BatchTimeout: 2s: This sets the maximum time the orderer will wait to create a batch of transactions. In this case, it’s set to 2 seconds.
BatchSize: This section specifies the maximum number and size of transactions that can be included in a batch.
MaxMessageCount: 10: Maximum number of messages (transactions) in a batch.
AbsoluteMaxBytes: 99 MB: Absolute maximum size of a batch, regardless of the number of messages.
PreferredMaxBytes: 512 KB: Preferred maximum size of a batch. This is the target size for batches, but it can be exceeded if necessary.
Policies: Similar to the previous explanation, this section defines policies for who can read, write, and administer the orderer.
Readers: Any member of any organization can read orderer data.
Writers: Any member of any organization can write orderer data.
Admins: Administrative tasks require the approval of the majority of admins from all organizations in the network.
Organizations: This section would normally list the organizations allowed to interact with the orderer, but it’s left empty in this snippet. It means that any organization can interact with the orderer.

5. Channel

The Channel section defines the default policies for channels.

Channel: &ChannelDefaults
  Policies:
    Readers:
      Type: ImplicitMeta
      Rule: "ANY Readers"
    Writers:
      Type: ImplicitMeta
      Rule: "ANY Writers"
    Admins:
      Type: ImplicitMeta
      Rule: "MAJORITY Admins"
  Capabilities:
    <<: *ChannelCapabilities

Policies: Policies define who can perform certain actions on the channel. In this snippet:
Readers: Any member of any organization can read data from the channel.
Writers: Any member of any organization can write data to the channel.
Admins: Administrative tasks on the channel require the approval of the majority of admins from all organizations in the network.
Capabilities: This section specifies the capabilities of the channel, which are the features and functionalities supported by the channel. It’s inheriting the capabilities defined elsewhere in the configuration file.

The ImplicitMeta type policies are used here. They allow for more complex rules:

ANY Readers: Any member of any organization can read data from the channel.
ANY Writers: Any member of any organization can write data to the channel.
MAJORITY Admins: Administrative tasks require approval from the majority of admins from all organizations in the network.

6. Profiles

Profiles combine different sections to create a complete network profile, including the genesis block and channel configurations.

Genesis Block Profile:

Profiles:
  OrgsOrdererGenesis:
    Orderer:
      <<: *OrdererDefaults
      Organizations:
        - *OrdererOrg
    Consortiums:
      SampleConsortium:
        Organizations:
          - *Org1
          - *Org2

OrgsOrdererGenesis: This profile is named OrgsOrdererGenesis, which suggests it's used for setting up the initial configuration for the orderer and the genesis block.
Orderer: This section defines the configuration for the orderer component within this profile. It’s inheriting settings from the OrdererDefaults section using <<: *OrdererDefaults. This means it takes all the configurations defined in the OrdererDefaults section and applies them here.
Organizations: This specifies the organizations that will be part of the orderer consortium for the genesis block. In this case, it includes only OrdererOrg, which likely represents the orderer organization.
Consortiums: This section defines the consortiums within this profile. A consortium is a group of organizations that come together to form a business network. Here, a consortium named SampleConsortiumis defined.
Organizations: Within the SampleConsortium consortium, the organizations Org1 and Org2 are listed. This means that Org1 and Org2 will be part of this consortium and can transact with each other.

Channel Profile:

OrgsChannel:
    Consortium: SampleConsortium
    Application:
      <<: *ApplicationDefaults
      Organizations:
        - *Org1
        - *Org2
      Capabilities:
        <<: *ApplicationCapabilities

the OrgsChannel profile defines configurations for creating a channel. It specifies the consortium to which the channel belongs, lists the participating organizations (Org1 and Org2), and inherits default settings and capabilities for the application layer. This profile is used as a blueprint for creating channels within the Hyperledger Fabric network.

Creating `configtx.yaml`

To create a configtx.yaml file, follow these steps:

Define Organizations: List all participating organizations, specifying their MSP directories and policies.
Set Capabilities: Enable necessary capabilities for channels, orderers, and applications.
Configure Application and Orderer: Define the default settings for the application and orderer sections.
Specify Channel Policies: Define the default policies for channel operations.
Create Profiles: Combine different sections to form profiles for genesis blocks and channel configurations.

Example `configtx.yaml`

Here’s an example of a complete configtx.yaml file:

Organizations:
  - &OrdererOrg
    Name: OrdererOrg
    ID: OrdererMSP
    MSPDir: crypto-config/ordererOrganizations/example.com/msp
    Policies:
      Readers:
        Type: Signature
        Rule: "OR('OrdererMSP.member')"
      Writers:
        Type: Signature
        Rule: "OR('OrdererMSP.member')"
      Admins:
        Type: Signature
        Rule: "OR('OrdererMSP.admin')"

  - &Org1
    Name: Org1MSP
    ID: Org1MSP
    MSPDir: crypto-config/peerOrganizations/org1.example.com/msp
    Policies:
      Readers:
        Type: Signature
        Rule: "OR('Org1MSP.admin', 'Org1MSP.peer', 'Org1MSP.client')"
      Writers:
        Type: Signature
        Rule: "OR('Org1MSP.admin', 'Org1MSP.client')"
      Admins:
        Type: Signature
        Rule: "OR('Org1MSP.admin')"
    AnchorPeers:
      - Host: peer0.org1.example.com
        Port: 7051  - &Org2
    Name: Org2MSP
    ID: Org2MSP
    MSPDir: crypto-config/peerOrganizations/org2.example.com/msp
    Policies:
      Readers:
        Type: Signature
        Rule: "OR('Org2MSP.admin', 'Org2MSP.peer', 'Org2MSP.client')"
      Writers:
        Type: Signature
        Rule: "OR('Org2MSP.admin', 'Org2MSP.client')"
      Admins:
        Type: Signature
        Rule: "OR('Org2MSP.admin')"
    AnchorPeers:
      - Host: peer0.org2.example.com
        Port: 8051Capabilities:
  Channel: &ChannelCapabilities
    V2_0: true
  Orderer: &OrdererCapabilities
    V2_0: true
  Application: &ApplicationCapabilities
    V2_0: trueApplication: &ApplicationDefaults
  Organizations:
  Policies:
    Readers:
      Type: ImplicitMeta
      Rule: "ANY Readers"
    Writers:
      Type: ImplicitMeta
      Rule: "ANY Writers"
    Admins:
      Type: ImplicitMeta
      Rule: "MAJORITY Admins"
  Capabilities:
    <<: *ApplicationCapabilitiesOrderer: &OrdererDefaults
  OrdererType: solo
  Addresses:
    - orderer.example.com:7050
  BatchTimeout: 2s
  BatchSize:
    MaxMessageCount: 10
    AbsoluteMaxBytes: 99 MB
    PreferredMaxBytes: 512 KB
  Policies:
    Readers:
      Type: ImplicitMeta
      Rule: "ANY Readers"
    Writers:
      Type: ImplicitMeta
      Rule: "ANY Writers"
    Admins:
      Type: ImplicitMeta
      Rule: "MAJORITY Admins"
  Organizations:Channel: &ChannelDefaults
  Policies:
    Readers:
      Type: ImplicitMeta
      Rule: "ANY Readers"
    Writers:
      Type: ImplicitMeta
      Rule: "ANY Writers"
    Admins:
      Type: ImplicitMeta
      Rule: "MAJORITY Admins"
  Capabilities:
    <<: *ChannelCapabilitiesProfiles:
  OrgsOrdererGenesis:
    Orderer:
      <<: *OrdererDefaults
      Organizations:
        - *OrdererOrg
    Consortiums:
      SampleConsortium:
        Organizations:
          - *Org1
          - *Org2  OrgsChannel:
    Consortium: SampleConsortium
    Application:
      <<: *ApplicationDefaults
      Organizations:
        - *Org1
        - *Org2
      Capabilities:
        <<: *ApplicationCapabilities

The configtx.yaml file is fundamental for configuring a Hyperledger Fabric network. It defines the organizational structure, policies, capabilities, and profiles needed for the network's genesis block and channel configurations. By following the steps outlined in this article, you can create a comprehensive configtx.yaml file tailored to your blockchain network's requirements.

Creating and Understanding configtx.yaml in Hyperledger Fabric

Introduction to configtx.yaml

Key Sections of configtx.yaml