【Fabric2.4文档翻译】12体系结构参考-03Fabric网关

Fabric Gateway

官方文档：https://hyperledger-fabric.readthedocs.io/en/latest/gateway.html

参考翻译：https://blog.csdn.net/zhanglingge/article/details/122926437

Fabric Gateway is a service, introduced in Hyperledger Fabric v2.4 peers, that provides a simplified, minimal API for submitting transactions to a Fabric network. Requirements previously placed on the client SDKs, such as gathering transaction endorsements from peers of various organizations, are delegated to the Fabric Gateway service running within a peer to enable simplified application development and transaction submission in v2.4.

Fabric gateway是Hyperledger Fabric v2.4 peer节点中引入的一项服务，它为向Fabric网络提交交易提供了一个简化的、最小的API。先前对客户端SDK提出的要求（如从不同组织的peer节点收集交易背书）被委托给在peer节点中运行的Fabricgateway服务，以简化v2.4中的应用程序开发和交易提交。(只需要一个peer运行一个应用进程即可提交事务)

Writing client applications

Starting with Fabric v2.4, client applications should use one of the gateway SDKs (Go, Node, or Java), which are optimized to interact with the Fabric Gateway. These SDKs expose the same high-level programming model which was initially introduced in Fabric v1.4.

Fabric Gateway (aka the gateway) manages the following transaction steps:

• Evaluate a transaction proposal. This will invoke a smart contract (chaincode) function on a single peer and return the result to the client. This is typically used to query the current state of the ledger without making any ledger updates.
  The gateway will preferably select a peer in the same organization as the gateway peer and choose the peer
  with the highest ledger block height. If no peer is available in the gateway’s organization, then it will choose a peer
  from another organization.
• Endorse a transaction proposal. This will gather enough endorsement responses to satisfy the combined signature policies
  (see below) and return a prepared transaction envelope to the client for signing.
• Submit a transaction. This will send a signed transaction envelope to the ordering service to commit to the ledger.
• Wait for commit status events. This allows the client to wait for the transaction to be committed to the ledger and to
  get the commit (validation/invalidation) status code.
• Receive chaincode events. This will allow client applications to respond to events that are emitted by a smart contract
  function when a transaction is committed to the ledger.

The gateway SDKs combine the Endorse/Submit/CommitStatus actions into a single blocking SubmitTransaction function to support transaction submission with a single line of code. Alternatively, the individual actions can be invoked to support flexible application patterns.

编写客户端应用程序

从Fabric v2.4开始，客户端应用程序应使用其中一个gateway SDK（Go/Node/Java），这些SDK经过优化以与Fabricgateway交互。这些SDK暴露了最初在Fabric v1.4中引入的相同的高级编程模型。
Fabric gateway（也称为gateway）管理以下交易步骤：

• 评估交易提案。这将在单个peer节点上调用智能合约（链码）函数，并将结果返回给客户端。这通常用于查询账本的当前状态，而不对账本进行任何更新。gateway将优选地选择在同一组织中的peer节点，并选择具有最高区块高度的peer节点。如果gateway的组织中没有可用的peer节点，那么它就会选择来自另一个组织的peer节点
• 签署背书交易提案。这将收集足够的背书以满足组合签名策略（见下文)（below）并将准备好的交易信封返回给客户端进行签名
• 提交一个交易。这将会发送一个已签名的交易信封给排序服务order，提交给账本
• 等待提交状态事件。这允许客户端等待交易被提交到账本并获得已提交到账本状态码（交易状态码）。
• 接收链码事件。这将允许客户端应用程序响应当事务提交到账本时，智能合约函数发出的事件。（响应智能合约函数返回的数据）

gatewaySDK将 背书/提交/提交状态操作 组合成一个 SubmitTransaction（提交交易）函数，以支持使用单行代码提交交易。或者，可以调用单个操作来支持灵活的应用程序模式。

【tips：关于SubmitTransaction】 https://cloud.tencent.com/developer/article/2159268

invoke.js:

await contract.submitTransaction('createCar', 'CAR12', 'Honda', 'Accord', 'Black', 'Tom');

