Skip to content

Migration Guide for v1.1.0

Jump to bottom
Andrew Richardson edited this page Aug 4, 2022 · 27 revisions

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.

Significant care has been taken to ensure that backward-compatibility is preserved, with the goal that most existing environments can be upgraded with minimal extra steps. However, this document attempts to call out all potentially breaking changes, so that users can easily assess the impact of the upgrade and any needed preparation before proceeding.

Before Upgrading

Common Steps

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.

Less Common Situations

Record all broadcast namespaces in the config file

Expand for migration details only if your application uses non-default namespaces.

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).

Identify queries for organization/node identities

Expand for migration details only if your application queries /network/organizations or /network/nodes.

Applications that query /network/organizations or /network/nodes will temporarily receive empty result lists after upgrading to v1.1.0, just until all identities have been re-registered (see steps in "After Upgrading"). This is because organization and node identities were broadcast on a global "ff_system" namespace in v1.0, but are no longer global in v1.1.0.

The simplest solution is to shut down applications until the FireFly upgrade is complete on all nodes and all identities have been re-broadcast.

If this poses a problem and you require zero downtime from these APIs, you can proactively mitigate with the following steps in your application code:

  • Applications that query the /network/organizations may be altered to also query /namespaces/ff_system/network/organizations and combine the results (but should disregard the second query if it fails).
  • Applications that query the /network/nodes may be altered to also query /namespaces/ff_system/network/nodes and combine the results (but should disregard the second query if it fails).

Further details on the changes to /network APIs are provided in the next section.

Identify usage of changed APIs

Expand for migration details on all changes to /namespaces, /status, and /network APIs.

The primary API change in this version is that the "global" paths beginning with /network and /status have been relocated under the /namespaces/{ns} prefix, as this data is now specific to a namespace instead of being global. At the same time, the API server has been enhanced so that omitting a namespace from an API path will query the default namespace instead. That is, querying /messages is now the same as querying /namespaces/default/messages (assuming your default namespace is named "default"). This has the effect that most of the moved APIs will continue to function without requiring changes. See below for details on the affected paths.

These global routes have been moved under /namespaces/{ns}. Continuing to use them without the namespace prefix will still work, and will simply query the default namespace.

/network/diddocs/{did}
/network/nodes
/network/nodes/{nameOrId}
/network/nodes/self
/network/organizations
/network/organizations/{nameOrId}
/network/organizations/self
/status
/status/batchmanager

These global routes have been moved under /namespaces/{ns} and have also been deprecated in favor of a new route name. Continuing to use them without the namespace prefix will still work, and will simply query the default namespace. However, it is recommended to switch to the new API spelling when possible.

/network/identities - replaced by existing /namespaces/{ns}/identities
/network/identities/{did} - replaced by new /namespaces/{ns}/identities/{did}

These global routes have been have been permanently renamed. They are deemed less likely to be used by client applications, but any usage will be broken by this release and must be changed after upgrading.

/status/pins - moved to /namespaces/{ns}/pins (or /pins to query the default namespace)
/status/websockets - moved to /websockets

The response bodies of the following APIs have also had fields removed. Any usage of the removed fields will be broken by this release and must be changed after upgrading.

/namespaces - removed all fields except "name", "description", "created"
/namespaces/{ns} - same as above
/namespaces/{ns}/status - removed "defaults"

Performing the Upgrade

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.

After Upgrading

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.

Re-broadcast organization and node identities

Once all nodes in the multiparty network have been upgraded and are running without errors, each node should re-broadcast its org and node identity by invoking /network/organizations/self and /network/nodes/self (or, if your application uses a non-default namespace, by invoking the /namespace/{ns}-prefixed versions of these APIs).

This will ensure that queries to /network/organizations and /network/nodes return the expected results, and will register the identities in a way that can be supported by both V1 and V2 multiparty contracts (see "Upgrading the Multi-Party Contract").

Update config file to latest format

TODO

Upgrading the Multi-Party Contract

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.

It is recommended to upgrade your multi-party system to the latest contract version by following these steps.

  1. Compile and deploy an instance of the new FireFly contract (linked above) to your blockchain, using ff deploy or a similar method.
  2. Edit the config file on each node in your network, to add the new contract to the multi-party contract list like so:
namespaces:
  predefined:
  - name: default
    multiparty:
      enabled: true
      contract:
      - location:
          address: 0x09f107d670b2e69a700a4d9ef1687490ae1568db
      - location:
          address: 0x1bee32b37dc48e99c6b6bf037982eb3bee0e816b

This example assumes 0x09f1... represents the address of the original contract, and 0x1bee... represents the new one. Note that if you have multiple namespaces, you must repeat this step for each namespace in the config - and you must deploy a unique contract instance per namespace (in the new network rules, multiple namespaces cannot share a single contract).

  1. After updating each node's configuration, restart the node and ensure it starts without issues.
  2. Have any member of the multi-party network invoke the /namespaces/{ns}/network/action FireFly API with a body of {"type": "terminate"}. This will terminate the old contract and instruct all members to move simultaneously to the newly configured one.
  3. Verify success by querying /namespaces/{ns}/status on each node and checking that the active multi-party contract matches the new address.
Clone this wiki locally