CKB SDK Java

Java SDK for Nervos CKB.

The ckb-sdk-java is still under development and NOT production ready. You should get familiar with CKB transaction structure and RPC before using it.

Note: All RPC methods in the indexer module have been deprecated since CKB version v0.36.0 and they will be removed in the near future. As a temporary solution, you can set enable_deprecated_rpc = true in ckb.toml. We strongly recommend migrating to ckb-indexer as soon as possible. You can refer to the examples of ckb-indexer in this project.

Prerequisites

• Java 8
• Gradle 5.0 or later

Installation

Install from repositories:

version <= 0.24.0

• Maven

<dependency>
  <groupId>org.nervos.ckb</groupId>
  <artifactId>core</artifactId>
  <version>{version}</version>
</dependency>

• Gradle

implementation 'org.nervos.ckb:core:{version}'

version >= 0.24.1

• Maven

<dependency>
  <groupId>org.nervos.ckb</groupId>
  <artifactId>ckb</artifactId>
  <version>{version}</version>
</dependency>

• Gradle

implementation 'org.nervos.ckb:ckb:{version}'

Install manually

You can generate the jar and import manually.

git clone https://github.com/nervosnetwork/ckb-sdk-java.git

cd ckb-sdk-java

gradle shadowJar  // ./gradlew shadowJar 

version <= 0.24.0

A console-{version}-all.jar package will be generated in console/build/libs, which you can put into your project to develop with it.

version >= 0.24.1

A ckb-sdk-{version}-all.jar package will be generated in ckb-sdk/build/libs, which you can put into your project to develop with it.

If you don't want to generate the jar by yourself, you can download a build from releases.

Import Jar to Project

When you need to import ckb-java-sdk dependency to your project, you can add the console-{version}-all.jar or ckb-sdk-{version}-all.jar to your project libs package.

If you use Java IDE (eg. IntelliJ IDEA or Eclipse or other Editors), you can import jar according to IDE option help documents.

Usage

JSON-RPC

You can make JSON-RPC request to your CKB node URL with this SDK. Below are some examples:

Api api = new Api("your-ckb-node-url");

// using RPC `get_tip_block_number`, it will return the latest block number
BigInteger blockNumber = api.getTipBlockNumber();

// using RPC `get_block_hash` with block number as parameter, it will return block hash
String blockNumber = "0"
String blockHash = api.getBlockHash(blockNumber);

// using RPC `get_block` with block hash as parameter, it will return block object
Block block = api.getBlock(blockHash);

You can see more JSON-RPC requests from RPC Document

Single-sig Transfer

Note: If you want to run transfer example, you should update example private key of sender whose balance is not zero. And if you want to use example default private key to run, you should make the example sender's balance is not zero or set the blake160 of default sender's public key to CKB dev chain node configuration file to be a miner.

SingleSigWithCkbIndexerTxExample provides sendCapacity method with any amount inputs which belong to a private key.

MultiKeySingleSigTxExample provides sendCapacity method with any amount inputs which belong to any amount private keys.

You can reference detail example in example/MultiKeySingleSigTxExample.java.

  Api api = new Api("your-ckb-node-url");

  List<CellInput> inputs = Arrays.asList(
    new CellInput(inputs1), // Input from address 'cktxxx', capacity 100 CKB
    new CellInput(inputs2), // Input from address 'cktxxx', capacity 200 CKB
    new CellInput(inputs3), // Input from address 'cktxxx', capacity 300 CKB
  );
  
  List<CellOutput> outputs = Arrays.asList(
    output1, // Output to address 'cktxxx', capacity 200
    output2, // Output to address 'cktxxx', capacity 300
    output3, // Output to address 'cktxxx' as change, capacity 100
  );
  
  TransactionBuilder txBuilder = new TransactionBuilder(api);
  
  SignatureBuilder signBuilder = new SignatureBuilder(txBuilder.buildTx());
  
  // A script group is defined as scripts that share the same hash.
  for (ScriptGroup scriptGroup : scriptGroups) {
    signBuilder.sign(scriptGroup);
  }
  
  String hash = api.sendTransaction(signBuilder.buildTx());

Multi-sig Transfer

Note: If you want to run transfer example, you should update example private key of sender whose balance is not zero. And if you want to use example default private key to run, you should make the example sender's balance is not zero or set the blake160 of default sender's public key to CKB dev chain node configuration file to be a miner.

SendToMultiSigAddressTxExample provides sendCapacity method which single-sig address sends capacity to 2/3 format multi-sig address.

MultiSignTransactionExample provides sendCapacity method which 2/3 format multi-sig address sends capacity to single-sig address.

Address

You can generate ckb address through this SDK as below:

// Generate mainnet address with SECP256K1 and public blake160 hash
String publicKey =
    Sign.publicKeyFromPrivate(
            Numeric.toBigInt(
                "e79f3207ea4980b7fed79956d5934249ceac4751a4fae01a0f7c4a96884bc4e3"),
            true)
        .toString(16);
Script script =
        new Script(
            "0x9bd7e06f3ecf4be0f2fcd2188b23f1b9fcc88e5d4b65a8637b17723bbda3cce8",
            Hash.blake160(publicKey),
            Script.TYPE);
String address = AddressGenerator.generate(Network.MAINNET, script);

Development

We use Google Java Code Format and follow Google Checkstyle for development.

If verifyGoogleJavaFormat FAILED happens when you build this project, please format your code with Google Java Code Format or execute ./gradlew goJF on macOS and Linux, or gradlew goJF on Windows.

If you use IntelliJ IDEA to develop, you can install google-java-format plugin to format code automatically.

License

The SDK is available as open source under the terms of the MIT License.

Changelog

See CHANGELOG for more information.