Migrating Hyperledger Fabric 1.4.x to 2.2.x

Hyperledger Fabric 1.4.x to 2.2.x migration
Hyperledger Fabric 1.4.x to 2.2.x migration approach, learnings and challenges.


  • some of the new exciting features,
  • three step approach to migration,
  • major challenges faced and
  • touch upon migration of your chaincode.

Major Changes in Newer Version(v2.2.x)

Migrating From 1.4.x to 2.2.x

  • Prepare your Network
    - Take backup of configuration, ledger and MSPs
  • Prepare your Code
    - Due to the enhancements and structural changes between version 1.4 and 2.2, it becomes difficult to use the smart contracts and application written for 1.4 to run smoothly over 2.2. Refer the ‘Migrate your Chaincode’ section below for details.
  • Migrate
    - Upgrade your orderer instances, one at a time.
    - Update your peers, one at a time.
  • Soft-Switch
    - It is called Soft-Switch because you don’t need to bring your network down to make the switch.
    - Update the capabilities of your orderer and peers. (Ensure that your orderer and peers are all upgraded before your move to upgrade the capabilities).
  • Train your Operations team
    - Provide appropriate training to the operations team, to bring them up to speed on the new features and updates on the newer version.
  • Migrate your Chaincode
    - If you plan to migrate a project from Fabric 1.4.x to 2.2.x, and your project is more than a simple PoC, then higher chances are that you will have to migrate your Chaincode and write your clientSDK wrapper to continue using the features that were previously available out-of-the-box from the 1.4.x clientSDK wrapper.

Main Challenges faced in migration

  • Retraining of the operations team on newer version due to the administrative differences between the releases.
  • Chaincode structural changes and features deprecated & since removed in the newer version reduces the compatibility with the code written in previous version.
  • The opensource Hyperledger endorsed Fabric Client SDK wrapper, which was previously available for 1.4 version which allowed extended features without explicit need to write code is not compatible with the newer version.
    — Hyperledger has released newer version of its client SDK but it requires developers to write the wrapper code to include the extended features. For example, the feature to fetch a block from the ledger has been introduced recently and was not available initially. Many such features are still not available.
  • No more fabric token. Fabric previously provided ‘fabric token’ which was utilized by the developers to validate the authentication of the user, is not available in the new client SDK.
  • Chaincode lifecycle policy by default requires the Chaincode to be approved by the nodes. Thus, if left as is causes additional steps to be performed every time a Chaincode is modified and thereby increasing the dev/test overhead.

Approach to Migrating your Chaincode

  • Identify missing features from ClientSDK that you would need.
  • Identify the Chaincode changes required. This may be needed due to change is SHIM packaging, removal of Logging, Chaincode function definition signatures changes.
  • Write code in your clientSDK wrapper to account for the missing features. The quantum of changes depends on whether your clientSDK wrapper was from 1.4.x or if you continued using the older client sdk conventions.
  • Convert your Chaincode to latest structure.
  • Perform necessary smoke and regression testing.





Emerging Technologies Architect/Evangelist with credentials in Blockchain, Virtual Asssitant, Data Analytics & Computer Vision. LinkedIn: http://bit.ly/viKram

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Polkadex — The trading engine for web3 and Defi

Is DeFi resilient enough for mass adoption?

Deploy Your First Solidity Contract on Dune Network

TOP Network Forms A Strategic Partnership With KardiaChain to Jointly Develop The Global Market

Why you should invest in the all round public blockchain network thinkium

KGR Public Sale Notice:The first nad only public sale are finished in 3minutes

[AMA] TomTom Coin AMA Recap 🎈

What is Zilliqa?

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Vikram Sharma

Vikram Sharma

Emerging Technologies Architect/Evangelist with credentials in Blockchain, Virtual Asssitant, Data Analytics & Computer Vision. LinkedIn: http://bit.ly/viKram

More from Medium

Why we churned from Algolia (It’s not for everyone)

Decentralized Identity & Data Monetization — walt.id

What are Protocol Buffers AKA Protobuf?

Introduction to privacy policy implementation in organisations