Gateway documentation

[denyeart]

Terminology

• Target peer endpoint (or set of load balanced peers).
• Peer Gateway ("gateway in the peer") versus SDK Gateway ("gateway in the SDK")
• Fabric Gateway SDKs versus Legacy SDKs

Top Priorities (Dave)

• https://hyperledger-fabric.readthedocs.io/en/latest/whatsnew.html#
• https://hyperledger-fabric.readthedocs.io/en/latest/txflow.html

Top priorities (Mark)

• https://hyperledger-fabric.readthedocs.io/en/latest/sdk_chaincode.html#fabric-application-sdks
• https://hyperledger-fabric.readthedocs.io/en/latest/fabric-sdks.html this page could be removed in favor of the prior page.
• https://hyperledger-fabric.readthedocs.io/en/latest/write_first_app.html talks about SDK gateway and submitTransaction() - switch from asset-transfer-basic/application-javascript to asset-transfer-basic/application-gateway-typescript. Mention the two primary patterns 1) delegating endorsement to peer gateway and 2) specifying the endorsing organizations
• https://hyperledger-fabric.readthedocs.io/en/latest/peer_event_services.html#sdk-event-documentation

Top priorities (Andy)

• Add "Gateway" topic next to current Service Discovery architectural topic, cross-link them, and make any updates to "Service Discovery" so that they complement each other well.

Top priorities (Josh with guidance from Andy)

• Key Concepts - Peer topic. Add a peer gateway section in or around the "Applications and Peers" section to introduce the gateway key concepts. Mention the two primary patterns 1) delegating endorsement to peer gateway and 2) specifying the endorsing organizations.
• https://hyperledger-fabric.readthedocs.io/en/latest/peers/peers.html#applications-and-peers -
• https://hyperledger-fabric.readthedocs.io/en/latest/peers/peers.html#peers-and-organizations
• https://hyperledger-fabric.readthedocs.io/en/latest/peers/peers.html#phase-1-proposal

Top priorities (Chris with guidance from Andy and Mark)

• updating existing applications to use new SDKs

Key Concepts - Private data (Andy)

• Mention the different gateway behavior when working with private data collections.
• https://hyperledger-fabric.readthedocs.io/en/latest/private-data/private-data.html#transaction-flow-with-private-data

Other Key Concept topics (Josh)

• There are minor references to application/peer flow in these topics. At each occurrence mention 'target' peer distributes the request to endorsing peers, and when using 'legacy SDKs' it is the application/SDK responsibility.
• https://hyperledger-fabric.readthedocs.io/en/latest/network/network.html#using-an-application-on-the-channel
• https://hyperledger-fabric.readthedocs.io/en/latest/orderer/ordering_service.html#phase-one-proposal
• https://hyperledger-fabric.readthedocs.io/en/latest/orderer/ordering_service.html#phase-two-ordering-and-packaging-transactions-into-blocks

Tutorials (Josh)

• Each of these tutorials utilize peer CLI "peer chaincode invoke" with --peerAddresses. At the first occurrence within each tutorial simply state that CLI does not use gateway and you must target all the endorsing peers.
• https://hyperledger-fabric.readthedocs.io/en/latest/test_network.html
• https://hyperledger-fabric.readthedocs.io/en/latest/deploy_chaincode.html
• https://hyperledger-fabric.readthedocs.io/en/latest/secured_asset_transfer/secured_private_asset_transfer_tutorial.html

FAQ - minor edits required (Dave)

• https://hyperledger-fabric.readthedocs.io/en/latest/Fabric-FAQ.html#endorsement
• https://hyperledger-fabric.readthedocs.io/en/latest/Fabric-FAQ.html#application-side-programming-model

Developing Applications and Commercial Paper tutorial (Andy/Mark/Matthew/James)

