github.com/osdi23p228/fabric@v0.0.0-20221218062954-77808885f5db/release_notes/v2.2.0.md

v2.2.0 Release Notes - July 9, 2020
===================================

What's New in Hyperledger Fabric v2.2
-------------------------------------

**FAB-13460: Add Support for TLS 1.3**

TLS 1.3 is now supported and will be utilized automatically if client supports TLS 1.3.

**FAB-17401: Add function to query the details of the approved chaincode definition**

Add support to query an organization's approved chaincode definition from its peer.
The function is available by using peer CLI command `peer lifecycle chaincode queryapproved`.


Fixes
-----

**Return Error From PKCS11 CreateSession**

The prior implementation of BCCSP performed a fatal
logging function in the event it could not open a session
with the HSM.  It was possible for the fatal log to occur when an expected error
occurred, i.e., the HSM had reached its maximum session handles.
Instead of issuing a fatal log call, an error is returned so that
the error can be properly handled.

**FAB-17819: Discovery returns user friendly errors**

Service discovery endorsement service error message "cannot satisfy any principal combination" is
improved to return a more specific message, either "no peer combination can satisfy the endorsement policy"
or "required chaincodes are not installed on sufficient peers".

**FAB-17774: Support orderer restart without system channel genesis block**

When BootstrapMethod was set to 'file', the system channel genesis block
was required to be passed for every orderer service start. The system
channel genesis block is now only required for the initial orderer start.

**FAB-17844: External builder fails to copy symlinks from build output into persistent directory**

Previously, the external builder code did not check for symlinks in build output when copying them.
This resulted in the resolved files being copied as files instead of symlinks. The external builder
now copies them as symlinks instead of copying them as files into the destination directory.

**Errors should be checked when orderer gRPC server is serving requests**

gRPC errors are now checked when servicing the orderer atomic broadcast gRPC service.

**FAB-17900: Fix environment variable override bug**

Integer config values for peer and orderer could not be overridden with environment variables.

**FAB-17951: Fetch correct node id for orderer consenter validation**

Config update validator may incorrectly reject updates if some nodes are inactive.

**FAB-17875: Fix ordering service node leader election failure**

Previously with Raft consensus, when one ordering service node was deleted
from a channel and rejoined later, it would be assigned a new Raft id.
However, in some cases the ordering service node still used the old Raft
id. Other ordering service nodes including the leader are using the latest view and believe
that the rejoined node would use a new Raft id.  This may result in leader election failure and no new
transactions would be accepted. The fix ensures the correct Raft id is used after tracking the latest config block.

**Private data performance optimization: purge transient store in background**

Private data performance is improved by purging entries present in the transient store in the background.

**FAB-17933: Fix cache update logic for installed chaincode info when an empty or uninstalled package ID is specified**

Previous cache update logic for install chaincode info did not work properly when an empty or uninstalled package ID was specified.

**FAB-17539: Always remember gossip anchor peers in membership**

Gossip removes a peer from its membership cache if no new heartbeats are received from the peer within a timely manner.
If a network partition persists for too long, peers of different organizations never re-establish communication because all membership is purged.
With the fix, anchor peers are no longer removed from the membership cache even if they are offline.
Therefore, after the network partition is healed, peers among different organizations can reestablish communication as long as anchor peers are reachable.

**Note: Fixes included in v2.1.1 release notes are also included in v2.2.**

Changes
-------

**FAB-17786: upgrade_dbs peer command now drops state CouchDB databases**

Previously the upgrade_dbs command did not automatically drop state CouchDB
databases and therefore a separate step was required to drop CouchDB data
when upgrading to v2.x. upgrade_dbs command now automatically drops
state CouchDB databases. CouchDB state database will get rebuilt on the first
peer start after the upgrade to v2.x. CouchDB database service
must be available when running upgrade_dbs command. Similarly,
rebuild-dbs also drops state CouchDB data now, so that state database
can be rebuilt on the next peer start.

**FAB-17869: Allow TLS CAs with overlapping issuers**

The client root TLS CA certificate pool construction didn't allow different issuers
with the same subject name to exist in the CA cert pool. Different issuers with
the same subject name are now allowed.

**Fabric CouchDB tests have been updated from CouchDB 2.3.1 to CouchDB 3.1.0**

Support is added 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](https://hyperledger-fabric.readthedocs.io/en/release-2.2/couchdb_as_state_database.html#couchdb-configuration)
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-17917: Peer CouchDB default `maxRetriesOnStartup` property has been updated**

Peer property `peer.ledger.state.couchDBConfig.maxRetriesOnStartup` default has
changed from 12 to 10. The time between retries doubles after each attempt.
Therefore if CouchDB is not yet started, the peer start will now retry
for about 2 minutes rather than 16 minutes before retries are exhausted.

**FAB-16435: Peer gossip defaults have been updated**

Block dissemination via gossip may be removed in a future release,
since it is more straightforward for peers to simply pull blocks from ordering service.
The gossip defaults have been updated to prepare users for this possible change, so that peers by default
pull blocks from ordering service, do not use leader election, and do not use block transfer across peers.
Additionally, two block cache default sizes have been lowered to reduce the memory
used by a peer when it has joined many channels.
The new defaults are as follows:
```
peer.gossip.orgLeader: true
peer.gossip.useLeaderElection: false
peer.gossip.state.enabled: false
peer.gossip.maxBlockCountToStore: 10
peer.gossip.state.blockBufferSize: 20
```
Default configuration values are included in the peer docker image, therefore if you apply
the new peer image the new defaults will be effective unless you specifically override them
in your configuration.

**Build Your First Network sample and tutorial has been removed**

Users are recommended to use the [test network](https://hyperledger-fabric.readthedocs.io/en/release-2.2/test_network.html) introduced in v2.0 instead,
and to review the new [deployment guides](https://hyperledger-fabric.readthedocs.io/en/release-2.2/deployment_guide_overview.html).

**FAB-18028: Replace `environmentWhiteList` peer property with `propagateEnvironment`**

Peer configuration property `peer.chaincode.externalBuilders.environmentWhiteList` has been replaced with `peer.chaincode.externalBuilders.propagateEnvironment`.
`environmentWhiteList` continues to work but is deprecated.


Dependency updates
------------------
Fabric project now uses Go modules for vendoring code dependencies.

Bump Go gRPC to 1.29.1.

Bump Go to 1.14.4.

Bump Alpine to 3.12 in Fabric images.

CouchDB 3.1.0 is now the tested CouchDB version.


Deprecations
------------

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

**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 by using the following configuration:
```
peer.gossip.orgLeader: true
peer.gossip.useLeaderElection: false
peer.gossip.state.enabled: 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](https://hyperledger-fabric.readthedocs.io/en/release-2.2/enable_cc_lifecycle.html).


Change log
----------
For the full list of changes, refer to the release change log:
https://github.com/osdi23p228/fabric/blob/release-2.2/CHANGELOG.md#v220