github.com/darrenli6/fabric-sdk-example@v0.0.0-20220109053535-94b13b56df8c/proposals/r1/System-Chaincode-Specification.md (about)

     1  
     2  System Chaincode
     3  ================
     4  
     5  Introduction
     6  ------------
     7  
     8  User written Chaincode runs in a container (called "user chaincode" in
     9  this doc) and communicates with the peer over the network. These
    10  chaincodes have restrictions with regards to what code they can execute.
    11  For example, they can only interact with the peer via \`ChaincodeStub\`
    12  interface such as GetState or PutState. There is a need for chaincode
    13  that have these restrictions relaxed. Such chaincode is broadly termed
    14  "System Chaincode".
    15  
    16  The purpose of system chaincode is to enable customization of certain
    17  behaviors of the fabric such as timer service or naming service.
    18  
    19  The simplest way to design a system chaincode is to run it in the same
    20  process as the Peer. This document goes into this design.
    21  
    22  In-process chaincode
    23  --------------------
    24  
    25  The approach is to consider the changes and generalizations needed to
    26  run chaincode in-process as the hosting peer.
    27  
    28  Requirements
    29  
    30  -   coexist with user chaincode
    31  -   adhere to same lifecycle as user chaincode - except for possibly
    32      "deploy"
    33  -   easy to install
    34  
    35  The above requirements impose the following design principles
    36  
    37  -   design consistent with user chaincode
    38  -   uniform treatment of both types of chaincode in the codebase
    39  
    40  Though the impetus for the in-process chaincode design comes from
    41  "system chaincode", in principle the general "in process chaincode"
    42  design would allow any chaincode to be deployed.
    43  
    44  Key considerations for a chaincode environment
    45  ----------------------------------------------
    46  
    47  There are two main considerations for any chaincode environment
    48  (container, in-process,etc)
    49  
    50  -   Runtime Considerations
    51  -   Lifecycle Considerations
    52  
    53  ### Runtime Considerations
    54  
    55  Runtime considerations can be broadly classified into Transport and
    56  Execution mechanisms. The abstractions provided by the Fabric for these
    57  mechanisms are key to the ability to extend the system to support new
    58  chaincode runtimes consistent with existing ones in a fairly
    59  straightforward manner.
    60  
    61  ### Transport mechanism
    62  
    63  Peer and chaincode communicate using ChaincodeMessages.
    64  
    65  -   the protocol is completely encapsulated via ChaincodeMessage
    66  -   current gRPC streaming maps nicely to Go Channels
    67  
    68  The above allow abstraction of a small section of code dealing with
    69  chaincode transport, leaving most of the code common to both
    70  environments. This is the key to the uniform treatment of runtime
    71  environments.
    72  
    73  ### Execution mechanism
    74  
    75  The fabric provides a basic interface for a “vm”. The Docker container
    76  is implemented on top of this abstraction. The “vm” ([vm interface](https://github.com/hyperledger/fabric/blob/master/core/container/controller.go))
    77  can be used to provide an execution environment for the in-process
    78  runtime as well. This has the obvious benefit of encapsulating all
    79  execution access (deploy, launch, stop, etc) transparent to the
    80  implementation.
    81  
    82  Lifecycle Considerations
    83  ------------------------
    84  
    85  | Life cycle             | Container model                                                  | In-process Model                                                                                                                                                      |
    86  |------------------------|------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
    87  | Deploy                 | User deploys with an external request. Participates in consensus | Two possibilities +++  (1) comes up automatically with the peer, does not participate in consensus (2) user starts the chaincode with a request. Participates in consensus  |
    88  | Invoke/query           | User sends request                                               | User sends request                                                                                                                                                    |
    89  | Stop (not implemented) | User sends request                                               | User sends request                                                                                                                                                    |
    90  | Upgrade *** (not impemented)           |                                                                  |                                                                                                                                                                       |
    91  +++ System chaincodes that are part of genesis block cannot/should not
    92  be part of consensus. E.g., bootstrapping requirements that would
    93  prevent them from taking part in consensus. That is not true for
    94  upgrading those chaincodes.
    95  
    96  So this may then be the model - “system chaincode that are in genesis
    97  block will not be deployed via consensus. All other chaincode deployment
    98  and all chaincode upgrades (including system chaincode) will be part of
    99  consensus.
   100  
   101  \*\*\*\* Upgrade is mentioned here just for completeness. It is an
   102  important part of life-cycle that should be a separate discussion unto
   103  itself involving devops considerations such as versioning, staging,
   104  staggering etc.
   105  
   106  Deploying System Chaincodes
   107  ---------------------------
   108  
   109  System chaincodes come up with a system. System chaincodes will be
   110  defined in core.yaml. Minimally, a chaincode definition would contain
   111  the following information { Name, Path }. Each chaincode definition
   112  could also specify dependent chaincodes such that a chaincode will be
   113  brought up only if its dependent chaincodes are. The chaincodes would be
   114  brought up in the order specified in the list.
   115  
   116  <a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.
   117  s