github.com/hechain20/hechain@v0.0.0-20220316014945-b544036ba106/docs/source/peers/peers.md (about) 1 # Peers 2 3 A fundamental element of a Hechain blockchain network is the set of 4 *peer nodes* (or, simply, *peers*). Peers are fundamental because they manage 5 ledgers and smart contracts. Starting in Hechain v2.4, peers also 6 manage transaction proposals and endorsements by running the 7 [Fabric Gateway](../gateway.html) service. Recall that a ledger 8 immutably records all of the transactions generated by smart contracts (which in 9 Hechain are contained 10 in *chaincode*, more on this later) and endorsed by the required organizations. 11 Smart contracts and ledgers encapsulate the *processes* and *information*, respectively, 12 that are shared by channel peers. These aspects of peers make them a good starting 13 point for understanding a Fabric network. 14 15 Besides peers, other elements of a Fabric blockchain network are also important: 16 ledgers and smart contracts, orderers, policies, channels, client applications, 17 organizations, identities, and membership, which you can read about in their own dedicated sections. 18 This section focuses on peers, and their relationships to these other elements in a Fabric 19 network. 20 21  22 23 *A Fabric blockchain network (above) is comprised of peers (non-ordering nodes), each 24 of which stores and manages copies of ledgers and smart contracts. In this example, the Fabric 25 network N consists of peers P1, P2 and P3, each of which maintains its own instance of 26 the distributed ledger L1. P1, P2 and P3 each invoke the same chaincode, S1, 27 to access their respective copies of the distributed ledger.* 28 29 Peers are a flexible and redundant element that can be created, started, 30 stopped, reconfigured and deleted. Peers expose a set of APIs that enable 31 client applications to interact with the services that peers provide --- the 32 [Fabric Gateway](../gateway.html) service in particular. 33 34 ## Chaincode terminology 35 36 Fabric implements **smart contracts** through a type of logic called **chaincode** 37 --- code that accesses the ledger --- which is written 38 using the [chaincode APIs](../sdk_chaincode.html). In this topic, we use the term 39 **chaincode**, but feel free to interpret chaincode as a **smart contract** if 40 that concept is more familiar. To learn more about chaincode and smart contracts, check out 41 the [documentation on smart contracts and chaincode](../smartcontract/smartcontract.html). 42 43 ## Ledgers and Chaincode 44 45 Now let's look at a peer in a little more detail. We can see that it's the 46 peer that hosts both the ledger and chaincode, in addition to services such as 47 Fabric Gateway. More precisely, the peer hosts *instances* of the ledger, 48 and *instances* of chaincode, because blockchain requires consistent replicas of 49 data and smart contracts across peers in a channel. This design provides a deliberate 50 redundancy in a Fabric network --- avoiding single points of failure and providing 51 consistent, current ledgers. We'll learn more about the distributed and decentralized 52 nature of a Fabric blockchain network later in this section. 53 54  55 56 *A peer hosts instances of ledgers and instances of chaincodes (above). In 57 this example, P1 hosts an instance of ledger L1 and an instance of chaincode S1. 58 There can be many ledgers and chaincodes hosted on any individual peer.* 59 60 Because a peer is a *host* for ledgers, chaincodes and services, client 61 applications and administrators must interact with a peer to access these resources. 62 That's why peers are considered the fundamental building blocks of a Fabric network. 63 We'll see later how ledgers get created, and how chaincodes get installed, on peers. 64 65 ### Multiple Ledgers 66 67 A peer is capable of hosting more than one ledger, which is useful because it allows 68 for a flexible system design where a single peer can belong to multiple channels in 69 a Fabric network. In the simplest configuration, a peer hosts a single ledger, and 70 therefore belongs to a single channel. But it is not uncommon for a peer to host 71 multiple ledgers because it belongs to multiple channels. 72 73  74 75 *A peer hosting multiple ledgers (above). Peers host one or more ledgers and 76 the chaincodes that access them. In this example, peer P1 hosts ledgers 77 L1 and L2. Ledger L1 is accessed using chaincode S1; Ledger L2 can be accessed 78 using either chaincode S1 or S2.* 79 80 Chaincodes installed on a peer can query or update (write to) a ledger. Note 81 that peers also host special *system chaincodes* which relate to the overall 82 configuration of the Fabric network. 83 84 ### Multiple Chaincodes 85 86 A chaincode is instantiated on a single channel. Each channel (and ledger) can 87 have multiple chaincodes that interact with it. 88 89  90 91 *An example of a peer hosting multiple chaincodes (above). Each ledger can have 92 many chaincodes which access it. In this example, peer P1 hosts ledgers L1 and L2, 93 where L1 is accessed by chaincodes S1 and S2, and L2 is accessed by S1 and S3. S1 94 can access both L1 and L2.* 95 96 We'll see a little later why the concept of **channels** in Fabric is important 97 to hosting multiple ledgers and multiple chaincodes on a peer. 98 99 ## Fabric Gateway service 100 101 Starting in Hechain v2.4, the [Fabric Gateway](../gateway.html) service 102 is installed and enabled on each peer by default. The gateway service, as opposed 103 to the client application (in Fabric v2.3 and earlier), manages transaction proposals 104 and endorsements on the peer. The Gateway SDKs (v1.0.0 for Go, Node and Java) incorporate 105 this peer-centric model of transaction processing, enabling simplified application 106 development. Client applications developed with Fabric v2.3 or earlier SDKs will 107 continue to run in Fabric v2.4. 108 109 ## Applications and Peers 110 111 We're now going to show how client applications interact with peers, and more 112 specifically, with the [Fabric Gateway](../gateway.html) service running on peers, 113 to access the ledger. Ledger-queries involve a simple dialogue between an 114 application and a peer, while ledger-updates (writes) involve additional steps. 115 116 A client application connects to the [Fabric Gateway](../gateway.html) service 117 on a peer in order to access ledgers and chaincodes. Starting in Fabric v2.4, the Gateway SDKs 118 (v1.x) make this easy for programmers. The APIs enable applications, via 119 the gateway, to submit transaction proposals (which invokes chaincode), request 120 endorsement, receive events, and forward endorsed transactions to the ordering 121 service. 122 123 Through a peer connection on the gateway, applications can run chaincodes to query or 124 update the ledger. The result of a ledger query transaction is returned with 125 simple processing, whereas a ledger update (write) involves a more complex workflow 126 between applications, peers and orderers. Let's investigate this ledger update process in 127 detail. 128 129 Peers, in conjunction with orderers, ensure that the ledger is kept consistent 130 and current on every peer in a channel. The following sequence, in three 131 phases, describes how interactions between a client application, the gateway 132 service running on a peer, orderer nodes and additional peers update the ledger. 133 134 **Attention:** The three transaction phases which follow explain the internal methods of how Fabric manages transactions. The Fabric Gateway SDKs implement these phases seamlessly; developers only need to use a [Gateway SDK (1.x)](../gateway.html). 135 136 ### Phase 1 - Transaction Proposal and Endorsement 137 138 Phase 1 of a ledger update (write) consists of transaction proposal submission, execution and endorsement: 139 140 a) **Transaction proposal** --- The client application (A1) submits a signed transaction proposal by connecting to the gateway service on P1. A1 must either delegate the selection of endorsing organizations to the gateway service or explicitly identify the organizations required for endorsement. 141 142 b) **Transaction execution** --- The gateway service selects P1, or another peer in its organization, to execute the transaction. The selected peer executes the chaincode (S1) specified in the proposal, generates a proposal response (containing the read-write set). The selected peer signs the proposal response and returns it to the gateway. 143 144 c) **Transaction endorsement** --- The gateway repeats transaction execution (b) for each organization required by the chaincode (smart contract) endorsement policies. The gateway service collects the signed proposal responses and creates a transaction envelope --- which it returns to the client (SDK) for signing. 145 146 ### Phase 2 - Transaction Submission and Ordering 147 148 Phase 2 of a ledger update consists of transaction submission and ordering into blocks: 149 150 a) **Transaction submission** --- The client (SDK) sends the signed transaction envelope to the gateway service. The gateway forwards the envelope to an ordering node and returns a success message to the client. 151 152 b) **Transaction ordering** --- The ordering node (O1) verifies the signature, and the ordering service orders the transaction, and packages it with other ordered transactions into blocks. The ordering service then distributes the block to all peers in the channel for validation and commitment to the ledger. 153 154 ### Phase 3 - Transaction Validation and Commitment 155 156 Phase 3 of a ledger update consists of transaction validation, ledger commitment and a commit event: 157 158 a) **Transaction validation** --- Each peer checks that the client signature on the transaction envelope matches the signature on the original transaction proposal. Each peer also checks that 159 all read-write sets and status responses are equivalent (i.e. the endorsements from all peers match) and that the endorsements satisfy the endorsement policies. Each peer then marks each transaction as valid or invalid for commitment to the ledger. 160 161 b) **Transaction commitment** --- Each peer commits the ordered block of transactions to the channel ledger (L1). The commit is an immutable ledger update (write) to the channel ledger. The world state (essentially, the sum of all valid transactions) of the channel is updated with results of valid transactions only. 162 163 c) **Commit event** --- Each peer that commits to the ledger sends the client a commit status event with proof of the ledger update. 164 165 Note: Fabric v2.3 SDKs, which embed transaction proposal and endorsement functionality in the client application, remain supported in Fabric v2.4. Refer to the [v2.3 Applications and Peers](https://hyperledger-fabric.readthedocs.io/en/release-2.3/peers/peers.html#applications-and-peers) topic for details. 166 167 ## Peers and Channels 168 169 It is worth spending some time understanding how peers interact with each other, and 170 with applications, on a *channel* --- a mechanism by which components within a Fabric 171 blockchain network communicate and transact *privately*. 172 173 Channel components include peer nodes, orderer nodes and applications, and 174 by joining a channel, they agree to collaborate to collectively manage and 175 share identical copies of the ledger. Conceptually, you can compare channels 176 to groups of friends; a person might have several groups of friends with each 177 group participating in different activities. These groups might be entirely 178 separate (a group of work friends as compared to a group of hobby friends), or there 179 can be some crossover membership between them. Nevertheless, each friend group 180 is its own entity, with specific rules (or expectations) that establish and 181 maintain membership. 182 183 Channel membership works the same way as in other groups; any one peer may belong 184 to several channels and maintain a ledger and chaincodes specific to each channel. 185 Or a peer may belong to only a single channel, and therefore have only one set of 186 rules to follow. 187 188  189 190 *Channels allow a specific set of applications and peers (and organizations) 191 to communicate with each other on a Fabric blockchain network. 192 In the example above, application A communicates with peers P1 and P2, through 193 the gateway service, on channel C. The channel is a pathway for communications 194 between specific applications and peers. 195 196 We see that channels don't exist in the same way that peers do --- it's more 197 accurate to think of a channel as a logical structure that is formed by a 198 collection of physical peers. *It is vital to understand this point --- peers 199 provide the control point for access to, and management of, channels*. 200 201 ## Peers and Organizations 202 203 Now that you understand peers and their relationship to ledgers, chaincodes 204 and channels, you'll be able to see how multiple organizations come together to 205 form a blockchain network. 206 207 Fabric blockchain networks are administered by a collection of organizations rather 208 than a single organization. Peers are central to how this kind of distributed 209 network is built because they are owned by --- and are the network connection points 210 for --- these organizations. 211 212 <a name="Peer8"></a> 213  214 215 *The example above shows organizations and their peers in a Fabric blockchain network. 216 We see four organizations contributing a total of eight peers to form a network. 217 Channel C connects five of these peers in the network N --- P1, P3, 218 P5, P7 and P8. The other peers owned by these organizations have not joined 219 channel C, but typically join at least one other channel. Applications 220 developed by an organization connect to peers, via the Fabric Gateway service, 221 in the same organization as well as peers in other organizations on a channel. 222 223 It is important to notice what happens during the formation of a Fabric 224 blockchain network. *The network is both formed and managed by the multiple 225 organizations that contribute resources to it.* Peers are the resources that 226 we're discussing in this topic, but organizations provide other resources too, 227 such as chaincode and ordering service nodes. There's a principle at work here --- the network literally 228 does not exist without organizations contributing their individual resources to 229 the collective network. Moreover, the network grows as resources are provided 230 by collaborating organizations, increasing the resiliency and security of the 231 network. 232 233 You can see that (other than the ordering service, to some degree) there are no 234 centralized resources --- in the [previous diagram](#Peer8), the network **N** 235 would not exist if the organizations did not contribute their peers and other 236 resources. Moreover, the network does not depend on any individual organization --- it 237 continues to exist despite departures as long as its membership meets the 238 self-defined requirements of the network. This is at the heart of what it means 239 for a network to be decentralized; all of its member organizations share and 240 contribute equally. 241 242 Applications used by organizations, as in the [previous diagram](#Peer8), may or 243 may not be the same, because each organization can decide how it wants to use 244 data on the ledger. Both application and presentation logic can therefore vary 245 across organizations, even though all peers host an equivalent copy of the ledger. 246 247 ## Peers and Identity 248 249 Now that you've seen how peers from different organizations come together to 250 form a blockchain network, it's worth spending a few moments understanding how 251 peers get assigned to organizations by their administrators. 252 253 Peers have an identity assigned to them via a digital certificate from a 254 particular certificate authority. You can read a lot more about how X.509 255 digital certificates work elsewhere in this guide, but for now, think of a 256 digital certificate as like an ID card that provides verifiable 257 information about a peer. *Each and every peer in the network is assigned a 258 digital certificate by an administrator from its owning organization*. 259 260  261 262 *When a peer connects to a channel, its digital certificate identifies its 263 owning organization via a channel MSP. In the example above, P1 and P2 264 have identities issued by a certificate authority (CA1). Channel C determines, 265 from a policy in its channel configuration, that identities from CA1 should be 266 associated with Org1 using ORG1.MSP. Similarly, P3 and P4 are identified by 267 ORG2.MSP as part of Org2.* 268 269 Whenever a peer connects to a Fabric network channel, *a policy in 270 the channel configuration uses the peer's identity to determine its 271 rights.* The mapping of identity to organization is provided by a component 272 called a *Membership Service Provider* (MSP) --- which determines how a peer gets 273 assigned to a specific role in a particular organization and accordingly, gains 274 authorized access to resources. Moreover, a peer can be owned only 275 by a single organization, and is therefore associated with a single MSP. Think of 276 an MSP as linking an individual identity with a particular organizational role 277 in a Fabric network. 278 279 Peers, and *anything that interacts with a Fabric network, acquire their 280 organizational identity from their digital certificate and an MSP*. Peers, 281 applications, end users, administrators and orderers must each have an 282 identity, and an associated MSP, to interact with the network. Any entity 283 that interacts with a blockchain network using an identity is known as a 284 *principal.* Note that identity is distinct from where the peer is physically 285 located --- it could reside in the cloud, or in a data center owned by one 286 of the organizations, or on a local machine --- the digital certificate 287 associated with the peer is what identifies it as owned by a particular 288 organization. In the previous example diagram, P3 could be hosted in Org1's data center, but 289 as long as the digital certificate associated with it is issued by CA2, it 290 is owned by Org2. 291 292 ## Peers and Orderers 293 294 We've seen that peers form the basis for a Fabric blockchain network, hosting 295 ledgers and smart contracts which can be queried and updated by peer-connected 296 applications. The mechanism by which applications and peers interact with each 297 other to keep the ledger current and consistent across a channel is mediated by 298 special nodes called *orderers*. It's to these orderer nodes that we now turn our 299 attention. 300 301 A ledger update transaction is different from a query transaction because a single 302 peer cannot, on its own, update the ledger --- that requires the consent of other 303 peers in the network, a process known as *consensus*. When the peers required to 304 approve the transaction do so, and the transaction is committed to the ledger, 305 the gateway service notifies the applications that the ledger has been updated. 306 Peers and orderers work together to manage consensus. 307 308 ### Orderers and the Three Phases 309 310 Previously, in the [Applications and Peers](#peers-and-application) topic, we 311 saw how a client application that requests a ledger update initiates a three-phase 312 process which, with help from the Fabric Gateway service, ensures that 313 all peers in a Fabric network maintain current and consistent copies of the ledger. 314 As described, orderers are also involved; the following sections take a closer 315 look at the three-phase process from the perspective of ordering nodes and peers 316 (i.e. the ordering service and the gateway service). 317 318 ### Phase 1: Transaction Proposal 319 320 Phase 1 of the transaction workflow involves an interaction between a client 321 application, peers and orderers. In Phase 1, the client application initiates 322 a request to the Fabric Gateway service to evaluate a transaction proposal. 323 324 The target peer, selected by the client application, executes the transaction 325 by invoking chaincode --- this step can be described as simulating the transaction, 326 because it runs the transaction without any effect on the ledger. The peer then 327 returns its transaction result to the client. 328 329 The gateway service also forwards the transaction proposal to the required 330 *endorsing peers* (based on the endorsement policies), which also execute the 331 transaction and return their results to the peer. The gateway service collects 332 all responses, and if they collectively satisfy the endorsement policies, forwards 333 the transaction to the ordering service. 334 335 If the proposed transaction would write to a private data collection, (as *transient* data) 336 the client application must explicitly specify the organizations required for endorsement. 337 338 Note that a peer endorses a proposal response by adding its digital signature, and 339 signing the entire payload using its private key. This endorsement can be subsequently 340 used to prove that this organization's peer generated a particular response. 341 342 ### Phase 2: Transaction Ordering 343 344 The second phase of the transaction workflow is the ordering and packaging phase. 345 The ordering service (running on orderer nodes) receives transactions containing signed and 346 endorsed proposal responses, from one or more applications via the gateway service, and 347 orders and packages the transactions into blocks. These are the blocks (which are also ordered) --- consisting 348 of endorsed and ordered transactions --- that make up a Fabric blockchain ledger. 349 350 For details about the ordering and packaging phase, see 351 the [conceptual information about the ordering phase](../orderer/ordering_service.html#phase-two-ordering-and-packaging-transactions-into-blocks). 352 353 ### Phase 3: Validation and Commitment 354 355 The third and final phase of the transaction workflow is the distribution of ordered 356 transactions from orderers to peers. Each peer then validates each transaction, in 357 the correct order, and ensures that each transaction has been consistently endorsed by all 358 required organizations. Only then does the peer commit the block to its copy of the channel ledger. 359 360  361 362 *An orderer node distributes ordered blocks to peers for validation and 363 commitment. In this example above, orderer O1 distributes block B2 to peers P1 and P2. Peer P1 364 processes block B2, resulting in a new block being added to ledger L1 on P1. 365 In parallel, peer P2 processes block B2, resulting in a new block being added 366 to ledger L1 on P2. Once complete, the ledger L1 has been consistently updated 367 on peers P1 and P2, and the gateway service informs the 368 relevant applications that the transaction has been committed.* 369 370 Phase 3 begins with the orderer distributing blocks to all peers connected to 371 it. Peers are connected to orderers on channels such that when a new block is 372 generated, all of the peers connected to the orderer will be sent a copy of the 373 new block. Each peer will process this block independently, but in exactly the 374 same way as every other peer on the channel. In this way, we'll see that the 375 ledger can be kept consistent. It's also worth noting that not every peer needs 376 to be connected to an orderer --- peers can cascade blocks to other peers using 377 the **gossip** protocol, who also can process them independently. But let's 378 leave that discussion to another time! 379 380 Upon receipt of a block, a peer will process each transaction in the sequence 381 specified in the block. For each transaction, the peer will verify that 382 the transaction has been endorsed by the required organizations according to the 383 *endorsement policies* for the chaincode which generated the transaction. For 384 example, some transactions may only need to be endorsed by a single 385 organization, whereas others may require multiple endorsements to be valid. This process of 386 validation verifies that all relevant organizations have generated the same outcome or result. 387 388 If a transaction has been endorsed correctly, the peer will attempt to apply it 389 to the ledger. To do this, a peer must perform a ledger consistency check to 390 verify that the current state of the ledger is compatible with the state of the 391 ledger when the proposed update was generated. This may not always be possible, 392 even when the transaction has been fully endorsed. For example, another 393 transaction may have updated the same asset in the ledger such that the 394 transaction update is no longer valid and therefore can no longer be applied. In 395 this way, the ledger is kept consistent across each peer in the channel because 396 they each follow the same rules for validation. 397 398 After a peer has successfully validated each individual transaction, it updates 399 the ledger. Failed transactions are not applied to the ledger, but they are 400 retained for audit purposes, as are successful transactions. This means that 401 peer blocks are almost exactly the same as the blocks received from the orderer, 402 except for a valid or invalid indicator on each transaction in the block. 403 404 Note that phase 3 does not require running chaincode --- this is 405 done only during phase 1, and that's important. It means that chaincodes only have 406 to be available on endorsing nodes, rather than throughout the blockchain 407 network. This keeps the logic of the chaincode confidential to endorsing organizations 408 only. This is in contrast to the output of 409 the chaincodes (transaction proposal responses), which are shared with every 410 peer in the channel, whether or not they endorsed the transaction. This 411 specialization of endorsing peers is designed to help scalability and confidentiality. 412 413 Finally, each time a block is committed to a peer's ledger, that peer 414 generates an *event*. *Block events* include the full block content, 415 while *block transaction events* include summary information only, such as 416 whether each transaction in the block has been validated or invalidated. 417 *Chaincode* events that the chaincode execution has produced can also be 418 published at this time. Applications can register for these event types 419 for notification. The commit event notification concludes the third and final 420 phase of the transaction workflow. 421 422 In summary, phase 3 sees the transaction blocks which are generated by the orderer 423 validated and consistently applied to the ledger. The strict ordering of transactions 424 into blocks allows each peer to validate that transaction updates are consistently 425 applied across the channel. 426 427 ### Orderers and Consensus 428 429 This entire transaction workflow process is called *consensus*, because peers have 430 to collectively reach agreement on the order and content of transactions, with 431 mediation from orderers. Consensus is a multi-step process and ledger updates 432 only occur when the process completes successfully --- which can happen at slightly 433 different times on different peers. Think of the orderers as nodes which sequence 434 and distribute proposed ledger updates for peers to endorse and add to the ledger. 435 436 ## Peers Summary 437 438 That's it! We've now finished our detailed tour of peers and their interactions 439 with other Fabric components, including client applications, chaincodes and orderers. We've seen 440 that peers are in many ways the most fundamental element of Hechain 441 architecture --- they form the network, host chaincodes and the ledger, handle 442 transaction proposals and responses, and keep the ledger updated and consistent 443 with validated and endorsed transactions. 444 445 <!--- Licensed under Creative Commons Attribution 4.0 International License 446 https://creativecommons.org/licenses/by/4.0/) -->