-
Notifications
You must be signed in to change notification settings - Fork 144
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update and simplify compatibility documentation (#448)
Signed-off-by: Mark S. Lewis <[email protected]>
- Loading branch information
1 parent
1e1ca14
commit 47b35f0
Showing
1 changed file
with
22 additions
and
52 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,68 +1,38 @@ | ||
| # Support and Compatibility for fabric-chaincode-node | ||
| # Support and Compatibility | ||
|
|
||
| Github is used for code base management, issues should reported in the repository's [GitHub Issues](https://github.com/hyperledger/fabric-chaincode-node/issues). | ||
| Github is used for code base management and [issue](https://github.com/hyperledger/fabric-chaincode-node/issues) tracking. | ||
|
|
||
| ## Summary of Compatibility | ||
|
|
||
| This table shows the summary of the compatibility of the Node modules at versions 1.4 and 2.x, together with the Node.js runtime they require and the Fabric Peer versions they can communicate with. | ||
| This table shows the summary of the compatibility of the Node chaincode packages, together with the Node.js runtime they require. | ||
|
|
||
| | Chaincode Docker image | Peer connectivity v1.4 | Peer connectivity v2.x | Minimum supported Node.js | Node.js runtime | | ||
| | ----------------------- | ---------------------- | ---------------------- | ------------------------- | --------------- | | ||
| | **v1.4.5** | Yes | Yes | 8 | 8 | | ||
| | **v2.2.x** | Yes | Yes | 12 | 12 | | ||
| | **v2.3.x** | Yes | Yes | 12 | 12 | | ||
| | **v2.4.x** | Yes | Yes | 16 | 16 | | ||
| | **v2.5.0** - **v2.5.4** | Yes | Yes | 18 | 18 | | ||
| | **v2.5.5** - **v2.5.7** | Yes | Yes | 18 | 20 | | ||
| | **v2.5.8+** | Yes | Yes | 18 | 22 | | ||
| | Node chaincode version | Minimum supported Node.js | Node.js runtime | Docker image platforms | | ||
| | ---------------------- | ------------------------- | --------------- | ---------------------- | | ||
| | v1.4 | 8 | 8 | amd64 | | ||
| | v2.2 | 12 | 12 | amd64 | | ||
| | v2.5.0 - v2.5.4 | 18 | 18 | amd64, arm64 | | ||
| | v2.5.5 - v2.5.7 | 18 | 20 | amd64, arm64 | | ||
| | v2.5.8+ | 18 | 22 | amd64, arm64 | | ||
|
|
||
| Whilst these are defaults based on the corresponding `fabric-nodeenv` Docker image version, the Docker image used to host the chaincode and contracts can be altered. Set the environment variable `CORE_CHAINCODE_NODE_RUNTIME` on the peer to the name of the desired Docker image and version. | ||
| The Node runtime provided by the chaincode Docker image determines the maximum Node version (and features) that smart contract code can exploit when using the default Node chaincode container. | ||
|
|
||
| For example `CORE_CHAINCODE_NODE_RUNTIME=hyperledger/fabric-nodeenv:2.2` will allow the use of a Node 12 runtime to be used within a Peer v1.4. | ||
| Subject to a suitable runtime environment, the Node chaincode libraries can be used to communicate with Fabric peers at different LTS versions. The level of functionality is determined by the Fabric version in use and channel capabilities. | ||
|
|
||
| The Node chaincode modules will connect to the peer whilst running; this is referred to as 'Fabric Peer Connectivity' in the table. For example, whilst the Fabric Peer v1.4 will create a Node.js 8 runtime, if a Node.js 12 runtime was configured, the node chaincode modules at v2.x still function when connecting to the Fabric Peer v1.4. | ||
| All Docker images, chaincode libraries and tools are tested using amd64 (x86-64) only. | ||
|
|
||
| ### Version 1.4 compatibility with later Node.js runtimes | ||
| ## Chaincode builder | ||
|
|
||
| Note that the `fabric-contract-api` & `fabric-shim` node modules must be at v1.4.5 or greater to work with Node.js version 12. If you therefore use a contract originally written to work with Fabric 1.4, check the node modules before deploying on Fabric v2. | ||
| The default Fabric chaincode builder creates a Docker container to run deployed smart contracts. Node chaincode Docker containers are built using the `hyperledger/fabric-nodeenv` Docker image, tagged with the same major and minor version as the Fabric peer version. For example, Fabric v2.5 creates Node chaincode containers using the `hyperledger/fabric-nodeenv:2.5` Docker image. Fabric v3 continues to use the v2.5 Node chaincode image. | ||
|
|
||
| Also please note that that the v1.4 libraries WILL NOT work with Node.js 16 or Node.js 18. Unless you configure a different node environment, any chaincode using the v1.4 node chaincode libraries will need to update to the v2.5 node chaincode libraries before being able to run with a Fabric v2.5 Peer. | ||
| A different chaincode Docker image can be specified using the CORE_CHAINCODE_NODE_RUNTIME environment variable on the Fabric peer. For example, CORE_CHAINCODE_NODE_RUNTIME=example/customNodeRuntime:latest. | ||
|
|
||
| ## Compatibility | ||
| With Fabric v2 and later, an alternative chaincode builder can be configured on the Fabric peer. In this case the configured chaincode builder controls how chaincode is launched. See the [Fabric documentation](https://hyperledger-fabric.readthedocs.io/en/release-2.5/cc_launcher.html) for further details. | ||
|
|
||
| The key elements are : | ||
| ## Chaincode packaging | ||
|
|
||
| - the version of the Fabric Contract Node modules used | ||
| - the version of the Node.js runtime used to run the code | ||
| - When starting a chaincode container to run a Smart Contract, the version of the runtime that is used is determined by these factors: | ||
| When using the `hyperledger/fabric-nodeenv` Node chaincode Docker images at v2 (and later), deployed chaincode is installed with npm as follows: | ||
|
|
||
| Fabric v1.4.x, and Fabric v2.x will, by default, start up a Docker container based on `fabric-nodeenv` to host the chaincode and contracts. The version of the Docker image used is driven by the version of Fabric in use, but can be overridden by setting the peer's `CORE_CHAINCODE_NODE_RUNTIME` environment variable. | ||
| - If a `package-lock.json` or a `npm-shrinkwrap.json` file is present, `npm ci --only=production` will be used. | ||
| - Otherwise, `npm install --production` will be used. | ||
|
|
||
| With Fabric v2.x, the chaincode container can be configured to be started by other means, and not the Peer. In this case, the environment used is not in the control of Fabric. | ||
|
|
||
| Node modules that are produced are `fabric-contract-api`, `fabric-shim` & `fabric-shim-api` | ||
|
|
||
| ### Supported Runtimes | ||
|
|
||
| - Fabric v1.4 Node.js chaincode modules are supported running Nodejs 8.16.1 with the x86_64 architecture. | ||
| - Fabric v2.2/v2.3 Node.js chaincode modules are supported running in Node.js 12.22.6, with the x86_64 architecture. | ||
| - Fabric v2.4 Node.js chaincode modules are supported running in Node.js 16.x, with the x86_64 architecture. | ||
| - Fabric v2.5.x Node.js chaincode modules are supported running in Node.js 18.x, with the x86_64 and arm64 architectures. | ||
|
|
||
| Architecture Support: all Docker images, runtimes, tools are tested under x86_64 ONLY | ||
|
|
||
| ### Default Peer Runtime selection | ||
|
|
||
| - Fabric 2.2/2.3 `fabric-nodeenv` Docker image is based on node:12.22.6-alpine. | ||
| - Fabric 2.4 `fabric-nodeenv` Docker image is based on node:16-alpine. | ||
| - Fabric 2.5.0 - 2.5.4 `fabric-nodeenv` Docker image is based on node:18-alpine. | ||
| - Fabric 2.5.5+ `fabric-nodeenv` Docker image is based on node:20-alpine. | ||
| - Fabric 3.0 `fabric-nodeenv` Docker image is based on node:22-alpine | ||
|
|
||
| _Note:_ With the default Docker image used by Fabric 2.x and later, the packaged code will be installed with npm. If a `package-lock.json` or a `npm-shrinkwrap.json` file is present, `npm ci --only=production` will be used. Otherwise `npm install --production` will be used. | ||
|
|
||
| When using Fabric 1.4.x, the Docker image that is used to run the Node.js chaincode is node v8.16.1. It is installed with npm install --production | ||
|
|
||
| ### Supported Runtime communication with the Peer | ||
|
|
||
| Subject to a suitable runtime environment, the 1.4.x Node.js chaincode modules and 2.x Node.js chaincode modules can be used to communicate with a Fabric 2.x or 1.4.x Peer - with the level of functionality that is implied by the Fabric version in use. | ||
| When using the v1.4 `hyperledger/fabric-nodeenv` Node chaincode Docker images, deployed chaincode is installed with `npm install --production`. |