inovke程序使用的是submitTransactionAPI和区块链网络交互的，而不是evaluateTransaction。

submitTransaction比evaluateTransaction要复杂的多。不只是和单个节点交互，SDK将把submitTransaction提案发送到区块链网络中每一个必要的组织的节点。每一个节点都将根据这个提案执行请求的智能合约，并生成一个该节点签名的交易响应并返回给SDK 。SDK将所有经过签名的交易响应收集到一个交易中，这个交易将会被发送到排序节点。排序节点搜集并排序每个应用的交易，并把这些交易放入到一个交易区块。然后排序节点将这些区块分发到网络中的节点，每一笔交易都会在节点中进行验证和提交。最后，SDK会后到提醒，并把控制权返回给应用程序。

submitTransaction也会包括一个监听器用于确保交易已经被校验和提交到账本里了。应用程序需要利用监听器或者使用submitTransaction接口，它内部已经实现了监听器。如果没有监听器，你可能无法确定交易是否被排序校验以及提交。

应用程序中的这些工作由submitTransaction完成！应用程序、智能合约、节点和排序服务一起工作来保证网络中账本一致性的程序被称为共识。

Software Development Kits (SDKs)

The Gateway and its SDKs are designed to allow you, as a client
application developer, to concentrate on the business logic of your
application without having to concern yourself with the
infrastructure logic associated with a Fabric network. As such, the APIs provide logical abstractions such as organization and
contract rather than operational abstractions such as peer and chaincode. [Side note - clearly an admin API would want to expose these operational abstractions, but this is not an admin API].

Hyperledger Fabric currently supports client application development
in three languages:

• Go. See the Go SDK for Fabric Gateway documentation
  for full details.
• Node (Typescript/Javascript). See the Node SDK for Fabric Gateway
  documentation
  for full details.
• Java. See the Java SDK for Fabric Gateway documentation
  for full details.

软件开发工具(SDK)

gateway和它提供的SDK被设计得允许客户端应用开发者集中精力在应用程序上，而不用担心如何与Fabric网络基础设施逻辑交互。因此，API提供逻辑抽象，如组织和合约 而不是操作抽象，如peer节点和链码。[tips:显然管理员API希望公开这些操作抽象，但这不是一个管理API]

Hyperledger Fabric 目前支持3种语言进行客户端应用开发：

• Go Go SDK for Fabric Gateway documentation
• Node(Typescript/javascript) Node SDK for Fabric Gateway documentation
• Java Java SDK for Fabric Gateway documentation

How the gateway endorses your transaction proposal

In order for a transaction to be successfully committed to the ledger, a sufficient number of endorsements are required in order to satisfy the endorsement policy. Getting an endorsement from an organization involves connecting to one
of its peers and have it simulate (execute) the transaction proposal against its copy of the ledger. The peer simulates the transaction by invoking the chaincode function, as specified by its name and arguments in the proposal, and building (and signing) a read-write set. The read-write set contains the current ledger state and proposed changes in response to the state get/set instructions in that function.

The endorsement policy, or sum of multiple policies, that gets applied to a transaction depends on the implementation of the chaincode function that is being invoked, and could be a combination of the following:

• Chaincode endorsement policies. These are the policies agreed to by channel members when they approve a chaincode definition for their organization. If the chaincode function invokes a function in another chaincode, then both policies will need to be satisfied.
• Private data collection endorsement policies. If the chaincode function writes to a state in a private data collection,
  then the endorsement policy for that collection will override the chaincode policy for that state. If the chaincode function reads from a private data collection, then it will be restricted to organizations that are members of that collection.
• State-based endorsement (SBE) policies. Also known as key-level signature policies, these can be applied to individual
  states and will override the chaincode policy or collection policy for private data collection states. The endorsement policies themselves are stored in the ledger and can be updated by new transactions.

The combination of endorsement policies to be applied to the transaction proposal is determined at chaincode runtime and cannot necessarily be derived from static analysis.

The Fabric Gateway manages the complexity of transaction endorsement on behalf of the client, using the following process:

