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