All Products
Search
Document Center

Blockchain as a Service:Java SDK quick start

Last Updated:Sep 07, 2023

This topic describes how to run an application, shows an example execution process, and provides guidance on how to specify a cryptographic kit.

Run an application

Running an application involves the following four steps:

  1. Prepare the environment

  2. Write an application

  3. Compile the application

  4. Execute the application

Prepare the environment

  • Prepare the SSL connection file and account private key file.

    To establish an SSL connection with the BaaS platform, prepare three certificate files: CA root certificate (trustCa), client certificate file (client.crt), and client private key file (client.key). In addition, the account private key file (user.key) is required for submitting transactions. The following table describes these four files.

    File name

    Description

    Source

    client.crt

    The client certificate file.

    Use the BaaS platform’s key generator to generate a certificate request file client.csr, submit client.csr to the BaaS platform to apply for a certificate, and download the .crt file upon application approval.

    client.key

    The client private key file.

    Generate this file with the BaaS platform’s key generator.

    trustCa

    The trustStore for storing CA certificates.

    Download this file from the BaaS platform. The password for the trustCa file is mychain.

    user.key

    The account private key file.

    Use the BaaS platform’s key generator to manually or automatically generate this file.

  • Prepare the TEE hardware privacy contract chain file.

    To use the TEE hardware privacy contract chain, prepare the tee_rsa_public_key.pem file, which can be applied for from the existing TEE hardware privacy contract chain. This file is not required if you use a standard contract chain.

    File name

    Description

    Source

    tee_rsa_public_key.pem

    The TEE hardware privacy contract chain file, which is a node’s open RSA public key file.

    Download this file from the BaaS platform.

  • Check the contract chain node information.

    To obtain the IP address and port number of the chain node for interaction with the contract chain, check the node details of the target contract chain in the block browser on the BaaS platform.

Write an application

  1. Use IntelliJ IDEA to create a demo Maven project. The following figure shows the project’s directory structure.

    1545295559042-521770ec-412b-49ed-935e-a6b644bb0949.png

  2. In the java directory, create a custom package named, for example, com.example.demo, copy all content in DemoSample.java (click to download DemoSample.java) to the created package, and place the client.crt, client.key, trustCa, and user.key files required for the SDK in the resources directory, as shown in the following figure.

    1
    Note

    The bytecode into which the contract’s source code is compiled must be used in the demo project. For more information about the contract’s source code, see Solidity contract development. For more information about the Solidity compiler, see Solidity contract compiler.

  3. Add dependencies to pom.xml. Introduce the SDK and slf4j-log4j12 for demonstration into the pom.xml file, and add the configuration file of log4j to the resources directory.

    Important

    Use the latest version of SDK dependencies.

     pom

    For more information about the complete pom dependencies carrying slf4j-log4j12, see the following example.

    <dependencies>
         <dependency>
             <groupId>com.alipay.mychainx</groupId>
             <artifactId>mychainx-sdk</artifactId>
             <!-- Use the latest SDK version. -->
             <version>0.10.2.12</version>
         </dependency>
    
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-log4j12</artifactId>
             <version>1.8.0-alpha0</version>
         </dependency>
     </dependencies>
    
     <build>
         <extensions>
             <extension>
                 <groupId>kr.motd.maven</groupId>
                 <artifactId>os-maven-plugin</artifactId>
                 <version>1.6.1</version>
             </extension>
         </extensions>
     </build>

    In some cases, the following error may occur:

    2

    This error may result from a Netty loading failure. Try to modify the pom dependencies as follows:

    <dependencies>
             <dependency>
                 <groupId>com.alipay.mychainx</groupId>
                 <artifactId>mychainx-sdk</artifactId>
                 <!-- Use the latest SDK version. -->
                 <version>0.10.2.12</version>
                 <exclusions>
                     <exclusion>
                         <groupId>io.netty</groupId>
                         <artifactId>netty-tcnative-openssl-static</artifactId>
                     </exclusion>
                 </exclusions>
             </dependency>
    
             <dependency>
                 <groupId>org.slf4j</groupId>
                 <artifactId>slf4j-log4j12</artifactId>
                 <version>1.8.0-alpha0</version>
             </dependency>
     </dependencies>
    
         <build>
             <extensions>
                 <extension>
                     <groupId>kr.motd.maven</groupId>
                     <artifactId>os-maven-plugin</artifactId>
                     <version>1.6.1</version>
                 </extension>
             </extensions>
         </build>

    The content of the log4j.properties file is as follows:

     log4j.rootLogger=INFO, R
    
     # Log outputs are in the console.
     log4j.appender.stdout=org.apache.log4j.ConsoleAppender
     log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
     log4j.appender.stdout.layout.ConversionPattern=[QC] %p [%t] %C.%M(%L) | %m%n
    
     # Log outputs are in a file.
     log4j.appender.R=org.apache.log4j.DailyRollingFileAppender
     log4j.appender.R.File=./sdk.log
     log4j.appender.R.layout=org.apache.log4j.PatternLayout
     log4j.appender.R.layout.ConversionPattern=%d-[TS] %p %t %c - %m%n
    
     # mychain-sdk log switch configuration
     log4j.logger.MychainClient=OFF

    If you are using the logging framework of logback, the configuration method of the log switch is as follows:

    <logger name="MychainClient" level="OFF"/>