• The Fabric Gateway selects the endorsing peer from the gateway peer’s organization (MSPID) by identifying the (available) peer with the highest ledger block height. The assumption is that all peers within the gateway peer’s organization are trusted by the client application that connects to the gateway peer.
• The transaction proposal is simulated on the selected endorsement peer. This simulation captures information about the accessed states, and therefore the endorsement policies to be combined (including any individual state-based policies
  stored on the endorsement peer’s ledger).
• The captured policy information is assembled into a ChaincodeInterest protobuf structure and passed to the discovery service in order to derive an endorsement plan specific to the proposed transaction.
• The gateway applies the endorsement plan by requesting endorsement from the organizations required to satisfy all policies in the plan. For each organization, the gateway peer requests endorsement from the (available) peer with the highest block height.

The gateway is dependent on the discovery service to get the connection details of both the available peers and ordering service nodes, and for calculating the combination of peers that are required to endorse the transaction proposal. The discovery service must therefore always remain enabled on peers where the gateway service is enabled.

The gateway endorsement process is more restrictive for private data passed in the proposal as transient data because it often contains sensitive or personal information that must not be passed to peers of all organizations. In this case, the gateway will restrict the set of endorsing organizations to those that are members of the private data collection to be accessed (either read or write). If this restriction for transient data would not satisfy the endorsement policy, the gateway returns an error to the client rather than forwarding the private data to organizations that may not be authorized to access the private data. In these cases, client applications should be written to explicitly define which organizations should endorse the transaction.

gateway怎样背书你的交易提案

为了将交易成功提交到账本，需要足够数量的背书才能满足[背书政策] endorsement policy. 获得组织的认可需要连接到组织中的peer节点，并让它根据其账本副本模拟（执行）交易提案。peer节点通过调用链码函数（由提案中的名称和参数指定）并构建（和签名）读写集来模拟交易。读写集包含当前账本状态以及响应该函数中的状态 GET/SET 指令的建议更改。

应用于交易的背书策略或多个策略的总和取决于正在调用的链码函数的实现，并且可能是以下组合：

• 链码背书策略。这些是通道成员在批准其组织的链码定义时同意的策略。如果链码函数调用另一个链码中的函数，则需要同时满足两个策略。
• 私人数据收集认可政策。如果链码函数写入私有数据收集中的状态，然后，该集合的背书策略将覆盖该状态的链码策略。如果链码函数从私有数据收集中读取，那么它将仅限于作为该集合成员的组织。
• 基于状态的认可 （SBE） 策略。也称为密钥级签名策略，这些策略可应用于单个状态，并将覆盖私有数据收集状态的链码策略或收集策略。背书策略本身存储在账本中，可以通过新交易进行更新。

应用于交易提案的背书策略组合在链码运行时确定，不一定来自静态分析。

Fabricgateway使用下面这些过程代表客户端管理交易背书的复杂性：

• Fabric Gateway通过识别具有最高账本块高度的（可用）peer节点，从gateway peer的组织 （MSPID） 中选择背书peer。假设gatewaypeer组织中的所有peer都受连接到gatewaypeer的客户端应用程序的信任。
• 在选定的背书对等节点上模拟交易提案。此模拟捕获有关访问状态的信息，从而捕获要组合的背书策略（包括任何单个基于状态的策略）存储在背书对等方的分类账上）。
• 捕获的策略信息被组装成“ChaincodeInterest”protobuf结构，并传递给发现服务，以便得出特定于提出交易的背书计划。
• gateway通过向满足计划中的所有策略所需的组织请求背书来应用背书计划。对于每个组织，gateway peer会选取组织中区块最高的peer

gateway靠发现服务获取可用peer和排序服务节点的连接细节，并计算交易背书所需哪些peer。所以在gateway服务开启的peer上，discovery service也要开启。

gateway背书进程对私密数据有严格的限制，数据会以临时数据的方式在组织中传递，因为私密数据往往是敏感和个人数据，不能在全部组织中传递。对于这种情况，gateway需要限制背书组织为私密数据集合的成员（或读或写）。如果限制没有满足背书策略，gateway会返回error到客户端，而不是继续将私密数据在组织间传递，因为这可能会被私密数据拒绝访问。这种情况下客户端应用需要写清楚 explicitly define which organizations should endorse。

