v2.4.0 Release Notes - November 29, 2021

New features

Fabric Gateway

Fabric Gateway is a new service running on peer nodes that manages transaction submission and processing for client applications, with the following benefits:

• Simplifies client applications and SDKs - Your client application can simply delegate transaction submission to a trusted peer. There is no need for your application to open connections to peer nodes and ordering service nodes from other organizations.
• Fabric Gateway manages collection of transaction endorsements from other organizations and submission to ordering service on behalf of client applications.
• Fabric Gateway has intelligence to determine what endorsements are required for a given transaction, even if your solution utilizes a combination of chaincode-level endorsement policies, private data collection endorsement policies, and state-based endorsement policies.

New lightweight Gateway SDKs (v1.0.0) are available for Node, Java, and Go. The SDKs support flexible application patterns:

• You can utilize the high level programming model similar to prior SDK versions, allowing your application to simply call a single SubmitTransaction() function.
• More advanced applications can leverage the gateway's individual Endorse, Submit, and CommitStatus services for transaction submission, and the Evaluate service for queries.
• You can delegate transaction endorsement entirely to the gateway, or if needed, specify the endorsing organizations and the gateway will utilize a peer from each organization.

For more information, see the Fabric Gateway documentation topic.

Unjoin a channel from a peer

The new command peer node unjoin enables an administrator to remove (unjoin) a channel from a peer.
The peer must be stopped when the command is executed so that channel artifacts can be cleaned up.
The channel's blockchain, state database, and associated entries will be removed from the peer.
When the peer is restarted it will no longer receive blocks for the channel.

For more information, see the peer node command reference.

Calculate package ID of a packaged chaincode

You can calculate the package ID from a packaged chaincode without installing the chaincode on peers using the new peer lifecycle chaincode calculatepackageid command.
This command will be useful, for example, in the following cases:

• When multiple chaincode packages with the same label name are installed, it is possible to identify which ID corresponds to which package later.
• To check whether a particular chaincode package is installed or not without installing that package.

For more information, see the peer lifecycle command reference.

Improvements

peer and orderer - Implement legacy name constraints verification for Go 1.15 and above

These changes reproduce the Go 1.14 name constraint verification in the MSP.
Without these changes, certificate chains that would fail verification in Go 1.14 would
successfully validate in Go 1.15 and above due to the change mentioned in the Go 1.15 release notes.
Specifically, if a signing certificate contains a name constraint, the leaf certificate
does not include SAN extensions, and the leaf's common name looks like a host name,
then the additional verification is performed to ensure deterministic behavior relative
to prior Fabric releases.

peer and orderer - Default log record format improvements

Expanded the width of the log record sequence number to a minimum of four characters,
moved the log sequence number and log level to the left,
and added bold formatting to the function name.
These changes keep the fixed-width columns together at the left
and add a visual break between the logging module name and log message text.

peer - New configuration option to disable gossip block forwarding

If all peers in an organization explicitly set "peer.deliveryclient.blockGossipEnabled" to false,
no peer in the organization gossips blocks to any other peer in that organization.
Use this setting when all peers pull blocks from ordering service. For more
information see deprecation announcement below: FAB-15317: Block dissemination via gossip is deprecated.

orderer - Return transaction forwarding result back to the client synchronously

With this improvement a Raft follower waits for the transaction to be forwarded to the Raft leader,
and returns the result (success or failure) back to the client accordingly.
Prior to this improvement, the Raft follower returned success after enqueueing it into the message queue,
which might have resulted in the transaction being dropped but a success being returned to the client.
Application clients should still monitor transaction commit events, since the Raft leader is not guaranteed
to deliver the transaction into a block in exception scenarios, but this improvement avoids
transactions from being dropped when there are connection issues between a Raft follower and Raft leader.

peer - Ability to override core.yaml chaincode.externalBuilders via environment variable

Since chaincode.externalBuilders is an array, it previously was not possible to set via environment variable override.
It is now possible to override chaincode.externalBuilders using an environment variable
using the format CORE_CHAINCODE_EXTERNALBUILDERS=[{name: x, path: dir1}, {name: y, path: dir2}].

peer and orderer - Make gRPC maximum message size configurable

This improvement makes gRPC maximum message size configurable in peer and orderer.
Previously the maximum message size was hardcoded to 100 megabytes.
Since all nodes should be consistent it is recommended to keep
the default value of 100 megabytes for MaxRecvMsgSize & MaxSendMsgSize.
The value can be configured if needed however.
Configure in peer core.yaml with peer.maxRecvMsgSize and peer.maxSendMsgSize.
Configure in orderer orderer.yaml with General.MaxRecvMsgSize and General.MaxSendMsgSize.

Fixes

All fixes as of v2.3.3 are included in v2.4.0. Additionally, the following fix is made in v2.4.0.

orderer - Fix bug when an orderer crashes at channel creation

