-
Notifications
You must be signed in to change notification settings - Fork 212
Migration Guide for v1.1.0
Hyperledger FireFly v1.1.0 is the next planned minor release. Although labeled as "minor", it includes significant new functionality around namespaces and plugins, as detailed in FIR-12. As a result, upgrading an existing FireFly environment from any prior release may require special steps depending on the functionality used. This guide will attempt to lay out the required steps to migrate a pre-existing environment in all cases.
Upgrade to latest v1.0.x patch release
Before upgrading to v1.1.0, it is strongly recommended to upgrade to the latest v1.0.x patch release (v1.0.3 as of the writing this document). Do not proceed any further in this guide until all nodes are successfully running the latest patch release version.
Fix any deprecated config usage
All items in FireFly's YAML config that were deprecated at any time in the v1.0.x line will be unsupported in v1.1.0. After upgrading to the latest v1.0.x patch release, you should therefore look for any deprecation warnings when starting FireFly, and ensure they are fixed before upgrading to v1.1.0. Failure to do so will cause your config file to be rejected in v1.1.0, and FireFly will fail to start.
Record all namespaces in the config file
FireFly v1.0 allowed for the dynamic creation of new namespaces by broadcasting a namespace definition to all nodes. This functionality is removed in v1.1.0. If your network relies on any namespaces that were created via a broadcast, you must add those namespaces to the namespaces.predefined list in your YAML config prior to upgrade. If you do not, they will cease to function after upgrading to v1.1.0 (all events on those namespaces will be ignored by your node). Note that if you are only using the default namespace, no action is needed here.
Identify usage of removed APIs
No special considerations are needed during the upgrade. After performing the steps above, bring FireFly down and replace it with the new v1.1.0 binary, then start it up again.
Ensure nodes start without errors
Ensure that FireFly starts without errors. There will likely be new deprecation warnings for config that was deprecated in v1.1.0, but these are safe to ignore for the moment. If you face any errors or crashes, please report the logs to the FireFly channel on Discord, and return your nodes to running the previous version of FireFly if necessary.
Optional: clean up old token subscriptions
Optional: clean up old multiparty subscriptions
FireFly v1.1.0 includes a new recommended version of the contract used for multi-party systems (for both Ethereum and Fabric). It also introduces a versioning method for this contract, and a path for migrating networks from one contract address to a new one.