Use the Hyperledger Fabric SDKs to Develop Applications

Applications use a software development kit (SDK) to access the APIs that permit queries and updates to the ledger. You can install and use the Hyperledger Fabric SDKs to develop applications for Oracle Blockchain Platform.

The REST APIs provided by Oracle Blockchain Platform have been created with maximum flexibility in mind; you can invoke a transaction, invoke a query, or view the status of a transaction. See REST API for Oracle Blockchain Platform.

However this means that you'll likely want to wrap the existing API endpoints in an application to provide object-level control. Applications can contain much more fine-grained operations.

SDK Versions

Multiple versions of the Hyperledger Fabric SDKs are available. Use the version of the SDK that matches the version of Hyperledger Fabric that your instance is based on.

Installing the Hyperledger Fabric SDK for Node.js

Information about how to use the Fabric SDK for Node.js can be found here: Hyperledger Fabric SDK for Node.js documentation

On the Developer Tools tab, open the Application Development pane.

You can install the Hyperledger Fabric Node.js SDK by using the link on this tab.
(Hyperledger Fabric v1.4.7) If you've previously installed it you must modify it to work with Oracle Blockchain Platform following the instructions in Update the Hyperledger Fabric v1.4.7 SDKs to Work with Oracle Blockchain Platform.

Installing the Hyperledger Fabric SDK for Java

Information about how to use the Fabric SDK for Java can be found here: Hyperledger Fabric SDK for Java documentation

On the Developer Tools tab, open the Application Development pane.

You can install the Hyperledger Fabric Java SDK by using the link on this tab.
(Hyperledger Fabric v2.x) If you've previously installed it you must modify it to work with Oracle Blockchain Platform following the instructions in Update the Hyperledger Fabric v2.x SDKs to Work with Oracle Blockchain Platform.
(Hyperledger Fabric v1.4.7) If you've previously installed it you must modify it to work with Oracle Blockchain Platform following the instructions in Update the Hyperledger Fabric v1.4.7 SDKs to Work with Oracle Blockchain Platform.

Install a build tool such as Apache Maven.

Structuring your Application

Your Java application should be structured similar to the following:

/Application
  /artifacts
    /cypto
      /orderer
        Contains the certificates required for the application to act on the orderer node
        In participant instances only contains TLS certificates
      /peer
        Contains the certificates required for the application to act on the peer node
    /src
      chaincode.go if installing and deploying chaincode to the blockchain
  /java
    pom.xml or other build configuration files
    /resources
      Any resources used by the Java code, including artifacts such as the endorsement policy yaml file and blockchain configuration properties
    /src
      Java source files

Your Node.js application should be structured similar to the following:

/Application
  /artifacts
    /cypto
      /orderer
        Contains the certificates required for the application to act on the orderer node
        In participant instances only contains TLS certificates
      /peer
        Contains the certificates required for the application to act on the peer node
    /src
      chaincode.go if installing and deploying chaincode to the blockchain
  /node
    package.json file
    application.js
    /app
      Any javascript files called by the application
      /tools

Running the application

You’re now ready to run and test the application. In addition to any status messages returned by your application, you can check the ledger in the Oracle Blockchain Platform console to see your changes:

Go to the Channels tab in the console and locate and click the name of the channel running the blockchain.
In the channel’s Ledger pane, view the chaincode’s ledger summary.

Update the Hyperledger Fabric v2.x SDKs to Work with Oracle Blockchain Platform

There's an incompatibility between an OCI infrastructure component and the Java SDK provided with Hyperledger Fabric v2.x. Follow the steps in this topic to correct this problem.

Methods of updating the Hyperledger Fabric SDK

There are two ways of updating the SDK:

Download the modified package from the console. We’ve created an updated grpc-netty-shaded-1.38.0.jar file, which is the module referenced by the Java SDK that requires modifications.
Build the package manually, as described in this topic.

To download the grpc-netty-shaded-1.38.0.jar file, click the console’s Developer Tools tab, and then select the Application Development pane.

Manually building the package

For the fabric-sdk-java project, complete the following steps to rebuild the grpc-netty-shaded package to connect the peers and orderers with the grpcs client (via TLS). The grpc-netty-shaded package is a sub-project of grpc-java.

Install project dependencies:
```
mvn install
```

Download the grpc-java source code:

git clone https://github.com/grpc/grpc-java.git

Find the grpc version that your fabric-sdk-java uses, and check out the code.
In the grpc-java directory, check out the version of grpc that fabric-sdk-java uses:
```
cd grpc-java && git checkout v1.38.0
```

Change the code to avoid an alpn error from the server side. Create a grpc-java-patch patch file with the following contents:

