|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: v1.1.0 Migration Guide |
| 4 | +parent: pages.release_notes |
| 5 | +nav_order: 2 |
| 6 | +--- |
| 7 | + |
| 8 | +# v1.1.0 Migration Guide |
| 9 | +{: .no_toc } |
| 10 | + |
| 11 | +## Table of contents |
| 12 | +{: .no_toc .text-delta } |
| 13 | + |
| 14 | +1. TOC |
| 15 | +{:toc} |
| 16 | + |
| 17 | +--- |
| 18 | + |
| 19 | +## Overview |
| 20 | + |
| 21 | +Hyperledger FireFly v1.1.0 is a feature release that includes significant new functionality around namespaces and plugins, as detailed in [FIR-12](https://github.com/hyperledger/firefly-fir/pull/12). As a result, upgrading an existing FireFly environment from any prior release may require special steps (depending on the functionality used). |
| 22 | + |
| 23 | +If seamless data preservation is not required, you can simply create a new network from scratch using FireFly v1.1.0. |
| 24 | + |
| 25 | +If you want to preserve data from an existing 1.0.x network, significant care has been taken to ensure that it is possible. Most existing environments can be upgraded with minimal extra steps. This document attempts to call out all potentially breaking changes (both common and uncommon), so that you can easily assess the impact of the upgrade and any needed preparation before proceeding. |
| 26 | + |
| 27 | +## Before Upgrading |
| 28 | + |
| 29 | +These steps are all safe to do while running FireFly v1.0.x. While they do not _have_ to be done prior to upgrading, performing them ahead of time may allow you to preemptively fix some problems and ease the migration to v1.1.0. |
| 30 | + |
| 31 | +### Common Steps |
| 32 | + |
| 33 | +**Upgrade to latest v1.0.x patch release** |
| 34 | + |
| 35 | +Before upgrading to v1.1.0, it is _strongly_ recommended to upgrade to the latest v1.0.x patch release (v1.0.4 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. |
| 36 | + |
| 37 | +**Fix any deprecated config usage** |
| 38 | + |
| 39 | +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. |
| 40 | + |
| 41 | +You can utilize the [ffconfig](https://github.com/hyperledger/firefly/tree/main/ffconfig) tool to automatically check and fix deprecated config with a command such as: |
| 42 | + |
| 43 | +``` |
| 44 | +ffconfig migrate -f <input-file> -o <output-file> --to 1.0.4 |
| 45 | +``` |
| 46 | + |
| 47 | +This should ensure your config file is acceptable to 1.0.x _or_ 1.1.x. |
| 48 | + |
| 49 | +Note that if you are attempting to migrate a Dockerized development environment (such as one stood up by the firefly-cli), you may need to edit the config file _inside_ the Docker. Environments created by a v1.0.x CLI do not expose the config file outside the Docker container. |
| 50 | + |
| 51 | +### Less Common Situations |
| 52 | + |
| 53 | +**Record all broadcast namespaces in the config file** |
| 54 | + |
| 55 | +<details> |
| 56 | +<summary>Expand for migration details only if your application uses non-default namespaces.</summary> |
| 57 | + |
| 58 | +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). |
| 59 | + |
| 60 | +</details> |
| 61 | + |
| 62 | +**Identify queries for organization/node identities** |
| 63 | + |
| 64 | +<details> |
| 65 | +<summary>Expand for migration details only if your application queries <code>/network/organizations</code> or <code>/network/nodes</code>.</summary> |
| 66 | + |
| 67 | +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. |
| 68 | + |
| 69 | +The simplest solution is to shut down applications until the FireFly upgrade is complete on all nodes and all identities have been re-broadcast. |
| 70 | + |
| 71 | +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: |
| 72 | + |
| 73 | +- 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). |
| 74 | +- 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). |
| 75 | + |
| 76 | +Further details on the changes to `/network` APIs are provided in the next section. |
| 77 | + |
| 78 | +</details> |
| 79 | + |
| 80 | +**Identify usage of changed APIs** |
| 81 | + |
| 82 | +<details> |
| 83 | +<summary>Expand for migration details on all changes to <code>/namespaces</code>, <code>/status</code>, and <code>/network</code> APIs.</summary> |
| 84 | + |
| 85 | +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. |
| 86 | + |
| 87 | +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. |
| 88 | + |
| 89 | +``` |
| 90 | +/network/diddocs/{did} |
| 91 | +/network/nodes |
| 92 | +/network/nodes/{nameOrId} |
| 93 | +/network/nodes/self |
| 94 | +/network/organizations |
| 95 | +/network/organizations/{nameOrId} |
| 96 | +/network/organizations/self |
| 97 | +/status |
| 98 | +/status/batchmanager |
| 99 | +``` |
| 100 | + |
| 101 | +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. |
| 102 | + |
| 103 | +``` |
| 104 | +/network/identities - replaced by existing /namespaces/{ns}/identities |
| 105 | +/network/identities/{did} - replaced by new /namespaces/{ns}/identities/{did} |
| 106 | +``` |
| 107 | + |
| 108 | +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. |
| 109 | + |
| 110 | +``` |
| 111 | +/status/pins - moved to /namespaces/{ns}/pins (or /pins to query the default namespace) |
| 112 | +/status/websockets - moved to /websockets |
| 113 | +``` |
| 114 | + |
| 115 | +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. |
| 116 | + |
| 117 | +``` |
| 118 | +/namespaces - removed all fields except "name", "description", "created" |
| 119 | +/namespaces/{ns} - same as above |
| 120 | +/namespaces/{ns}/status - removed "defaults" |
| 121 | +``` |
| 122 | + |
| 123 | +</details> |
| 124 | + |
| 125 | +**Adjust or remove usage of admin APIs** |
| 126 | + |
| 127 | +<details> |
| 128 | +<summary>Expand for migration details on all changes to <code>/admin</code> and <code>/spi</code>.</summary> |
| 129 | + |
| 130 | +FireFly provides an administrative API in addition to the normal API. In v1.1.0, this has been renamed to |
| 131 | +SPI (Service Provider Interface). Consequently, all of the routes have moved from `/admin` to `/spi`, and |
| 132 | +the config section has been renamed from `admin` to `spi`. There is no automatic migration provided, so |
| 133 | +any usage of the old routes will need to be changed, and your config file will need to be adjusted if you |
| 134 | +wish to keep the SPI enabled (although it is perfectly fine to have both `admin` and `spi` sections if |
| 135 | +needed for migration). |
| 136 | + |
| 137 | +The ability to set FireFly config via these routes has also been removed. Any usage of the `/admin/config` |
| 138 | +routes must be discontinued, and config should be set exclusively by editing the FireFly config file. |
| 139 | +The only route retained from this functionality was `/admin/config/reset`, which has been renamed to |
| 140 | +`/spi/reset` - this will continue to be available for performing a soft reset that reloads FireFly's config. |
| 141 | + |
| 142 | +</details> |
| 143 | + |
| 144 | +## Performing the Upgrade |
| 145 | + |
| 146 | +**Backup current data** |
| 147 | + |
| 148 | +Before beginning the upgrade, it is recommended to take a **full backup** of your FireFly database(s). |
| 149 | +If you encounter any serious issues after the upgrade, you should revert to the old binary and restore |
| 150 | +your database snapshot. While down-migrations are provided to revert a database in place, they are |
| 151 | +not guaranteed to work in all scenarios. |
| 152 | + |
| 153 | +**Upgrade FireFly and all dependencies** |
| 154 | + |
| 155 | +Bring FireFly down and replace it with the new v1.1.0 binary. You should also replace other runtimes (such as blockchain, data exchange, and token connectors) with the supported versions noted in the [v1.1.0 release](https://github.com/hyperledger/firefly/releases/tag/v1.1.0). Once all binaries have been replaced, start them up again. |
| 156 | + |
| 157 | +## After Upgrading |
| 158 | + |
| 159 | +**Ensure nodes start without errors** |
| 160 | + |
| 161 | +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. |
| 162 | + |
| 163 | +**Re-broadcast organization and node identities** |
| 164 | + |
| 165 | +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). |
| 166 | + |
| 167 | +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"). |
| 168 | + |
| 169 | +**Update config file to latest format** |
| 170 | + |
| 171 | +Once the network is stable, you should update your config file(s) again to remove deprecated |
| 172 | +configuration and set yourself up to take advantage of all the new configuration options |
| 173 | +available in v1.1.0. |
| 174 | + |
| 175 | +You can utilize the [ffconfig](https://github.com/hyperledger/firefly/tree/main/ffconfig) tool to automatically check and fix deprecated config with a command such as: |
| 176 | + |
| 177 | +``` |
| 178 | +ffconfig migrate -f <input-file> -o <output-file> |
| 179 | +``` |
| 180 | + |
| 181 | +## Upgrading the Multi-Party Contract |
| 182 | + |
| 183 | +FireFly v1.1.0 includes a new recommended version of the contract used for multi-party systems (for both [Ethereum](https://github.com/hyperledger/firefly/tree/main/smart_contracts/ethereum/solidity_firefly/contracts) and [Fabric](https://github.com/hyperledger/firefly/tree/main/smart_contracts/fabric/firefly-go/chaincode)). It also introduces a versioning method for this contract, and a path for migrating networks from one contract address to a new one. |
| 184 | + |
| 185 | +After upgrading FireFly itself, it is recommended to upgrade your multi-party system to the |
| 186 | +latest contract version by following these steps. |
| 187 | + |
| 188 | +1. Compile and deploy an instance of the new FireFly contract (linked above) to your blockchain, using `ff deploy` or [a similar method](https://hyperledger.github.io/firefly/tutorials/custom_contracts/ethereum.html#contract-deployment). |
| 189 | +2. Edit the config file on each node in your network, to add the new contract to the multi-party contract list like so: |
| 190 | + |
| 191 | +``` |
| 192 | +namespaces: |
| 193 | + predefined: |
| 194 | + - name: default |
| 195 | + multiparty: |
| 196 | + enabled: true |
| 197 | + contract: |
| 198 | + - location: |
| 199 | + address: 0x09f107d670b2e69a700a4d9ef1687490ae1568db |
| 200 | + - location: |
| 201 | + address: 0x1bee32b37dc48e99c6b6bf037982eb3bee0e816b |
| 202 | +``` |
| 203 | + |
| 204 | +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). |
| 205 | + |
| 206 | +3. After updating each node's configuration, restart the node and ensure it starts without issues. |
| 207 | +4. 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. |
| 208 | +5. Verify success by querying `/namespaces/{ns}/status` on each node and checking that the active multi-party contract matches the new address. |
0 commit comments