This fix handles a scenario where an ordering service node crashes during channel creation.
Previously the ordering service node would attempt to re-create the channel upon next startup,
resulting in a panic with the following error:
"Error creating chain support: error creating consenter for channel: failed to restore persisted raft data: failed to create or read WAL: failed to open WAL: fileutil: file already locked".

Dependencies

Fabric v2.4.0 has been tested with the following dependencies:

• Go 1.16.7
• CouchDB v3.1.1

Fabric docker images on dockerhub utilize Alpine 3.14.

Deprecations (new)

Ordering service system channel is deprecated

v2.3 introduced the ability to manage an ordering service without a system channel.
Managing an ordering service without a system channel has privacy, scalability,
and operational benefits. The use of a system channel is deprecated and may be removed in a future release.
For information about removal of the system channel, see the Create a channel without system channel documentation.

Deprecations (existing)

FAB-15754: The 'Solo' consensus type is deprecated.

The 'Solo' consensus type has always been marked non-production and should be in
use only in test environments, however for compatibility it is still available,
but may be removed entirely in a future release.

FAB-16408: The 'Kafka' consensus type is deprecated.

The 'Raft' consensus type was introduced in v1.4.1 and has become the preferred
production consensus type. There is a documented and tested migration path from
Kafka to Raft, and existing users should migrate to the newer Raft consensus type.
For compatibility with existing deployments, Kafka is still supported,
but may be removed entirely in a future release.
Additionally, the fabric-kafka and fabric-zookeeper docker images are no longer updated, maintained, or published.

Fabric CouchDB image is deprecated

v2.2.0 added support for CouchDB 3.1.0 as the recommended and tested version of CouchDB.
If prior versions are utilized, a Warning will appear in peer log.
Note that CouchDB 3.1.0 requires that an admin username and password be set,
while this was optional in CouchDB v2.x. See the
Fabric CouchDB documentation
for configuration details.
Also note that CouchDB 3.1.0 default max_document_size is reduced to 8MB. Set a higher value if needed in your environment.
Finally, the fabric-couchdb docker image will not be updated to v3.1.0 and will no longer be updated, maintained, or published.
Users can utilize the official CouchDB docker image maintained by the Apache CouchDB project instead.

FAB-7559: Support for specifying orderer endpoints at the global level in channel configuration is deprecated.

Utilize the new 'OrdererEndpoints' stanza within the channel configuration of an organization instead.
Configuring orderer endpoints at the organization level accommodates
scenarios where orderers are run by different organizations. Using
this configuration ensures that only the TLS CA certificates of that organization
are used for orderer communications, in contrast to the global channel level endpoints which
would cause an aggregation of all orderer TLS CA certificates across
all orderer organizations to be used for orderer communications.

FAB-17428: Support for configtxgen flag --outputAnchorPeersUpdate is deprecated.

The --outputAnchorPeersUpdate mechanism for updating anchor peers has always had
limitations (for instance, it only works the first time anchor peers are updated).
Instead, anchor peer updates should be performed through the normal config update flow.

FAB-15406: The fabric-tools docker image is deprecated

The fabric-tools docker image will not be published in future Fabric releases.
Instead of using the fabric-tools docker image, users should utilize the
published Fabric binaries. The Fabric binaries can be used to make client calls
to Fabric runtime components, regardless of where the Fabric components are running.

FAB-15317: Block dissemination via gossip is deprecated

Block dissemination via gossip is deprecated and may be removed in a future release.
Fabric peers can be configured to receive blocks directly from an ordering service
node and not gossip blocks by using the following configuration:

peer.gossip.orgLeader: true
peer.gossip.useLeaderElection: false
peer.gossip.state.enabled: false
peer.deliveryclient.blockGossipEnabled: false

FAB-15061: Legacy chaincode lifecycle is deprecated

The legacy chaincode lifecycle from v1.x is deprecated and will be removed
in a future release. To prepare for the eventual removal, utilize the v2.x
chaincode lifecycle instead, by enabling V2_0 application capability on all
channels, and redeploying all chaincodes using the v2.x lifecycle. The new
chaincode lifecycle provides a more flexible and robust governance model
for chaincodes. For more details see the
documentation for enabling the new lifecycle.

Changes:

• 41b6586 v2.4.0 release commit (#3078)
• 4f4e096 Update v2.4.0 release notes
• f15b4ee Add command reference doc for ledgerutil
• 45707ac Add read version to the example in read-write set
• b0de139 Add logging for identity, policy, and signature troubleshooting
• 1266978 Clarify v2.x upgrade docs (#3083)
• 6a7cdd0 Refine Gateway gRPC error status codes (#3075)
• 40fea67 goimports updates to prepare for Go 1.17 (#3070)
• c14239c Add gateway ref to private data doc topic
• a6a9fde EndorsementTimeout should apply to each endorser