diff --git a/netty/src/main/java/io/grpc/netty/ProtocolNegotiators.java b/netty/src/main/java/io/grpc/netty/ProtocolNegotiators.java
index 19d3e01b7..ebc4786a3 100644
— a/netty/src/main/java/io/grpc/netty/ProtocolNegotiators.java
+++ b/netty/src/main/java/io/grpc/netty/ProtocolNegotiators.java
@@ -611,7 +611,8 @@ final class ProtocolNegotiators {
SslHandshakeCompletionEvent handshakeEvent = (SslHandshakeCompletionEvent) evt;
if (handshakeEvent.isSuccess()) {
SslHandler handler = ctx.pipeline().get(SslHandler.class);

    if (sslContext.applicationProtocolNegotiator().protocols()
    + if (handler.applicationProtocol() == null
    + || sslContext.applicationProtocolNegotiator().protocols()
    .contains(handler.applicationProtocol())) {
    // Successfully negotiated the protocol.
    logSslEngineDetails(Level.FINER, ctx, "TLS negotiation succeeded.", null);

Apply the patch:
```
git apply grpc-java.patch
```
Build the project to generate the target patched package. Use gradle to build the grpc-java-shaded project:
```
cd netty/shaded
gradle build -PskipAndroid=true -PskipCodegen=true
```
After the build completes, the target patched .jar package is available at grpc-java/netty/build/libs/grpc-netty-shaded-1.38.0.jar.
Add the patched package into your Maven local repository.
Replace the original grpc-netty-shaded .jar package with the patched package in either of the following two ways:
- Use Maven to install the package by local file:
```
mvn install:install-file -Dfile=grpc-netty-shaded-build/grpc-netty-shaded-1.38.0.jar -DgroupId=io.grpc -DartifactId=grpc-netty-shaded -Dversion=1.38.0 -Dpackaging=jar
```
  You must keep the target groupid, artifactid, and version the same as the package you want to replace.
- Manually replace your package. Go to the local Maven repository, find the directory where the target package is located, and replace the package with patched package.
Run the project.

Update the Hyperledger Fabric v1.4.7 SDKs to Work with Oracle Blockchain Platform

There's an incompatibility between an OCI infrastructure component and the Node.js and Java SDKs provided with Hyperledger Fabric v1.4.7. Follow the steps in this topic to correct this problem.

Methods of updating the Hyperledger Fabric SDKs

There are two ways of updating the SDK:

Using Oracle scripts to download and install the Node.js SDK or Java SDK which will patch the code as it installs.
Manually as described in this topic.

To use the scripts, on the console’s Developer Tools tab, select the Application Development pane. The links to download both the Node.js SDK and Java SDK have updates built in which will patch the code as it installs.

Fabric Java SDK: We’ve created an updated grpc-netty-1.23.0.jar file, which is the module referenced by the Java SDK which requires modifications.
Fabric Node.js SDK: We have created the npm_bcs_client.sh script to replace the standard Fabric npm install operations that users would perform to download and install the Node.js Fabric client package. The script runs the same npm command, but it also patched the needed component and rebuilds it.

Manually updating the Fabric Node.js SDK

Do the following to rebuild the grpc-node module to connect the peers and orderers with grpcs client (via TLS).

Install fabric-client without executing the grpc module's build script:
```
npm install --ignore-scripts fabric-client
```
On Windows, you need to disable ALPN explicitly
- Update node_modules/grpc/binding.gyp by changing:
```
'_WIN32_WINNT=0x0600'
```
  to
```
'_WIN32_WINNT=0x0600','TSI_OPENSSL_ALPN_SUPPORT=0'
```
- Due to the issue outlined in https://github.com/nodejs/node/issues/4932, to build grpc-node on Windows, you must first remove <node_root_dir>/include/node/openssl/. Run the following to find your <node_root_dir>:
```
node-gyp configure
```

Rebuild grpc

npm rebuild --unsafe-perm --build-from-source

You can now install any other modules you need and run the project.

Manually updating the Fabric Java SDK

For fabric-sdk-java, do the following steps to rebuild the grpc-netty package to connect the peers and orderers with grpcs client (via tls). grpc-netty is a sub-project of grpc-java.

Install project dependencies:
```
mvn install
```

Download grpc-java source code:

git clone https://github.com/grpc/grpc-java.git

Find the grpc version that your fabric-sdk-java uses, and checkout the code.
Different versions of fabric-sdk-java may use different version of grpc. Check pom.xml to find out what grpc version your fabric-sdk-java uses. For example, fabric-sdk-java 1.4.11 uses grpc-java 1.23.0 as found in its pom.xml: https://github.com/hyperledger/fabric-sdk-java/blob/v1.4.11/pom.xml.
In the grpc-java directory, checkout the version of grpc that fabric-sdk-java uses:
```
git checkout -b v1.23.0
```

Change the code to avoid an alpn error from the server side.

Change the target code of grpc-java_root/netty/src/main/java/io/grpc/netty/ProtocolNegotiators.java

In the function userEventTriggered0 change:

if (NEXT_PROTOCOL_VERSIONS.contains(handler.applicationProtocol())) {

if (handler.applicationProtocol() == null || NEXT_PROTOCOL_VERSIONS.contains(handler.applicationProtocol())) {

The code will look similar to:

    @Override
    protected void userEventTriggered0(ChannelHandlerContext ctx, Object evt) throws Exception {
      ...
          if (handler.applicationProtocol() == null || NEXT_PROTOCOL_VERSIONS.contains(handler.applicationProtocol())) {
            // Successfully negotiated the protocol.
            logSslEngineDetails(Level.FINER, ctx, "TLS negotiation succeeded.", null);
      ...
    }

Build the project to generate the target patched package. Use gradle to build the grpc-java project. Or you can just rebuild the grpc-netty sub-project in the grpc netty directory gradle build.

After the build is done, you can get the target patched jar package in the directory grpc-java\netty\build\libs\grpc-netty-1.23.0.jar.
Add the patched package into your Maven local repository.
Replace official grpc-netty jar package with the patched package in either of the following two ways:
- Use Maven to install the package by local file:
```
mvn install:install-file -Dfile=local_patched_grpc_netty_package_root/grpc-netty-1.23.0.jar -DgroupId=io.grpc -DartifactId=grpc-netty -Dversion=1.23.0 -Dpackaging=jar
```
  You must keep the target groupid, artifactid, and version the same as the package you want to replace.
- Manually replace your package. Go to the local Maven repository, find the directory where the target package is located, and replace the package with patched package.
Run the project.