Release commit for v3.1.0

denyeart · denyeart · commit dfdb97bb2465 · 2025-03-18T12:15:31.000-04:00
Update docs and release notes for v3.1.0.

Signed-off-by: David Enyeart &lt;enyeart@us.ibm.com&gt;
diff --git a/Makefile b/Makefile
@@ -46,7 +46,7 @@
 #   - verify - runs unit tests for only the changed package tree
 
 UBUNTU_VER ?= 22.04
-FABRIC_VER ?= 3.0.0
+FABRIC_VER ?= 3.1.0
 
 # 3rd party image version
 # These versions are also set in the runners in ./integration/runners/
diff --git a/docs/source/raft_bft_migration.md b/docs/source/raft_bft_migration.md
@@ -2,7 +2,7 @@
 
 Nodes at v3.0.0 or higher allow for users who want to transition channels from using Raft-based ordering services to BFT-based ordering services.
 This can be accomplished through a series of configuration update transactions on each channel in the network.
-To migrate, upgrade from version 2.x to version 3.0.0.
+To migrate, upgrade from version 2.x to version 3.x.
 
 This tutorial will describe the migration process at a high level, calling out specific details where necessary.
 
diff --git a/docs/source/upgrading_your_components.md b/docs/source/upgrading_your_components.md
@@ -215,7 +215,7 @@ To learn how to upgrade your Fabric CA server, click over to the [CA documentati
 
 ## Upgrade SDK clients
 
-SDK applications can be upgraded separate from a general upgrade of your Fabric network. The `Fabric Gateway client API <https://github.com/hyperledger/fabric-gateway>`_ has been tested with Fabric v2.5 and v3.0. If you have not yet migrated to the Fabric Gateway client API, you can `migrate <https://hyperledger.github.io/fabric-gateway/migration/>`_ while using a Fabric v2.5 network, or after you have upgraded to a Fabric v3.0 network. The legacy SDKs are no longer maintained and are not compatible with new v3.0 Fabric features such as SmartBFT consensus.
+SDK applications can be upgraded separate from a general upgrade of your Fabric network. The [Fabric Gateway client API](https://github.com/hyperledger/fabric-gateway) has been tested with Fabric v2.5 and v3. If you have not yet migrated to the Fabric Gateway client API, you can [migrate](https://hyperledger.github.io/fabric-gateway/migration) while using a Fabric v2.5 network, or after you have upgraded to a Fabric v3 network. The legacy SDKs are no longer maintained and are not compatible with new v3 Fabric features such as SmartBFT consensus.
 
 ## Upgrading CouchDB
 
diff --git a/docs/source/whatsnew.rst b/docs/source/whatsnew.rst
@@ -1,6 +1,48 @@
 What's new in Hyperledger Fabric
 ================================
 
+What's New in Hyperledger Fabric v3.1
+-------------------------------------
+
+Performance optimization - Batching of chaincode writes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Chaincodes that write large numbers of keys were inefficient since each key write required communication between the chaincode and the peer.
+The new feature enables a chaincode developer to batch multiple writes into a single communication between the chaincode and the peer.
+A batch can be started by calling ``StartWriteBatch()``. The chaincode can then perform key writes as usual. Then when ``FinishWriteBatch()`` is called the writes
+will be sent to the peer. Batches over a configured size will be split into multiple batch segments.
+The batching approach significantly improves performance for chaincodes that write to many keys.
+Note that the batching only impacts the endorsement phase. The transaction itself, as well as the validation and commit phases, remains the same as previous versions.
+
+The batch writes are configured with the following peer core.yaml chaincode properties:
+ * ``chaincode.runtimeParams.useWriteBatch`` - boolean that indicates whether write batching is enabled on peer
+ * ``chaincode.runtimeParams.maxSizeWriteBatch`` - integer that indicates the maximum number of keys written per batch segment.
+
+The new feature requires chaincode to utilize fabric-chaincode-go v2.1.0 or higher.
+
+Performance optimization - Batching of chaincode reads
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Chaincodes that read large numbers of keys were inefficient since each key read required communication between the chaincode and the peer.
+The new feature enables a chaincode developer to batch multiple reads into a single communication between the chaincode and the peer.
+Utilize the new ``GetMultipleStates()`` and ``GetMultiplePrivateData()`` chaincode functions to perform the batch reads.
+Batches over a configured size will be split into multiple batch segments.
+
+The batch reads are configured with the following peer core.yaml chaincode properties:
+ * ``chaincode.runtimeParams.useGetMultipleKeys`` - boolean that indicates whether read batching is enabled on peer
+ * ``chaincode.runtimeParams.maxSizeGetMultipleKeys`` - integer that indicates the maximum number of keys read per batch segment
+
+The new feature requires chaincode to utilize fabric-chaincode-go v2.2.0 or higher.
+
+Query all composite keys in a chaincode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A new chaincode function ``GetAllStatesCompositeKeyWithPagination()`` is available so that all composite keys within a chaincode can be retrieved.
+This function is useful when performing bulk operations on all composite keys in a chaincode.
+
+The new feature requires chaincode to utilize fabric-chaincode-go v2.3.0 or higher.
+
+
 What's New in Hyperledger Fabric v3.0
 -------------------------------------
 
@@ -56,6 +98,7 @@ The release notes provide more details about each release.
 Additionally, take a look at the announcements about changes and deprecations that are copied into each of the latest release notes.
 
 * `Fabric v3.0.0 release notes <https://github.com/hyperledger/fabric/releases/tag/v3.0.0>`_.
+* `Fabric v3.1.0 release notes <https://github.com/hyperledger/fabric/releases/tag/v3.1.0>`_.
 
 .. Licensed under Creative Commons Attribution 4.0 International License
    https://creativecommons.org/licenses/by/4.0/
diff --git a/release_notes/v3.1.0.md b/release_notes/v3.1.0.md
@@ -0,0 +1,77 @@
+v3.1.0 Release Notes - March 18, 2025
+=====================================
+
+New features
+------------
+
+**Performance optimization - Batching of chaincode writes**
+
+Chaincodes that write large numbers of keys were inefficient since each key write required communication between the chaincode and the peer.
+The new feature enables a chaincode developer to batch multiple writes into a single communication between the chaincode and the peer.
+A batch can be started by calling `StartWriteBatch()`. The chaincode can then perform key writes as usual. Then when `FinishWriteBatch()` is called the writes
+will be sent to the peer. Batches over a configured size will be split into multiple batch segments.
+The batching approach significantly improves performance for chaincodes that write to many keys.
+Note that the batching only impacts the endorsement phase. The transaction itself, as well as the validation and commit phases, remains the same as previous versions.
+
+The batch writes are configured with the following peer core.yaml chaincode properties:
+ - `chaincode.runtimeParams.useWriteBatch` - boolean that indicates whether write batching is enabled on peer
+ - `chaincode.runtimeParams.maxSizeWriteBatch` - integer that indicates the maximum number of keys written per batch segment.
+
+The new feature requires chaincode to utilize fabric-chaincode-go v2.1.0 or higher.
+
+**Performance optimization - Batching of chaincode reads**
+
+Chaincodes that read large numbers of keys were inefficient since each key read required communication between the chaincode and the peer.
+The new feature enables a chaincode developer to batch multiple reads into a single communication between the chaincode and the peer.
+Utilize the new `GetMultipleStates()` and `GetMultiplePrivateData()` chaincode functions to perform the batch reads.
+Batches over a configured size will be split into multiple batch segments.
+
+The batch reads are configured with the following peer core.yaml chaincode properties:
+ - `chaincode.runtimeParams.useGetMultipleKeys` - boolean that indicates whether read batching is enabled on peer
+ - `chaincode.runtimeParams.maxSizeGetMultipleKeys` - integer that indicates the maximum number of keys read per batch segment
+
+The new feature requires chaincode to utilize fabric-chaincode-go v2.2.0 or higher.
+
+**Query all composite keys in a chaincode**
+
+A new chaincode function `GetAllStatesCompositeKeyWithPagination()` is available so that all composite keys within a chaincode can be retrieved.
+This function is useful when performing bulk operations on all composite keys in a chaincode.
+
+The new feature requires chaincode to utilize fabric-chaincode-go v2.3.0 or higher.
+
+
+Improvements and Fixes
+----------------------
+
+All improvements and fixes as of v2.5.12 have also been included in v3.1.0.
+
+
+Dependencies
+------------
+Fabric v3.1.0 has been tested with the following dependencies:
+* Go 1.24.0
+* CouchDB v3.4.2
+
+Fabric docker images on docker.io and ghcr.io utilize Ubuntu 22.04.
+
+
+Changes and Removals
+--------------------
+
+See the [v3.0.0 release notes](https://github.com/hyperledger/fabric/releases/tag/v3.0.0) for changes and removals between Fabric v2.x and Fabric v3.x.
+
+
+Deprecated features
+-------------------
+
+**Block dissemination via gossip is deprecated and may be removed**
+
+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
+```
