Participation edits to network concept doc #2283
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
joealewine
force-pushed
the
parteditnet
branch
from
c072ccf
to
51ef289
Compare
denyeart
reviewed
Jan 19, 2021
docs/source/network/network.md
Outdated
|
|
||
| ## Join nodes to the channel | ||
|
|
||
| Peers are a fundamental element of the network because they host ledgers and chaincode (which contain smart contracts) and are therefore one of the physical points at which organizations that transact on a channel connect to the channel (the other being an application). A peer can belong to as many channels as an organizations deems appropriate (depending on factors like the processing limitations of the peer pod and data residency rules that exist in a particular country). In most production networks, they will be the most common physical component connected to a channel. For more information about peers, check out [Peers](../peers/peers.html). |
There was a problem hiding this comment.
I would remove "In most production networks, they will be the most common physical component connected to a channel." That sentence seems to bring more questions than answers.
docs/source/network/network.md
Outdated
|
|
||
| In Fabric, the business logic that defines how peer organizations interact with the ledger (for example, a transaction that changes the ownership of an asset), is contained in a smart contract. The structure that contains the smart contract, called chaincode, is installed on the relevant peers, approved by the relevant peer organizations, and committed on the channel. In this way, you can consider a chaincode to be **physically hosted** on a peer but **logically hosted** on a channel. In our example, the chaincode, S5, is installed on every peer, even though organizations are not required to install every chaincode. Note that the ordering service does not have the chaincode installed on it, as ordering nodes do not typically propose transactions. The process of installing, approving, and committing a chaincode is known as the "lifecycle" of the chaincode. For more information, check out [Fabric chaincode lifecycle](../chaincode_lifecycle.html). | ||
|
|
||
| The most important piece of information supplied within the chaincode definition is the [endorsement policy](../glossary.html#endorsement-policy). It describes which organizations must approve transactions before they will be accepted by other organizations onto their copy of the ledger. An endorsement policy can be set to any combination of members in a channel, depending on the use case. If an endorsement policy is not set, it is inherited from the default endorsement policy specified in the channel configuration. |
There was a problem hiding this comment.
Suggested change
| The most important piece of information supplied within the chaincode definition is the [endorsement policy](../glossary.html#endorsement-policy). It describes which organizations must approve transactions before they will be accepted by other organizations onto their copy of the ledger. An endorsement policy can be set to any combination of members in a channel, depending on the use case. If an endorsement policy is not set, it is inherited from the default endorsement policy specified in the channel configuration. | |
| The most important piece of information supplied within the chaincode definition is the [endorsement policy](../glossary.html#endorsement-policy). It describes which organizations must endorse transactions before they will be accepted by other organizations onto their copy of the ledger. An endorsement policy can be set to any combination of members in a channel, depending on the use case. If an endorsement policy is not set, it is inherited from the default endorsement policy specified in the channel configuration. |
I prefer to avoid the term 'approve' since that sounds like a human activity.
docs/source/network/network.md
Outdated
|
|
||
| Although the update to the diagram looks one simple step, adding a new organization to a channel is, at a high level, a three step process: | ||
|
|
||
| 1. Decide on the new organization's permissions and role. The full scope of these rights must be agreed to before R3 is added to C1 and is beyond the scope of this topic, but comprise the same kinds of questions that must be answered when creating a channel in the first place. What kind of permissions and rights will R3 have on C1? Will it be an admin on the channel, with full rights to sign channel configuration updates of its own? Will its access to any channel resources be restricted (for example, R3 might only be able to write to C1, which means it can propose changes but not sign them)? What chaincodes will R3 install on its peers? What chaincodes will be redefined and recommitted at a channel level to add R3 as an endorser? |
There was a problem hiding this comment.
This makes it sound like a single org has admin priv on a channel. By default a majority of orgs must sign off on channel config updates.
Similarly, the default endorsement policy is majority, and if that is the case, the chaincode does not have to be redefined and recommitted upon adding an org.
docs/source/network/network.md
Outdated
|
|
||
| 1. Decide on the new organization's permissions and role. The full scope of these rights must be agreed to before R3 is added to C1 and is beyond the scope of this topic, but comprise the same kinds of questions that must be answered when creating a channel in the first place. What kind of permissions and rights will R3 have on C1? Will it be an admin on the channel, with full rights to sign channel configuration updates of its own? Will its access to any channel resources be restricted (for example, R3 might only be able to write to C1, which means it can propose changes but not sign them)? What chaincodes will R3 install on its peers? What chaincodes will be redefined and recommitted at a channel level to add R3 as an endorser? | ||
| 2. Update the channel, including the relevant chaincodes, to reflect these decisions. | ||
| 3. The organization joins its components the channel and begins participating. |
There was a problem hiding this comment.
Suggested change
| 3. The organization joins its components the channel and begins participating. | |
| 3. The organization joins its peer nodes (and potentially ordering nodes) to the channel and begins participating. |
docs/source/network/network.md
Outdated
|
|
||
|  | ||
|
|
||
| In this example, R3 adds P3, which was previously joined to C2, to C1. When it does this, P3 pulls C1's ledger, L2. As we mentioned in the previous section, R3 has been added to C1 with equivalent rights as R1 and R2. Similarly, because the chaincode S5 was redefined and reapproved on the channel to include R3, R3 can now install S5 and begin transacting. Just as R2 modified its application A2 to be able to be used with channel C2, A3 is also now able to invoke transactions on C1. |
There was a problem hiding this comment.
Should we keep the numbers consistent, e.g. channel C1 has ledger L1?
docs/source/network/network.md
Outdated
|
|
||
| We've covered a lot of ground in this topic. We've gone from a simple configuration with two organizations transacting on a single channel to multiple organizations transacting on multiple channels as well as the process for joining an organization to a channel that already exists. | ||
|
|
||
| While this topics represents a relatively simple case, there are endless combinations of sophisticated topologies which are possible to achieve in Fabric, supporting and endless number of operational goals, and no theoretical limit to how big a network can get. The careful use of network and channel policies allow even large networks to be well-governed. |
There was a problem hiding this comment.
Suggested change
| While this topics represents a relatively simple case, there are endless combinations of sophisticated topologies which are possible to achieve in Fabric, supporting and endless number of operational goals, and no theoretical limit to how big a network can get. The careful use of network and channel policies allow even large networks to be well-governed. | |
| While this topic represents a relatively simple case, there are endless combinations of sophisticated topologies which are possible to achieve in Fabric, supporting and endless number of operational goals, and no theoretical limit to how large a network can get. The careful use of network and channel policies allow even large networks to be well-governed. |
wlahti
reviewed
Jan 20, 2021
docs/source/network/network.md
Outdated
| solid understanding of the major structure and process components in a | ||
| Hyperledger Fabric blockchain network. This topic will use a manageable worked | ||
| example that introduces all of the major components in a blockchain network. | ||
| This topic will describe, **at a conceptual level**, how Hyperledger Fabric allows organizations to collaborate in the formation of blockchain networks. If you're an architect, administrator or developer, you can use this topic to get a solid understanding of the major structure and process components in a Hyperledger Fabric blockchain network. This topic will use a manageable worked example that introduces all of the major components in a blockchain network. |
There was a problem hiding this comment.
Suggested change
| This topic will describe, **at a conceptual level**, how Hyperledger Fabric allows organizations to collaborate in the formation of blockchain networks. If you're an architect, administrator or developer, you can use this topic to get a solid understanding of the major structure and process components in a Hyperledger Fabric blockchain network. This topic will use a manageable worked example that introduces all of the major components in a blockchain network. | |
| This topic will describe, **at a conceptual level**, how Hyperledger Fabric allows organizations to collaborate in the formation of blockchain networks. If you're an architect, administrator or developer, you can use this topic to get a solid understanding of the major structure and process components in a Hyperledger Fabric blockchain network. This topic will use a manageable working(?) example that introduces all of the major components in a blockchain network. |
| is the only member of the network. | ||
| Before we start, let's show you what we're aiming at! Here's a diagram representing the **final state** of our sample network. | ||
|
|
||
| It might look complicated right now, but as we go through this topic, we will build up the network piece by piece, so that you see how the organizations R1, R2, R3 and R0 contribute infrastructure to the network to help form it. This infrastructure implements the blockchain network, and it is governed by policies agreed by the organizations who form the network -- for example, who can add new organizations. You'll discover how applications consume the ledger and smart contract services provided by the blockchain network. |
There was a problem hiding this comment.
Why the change to R0 here instead of R4? Start at 0 for numbering in the context of a doc seems weird but maybe that's just me.
There was a problem hiding this comment.
It was helpful to have the ordering service org be 0 because then the peer orgs wouldn't be 1, 2, and 4. Also the zero seemed to match with the o in ordering service.
|
|
||
|  | ||
|
|
||
| In Fabric, the business logic that defines how peer organizations interact with the ledger (for example, a transaction that changes the ownership of an asset), is contained in a smart contract. The structure that contains the smart contract, called chaincode, is installed on the relevant peers, approved by the relevant peer organizations, and committed on the channel. In this way, you can consider a chaincode to be **physically hosted** on a peer but **logically hosted** on a channel. In our example, the chaincode, S5, is installed on every peer, even though organizations are not required to install every chaincode. Note that the ordering service does not have the chaincode installed on it, as ordering nodes do not typically propose transactions. The process of installing, approving, and committing a chaincode is known as the "lifecycle" of the chaincode. For more information, check out [Fabric chaincode lifecycle](../chaincode_lifecycle.html). |
There was a problem hiding this comment.
Is there another document or part of this document that mentions chaincodes S1, S2, S3, and S4? If not, why start at S5?
There was a problem hiding this comment.
There isn't --- it's a detail from before I chose not to change. I think originally it was meant to not conflict with other numbers in the diagram, or to make people think that a smart contract was confined to a particular channel.
docs/source/network/network.md
Outdated
|
|
||
| Think about this configuration from the standpoint of R2, which is joined to both channels. From their perspective, they might think about both C1 and C2, as well as the components they have joined to both, as the "network", even though both channels are distinct from each other. In this sense, a "network" can also be seen as existing within the perspective of a particular organization as "all of the channels I am a member of and all of the components I own". | ||
|
|
||
| Now that we have shown how organizations and their components can be joined to multiple channels, lets talk about how an organization and its components are added to an existing channel. |
There was a problem hiding this comment.
Suggested change
| Now that we have shown how organizations and their components can be joined to multiple channels, lets talk about how an organization and its components are added to an existing channel. | |
| Now that we have shown how organizations and their components can be joined to multiple channels, let's talk about how an organization and its components are added to an existing channel. |
Nit
docs/source/network/network.md
Outdated
|
|
||
| As channels mature, it is natural that its configuration will also mature, reflecting changes in the world that must be reflected in the channel. One of the more common ways a channel will be modified is to add new organizations to it. While it also possible to add more orderer organizations (who may or may not contribute their own nodes), in this example we'll describe the process of how a peer organization, R3, is added to the channel configuration CC1 of channel C1. | ||
|
|
||
| **Note that rights and permissions are defined at a channel level. Just because an organization is administrator of one channel does not mean it will be an administrator of a different channel. Each channel is a distinct administrative zone and fully customizable to the use case it's serving.** |
There was a problem hiding this comment.
Suggested change
| **Note that rights and permissions are defined at a channel level. Just because an organization is administrator of one channel does not mean it will be an administrator of a different channel. Each channel is a distinct administrative zone and fully customizable to the use case it's serving.** | |
| **Note that rights and permissions are defined at a channel level. Just because an organization is an administrator of one channel does not mean it will be an administrator of a different channel. Each channel is a distinct administrative zone and fully customizable to the use case it's serving.** |
Nit
docs/source/network/network.md
Outdated
|
|
||
|  | ||
|
|
||
| Although the update to the diagram looks one simple step, adding a new organization to a channel is, at a high level, a three step process: |
There was a problem hiding this comment.
Suggested change
| Although the update to the diagram looks one simple step, adding a new organization to a channel is, at a high level, a three step process: | |
| Although the update to the diagram looks like(?) one simple step, adding a new organization to a channel is, at a high level, a three step process: |
docs/source/network/network.md
Outdated
|
|
||
| For more information about the process of adding an organization to a channel, check out [Adding an org to a channel](../channel_update_tutorial.html). | ||
|
|
||
| For more information about policies (which define the roles organizations have a channel), check out [Policies](../policies/policies.html). |
There was a problem hiding this comment.
Suggested change
| For more information about policies (which define the roles organizations have a channel), check out [Policies](../policies/policies.html). | |
| For more information about policies (which define the roles organizations have on(?) a channel), check out [Policies](../policies/policies.html). |
docs/source/network/network.md
Outdated
|
|
||
| For more information about policies (which define the roles organizations have a channel), check out [Policies](../policies/policies.html). | ||
|
|
||
| For more information about adding a new organization to a chaincode, check out [Upgrade a chaincode](../chaincode_lifecycle.html#upgrade-a-chaincode). |
There was a problem hiding this comment.
"adding a new organization to a chaincode" sounds odd to me. I don't have any great suggestions right now as I'm not entirely sure what aspect you're specifically thinking of here but I think this could use some re-writing.
There was a problem hiding this comment.
Yeah, just went back to "upgrade" here.
docs/source/network/network.md
Outdated
|
|
||
| ### Adding existing components to the newly joined channel | ||
|
|
||
| Now that R3 is able to fully participate in channel C2, it can add its components to the channel. Rather than do this one component at a time, let's show its peer, its local copy of a ledger, a smart contract and a client application be joined all at once! |
There was a problem hiding this comment.
Suggested change
| Now that R3 is able to fully participate in channel C2, it can add its components to the channel. Rather than do this one component at a time, let's show its peer, its local copy of a ledger, a smart contract and a client application be joined all at once! | |
| Now that R3 is able to fully participate in channel C2, it can add its components to the channel. Rather than do this one component at a time, let's show that its peer, its local copy of a ledger, a smart contract and a client application can be joined all at once! |
Or something like that?
docs/source/network/network.md
Outdated
|
|
||
| We've covered a lot of ground in this topic. We've gone from a simple configuration with two organizations transacting on a single channel to multiple organizations transacting on multiple channels as well as the process for joining an organization to a channel that already exists. | ||
|
|
||
| While this topics represents a relatively simple case, there are endless combinations of sophisticated topologies which are possible to achieve in Fabric, supporting and endless number of operational goals, and no theoretical limit to how big a network can get. The careful use of network and channel policies allow even large networks to be well-governed. |
There was a problem hiding this comment.
Suggested change
| While this topics represents a relatively simple case, there are endless combinations of sophisticated topologies which are possible to achieve in Fabric, supporting and endless number of operational goals, and no theoretical limit to how big a network can get. The careful use of network and channel policies allow even large networks to be well-governed. | |
| While this topics represents a relatively simple case, there are endless combinations of sophisticated topologies which are possible to achieve in Fabric, supporting an endless number of operational goals, and no theoretical limit to how big a network can get. The careful use of network and channel policies allow even large networks to be well-governed. |
joealewine
force-pushed
the
parteditnet
branch
from
51ef289
to
96a2095
Compare
pamandrejko
previously approved these changes
Jan 22, 2021
docs/source/network/network.md
Outdated
|
|
||
|  | ||
|
|
||
| The channel configuration, CC1, has been agreed to by organizations R1, R2, and R0 and is contained in a block known as a "configuration block" that is, typically, created by the `configtxgen` tool from a `configtx.yaml` file. While it is possible for one organization to create this a channel unilaterally and then invite other organizations to it (we'll explore this in [Adding an organization to an existing channel](#adding-an-organization-to-an-existing-channel), for now we'll assume that the organizations wish to collaborate on the channel from the beginning. |
There was a problem hiding this comment.
Need an additional closing parentheses here:
While it is possible for one organization to create this a channel unilaterally and then invite other organizations to it (we'll explore this in Adding an organization to an existing channel
docs/source/network/network.md
Outdated
|
|
||
| Firstly, different components of the blockchain network use certificates to identify themselves to each other as being from a particular organization. That's why there is usually more than one CA supporting a blockchain network -- different organizations often use different CAs. We're going to use three CAs in our channel; one for each organization. Indeed, CAs are so important that Hyperledger Fabric provides you with a built-in one (called the *Fabric-CA*) to help you get going, though in practice, organizations will choose to use their own CA. | ||
|
|
||
| The mapping of certificates to member organizations is achieved by via a structure called a [Membership Services Provider (MSP)](../membership/membership.html), which defines an organization by creating an MSP which is tied to a root CA certificate to identify that components and identities were created by the root CA. The channel configuration can then assign certain rights and permissions to the organization through a policy (which will give a particular organization, such as R1, the right to add new organizations to the channel). We don't show MSPs on these diagrams, as they would clutter them up, but because they define organizations, they are very important. |
docs/source/network/network.md
Outdated
|
|
||
| ## Joining components to multiple channels | ||
|
|
||
| Now that we have showed how the process for how a channel is created and joined, as well as the nature of the high level interactions between organizations, nodes, policies, chaincodes, and applications, let's expand our view by adding a new organization and a new channel to our scenario. To show how Fabric components can be joined to multiple channels, we'll join R2 and its peer, P2, to the new channel, while R1 and P1 will not be joined. |
There was a problem hiding this comment.
Now that we have showed the process for how a channel is created
joealewine
force-pushed
the
parteditnet
branch
from
96a2095
to
deee89d
Compare
|
Final edits look really good, although it looks like Pam's last comment was not applied: |
joealewine
force-pushed
the
parteditnet
branch
from
deee89d
to
f8e861a
Compare
|
Ah, @denyeart I thought she was only talking about the end of the sentence. I see the other suggestion now. |
nikhil550
reviewed
Jan 25, 2021
|
|
||
| In most cases, multiple [organizations](../glossary.html#organization) come together to form a **channel** on which transactions are invoked on chaincodes and where permissions are determined by a set of [policies](../policies/policies.html) that are agreed to when the channel is originally configured. Moreover, policies can change over time subject to the agreement of the organizations. | ||
|
|
||
| **In this topic, we'll refer to both the "network" and the "channel". In Hyperledger Fabric, these terms are effectively synonymous, as they both refer collectively to the organizations, components, policies, and processes that govern the interactions between organizations within a defined structure.** |
There was a problem hiding this comment.
I think this idea, that channel and network are synonymous, is a good idea.
docs/source/network/network.md
Outdated
| @@ -1,1032 +1,165 @@ | |||
| # Blockchain network | |||
| # How blockchain networks are structured | |||
There was a problem hiding this comment.
I am a sure that there has been discussion about this, but should this article be about how Fabric networks are structured. Even if blockchain = Fabric in the Fabric docs, I think it would help to have the title be more precise.
Change-Id: I4c638f132076c5e0d7b36a2a498340e0594a31fd Signed-off-by: joe-alewine <Joe.Alewine@ibm.com>
joealewine
force-pushed
the
parteditnet
branch
from
f8e861a
to
9bae936
Compare
denyeart
approved these changes
Jan 25, 2021
|
@Mergifyio backport release-2.3 |
|
Command
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Change-Id: I4c638f132076c5e0d7b36a2a498340e0594a31fd
Signed-off-by: joe-alewine Joe.Alewine@ibm.com
Type of change
Description
The "network" concept doc, which describes the iterative way in which a network should be created and developed, must be extensively reworked to fit with the new participation API process. Because this doc was developed a long time ago, it is also now possible to rely on docs that did not exist when it was written to fill in the gaps, allowing this intimidating doc to be greatly shortened and simplified, hopefully making it more consumable.