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
- 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
- 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 yourfabric-sdk-java
uses, and check out the code.In thegrpc-java
directory, check out the version ofgrpc
thatfabric-sdk-java
uses:cd grpc-java && git checkout v1.38.0
-
Change the code to avoid an
alpn
error from the server side. Create agrpc-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 atgrpc-java/netty/build/libs/grpc-netty-shaded-1.38.0.jar
. -
Add the patched package into your Maven local repository.
Replace the originalgrpc-netty-shaded
.jar
package with the patched package in either of the following two ways:-
Use Maven to install the package by local file:
You must keep the targetmvn 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
groupid
,artifactid
, andversion
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 Fabricnpm 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
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:
to'_WIN32_WINNT=0x0600'
'_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
- Update
-
Rebuild
grpc
npm rebuild --unsafe-perm --build-from-source
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 yourfabric-sdk-java
uses, and checkout the code.Different versions of
fabric-sdk-java
may use different version ofgrpc
. Checkpom.xml
to find out whatgrpc
version yourfabric-sdk-java
uses. For example,fabric-sdk-java 1.4.11
usesgrpc-java 1.23.0
as found in itspom.xml
: https://github.com/hyperledger/fabric-sdk-java/blob/v1.4.11/pom.xml.In thegrpc-java
directory, checkout the version ofgrpc
thatfabric-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:
toif (NEXT_PROTOCOL_VERSIONS.contains(handler.applicationProtocol())) {
The code will look similar to:if (handler.applicationProtocol() == null || NEXT_PROTOCOL_VERSIONS.contains(handler.applicationProtocol())) {
@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); ... }
- Change the target code of
-
Build the project to generate the target patched package. Use gradle to build the
grpc-java
project. Or you can just rebuild thegrpc-netty
sub-project in the grpc netty directorygradle 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 officialgrpc-netty
jar package with the patched package in either of the following two ways:-
Use Maven to install the package by local file:
You must keep the targetmvn 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
groupid
,artifactid
, andversion
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.