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

Where to Buy Blockstack | Buy STX | Buy Blockstack (STX) with Credit Card?

Why I Think Decentralized Finance Should Have Almost Nothing To Do With Finance (and What Currency…

Asset management

Grab Your NFTs and Get Ready for Alpha!

Breaking the value island of advertising industry,JAMBO joins Polkadot ecology

Axelar Newsletter — December issue

January 2022- Enterprise blockchain monthly review

DotFriday Chapter 7 — Into the Metaverse!

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

A story of leaking uninitialized memory from Fastly

Using Fastify with Passport.js for Google OAuth

Securing Large API Ecosystems

Native PGP Support for Sterling B2B Integrator