• These topics discuss legacy SDK approach in detail. Developing Applications needs an entire overhaul with peer gateway highlighted. Will be tracked in Refactor Developing Applications documentation #2983.
• https://hyperledger-fabric.readthedocs.io/en/latest/developapps/application.html
• https://hyperledger-fabric.readthedocs.io/en/latest/developapps/connectionprofile.html
• https://hyperledger-fabric.readthedocs.io/en/latest/developapps/connectionoptions.html
• https://hyperledger-fabric.readthedocs.io/en/latest/developapps/wallet.html
• https://hyperledger-fabric.readthedocs.io/en/latest/developapps/gateway.html
• https://hyperledger-fabric.readthedocs.io/en/latest/tutorial/commercial_paper.html

[yacovm]

https://hyperledger-fabric.readthedocs.io/en/latest/discovery-overview.html Update "Service Discovery" topic to be "Service Discovery and Gateway"

I don't think we should couple SD and GW.
Service discovery is a service that is used also by Fabric smart client and older SDKs.
The fact that the gateway uses it doesn't mean we should couple the two together.

The gateway feature is big enough to deserve its own page. Of course, it makes sense to link to the gateway from the service discovery and vice versa, but let's not create technical confusion.

[denyeart]

@yacovm

Add "Gateway" topic next to current Service Discovery architectural topic, cross-link them, and make any updates to "Service Discovery" so that they complement each other well.

You can remove your emoji now!

[joshhus]

@denyeart Should this link to Epic #2825 ... no correct answer.

[denyeart]

@joshhus yes this issue is a child of epic #2825

[joshhus]

