github.com/tenywen/fabric@v1.0.0-beta.0.20170620030522-a5b1ed380643/docs/source/chaincode.rst (about)

     1  What is chaincode?
     2  ==================
     3  
     4  Chaincode is a piece of code that is written in one of the supported
     5  languages such as Go or Java. It is installed and instantiated through
     6  an SDK or CLI onto a network of Hyperledger Fabric peer nodes, enabling
     7  interaction with that network's shared ledger.
     8  
     9  There are three aspects to chaincode development:
    10  
    11  * Chaincode Interfaces
    12  * APIs
    13  * Chaincode Responses
    14  
    15  Chaincode interfaces
    16  --------------------
    17  
    18  A chaincode implements the Chaincode Interface that supports two
    19  methods:
    20  
    21  * ``Init``
    22  * ``Invoke``
    23  
    24  Init()
    25  ^^^^^^
    26  
    27  Init is called when you first deploy your chaincode. As the name
    28  implies, this function is used to do any initialization your chaincode
    29  needs.
    30  
    31  Invoke()
    32  ^^^^^^^^
    33  
    34  Invoke is called when you want to call chaincode functions to do real
    35  work (i.e. read and write to the ledger). Invocations are captured as
    36  transactions, which get grouped into blocks on the chain. When you need
    37  to update or query the ledger, you do so by invoking your chaincode.
    38  
    39  Dependencies
    40  ------------
    41  
    42  The import statement lists a few dependencies for the chaincode to
    43  compile successfully.
    44  
    45  * fmt – contains ``Println`` for debugging/logging.
    46  * errors – standard go error format.
    47  * `shim <https://github.com/hyperledger/fabric/tree/master/core/chaincode/shim>`__ – contains the definitions for the chaincode interface and the chaincode stub, which are required to interact with the ledger.
    48  
    49  Chaincode APIs
    50  --------------
    51  
    52  When the Init or Invoke function of a chaincode is called, the fabric
    53  passes the ``stub shim.ChaincodeStubInterface`` parameter and the
    54  chaincode returns a ``pb.Response``. This stub can be used to call APIs
    55  to access to the ledger services, transaction context, or to invoke
    56  other chaincodes.
    57  
    58  The current APIs are defined in the shim package, and can be generated
    59  with the following command:
    60  
    61  .. code:: bash
    62  
    63      godoc github.com/hyperledger/fabric/core/chaincode/shim
    64  
    65  However, it also includes functions from chaincode.pb.go (protobuffer
    66  functions) that are not intended as public APIs. The best practice is to
    67  look at the function definitions and comments in interfaces.go and the
    68  `examples <https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go>`__
    69  directory.
    70  
    71  Response
    72  --------
    73  
    74  The chaincode response comes in the form of a protobuffer.
    75  
    76  .. code:: go
    77  
    78      message Response {
    79  
    80          // A status code that should follow the HTTP status codes.
    81          int32 status = 1;
    82  
    83          // A message associated with the response code.
    84          string message = 2;
    85  
    86          // A payload that can be used to include metadata with this response.
    87          bytes payload = 3;
    88  
    89      }
    90  
    91  The chaincode will also return events. Message events and chaincode
    92  events.
    93  
    94  .. code:: go
    95  
    96      messageEvent {
    97  
    98          oneof Event {
    99  
   100          //Register consumer sent event
   101          Register register = 1;
   102  
   103          //producer events common.
   104          Block block = 2;
   105          ChaincodeEvent chaincodeEvent = 3;
   106          Rejection rejection = 4;
   107  
   108          //Unregister consumer sent events
   109          Unregister unregister = 5;
   110  
   111          }
   112  
   113      }
   114  
   115  .. code:: go
   116  
   117      messageChaincodeEvent {
   118  
   119          string chaincodeID = 1;
   120          string txID = 2;
   121          string eventName = 3;
   122          bytes payload = 4;
   123  
   124      }
   125  
   126  Once developed and deployed, there are two ways to interact with the
   127  chaincode - through an SDK or the CLI. The steps for CLI are described
   128  below. For SDK interaction, refer to the `balance transfer <https://github.com/hyperledger/fabric-sdk-node/tree/master/examples/balance-transfer>`__ samples. **Note**: This SDK interaction is covered in the **Getting Started** section.
   129  
   130  Command Line Interfaces
   131  -----------------------
   132  
   133  To view the currently available CLI commands, execute the following:
   134  
   135  .. code:: bash
   136  
   137      # this assumes that you have correctly set the GOPATH variable and cloned the Fabric codebase into that path
   138      cd /opt/gopath/src/github.com/hyperledger/fabric
   139      build /bin/peer
   140  
   141  You will see output similar to the example below. (**NOTE**: rootcommand
   142  below is hardcoded in main.go. Currently, the build will create a *peer*
   143  executable file).
   144  
   145  .. code:: bash
   146  
   147      Usage:
   148            peer [flags]
   149            peer [command]
   150  
   151          Available Commands:
   152            version     Print fabric peer version.
   153            node        node specific commands.
   154            channel     channel specific commands.
   155            chaincode   chaincode specific commands.
   156            logging     logging specific commands
   157  
   158  
   159          Flags:
   160            --logging-level string: Default logging level and overrides, see core.yaml for full syntax
   161            --test.coverprofile string: Done (default “coverage.cov)
   162            -v, --version: Display current version of fabric peer server
   163          Use "peer [command] --help" for more information about a command.
   164  
   165  The ``peer`` command supports several subcommands and flags, as shown
   166  above. To facilitate its use in scripted applications, the ``peer``
   167  command always produces a non-zero return code in the event of command
   168  failure. Upon success, many of the subcommands produce a result on
   169  stdout as shown in the table below:
   170  
   171  .. raw:: html
   172  
   173     <table width="665" cellpadding="8" cellspacing="0">
   174  
   175  .. raw:: html
   176  
   177     <colgroup>
   178  
   179  .. raw:: html
   180  
   181     <col width="262">
   182  
   183  .. raw:: html
   184  
   185     <col width="371">
   186  
   187  .. raw:: html
   188  
   189     </colgroup>
   190  
   191  .. raw:: html
   192  
   193     <thead>
   194  
   195  .. raw:: html
   196  
   197     <tr>
   198  
   199  .. raw:: html
   200  
   201     <th width="262" bgcolor="#ffffff" style="border-top: none; border-bottom: 1.50pt solid #e1e4e5; border-left: none; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0in; padding-right: 0in">
   202  
   203  Command
   204  
   205  .. raw:: html
   206  
   207     </th>
   208  
   209  .. raw:: html
   210  
   211     <th width="371" bgcolor="#ffffff" style="border-top: none; border-bottom: 1.50pt solid #e1e4e5; border-left: none; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0in; padding-right: 0in">
   212  
   213  stdout result in the event of success
   214  
   215  .. raw:: html
   216  
   217     </th>
   218  
   219  .. raw:: html
   220  
   221     </tr>
   222  
   223  .. raw:: html
   224  
   225     </thead>
   226  
   227  .. raw:: html
   228  
   229     <tbody>
   230  
   231  .. raw:: html
   232  
   233     <tr>
   234  
   235  .. raw:: html
   236  
   237     <td width="262" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   238  
   239  version
   240  
   241  .. raw:: html
   242  
   243     </td>
   244  
   245  .. raw:: html
   246  
   247     <td width="371" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   248  
   249  String form of peer.version defined in core.yaml
   250  
   251  .. raw:: html
   252  
   253     </td>
   254  
   255  .. raw:: html
   256  
   257     </tr>
   258  
   259  .. raw:: html
   260  
   261     <tr>
   262  
   263  .. raw:: html
   264  
   265     <td width="262" bgcolor="#ffffff" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   266  
   267  node start
   268  
   269  .. raw:: html
   270  
   271     </td>
   272  
   273  .. raw:: html
   274  
   275     <td width="371" bgcolor="#ffffff" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   276  
   277  N/A
   278  
   279  .. raw:: html
   280  
   281     </td>
   282  
   283  .. raw:: html
   284  
   285     </tr>
   286  
   287  .. raw:: html
   288  
   289     <tr>
   290  
   291  .. raw:: html
   292  
   293     <td width="262" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   294  
   295  node status
   296  
   297  .. raw:: html
   298  
   299     </td>
   300  
   301  .. raw:: html
   302  
   303     <td width="371" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   304  
   305  String form of StatusCode
   306  
   307  .. raw:: html
   308  
   309     </td>
   310  
   311  .. raw:: html
   312  
   313     </tr>
   314  
   315  .. raw:: html
   316  
   317     <tr>
   318  
   319  .. raw:: html
   320  
   321     <td width="262" bgcolor="#ffffff" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   322  
   323  node stop
   324  
   325  .. raw:: html
   326  
   327     </td>
   328  
   329  .. raw:: html
   330  
   331     <td width="371" bgcolor="#ffffff" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   332  
   333  String form of StatusCode
   334  
   335  .. raw:: html
   336  
   337     </td>
   338  
   339  .. raw:: html
   340  
   341     </tr>
   342  
   343  .. raw:: html
   344  
   345     <tr>
   346  
   347  .. raw:: html
   348  
   349     <td width="262" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   350  
   351  chaincode deploy
   352  
   353  .. raw:: html
   354  
   355     </td>
   356  
   357  .. raw:: html
   358  
   359     <td width="371" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   360  
   361  The chaincode container name (hash) required for subsequent chaincode
   362  invoke and chaincode query commands
   363  
   364  .. raw:: html
   365  
   366     </td>
   367  
   368  .. raw:: html
   369  
   370     </tr>
   371  
   372  .. raw:: html
   373  
   374     <tr>
   375  
   376  .. raw:: html
   377  
   378     <td width="262" bgcolor="#ffffff" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   379  
   380  chaincode invoke
   381  
   382  .. raw:: html
   383  
   384     </td>
   385  
   386  .. raw:: html
   387  
   388     <td width="371" bgcolor="#ffffff" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   389  
   390  The transaction ID (UUID)
   391  
   392  .. raw:: html
   393  
   394     </td>
   395  
   396  .. raw:: html
   397  
   398     </tr>
   399  
   400  .. raw:: html
   401  
   402     <tr>
   403  
   404  .. raw:: html
   405  
   406     <td width="262" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   407  
   408  chaincode query
   409  
   410  .. raw:: html
   411  
   412     </td>
   413  
   414  .. raw:: html
   415  
   416     <td width="371" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   417  
   418  By default, the query result is formatted as a printable
   419  
   420  .. raw:: html
   421  
   422     </td>
   423  
   424  .. raw:: html
   425  
   426     </tr>
   427  
   428  .. raw:: html
   429  
   430     <tr>
   431  
   432  .. raw:: html
   433  
   434     <td width="262" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   435  
   436  channel create
   437  
   438  .. raw:: html
   439  
   440     </td>
   441  
   442  .. raw:: html
   443  
   444     <td width="371" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   445  
   446  Create a chain
   447  
   448  .. raw:: html
   449  
   450     </td>
   451  
   452  .. raw:: html
   453  
   454     </tr>
   455  
   456  .. raw:: html
   457  
   458     <tr>
   459  
   460  .. raw:: html
   461  
   462     <td width="262" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   463  
   464  channel join
   465  
   466  .. raw:: html
   467  
   468     </td>
   469  
   470  .. raw:: html
   471  
   472     <td width="371" bgcolor="#f3f6f6" style="border-top: 1px solid #e1e4e5; border-bottom: 1px solid #e1e4e5; border-left: 1px solid #e1e4e5; border-right: none; padding-top: 0in; padding-bottom: 0.08in; padding-left: 0.16in; padding-right: 0in">
   473  
   474  Adds a peer to the chain
   475  
   476  .. raw:: html
   477  
   478     </td>
   479  
   480  .. raw:: html
   481  
   482     </tr>
   483  
   484  .. raw:: html
   485  
   486     <tr>
   487  
   488  .. raw:: html
   489  
   490     </tbody>
   491  
   492  .. raw:: html
   493  
   494     </table>
   495  
   496  .. _swimlane:
   497  
   498  Chaincode Swimlanes
   499  -------------------
   500  
   501  .. image:: images/chaincode_swimlane.png
   502  
   503  Deploy a chaincode
   504  ------------------
   505  
   506  [WIP] - the CLI commands need to be refactored based on the new
   507  deployment model. Channel Create and Channel Join will remain the same.
   508  
   509  .. Licensed under Creative Commons Attribution 4.0 International License
   510     https://creativecommons.org/licenses/by/4.0/