The process of writing a Fabric application begins with chaincode, but ultimately the developer must make judicious decisions about how an end user or a software agent must interface with that chaincode. How the assets of the chaincode, and the operations of the blockchain network running that chaincode, ought to be exposed to the user is a question that ought to be dealt with carefully. Significant damage is possible if these capabilities are exposed without restriction, especially the ones involving blockchain bootstrapping and configurations. Proper operation of the chaincode itself relies not just on its internal logic, but suitable access controls being built above it. As we saw in the previous section, setting up an application and preparing it for use is a complex process. In addition, the asynchronous nature of ledger-update transactions requires an arbitration layer between the chaincode and the user. To allow the user to focus on transactions that impact the application rather than the details of the network modules, all this complexity ought to be hidden as much as possible. It is for this reason that a three-layer architecture has evolved as the standard for a Fabric application, as illustrated in the following diagram:

At the lowest layer lies the smart contract that operates directly on the shared ledger, which may be written using one or more chaincode units. These chaincodes run on the network peers, exposing a service API for invocations and queries, and publishing event notifications of transaction results, as well as configuration changes occurring on the channel.

In the middle layer lies the functions to orchestrate the various stages of a blockchain application (see Figure 5.1: The stages in the creation and operation of a blockchain application). Hyperledger Fabric provides an SDK (currently available in Node.js as well as in Java) to perform functions such as channel creation and joining, registration, and enrollment of users, as well as chaincode operations. In addition, the SDK offers mechanisms to subscribe to transaction and configuration-related events emanating from the network. Depending on application needs, an off-chain database may be maintained for convenience, or as a cache of ledger state.

At the topmost layer lies a user-facing application that exports a service API consisting mostly of application-specific capabilities, though administrative operations such as channel and chaincode operations may also be exposed for system administrators. Typically, a user interface should also be provided for ease of use, though a well-defined API may suffice if the user is a software agent. We refer to this layer simply as the application, as this is what the end user (or agent) will see. Also, given that any blockchain application and network is an agglomeration of diverse participants, this layer will often consist of multiple application stacks tailored to the different participants.

This architecture should not be set in stone; it is meant to serve purely as a guideline for developers. Depending on the complexity of the application, both the number of layers and the verticals (or distinct applications) may vary. For a very simple application that has a small number of capabilities, the developer may even choose to compress the middleware and application layers into one. More generally though, this decoupling enables different sets of capabilities to be exposed to different network participants. For example, in our trade use case, a regulator and an exporter would view the blockchain in different ways and have diverging needs, and therefore it would be useful to build distinct service sets for them rather than force-fit all capabilities into one monolithic application with a uniform interface. Yet both these applications ought to hide the complexities of network operations, such as the creation and joining of channels, or privileged operations such as the installation of chaincode onto peers in similar ways, which would therefore benefit from a common middleware layer.

The ways in which the application layers the users directly interact with can be designed present many choices and complexities, and we will delve into those in the latter part of this chapter. First, though, we will describe how to implement the guts of a Fabric application, focusing on the essential elements. For instructive purposes, our topmost layer will be a simple web server exposing a RESTful service API.