Update 'Running a Fabric Application' tutorial for Fabric Gateway #3110
Conversation
bestbeforetoday
force-pushed
the
docs
branch
2 times, most recently
from
efa577b
to
974ae90
Compare
docs/source/write_first_app.rst
Outdated
| .. code:: bash | ||
| The sample application uses an X.509 certificate for the Org1 user identity, and a signing implementation based on the | ||
| corresponding private key. These credentials are created using the Org1 Certificate Authority when the test network | ||
| is started. |
There was a problem hiding this comment.
So needs something like "The following code snippet ... " is what, or does what.
docs/source/write_first_app.rst
Outdated
| The terminal output entry should look similar to below: | ||
| An initialization function to set up initial ledger state would typically be called only once after a smart contract | ||
| is deployed for the first time. A new version of the smart contract would likely not require the initialization to be | ||
| performed again. In this case it is good practice for the transaction function to check and perhaps also record some |
There was a problem hiding this comment.
tx function being the smart contract code, within the chaincode right.
| them to bytes internally. | ||
|
|
||
| Next, the sample application submits a transaction to transfer ownership of the newly created asset. This time | ||
| the transaction is invoked using ``submitAsync()``, which returns after successfully submitting the endorsed |
There was a problem hiding this comment.
note first time "endorsed" mentioned; may need to add it earlier.
docs/source/write_first_app.rst
Outdated
| Terminal Output: | ||
|
|
||
| .. code:: bash | ||
| The final part of the sequence demonstrates an error submitting a transaction. In this example, the application attempts |
There was a problem hiding this comment.
Should we mention "the gateway service" here as a player.
bestbeforetoday
force-pushed
the
docs
branch
3 times, most recently
from
5fd98df
to
f69764d
Compare
bestbeforetoday
force-pushed
the
docs
branch
from
f69764d
to
a73d21c
Compare
| to find a set of required endorsing peers for the chaincode, invoke the chaincode | ||
| on the required number of peers, gather the chaincode endorsed results from those peers, | ||
| and finally submit the transaction to the ordering service. | ||
| 1. Endorse the transaction proposal. |
There was a problem hiding this comment.
I think it makes sense to explain this at a high level (one paragraph), even though it is described in other key concepts topics in more detail.
e.g. something at this level of detail "submitTransaction() will request the targeted Gateway peer to execute the chaincode and gather endorsements from the required number of peers to meet the endorsement policy (in our case the Org1 gateway peer as well as the Org2 peer), then will sign the transaction."
There was a problem hiding this comment.
It was described at a high level previously but was deemed confusing, so avoided.
There was a problem hiding this comment.
@joshhus what was the concern? A sentence or two would definitely help here. Feel free to propose an edit to what I suggested.
There was a problem hiding this comment.
The discussion here was that it initially read as if an "endorsement" by one peer / org then leads to a commitment to the ledger. Without a full understanding of endorsement and endorsement policies, that sounded potentially misleading to me. We discussed this when reviewing the other topics also - endorsement by one org does not mean the Tx passes endorsement (policies). So generally a semantics issue of being imprecise with the word "endorsed" in different contexts.
There was a problem hiding this comment.
Actually the comments before were on whether the brief description of executing the transaction on peers matched the description of the endorsement process we already have in other pages.
My intent with this list of steps is to signpost the following application flow, which is what gets executed when you call submitTransaction(), not to describe the transaction flow at the server side:
- endorse()
- submit()
- getStatus() to wait for the transaction commit
Understanding the application API flow is important for interpreting error types that may be generated by that flow, touched on in the last step.
bestbeforetoday
force-pushed
the
docs
branch
from
a73d21c
to
c4439c6
Compare
|
The discussion around "gateway peer" - I don't see the comment here any more - was only that "gateway" to modify peer was deemed redundant in this context (in our prior reviews), because all peers are now "gateway" peers. So not to avoid using "peer" but to avoid using "gateway peer". ... So in prior docs we use "peer" when that is important - such as in getting a connection from the client app. ... When it's the "Fabric Gateway service" specifically (running on the peer) that is doing things, then we call it that, as opposed to a "peer" doing things. |
bestbeforetoday
force-pushed
the
docs
branch
from
c4439c6
to
5958b86
Compare
The client app only interacts with the Gateway service. Whether that Gateway service runs on a peer is irrelevant to the client application. There was a point in time where the Gateway service was implemented in a separate component, not in a peer, and this could be the case again in the future. It really makes no difference from the client application perspective discussed in this tutorial. |
|
Maybe 3 sections would have been clearer. To consider another time without a deadline -- |
I beg to differ... the client needs to connect to a certain endpoint, and that endpoint is generally known as the peer endpoint throughout all the other doc topics. I'm just suggesting to mention that the gateway service runs in a peer so that readers know exactly which endpoint they are connecting to. That seems like a fundamental concept that client application developers need to know. Yes, the Gateway could in theory run anywhere, and that's exactly why the reader may be in doubt. But we chose to run it in the peer and should communicate that. Just one mention early on would be sufficient to clear up any doubt. |
The code snippets and some of the supporting text already explicitly state that it's the peer endpoint. I'll add a little more wording to reinforce that though. |
Also fixed a few build warnings in other documents. Signed-off-by: Mark S. Lewis <mark_lewis@uk.ibm.com>
bestbeforetoday
force-pushed
the
docs
branch
from
5958b86
to
4de78e9
Compare
|
@Mergifyio backport release-2.4 |
✅ Backports have been created
|
Also fixed a few build warnings in other documents.
Contributes to #2807