github.com/true-sqn/fabric@v2.1.1+incompatible/docs/source/chaincode_lifecycle.md (about) 1 # Fabric chaincode lifecycle 2 3 ## What is Chaincode? 4 5 Chaincode is a program, written in [Go](https://golang.org), [Node.js](https://nodejs.org), 6 or [Java](https://java.com/en/) that implements a prescribed interface. 7 Chaincode runs in a secured Docker container isolated from the endorsing peer 8 process. Chaincode initializes and manages ledger state through transactions 9 submitted by applications. 10 11 A chaincode typically handles business logic agreed to by members of the 12 network, so it may be considered as a "smart contract". Ledger updates created 13 by a chaincode are scoped exclusively to that chaincode and can't be accessed 14 directly by another chaincode. However, within the same network, given the 15 appropriate permission a chaincode may invoke another chaincode to access 16 its state. 17 18 In this concept topic, we will explore chaincode through the eyes of a 19 blockchain network operator rather than an application developer. Chaincode 20 operators can use this topic as a guide to how to use the Fabric chainode 21 lifecycle to deploy and manage chaincode on their network. 22 23 ## Deploying a chaincode 24 25 The Fabric chaincode lifecycle is a process that allows multiple organizations 26 to agree on how a chaincode will be operated before it can be used on a channel. 27 A network operator would use the Fabric lifecycle to perform the following tasks: 28 29 - [Install and define a chaincode](#install-and-define-a-chaincode) 30 - [Upgrade a chaincode](#upgrade-a-chaincode) 31 - [Deployment Scenarios](#deployment-scenarios) 32 - [Migrate to the new Fabric lifecycle](#migrate-to-the-new-fabric-lifecycle) 33 34 You can use the Fabric chaincode lifecycle by creating a new channel and setting 35 the channel capabilities to V2_0. You will not be able to use the old lifecycle 36 to install, instantiate, or update a chaincode on channels with V2_0 capabilities 37 enabled. However, you can still invoke chaincode installed using the previous 38 lifecycle model after you enable V2_0 capabilities. If you are upgrading from a 39 v1.4.x network and need to edit your channel configurations to enable the new 40 lifecycle, check out [Enabling the new chaincode lifecycle](./enable_cc_lifecycle.html). 41 42 ## Install and define a chaincode 43 44 Fabric chaincode lifecycle requires that organizations agree to the parameters 45 that define a chaincode, such as name, version, and the chaincode endorsement 46 policy. Channel members come to agreement using the following four steps. Not 47 every organization on a channel needs to complete each step. 48 49 1. **Package the chaincode:** This step can be completed by one organization or 50 by each organization. 51 2. **Install the chaincode on your peers:** Every organization that will use the 52 chaincode to endorse a transaction or query the ledger needs to complete this 53 step. 54 3. **Approve a chaincode definition for your organization:** Every organization 55 that will use the chaincode needs to complete this step. The chaincode 56 definition needs to be approved by a sufficient number of organizations 57 to satisfy the channel's LifecycleEndorsment policy (a majority, by default) 58 before the chaincode can be started on the channel. 59 4. **Commit the chaincode definition to the channel:** The commit transaction 60 needs to be submitted by one organization once the required number of 61 organizations on the channel have approved. The submitter first collects 62 endorsements from enough peers of the organizations that have approved, and 63 then submits the transaction to commit the chaincode definition. 64 65 This topic provides a detailed overview of the operations of the Fabric 66 chaincode lifecycle rather than the specific commands. To learn more about how 67 to use the Fabric lifecycle using the Peer CLI, see the 68 [Deploying a smart contract to a channel tutorial](deploy_chaincode.html) 69 or the [peer lifecycle command reference](commands/peerlifecycle.html). 70 71 ### Step One: Packaging the smart contract 72 73 Chaincode needs to be packaged in a tar file before it can be installed on your 74 peers. You can package a chaincode using the Fabric peer binaries, the Node 75 Fabric SDK, or a third party tool such as GNU tar. When you create a chaincode 76 package, you need to provide a chaincode package label to create a succinct and 77 human readable description of the package. 78 79 If you use a third party tool to package the chaincode, the resulting file needs 80 to be in the format below. The Fabric peer binaries and the Fabric SDKs will 81 automatically create a file in this format. 82 - The chaincode needs to be packaged in a tar file, ending with a `.tar.gz` file 83 extension. 84 - The tar file needs to contain two files (no directory): a metadata file 85 "metadata.json" and another tar containing the chaincode files. 86 - "metadata.json" contains JSON that specifies the 87 chaincode language, code path, and package label. You can see an example of 88 a metadata file below: 89 ``` 90 {"Path":"fabric-samples/chaincode/fabcar/go","Type":"golang","Label":"fabcarv1"} 91 ``` 92 93 ![Packaging the chaincode](lifecycle/Lifecycle-package.png) 94 95 *The chaincode is packaged separately by Org1 and Org2. Both organizations use 96 MYCC_1 as their package label in order to identify the package using the name 97 and version. It is not necessary for organizations to use the same package 98 label.* 99 100 ### Step Two: Install the chaincode on your peers 101 102 You need to install the chaincode package on every peer that will execute and 103 endorse transactions. Whether using the CLI or an SDK, you need to complete this 104 step using your **Peer Administrator**. Your peer will build the chaincode 105 after the chaincode is installed, and return a build error if there is a problem 106 with your chaincode. It is recommended that organizations only package a chaincode 107 once, and then install the same package on every peer that belongs to their org. 108 If a channel wants to ensure that each organization is running the same chaincode, 109 one organization can package a chaincode and send it to other channel members 110 out of band. 111 112 A successful install command will return a chaincode package identifier, which 113 is the package label combined with a hash of the package. This package 114 identifier is used to associate a chaincode package installed on your peers with 115 a chaincode definition approved by your organization. **Save the identifier** 116 for next step. You can also find the package identifier by querying the packages 117 installed on your peer using the Peer CLI. 118 119 ![Installing the chaincode](lifecycle/Lifecycle-install.png) 120 121 *A peer administrator from Org1 and Org2 installs the chaincode package MYCC_1 122 on the peers joined to the channel. Installing the chaincode package builds the 123 chaincode and creates a package identifier of MYCC_1:hash.* 124 125 ### Step Three: Approve a chaincode definition for your organization 126 127 The chaincode is governed by a **chaincode definition**. When channel members 128 approve a chaincode definition, the approval acts as a vote by an organization 129 on the chaincode parameters it accepts. These approved organization definitions 130 allow channel members to agree on a chaincode before it can be used on a channel. 131 The chaincode definition includes the following parameters, which need to be 132 consistent across organizations: 133 134 - **Name:** The name that applications will use when invoking the chaincode. 135 - **Version:** A version number or value associated with a given chaincodes 136 package. If you upgrade the chaincode binaries, you need to change your 137 chaincode version as well. 138 - **Sequence:** The number of times the chaincode has been defined. This value 139 is an integer, and is used to keep track of chaincode upgrades. For example, 140 when you first install and approve a chaincode definition, the sequence number 141 will be 1. When you next upgrade the chaincode, the sequence number will be 142 incremented to 2. 143 - **Endorsement Policy:** Which organizations need to execute and validate the 144 transaction output. The endorsement policy can be expressed as a string passed 145 to the CLI, or it can reference a policy in the channel config. By 146 default, the endorsement policy is set to ``Channel/Application/Endorsement``, 147 which defaults to require that a majority of organizations in the channel 148 endorse a transaction. 149 - **Collection Configuration:** The path to a private data collection definition 150 file associated with your chaincode. For more information about private data 151 collections, see the [Private Data architecture reference](https://hyperledger-fabric.readthedocs.io/en/{BRANCH}/private-data-arch.html). 152 - **ESCC/VSCC Plugins:** The name of a custom endorsement or validation 153 plugin to be used by this chaincode. 154 - **Initialization:** If you use the low level APIs provided by the Fabric Chaincode 155 Shim API, your chaincode needs to contain an `Init` function that is used to 156 initialize the chaincode. This function is required by the chaincode interface, 157 but does not necessarily need to invoked by your applications. When you approve 158 a chaincode definition, you can specify whether `Init` must be called prior to 159 Invokes. If you specify that `Init` is required, Fabric will ensure that the `Init` 160 function is invoked before any other function in the chaincode and is only invoked 161 once. Requesting the execution of the `Init` function allows you to implement 162 logic that is run when the chaincode is initialized, for example to set some 163 initial state. You will need to call `Init` to initialize the chaincode every 164 time you increment the version of a chaincode, assuming the chaincode definition 165 that increments the version indicates that `Init` is required. 166 167 If you are using the Fabric peer CLI, you can use the `--init-required` flag 168 when you approve and commit the chaincode definition to indicate that the `Init` 169 function must be called to initialize the new chaincode version. To call `Init` 170 using the Fabric peer CLI, use the `peer chaincode invoke` command and pass the 171 `--isInit` flag. 172 173 If you are using the Fabric contract API, you do not need to include an `Init` 174 method in your chaincode. However, you can still use the `--init-required` flag 175 to request that the chaincode be initialized by a call from your applications. 176 If you use the `--init-required` flag, you will need to pass the `--isInit` flag 177 or parameter to a chaincode call in order to initialize the chaincode every time 178 you increment the chaincode version. You can pass `--isInit` and initialize the 179 chaincode using any function in your chaincode. 180 181 The chaincode definition also includes the **Package Identifier**. This is a 182 required parameter for each organization that wants to use the chaincode. The 183 package ID does not need to be the same for all organizations. An organization 184 can approve a chaincode definition without installing a chaincode package or 185 including the identifier in the definition. 186 187 Each channel member that wants to use the chaincode needs to approve a chaincode 188 definition for their organization. This approval needs to be submitted to the 189 ordering service, after which it is distributed to all peers. This approval 190 needs to be submitted by your **Organization Administrator**. After the approval 191 transaction has been successfully submitted, the approved definition is stored 192 in a collection that is available to all the peers of your organization. As a 193 result you only need to approve a chaincode for your organization once, even if 194 you have multiple peers. 195 196 ![Approving the chaincode definition](lifecycle/Lifecycle-approve.png) 197 198 *An organization administrator from Org1 and Org2 approve the chaincode definition 199 of MYCC for their organization. The chaincode definition includes the chaincode 200 name, version, and the endorsement policy, among other fields. Since both 201 organizations will use the chaincode to endorse transactions, the approved 202 definitions for both organizations need to include the packageID.* 203 204 ### Step Four: Commit the chaincode definition to the channel 205 206 Once a sufficient number of channel members have approved a chaincode definition, 207 one organization can commit the definition to the channel. You can use the 208 ``checkcommitreadiness`` command to check whether committing the chaincode 209 definition should be successful based on which channel members have approved a 210 definition before committing it to the channel using the peer CLI. The commit 211 transaction proposal is first sent to the peers of channel members, who query the 212 chaincode definition approved for their organizations and endorse the definition 213 if their organization has approved it. The transaction is then submitted to the 214 ordering service, which then commits the chaincode definition to the channel. 215 The commit definition transaction needs to be submitted as the **Organization** 216 **Administrator**. 217 218 The number of organizations that need to approve a definition before it can be 219 successfully committed to the channel is governed by the 220 ``Channel/Application/LifecycleEndorsement`` policy. By default, this policy 221 requires that a majority of organizations in the channel endorse the transaction. 222 The LifecycleEndorsement policy is separate from the chaincode endorsement 223 policy. For example, even if a chaincode endorsement policy only requires 224 signatures from one or two organizations, a majority of channel members still 225 need to approve the chaincode definition according to the default policy. When 226 committing a channel definition, you need to target enough peer organizations in 227 the channel to satisfy your LifecycleEndorsement policy. You can learn more 228 about the Fabric chaincode lifecycle policies in the [Policies concept topic](policies/policies.html). 229 230 You can also set the ``Channel/Application/LifecycleEndorsement`` policy to be a 231 signature policy and explicitly specify the set of organizations on the channel 232 that can approve a chaincode definition. This allows you to create a channel where 233 a select number of organizations act as chaincode administrators and govern the 234 business logic used by the channel. You can also use a signature policy if your 235 channel has a large number Idemix organizations, which cannot approve 236 chaincode definitions or endorse chaincode and may prevent the channel from 237 reaching a majority as a result. 238 239 ![Committing the chaincode definition to the channel](lifecycle/Lifecycle-commit.png) 240 241 *One organization administrator from Org1 or Org2 commits the chaincode definition 242 to the channel. The definition on the channel does not include the packageID.* 243 244 An organization can approve a chaincode definition without installing the 245 chaincode package. If an organization does not need to use the chaincode, they 246 can approve a chaincode definition without a package identifier to ensure that 247 the Lifecycle Endorsement policy is satisfied. 248 249 After the chaincode definition has been committed to the channel, the chaincode 250 container will launch on all of the peers where the chaincode has been installed, 251 allowing channel members to start using the chaincode. It may take a few minutes for 252 the chaincode container to start. You can use the chaincode definition to require 253 the invocation of the ``Init`` function to initialize the chaincode. If the 254 invocation of the ``Init`` function is requested, the first invoke of the 255 chaincode must be a call to the ``Init`` function. The invoke of the ``Init`` 256 function is subject to the chaincode endorsement policy. 257 258 ![Starting the chaincode on the channel](lifecycle/Lifecycle-start.png) 259 260 *Once MYCC is defined on the channel, Org1 and Org2 can start using the chaincode. The first invoke of the chaincode on each peer starts the chaincode 261 container on that peer.* 262 263 ## Upgrade a chaincode 264 265 You can upgrade a chaincode using the same Fabric lifecycle process as you used 266 to install and start the chainocode. You can upgrade the chaincode binaries, or 267 only update the chaincode policies. Follow these steps to upgrade a chaincode: 268 269 1. **Repackage the chaincode:** You only need to complete this step if you are 270 upgrading the chaincode binaries. 271 272 ![Re-package the chaincode package](lifecycle/Lifecycle-upgrade-package.png) 273 274 *Org1 and Org2 upgrade the chaincode binaries and repackage the chaincode. Both organizations use a different package label.* 275 276 2. **Install the new chaincode package on your peers:** Once again, you only 277 need to complete this step if you are upgrading the chaincode binaries. 278 Installing the new chaincode package will generate a package ID, which you will 279 need to pass to the new chaincode definition. You also need to change the 280 chaincode version, which is used by the lifecycle process to track if the 281 chaincode binaries have been upgraded. 282 283 ![Re-install the chaincode package](lifecycle/Lifecycle-upgrade-install.png) 284 285 *Org1 and Org2 install the new package on their peers. The installation creates a new packageID.* 286 287 3. **Approve a new chaincode definition:** If you are upgrading the chaincode 288 binaries, you need to update the chaincode version and the package ID in the 289 chaincode definition. You can also update your chaincode endorsement policy 290 without having to repackage your chaincode binaries. Channel members simply 291 need to approve a definition with the new policy. The new definition needs to 292 increment the **sequence** variable in the definition by one. 293 294 ![Approve a new chaincode definition](lifecycle/Lifecycle-upgrade-approve.png) 295 296 *Organization administrators from Org1 and Org2 approve the new chaincode definition for their respective organizations. The new definition references the new packageID and changes the chaincode version. Since this is the first update of the chaincode, the sequence is incremented from one to two.* 297 298 4. **Commit the definition to the channel:** When a sufficient number of channel 299 members have approved the new chaincode definition, one organization can 300 commit the new definition to upgrade the chaincode definition to the channel. 301 There is no separate upgrade command as part of the lifecycle process. 302 303 ![Commit the new definition to the channel](lifecycle/Lifecycle-upgrade-commit.png) 304 305 *An organization administrator from Org1 or Org2 commits the new chaincode definition to the channel.* 306 307 After you commit the chaincode definition, a new chaincode container will 308 launch with the code from the upgraded chaincode binaries. If you requested the 309 execution of the ``Init`` function in the chaincode definition, you need to 310 initialize the upgraded chaincode by invoking the ``Init`` function again after 311 the new definition is successfully committed. If you updated the chaincode 312 definition without changing the chaincode version, the chaincode container will 313 remain the same and you do not need to invoke ``Init`` function. 314 315 ![Upgrade the chaincode](lifecycle/Lifecycle-upgrade-start.png) 316 317 *Once the new definition has been committed to the channel, each peer will automatically start the new chaincode container.* 318 319 The Fabric chaincode lifecycle uses the **sequence** in the chaincode definition 320 to keep track of upgrades. All channel members need to increment the sequence 321 number by one and approve a new definition to upgrade the chaincode. The version 322 parameter is used to track the chaincode binaries, and needs to be changed only 323 when you upgrade the chaincode binaries. 324 325 ## Deployment scenarios 326 327 The following examples illustrate how you can use the Fabric chaincode lifecycle 328 to manage channels and chaincode. 329 330 ### Joining a channel 331 332 A new organization can join a channel with a chaincode already defined, and start 333 using the chaincode after installing the chaincode package and approving the 334 chaincode definition that has already been committed to the channel. 335 336 ![Approve a chaincode definition](lifecycle/Lifecycle-join-approve.png) 337 338 *Org3 joins the channel and approves the same chaincode definition that was 339 previously committed to the channel by Org1 and Org2.* 340 341 After approving the chaincode definition, the new organization can start using 342 the chaincode after the package has been installed on their peers. The definition 343 does not need to be committed again. If the endorsement policy is set the default 344 policy that requires endorsements from a majority of channel members, then the 345 endorsement policy will be updated automatically to include the new organization. 346 347 ![Start the chaincode](lifecycle/Lifecycle-join-start.png) 348 349 *The chaincode container will start after the first invoke of the chaincode on 350 the Org3 peer.* 351 352 ### Updating an endorsement policy 353 354 You can use the chaincode definition to update an endorsement policy without 355 having to repackage or re-install the chaincode. Channel members can approve 356 a chaincode definition with a new endorsement policy and commit it to the 357 channel. 358 359 ![Approve new chaincode definition](lifecycle/Lifecycle-endorsement-approve.png) 360 361 *Org1, Org2, and Org3 approve a new endorsement policy requiring that all three 362 organizations endorse a transaction. They increment the definition sequence from 363 one to two, but do not need to update the chaincode version.* 364 365 The new endorsement policy will take effect after the new definition is 366 committed to the channel. Channel members do not have to restart the chaincode 367 container by invoking the chaincode or executing the `Init` function in order to 368 update the endorsement policy. 369 370 ![Commit new chaincode definition](lifecycle/Lifecycle-endorsement-commit.png) 371 372 *One organization commits the new chaincode definition to the channel to 373 update the endorsement policy.* 374 375 ### Approving a definition without installing the chaincode 376 377 You can approve a chaincode definition without installing the chaincode package. 378 This allows you to endorse a chaincode definition before it is committed to the 379 channel, even if you do not want to use the chaincode to endorse transactions or 380 query the ledger. You need to approve the same parameters as other members of the 381 channel, but not need to include the packageID as part of the chaincode 382 definition. 383 384 ![Org3 does not install the chaincode](lifecycle/Lifecycle-no-package.png) 385 386 *Org3 does not install the chaincode package. As a result, they do not need to 387 provide a packageID as part of chaincode definition. However, Org3 can still 388 endorse the definition of MYCC that has been committed to the channel.* 389 390 ### One organization disagrees on the chaincode definition 391 392 An organization that does not approve a chaincode definition that has been 393 committed to the channel cannot use the chaincode. Organizations that have 394 either not approved a chaincode definition, or approved a different chaincode 395 definition will not be able to execute the chaincode on their peers. 396 397 ![Org3 disagrees on the chaincode](lifecycle/Lifecycle-one-disagrees.png) 398 399 *Org3 approves a chaincode definition with a different endorsement policy than 400 Org1 and Org2. As a result, Org3 cannot use the MYCC chaincode on the channel. 401 However, Org1 or Org2 can still get enough endorsements to commit the definition 402 to the channel and use the chaincode. Transactions from the chaincode will still 403 be added to the ledger and stored on the Org3 peer. However, the Org3 will not 404 be able to endorse transactions.* 405 406 An organization can approve a new chaincode definition with any sequence number 407 or version. This allows you to approve the definition that has been committed 408 to the channel and start using the chaincode. You can also approve a new 409 chaincode definition in order to correct any mistakes made in the process of 410 approving or packaging a chaincode. 411 412 ### The channel does not agree on a chaincode definition 413 414 If the organizations on a channel do not agree on a chaincode definition, the 415 definition cannot be committed to the channel. None of the channel members will 416 be able to use the chaincode. 417 418 ![Majority disagree on the chaincode](lifecycle/Lifecycle-majority-disagree.png) 419 420 *Org1, Org2, and Org3 all approve different chaincode definitions. As a result, 421 no member of the channel can get enough endorsements to commit a chaincode 422 definition to the channel. No channel member will be able to use the chaincode.* 423 424 ### Organizations install different chaincode packages 425 426 Each organization can use a different packageID when they approve a chaincode 427 definition. This allows channel members to install different chaincode binaries 428 that use the same endorsement policy and read and write to data in the same 429 chaincode namespace. 430 431 Organizations can use this capability to install smart contracts that 432 contain business logic that is specific to their organization. Each 433 organization's smart contract could contain additional validation that the 434 organization requires before their peers endorse a transaction. Each organization 435 can also write code that helps integrate the smart contract with data from their 436 existing systems. 437 438 ![Using different chaincode binaries](lifecycle/Lifecycle-binaries.png) 439 440 *Org1 and Org2 each install versions of the MYCC chaincode containing business 441 logic that is specific to their organization.* 442 443 ### Creating multiple chaincodes using one package 444 445 You can use one chaincode package to create multiple chaincode instances on a 446 channel by approving and committing multiple chaincode definitions. Each 447 definition needs to specify a different chaincode name. This allows you to run 448 multiple instances of a smart contract on a channel, but have the contract be 449 subject to different endorsement policies. 450 451 ![Starting multiple chaincodes](lifecycle/Lifecycle-multiple.png) 452 453 *Org1 and Org2 use the MYCC_1 chaincode package to approve and commit two 454 different chaincode definitions. As a result, both peers have two chaincode 455 containers running on their peers. MYCC1 has an endorsement policy of 1 out of 2, 456 while MYCC2 has an endorsement policy of 2 out of 2.* 457 458 ## Migrate to the new Fabric lifecycle 459 460 For information about migrating to the new lifecycle, check out [Considerations for getting to v2.0](./upgrade_to_newest_version.html#chaincode-lifecycle). 461 462 If you need to update your channel configurations to enable the new lifecycle, check out [Enabling the new chaincode lifecycle](./enable_cc_lifecycle.html). 463 464 ## More information 465 466 You can watch video below to learn more about the motivation of the new Fabric chaincode lifecycle and how it is implemented. 467 468 <iframe class="embed-responsive-item" id="youtubeplayer2" title="Starter Plan videos" type="text/html" width="560" height="315" src="https://www.youtube.com/embed/XvEMDScFU2M" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen> </iframe> 469 470 <!--- Licensed under Creative Commons Attribution 4.0 International License 471 https://creativecommons.org/licenses/by/4.0/ -->