Compile the application

Run mvn clean compile in the project’s root directory to compile the project.

Execute the application

In DemoSample.java, run the project. The generated log file sdk.log is in the project’s root directory. If the log file contains “Hand shake success”, a connection has been established successfully with the blockchain platform.

The expected output is as follows:

create testAccount1 success.
create testAccount2 success.
deploy contract success.
issue success.
transfer success.
check account balance success.

Example execution process

  1. Initialize the environment.

     // step 1: init logger.
     initLogger();
    
     // step 2: init mychain env.
     env = initMychainEnv();
    
     // step 3: start sdk.
     MychainClient  sdk = new MychainClient();
     sdk.init(env);
  2. Create an account transaction.

     // step 4: init account that will be created.
     initAccount();
    
     // step 5: init private key list which will be used during transaction.
     initPrivateKeyList();
    
     // step 6: execute create two accounts.
     createAccount();
  3. Deploy a smart contract.

    // step 7: deploy a contract using testAccount1.
     deployContract();
  4. Issue credits.

    // step 8: issue 100 credits to testAccount2.
     issue();
  5. Transfer credits between accounts.

    // step 9: transfer 50 credits from testAccount2 to testAccount1
     transfer();
  6. Query for the account balance.

    // step 10: query testAccount2 whose balance should be 50.
     BigInteger balance = query(test2PrivateKeyArrayList,testAccount2);
    
     // step 11: compare to expect balance.
     expect(balance,BigInteger.valueOf(50));
  7. Close the SDK connection.

    // step 12: sdk shut down
     sdk.shutDown();

Specify a cryptographic kit

The following two cryptographic kits can be used in the contract chain environment:

  • classic: uses international commercial cryptographic algorithms, including the SHA-256 digest, ECC public key algorithm, and AES symmetric encryption. This kit is configured for the standard contract chain by default.

  • china-sm: uses China’s national commercial cryptographic algorithms, including the SM3 digest, SM2 public key algorithm, and SM4 symmetric encryption. This kit is configured for the contract chain depending on China’s national encryption algorithms by default.

For more information about the cryptographic kit used for the target contract chain connected to the SDK, you may consult the chain administrator. When building ClientEnv, explicitly specify the SignerBase. The following is an example.

Pkcs8KeyOperator pkcs8KeyOperator = new Pkcs8KeyOperator();
Keypair keyPair = pkcs8KeyOperator.load(privateKeyPath, keyPassword);
SignerBase signerBase = MyCrypto.getInstance().createSigner(keyPair);

Note:The cryptographic kit does not affect the communications between the SDK and the contract platform, which are subject to the PKI authority that issues the certificate.