Add gateway ref to private data doc topic #3049
Conversation
| @@ -151,6 +151,15 @@ documentation on [transaction flow](../txflow.html). | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
| The [Fabric Gateway](../gateway.html) takes care of collecting the required set of endorsements | |||
There was a problem hiding this comment.
takes care of collecting >> "collects"
There was a problem hiding this comment.
The Fabric Gateway >>
"Fabric Gateway"
... (i.e. no "The" ... or alternatively, "The Fabric Gateway service" ...
There was a problem hiding this comment.
@denyeart So we'll need to back up on your equating "Fabric Gateway" with "Gateway" capital G ... because the shortened form Gateway is an abbreviation and no longer a proper noun. ... So we use either "Fabric Gateway" or "the gateway". ...
(Similar to how IBP should be called either the full name or "the platform" and not "(the) Platform" )
There was a problem hiding this comment.
"The Fabric Gateway service" also ok.
| @@ -151,6 +151,15 @@ documentation on [transaction flow](../txflow.html). | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
| The [Fabric Gateway](../gateway.html) takes care of collecting the required set of endorsements | |||
| on behalf of the client application. It does this by running the first simulation on a peer in | |||
There was a problem hiding this comment.
The gateway peer is a peer in the gateway's org., would/could it not run the simulation on itself.
There was a problem hiding this comment.
Is it debatable if we need to re-document what simulation means in describing gateway? ...
For example, is -
"The gateway peer simulates the transaction and aggregates the relevant endorsement policies generated by the transaction chaincode."
-- which goes less into the weeds -- satisfactory and preferable or the reverse.
There was a problem hiding this comment.
or alternatively, "The gateway peer manages simulating the transaction and aggregating the relevant ..."
There was a problem hiding this comment.
Yes it could do. It will select the peer with the largest ledger block height in the org.
| the gateway's organization and aggregating the relevant endorsement policies based on the read/write | ||
| set generated by the chaincode. Client applications that submit transaction requests through | ||
| the gateway using one of the [gateway SDKs](../gateway.html#software-development-kits-sdks) | ||
| will benefit from this [endorser selection logic](../gateway.html#how-the-gateway-endorses-your-transaction-proposal). |
There was a problem hiding this comment.
will benefit from this endorser selection logic >>
"will use the [endorsement logic] encoded in the gateway peer." ...
(the target linked topic is not only about "endorser selection" right).
| set generated by the chaincode. Client applications that submit transaction requests through | ||
| the gateway using one of the [gateway SDKs](../gateway.html#software-development-kits-sdks) | ||
| will benefit from this [endorser selection logic](../gateway.html#how-the-gateway-endorses-your-transaction-proposal). | ||
| The client application can override this logic by explicitly [specifying which organizations](../gateway.html#targeting-specific-endorsement-peers) |
There was a problem hiding this comment.
Suggest changing 160 to:
"If any endorsement policy fails for a private data transaction, the transaction proposal fails without a retry. The client is then required to [explicitly specify each endorsing organization]."
And then delete 161.
There was a problem hiding this comment.
The application developer would need to make this decision when they are designing/coding their client application. Your wording would suggest they would catch it and handle it as a runtime exception. I'm not sure that's appropriate for this.
andrew-coleman
force-pushed
the
private_data_doc
branch
from
32e3e13
to
cc8ed8f
Compare
| @@ -151,6 +151,15 @@ documentation on [transaction flow](../txflow.html). | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
| [Fabric Gateway](../gateway.html) collects the required set of endorsements | |||
There was a problem hiding this comment.
Andy, I was thinking we'd update steps 1 through 5 above to indicate that gateway orchestrates the flow, rather than client application. That's what I did for https://hyperledger-fabric.readthedocs.io/en/latest/txflow.html topic. I called it the "target peer", but maybe we should change that to "target gateway peer".
Alternatively, in each of these flow descriptions we could leave it open ended with language like "Client application (or gateway peer) submits proposal to endorsing peers", and describe at the beginning that you can either have the application orchestrate the flow if using a legacy SDK, or have the gateway peer orchestrate the flow if using a gateway SDK.
What do you think @joshhus ? You've got the same dilemma in the peer topic.
There was a problem hiding this comment.
target peer is good ... we are avoiding "gateway peer" usages in favor of "gateway service" (running on the target peer).
|
One question and answer that could elucidate the strategy is what 2.3 customers are going to do with their client apps - leave them as-is or re-write them to use gateway. Presuming they won't re-write them, then 2.4 should document both ways right, otherwise legacy apps would appear to be obsolete in 2.4 doc. ... So then we could leave the current doc as is entirely, no edits, and instead add new sections in each place for gateway - such as "H1 Applications and Peers" - with H2s - "Legacy Applications and Peers" (current doc) and then additional new H2 "Gateway Applications and Peers". ... That approach is more work, a longer runway, new diagrams, etc., but more complete longer term, rather than scattering text about the new way / both versions throughout the existing sections. |
|
Copying our strategy discussion here... |
A start at the text to use for applicable topics below -- @denyeart @andrew-coleman Is there any truth in the 3rd sentence below "To continue to use v2.3 ... " ? i.e. If a user runs their 2.3 app (includes endorsement logic) on a 2.4 peer with gateway enabled, is it seamless? Or do they need to disable the gateway service. ... Consider separate cases of 2.3 apps specifying orgs. explicitly and by endorsement policies only. "Attention: In v2.4, Fabric Gateway manages transaction proposal and endorsement by default. In prior Fabric versions, this logic was required in the client application. To continue to use v2.3 and earlier applications in Fabric v2.4, simply disable the gateway service on your applicable peer(s). For details on version v2.3 handling of transaction proposal and endorsement, see Applications and Peers." |
andrew-coleman
force-pushed
the
private_data_doc
branch
2 times, most recently
from
08aa516
to
5d3b00e
Compare
@joshhus Applications can continue to use the v2.3 approach of gathering endorsements on the client side, when using a v2.4 peer, regardless of whether gateway service is enabled or not. Basically, all the v2.3 grpc services are available on a v2.4 peer and continue to work the same way. Additionally, the new gateway grpc service is also available on a v2.4 peer and can be used if you want to delegate endorsement gathering and transaction submission to the gateway service. Client applications can utilize either approach. I expect most users will keep the default setting of gateway enabled, regardless of whether they immediately use it or not (it causes no harm to have the gateway service enabled but idle). |
| @@ -150,7 +157,7 @@ documentation on [transaction flow](../txflow.html). | |||
| transaction and the block. Upon validation/commit, the private data is moved to | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
There was a problem hiding this comment.
We've also talked about having a Note after sections like this, to mention that client application can gather the endorsements (and in this case, distribute the private data) instead of delegating that to a target gateway peer, along with a link to the corresponding release-2.3 doc topic that explains the flow from that perspective. But, we could add that in a later PR so that the Note is consistent across the various topics.
There was a problem hiding this comment.
Note: The client application can collect the endorsements instead of delegating that step to the target peer. Refer to the v2.3 Peers and Applications topic for details.
| @@ -151,6 +151,15 @@ documentation on [transaction flow](../txflow.html). | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
| The [Fabric Gateway](../gateway.html) takes care of collecting the required set of endorsements | |||
There was a problem hiding this comment.
@denyeart So we'll need to back up on your equating "Fabric Gateway" with "Gateway" capital G ... because the shortened form Gateway is an abbreviation and no longer a proper noun. ... So we use either "Fabric Gateway" or "the gateway". ...
(Similar to how IBP should be called either the full name or "the platform" and not "(the) Platform" )
| @@ -151,6 +151,15 @@ documentation on [transaction flow](../txflow.html). | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
| The [Fabric Gateway](../gateway.html) takes care of collecting the required set of endorsements | |||
There was a problem hiding this comment.
"The Fabric Gateway service" also ok.
| @@ -151,6 +151,15 @@ documentation on [transaction flow](../txflow.html). | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
| The [Fabric Gateway](../gateway.html) takes care of collecting the required set of endorsements | |||
| on behalf of the client application. It does this by running the first simulation on a peer in | |||
There was a problem hiding this comment.
or alternatively, "The gateway peer manages simulating the transaction and aggregating the relevant ..."
| should endorse the proposal request, or it can delegate the | ||
| [endorser selection logic](../gateway.html#how-the-gateway-endorses-your-transaction-proposal) | ||
| to the gateway service in the target peer. In the latter case, the gateway will | ||
| attempt to select a set of endorsing peers which are part of authorized organizations |
There was a problem hiding this comment.
I think since we already have the concept of "members of a private data collection" you can stay with that concept and phrasing here.
| data used to generate private data in chaincode, is sent in a `transient` | ||
| field of the proposal. | ||
|
|
||
| function (reading or writing private data) to a target peer, which will manage |
There was a problem hiding this comment.
I like your "target peer" concept, because it clarifies which of the candidate peers will run the gateway service for this transaction.
| @@ -150,7 +157,7 @@ documentation on [transaction flow](../txflow.html). | |||
| transaction and the block. Upon validation/commit, the private data is moved to | |||
| their copy of the private state database and private writeset storage. The | |||
| private data is then deleted from the `transient data store`. | |||
|
|
|||
There was a problem hiding this comment.
Note: The client application can collect the endorsements instead of delegating that step to the target peer. Refer to the v2.3 Peers and Applications topic for details.
| to the gateway service in the target peer. In the latter case, the gateway will | ||
| attempt to select a set of endorsing peers which are part of authorized organizations | ||
| of the collection(s) affected by the chaincode. The private data, or data used to | ||
| generate private data in chaincode, is sent in a `transient` field of the proposal. |
There was a problem hiding this comment.
"in the proposal" I think. (not of the proposal).
| 2. The endorsing peers simulate the transaction and store the private data in | ||
| a `transient data store` (a temporary storage local to the peer). They | ||
| distribute the private data, based on the collection policy, to authorized peers | ||
| via [gossip](../gossip.html). | ||
|
|
||
| 3. The endorsing peer sends the proposal response back to the client. The proposal | ||
| 3. The endorsing peer sends the proposal response back to the target peer. The proposal |
There was a problem hiding this comment.
lets keep it plural as in prior step -- "The endorsing peers send the ..."
andrew-coleman
force-pushed
the
private_data_doc
branch
from
5d3b00e
to
cd28c79
Compare
Signed-off-by: andrew-coleman <andrew_coleman@uk.ibm.com>
andrew-coleman
force-pushed
the
private_data_doc
branch
from
cd28c79
to
07974a6
Compare
Minor doc update. Contributes to #2807
Signed-off-by: andrew-coleman andrew_coleman@uk.ibm.com