• Reviewed / commented on Gateway overview doc PR - Add gateway architecture page to docs #3008 ... I would recommend another iteration before final, due to length and complexity.
• Terminology - I think we can properly initial capitalize "Fabric Gateway" as a feature (even though it's no-cost), and then safely use "gateway" as shorthand within that context.

[joshhus]

@denyeart Can you confirm the tutorials text - seems odd that the CLI would not use gateway. Or are we saying that CLI does not access the gateway for THIS command / examples.
Also what is this https://github.com/hyperledger/fabric/tree/main/docs
vs. this https://github.com/hyperledger-labs/fabric-operations-console/tree/main/docs

[denyeart]

@joshhus CLI should ideally use gateway, but updating the CLI has not been prioritized yet.

Your first link is the main fabric docs source that generates ReadTheDocs.
The second link is specific to the IBP fabric operations console that was contributed recently to Hyperledger.

[joshhus]

I don't seem to have access to check boxes. Tutorials done. Gateway overview done or close to it.
2 of 3 Key Concepts done, at high level mention. Will post URLs to verify.

[joshhus]

@denyeart I suggested some clarifications for your follow on PR - 2 comments - #3047
@andrew-coleman

[denyeart]

@denyeart I suggested some clarifications for your follow on PR - 2 comments - #3047 @andrew-coleman

@joshhus I answered your direct question in #3407. Please go ahead with any subsequent edits in another follow-on PR.

[joshhus]

@denyeart @andrew-coleman Another page to get a redo for for 2.4 gateway - https://hyperledger-fabric.readthedocs.io/en/release-2.3/txflow.html?highlight=transaction%20flow . ... With images.

[joshhus]

• New PR for Peers e3e edit. Gateway overview some minor updates. 1121 peers e2e and gateway #3072
• Note diagrams are commented out for Figure 6 and Figure 10. They are complex, the original source is lost, and we have no graphic design resource to redraw. TBA. In 2.3 these are https://hyperledger-fabric.readthedocs.io/en/release-2.3/peers/peers.html#applications-and-peers and https://hyperledger-fabric.readthedocs.io/en/release-2.3/peers/peers.html#phase-1-proposal

[jonmchan]

New hyperledger fabric developer feedback - I am totally confused between 2.4 Fabric Gateway and the previous gateway references.

1. What/where is the "Gateway" design element - https://hyperledger-fabric.readthedocs.io/en/latest/developapps/gateway.html. Is this deprecated by Fabric Gateway? What gateway code is being called in the code snippets await gateway.connect(connectionProfile, connectionOptions); ?

2. Is https://github.com/hyperledger/fabric-gateway-java related to 2.4 Fabric Gateway?

It would appear there are 3 references to 3 different "gateway" code or design elements. Clarity in documentation would be very much appreciated, especially if older versions can not be retroactively changed to remove overloaded references.

[bestbeforetoday]

@jonmchan The documentation is still being reworked following the release of Fabric v2.4, including the Fabric Gateway service. Developing Applications is one of the pieces not yet updated. Feedback on where it is deficient (and it is!) is welcome; as are contributions.

Do these updated pages make things any clearer around Fabric Gateway and the application APIs?

• https://hyperledger-fabric.readthedocs.io/en/latest/gateway.html
• https://hyperledger-fabric.readthedocs.io/en/latest/sdk_chaincode.html

[jonmchan]

@bestbeforetoday thanks for the reply. The updated pages provide limited clarity on the topic for me. Yes, through the documentation, I understand the gateway abstracts away from the client having to know which peers to connect and exposes evaluate, endorse, and submit functions to the client to interact with the blockchain, but how this relates to older versions of the code and fabric-gateway-java is not understood. Further, no working example of this is available (ran into issue trying to start fabric-gateway test network and scenarios - hyperledger/fabric-gateway#351 (comment)). A tutorial would be very useful. I found the original RFC more insightful than the documentation - https://hyperledger.github.io/fabric-rfcs/text/0000-fabric-gateway.html.

Open questions and state of learning discovery for this new hyperledger fabric developer:

What becomes of all the connection profiles and setup mentioned in https://hyperledger-fabric.readthedocs.io/en/latest/developapps/gateway.html?

It would appear from the RFC that fabric-gateway-java is indeed related to Fabric Gateway as mentioned in prior art https://hyperledger.github.io/fabric-rfcs/text/0000-fabric-gateway.html#prior-art? Is this the same project? Does the fabric-gateway-java become deprecated or are they independent methodologies of achieving the same thing?

[jonmchan]

imho, one of the biggest causes of confusion is the name overload for "fabric-gateway". The new 2.4 integrated Fabric Gateway is exactly the same as the 1.4 external fabric-gateway which makes google searching extremely confusing and frustrating - it's not like these 2 things are different - they're both implementations of a gateway system so you can't even tell from reading the context. The original poster "Peer Gateway" vs "SDK Gateway" terminology needs to be highlighted and utilized as much as possible.

[bestbeforetoday]

@jonmchan The tutorial for running a Fabric application has now been updated, and steps through set up and running one of the samples in the fabric-samples repository that uses the new application API:

https://hyperledger-fabric.readthedocs.io/en/latest/write_first_app.html

Does this help?

[bestbeforetoday]

@jonmchan The two documentation pages I linked to earlier should answer your question on how the fabric-gateway and fabric-gateway-java APIs relate to each other. For example, the Fabric Contract APIs and Application APIs page refers and links to the fabric-gateway API as "the preferred API for developing applications for Fabric v2.4 onwards", whereas it refers and links to the fabric-gateway-java SDK as "Legacy application SDKs [that] support versions of Fabric prior to v2.4, and do not require the Gateway peer capability."

Specific suggestions for what to say where to make things clearer are welcome.

[jonmchan]

@bestbeforetoday i'll go through the tutorial and leave feedback - this looks like it might be exactly what I'm looking for.

In terms of specific suggestions, since the documentation is very large and spans multiple pages, having a note on https://hyperledger-fabric.readthedocs.io/en/latest/developapps/gateway.html and https://hyperledger-fabric.readthedocs.io/en/latest/gateway.html may be useful for those directly going to those pages and not browsing the entire documentation. Alternatively, could the gateway pages be consolidated?

Thank you.

[joshhus]

@jonmchan In January we are restarting a HLF community monthly call on documentation. Perhaps you'd like to join it to give feedback and contributions. TBA. @denyeart

[jonmchan]

@joshhus sure - i'd be interested in participating. Keep me posted. Thank you.

[denyeart]

Closing this item in favor of individual issues for the remaining subtasks.

• Developing Applications Refactor Developing Applications documentation #2983
• FAQ Gateway documentation - Update FAQ #3152
• Updating existing applications Gateway documentation - New topic - updating existing applications to use new gateway SDKs #3151