Skip to content

v1.3.0 Migration Guide

Overview

Hyperledger FireFly v1.3.0 is a feature release that includes changes around event streaming, contract listeners, define/publish APIs as well as a range of general fixes.

For the most part, upgrading from v1.2.x to v1.3.0 should be a seamless experience, but there are several important things to note about changes between the two versions, which are described in detail on this page.

Docker image file permission considerations

Following security best practices, the official published Docker images for FireFly Core and all of its microservices now run as a non-root user by default. If you are running a FireFly release prior to v1.3.0, depending on how you were running your containers, you may need to adjust file permissions inside volumes that these containers write to. If you have overridden the default user for your containers (for example though a Kubernetes deployment) you may safely ignore this section.

⚠️ Warning: If you have been using the default root user and upgrade to FireFly v1.3.0 without changing these file permissions your services may fail to start.

The new default user is 1001. If you are not overriding the user for your container, this user or group needs to have write permissions in several places. The list of services and directories you should specifically check are:

  • firefly-evmconnect
  • persistence.leveldb.path directory set in the config file
  • firefly-ethconnect
  • rest.rest-gateway.openapi.storagePath directory in the config file
  • rest.rest-gateway.openapi.eventsDB directory in the config file
  • firefly-fabconnect
  • receipts.leveldb.path directory in the config file
  • events.leveldb.path directory in the config file
  • firefly-dataexchange-https
  • Data directory set by the DATA_DIRECTORY environment variable (default /data)

API definition/publication considerations

As of FireFly v1.3.0 in multi-party namespaces, by default, contract interfaces, contracts APIs, and token pools have distinct steps in their creation flow and by default they are unpublished.

These following described changes impact contract interfaces, contract APIs, and token pools.

Previously, when creating one of the affected resources in a multi-party network, if successful, the resource would be automatically broadcasted to other namespaces. In FireFly v1.3.0, this behaviour has changed, now when one of the resources is created there are 2 distinct states for the resource, published and unpublished. The default state for a resource (provided FireFly is not told otherwise) after creation is unpublished.

When a resource is unpublished it is not broadcasted to other namespaces in the multi-party network, and it is not pinned to the blockchain. In this state, it is possible to call the DELETE APIs to remove the resource (such as in the case where configuration needs to be changed) and reclaim the name that has been provided to it, so that it can be recreated.

When a resource is published it is broadcasted to other namespaces in the multi-party network, and it is pinned to the blockchain. In this state, it is no longer possible to call the DELETE APIs to remove the resource.

In FireFly v1.2.0 to create one of the affected resources and publish it to other parties, a POST call would be made to its respective API route and the broadcast would happen immediately. To achieve the same behaviour in FireFly v1.3.0, there are 2 options for all impacted resources, either providing a query parameter at creation to signal immediate publish, or a subsequent API call to publish the resources.

Contract interfaces

Previously, to create a contract interface a POST call would be made to /contracts/interfaces and the interface would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished interface on POST /contracts/interfaces/{name}/{version}/publish specifying the name and version of the interface.

For an exact view of the changes to contract interfaces, see PR #1279.

Contract APIs

Previously, to create a contract API a POST call would be made to /apis and the API would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished API on /apis/{apiName}/publish specifying the name of the API.

For an exact view of the changes to contract APIs, see PR #1322.

Token pools

Previously, to create a token pool a POST call would be made to /tokens/pools and the token pool would be broadcasted to all other namepsaces. In FireFly v1.3.0, this same call can be made with the publish=true query parameter, or a subsequent API call can be made on an unpublished token pool on /tokens/pools/{nameOrId}/publish specifying the name or ID of the token pool.

For an exact view of the changes to token pools, see PR #1261.

Event stream considerations

Single event stream per namespace

In this release, the model for event streams in a multi-party network has fundamentally changed. Previously, there was a single event stream for each blockchain plugin, even if this plugin served multiple namespaces. In FireFly v1.3.0 there is now a single event stream per namespace in the network.

When migrating from FireFly v1.2.X to v1.3.0, due to these changes, existing event streams will be rebuilt. This means that connectors will replay past events to FireFly, but FireFly will automatically de-duplicate them by design so this is a safe operation.

The migration to individual event streams promotes high-availability capability but is not itself a breaking change, however the ID format for event streams has changed. Event streams now follow the format <plugin_topic_name>/<namespace_name>. For example, an event stream for the default namespace with a plugin topic of 0 would now be: 0/default.

Summarily, these changes should not impact end-users of FireFly, but they're noted here as they are significant architectural changes to the relationships between namespaces, plugins, and connectors.

For an exact view of the changes, see PR #1388.

Configuration considerations

Deprecated configuration

In FireFly v1.3.0 deprecated configuration options for the blockchain, database, dataexchange, sharedstorage and tokens plugins have been removed, and can no longer be provided.

For an exact view of the changes, see PR #1289.

Token pool considerations

Activity indicator changes

Token pools have a status, when creating a token pool previously, it would go into a pending state immediately following creation, and then into a confirmed state when it has been confirmed on the chain. This behaviour is still consistent in FireFly v1.3.0, but the representation of the data has changed.

Previously, token pools had a state field with an enumerated value which was either pending, or confirmed, this has been replaced with an active boolean field, where true indicates the token pool has been committed onto chain, and false indicated the transaction has not yet been confirmed.

For an exact view of the changes, see PR #1305.

FabConnect event considerations

FabConnect Protocol ID format changes

Prior to FireFly v1.3.0, when the FabConnect client indexed events submitted by the Fabric SDK, FireFly would deduplicate events into a single event because the protocol ID of the events compiled into a single block would evaluate to be the same. In this release, we have changed the format of the calculated protocol ID so that is unique across events even if they are located within the same block. Crucially, the new format includes the transaction hash, so events are no longer alphanumerically sortable.

For an exact view of the changes, see PR #1345.

Local development considerations

Go version upgrade

FireFly v1.3.0 now uses Go 1.21 across all modules.