Skip to content

Commit

Permalink
Gateway overview edited
Browse files Browse the repository at this point in the history 
Signed-off-by: Josh Horton <joshh@us.ibm.com>
  • Loading branch information
@joshhus @denyeart
joshhus authored and denyeart committed Nov 16, 2021
1 parent 9c5e1df commit da935d7
Showing 1 changed file with 57 additions and 97 deletions.
154 changes: 57 additions & 97 deletions docs/source/gateway.md
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,33 @@
# Gateway
# Fabric Gateway

## Overview

The Gateway is a new service introduced in v2.4 that provides a simplified, minimal API for submitting transactions
to a Fabric network.
Fabric Gateway is a service, introduced in Hyperledger Fabric v2.4, that provides a simplified, minimal API for submitting transactions to a Fabric network. Requirements previously placed on the client SDKs, such as specifying specific endorsement peers, are migrated to a single Fabric Gateway peer to enable simplified application development in v2.4.

## Writing client applications

Starting with v2.4, client applications should use one of the v2.4 SDKs which are optimised to interact with the Gateway.
These SDKs expose the same high-level programming model which was first introduced with v1.4 of Fabric.
Starting with Fabric v2.4, client applications should use a v2.4 SDK (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:

The gateway supports the following actions
- **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
- **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](#how-the-gateway-endorses-your-transaction-proposal)) 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
- **Endorse** a transaction proposal. This will gather enough endorsement responses to satisfy the combined signature policies
(see [below](#how-the-gateway-endorses-your-transaction-proposal)) 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.
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.

## 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,
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:
Expand All @@ -45,87 +39,53 @@ Hyperledger Fabric currently supports client application development in three la
## 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](endorsement-policies.html). 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 does this by
invoking the chaincode function whose name and arguments are specified in the proposal and building (and signing) a read-write set
containing the current ledger state and changes it would make in response to the state get/set instructions in that function.

The endorsement policy 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 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 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 it reads from a private
collection, then it will be restricted to organizations that are members of that collection.
the [endorsement policy](endorsement-policies.html). 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 if it's a private collection state).
The policies themselves are stored in the ledger and can be modified by transactions.

Although it might seem obvious from the transaction proposal which policies would be applied, the actual combination of
polices depends on what the chaincode function does at runtime and cannot necessarily be derived from static analysis.

The gateway handles all of this complexity on behalf of the client using the following process:

- The gateway selects the endorsing peer in the gateway's organization (MSPID) that has the highest ledger block height.
The assumption is that all peers within this organization are *trusted* by the client application that connects
to this gateway.
- It simulates the transaction proposal on that peer. During simulation, it captures all the relevant information on which
states are accessed and hence which policies will need to be combined (including any individual state-based policies
as stored in the peer's copy of the ledger).
- This information is assembled into a `ChaincodeInterest` protobuf structure and passed to the discovery service in order
to derive an endorsement plan specific for this transaction.
- Using the endorsement plan, the gateway will connect to and request endorsement from other organizations' peers to satisfy
the overall endorsement policy. It will generally request endorsement from the peer with the highest block height for any
given organization.

The gateway is dependent on the [discovery service](discovery-overview.html) to get the connection details of available peers
and ordering service nodes in a network, as well as for calculating the various permutations of peers that are required for
endorsement. It is important, therefore, that the discovery service has not been disabled in a gateway peer.

If the transaction proposal contains transient data, then the gateway takes a more cautious approach.
Transient data is often used to carry sensitive or personal information that must not persist in the ledger.
A typical usage pattern involves sending the proposal to specific organizations which write the data to their private collections.
The gateway will restrict the set of endorsing organizations to those that are members of the collections involved.
If this restriction does not satisfy the endorsement policy, it will return an error to the client in preference
to potentially leaking sensitive data. In this situation, the client should [explicitly define which organizations should
endorse](#how-to-override-endorsement-policy-detection) the transaction.

### How to override endorsement policy detection

There may be situations where the client application needs to explicitly define which organizations should be targeted to
evaluate or endorse a transaction proposal. One such example is when sensitive data is being passed in the transient field,
and the client wants to be *absolutely sure* which organizations will receive it. In these situations the client application
can specify the endorsing organizations. The gateway will select a peer from each of these (bypassing the mechanism described above)
and build a transaction using these endorsements. It's important to note that if this set of organizations does not satisfy
the endorsement policy, then the transaction will be included in a block but invalidated by all peers, and the
transaction's writes will not be updated in the state database.

### Error and retry handling

#### Retry
The gateway, using information from the discovery service, will make every effort to evaluate or submit a transaction in a network
that could suffer from peers or ordering nodes being unavailable for any reason. If a peer fails, and its organization is
running multiple peers, then another one will be selected. If an organization fails to endorse entirely, then another
set of organizations which also satisfies the endorsement policy will be targeted. Only if there is no combination of available peers
that satisfy the endorsement policy will the gateway stop retrying. The gateway will not retry the same peer for
any given transaction proposal.

#### Errors
The gateway manages gPRC connections to other peers and ordering nodes in the network. If the failure of a gateway service
request is due to an error returned from one or more of these external nodes, then the details of this error, together with
endpoint address and MSPID of the failing node will be included in the `Details` field of the error returned from the gateway
to the client. If the `Details` field is empty, then the error would have originated in the gateway.
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](discovery-overview.html) 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 the Fabric Gateway peer.

The gateway endorsement process is more restrictive for transient data because it often contains sensitive or personal information that must not persist in the ledger. The gateway sends proposals involving transient data to only the organizations which write the specific transient data to their private collections. The gateway restricts the endorsing organizations to only those that write the specific transient data to a shared private data collection. If the restriction for transient data results in failed endorsement, the gateway rejects the transaction proposal. In this situation, the client should [explicitly define which organizations should endorse](#how-to-override-endorsement-policy-detection) the transaction, which must be limited to organizations that share the relevant private data collection.

### Targeting specific endorsement peers

In some cases, a client application must explicitly identify the specific organizations to evaluate or endorse a transaction proposal. Transient data, for example, often contains personal or sensitive information that must only be written to a shared private data collection. In these cases, the client application can explicitly specify the endorsing organizations; the gateway will select the available peer with the highest block count from each organization. However, if the inclusion of an organization violates a required endorsement policy, then the transaction is invalidated by all of the requested endorsing peers. This failed endorsement is recorded on the ledger but no transaction writes will exist in the state database.

### 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 gateway `Evaluate` and `Endorse` methods involve making gRPC requests to external peers. In order to limit the length
of time that the client must wait for these collective responses, a configurable `EndorsementTimeout` is available
to override in the gateway section of the [peer config file](https://github.com/hyperledger/fabric/blob/main/sampleconfig/core.yaml#L55).
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 `EndorsementTimeout` value can be overridden in the gateway section of the [peer config file](https://github.com/hyperledger/fabric/blob/main/sampleconfig/core.yaml#L55).

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

## How to listen for events
## Listening for events

The gateway provides a simplified API for receiving [chaincode events](peer_event_services.html#how-to-register-for-events)
in the client applications. Each SDK provides a mechanism to handle these events using its language-specific idiom.
The gateway provides a simplified API for client applications to receive [chaincode events](peer_event_services.html#how-to-register-for-events) in the client applications. Each SDK provides a mechanism to handle these events using its language-specific idiom.

0 comments on commit da935d7

Please sign in to comment.