Targeting specific endorsement peers

In some cases, a client application must explicitly select the organizations to evaluate or endorse a transaction proposal.
For example, transient data often contains personal or sensitive information which must be written only to a private data collection, thereby limiting the pool of endorsement organizations.
In these cases, the client application can explicitly specify the endorsing organizations to meet both the privacy and endorsement requirements of the application; the gateway will then select the (available) endorsing peer with the highest block count from each specified organization.
However, if the client specifies a set of organizations that does not satisfy an endorsement policy, the transaction may still get endorsed by the specified peers and submitted for ordering, but the transaction will later be invalidated by all peers in the channel during the validation and commit phase.
This invalidated transaction is recorded on the ledger but the transaction’s updates are not written to the state database on any channel peer.

指定具体的背书peer节点

在一些情况下，一个客户端应用必须明确地选择组织来审议或背书交易提案。例如，交易数据通常包含个人或隐私信息，这些信息必须被写入隐私数据集中，因此需要限制背书组织集合。这些情况下，客户端应用指明背书组织，以满足隐私和背书需求；gateway需要从指定的背书组织中选取区块最高的peer。但是，如果客户端指明的背书组织没有满足背书策略，交易依然会获取指明的peer的背书，并提交到order，但在验证和提交阶段，所有peer会使交易无效。这次无效会记录在账本上，但交易不会写入到状态任何peer的状态数据库中。

Retry and error handling

Fabric Gateway handles node connectivity retry attempts, errors, and timeouts as described below.

Retry attempts

The gateway will use discovery service information to retry any transaction that fails due to an unavailable peer or ordering node. If an organization is running multiple peer or ordering nodes, then another qualifying node will be attempted. If an organization fails to endorse a transaction proposal, then another one will be selected. If an organization fails to endorse entirely, a group of organizations that satisfies the endorsement policy will be targeted. Only if there is no combination of available peers that satisfies the endorsement policy will the gateway stop retrying. The gateway will continue with retry attempts until all possible combinations of endorsing peers have been tried once.

Error handling

The Fabric Gateway manages gRPC connections to network peer and ordering nodes. If a gateway service request error originates from a network peer or ordering node (i.e. external to the gateway), the gateway returns error, endpoint, and organization (MSPID) information to the client in the message Details field. If the Details field is empty, then the error originated from the gateway peer.

Timeouts

The Fabric Gateway Evaluate and Endorse methods make gRPC requests to peers external to the gateway. In order to limit the length of time that the client must wait for these collective responses, the peer.gateway.endorsementTimeout value can be overridden in the gateway section of the peer core.yaml configuration file.

Each Gateway SDK also provides a mechanism for setting timeouts for each gateway method when invoked from the client application.

重试和错误处理

gateway处理节点有重试连接，错误和延时处理。

重试

gateway会使用discovery service的信息来重试连接不可用的peer和node。如果一个组织运行了多个peer或order节点，那另一个合格的节点会被尝试连接。如果一个组织背书交易时失败，那另一个组织会被尝试。如果一个组织一直背书失败，一组满足条件的组织会成为新的目标。只有没有了满足背书策略的peer可用，gateway才会停止尝试。gateway会一致尝试，直到所有可能的背书peer都被试过。

错误处理

Fabric gateway通过gRPC联系网络中的peer和order。如果gateway请求错误源于peer和order的网络（也就是gateway外部），gateway会返回错误，端口，和组织ID信息给客户端在details字段中。如果details字段为空，那错误来自原gateway peer。

超时

Fabric gateway的评估和背书方法向外部的gateway发送gRPC请求。为了限制客户端需要等待响应的时间，core.yaml中的peer.gateway.endorsementTimeout可以再gateway中重置。

Fabric gateway客户端api也提供了默认设置和单次调用超时设置的机制。

Listening for events

The gateway provides a simplified API for client applications to receive chaincode events in the client applications. Each SDK provides a mechanism to handle these events using its language-specific idiom.

监听事件

gateway 提供了简单的接受chaincode events的API。每个SDK提供了一种机制，可以使用特定于语言的习惯用法来处理这些事件。