CKB SDK Java

https://github.com/nervosnetwork/ckb-sdk-java
Admin
CKB SDK Java provides a Java SDK for interacting with the Nervos CKB blockchain, enabling developers...
Tokens:2,463
Snippets:16
Trust Score:9.6
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install CKB SDK Java with Gradle

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

Add the CKB SDK Java dependencies to your Gradle `build.gradle` file for project integration. Replace `{version}` with the desired SDK version.

```Groovy
implementation 'org.nervos.ckb:ckb:{version}'
implementation 'org.nervos.ckb:core:{version}'
implementation 'org.nervos.ckb:utils:{version}'
```

--------------------------------

### Install CKB SDK Java with Maven

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

Add the CKB SDK Java dependency to your Maven `pom.xml` file to include the SDK in your project. Replace `{version}` with the desired SDK version.

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

--------------------------------

### Signing CKB Transactions: Before and After SDK Update

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/docs/migration-guide.md

This Java code snippet demonstrates the evolution of transaction signing in the CKB SDK. The 'Before' section shows the older approach using `MercuryScriptGroup` and `Secp256k1SighashBuilder` for manual signing. The 'Now' section illustrates the simplified process with the new `TransactionSigner` and `ScriptGroup`, requiring only the transaction with script groups and the private key for signing.

```Java
// Before:
static Map<String, String> addressWithKey = new HashMap<>();
// omit: put private key to `addressWithKey`
TransactionCompletionResponse txResponse = api.buildSimpleTransferTransaction(payload);
List<MercuryScriptGroup> scriptGroups = txResponse.getScriptGroup();
Secp256k1SighashBuilder signBuilder = new Secp256k1SighashBuilder(txResponse.txView);
for (MercuryScriptGroup sg : scriptGroups) {
    signBuilder.sign(sg, addressWithKey.get(sg.getAddress()));
}
Transaction tx = signBuilder.buildTx();
String hash = api.sendTransaction(tx);

// Now:
TransactionWithScriptGroups txWithScriptGroups = api.buildSimpleTransferTransaction(payload);
TransactionSigner.getInstance(Network.TESTNET)
                 .signTransaction(txWithScriptGroups, "0x6c9ed038....", "0x369dfe...");  // sign with private key
byte[] txHash = api.sendTransaction(txWithScriptGroups.txView);
```

--------------------------------

### Migrating CKB SDK Java Package Imports

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/docs/migration-guide.md

Several important packages and classes have been relocated in the new CKB Java SDK to consolidate types. For instance, classes previously in `org.nervos.ckb.type.transaction` are now directly under `org.nervos.ckb.type`. Developers should update their import statements and class references accordingly.

```Java
// Before:
import org.nervos.ckb.type.transaction;
// Now:
import org.nervos.ckb.type;

// Transaction class is in `org.nervos.ckb.type.transaction` before but now in `org.nervos.ckb.type`.
Transaction tx = api.getTransaction(txHash).transaction;
```

--------------------------------

### Parse CKB Address String in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

This example demonstrates how to parse an encoded CKB address string (preferably bech32m format) to retrieve its underlying script and network information. It also shows how to re-encode the address.

```Java
Address address = Address.decode("ckt1qyqxgp7za7dajm5wzjkye52asc8fxvvqy9eqlhp82g");
Script script = address.getScript();
Network network = address.getNetwork();
System.out.println(address.encode());
```

--------------------------------

### Generate New CKB secp256k1_blake160 Address in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

This example shows how to randomly generate a new CKB address, specifically the commonly used `secp256k1_blake160` type. It involves creating an ECKeyPair and then generating a corresponding Script and Address object.

```Java
// Generate a new address randomly
ECKeyPair keyPair = Keys.createEcKeyPair();
Script script = Script.generateSecp256K1Blake160SignhashAllScript(keyPair));
Address address = new Address(script, Network.TESTNET);
System.out.println(address.encode());
```

--------------------------------

### Encode CKB Address in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/docs/migration-guide.md

The new CKB Java SDK streamlines address encoding by providing an `encode()` method directly on the `Address` object. This replaces the static `AddressGenerator.generate()` method used in previous versions, simplifying the process of converting a `Script` and `Network` into an encoded address string.

```Java
// Before:
String encoded = AddressGenerator.generate(network, script);

// Now:
Address address = new Address(script, network);
String encoded = address.encode();
```

--------------------------------

### Parse CKB Address in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/docs/migration-guide.md

The new CKB Java SDK unifies address parsing and decoding into a single `Address` class, replacing multiple deprecated utility classes like `AddressParser`. This snippet demonstrates how to decode an encoded address string to retrieve the `Script` and `Network`.

```Java
String encoded = "ckt1qzda..."
// Before:
AddressParseResult result = AddressParser.parse(encoded);
Script script = result.script;
Network network = result.network;

// Now:
Address address = Address.decode(encoded);
Script script = address.getScript();
Network network = address.getNetwork();
```

--------------------------------

### Representing CKB Hashes in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/docs/migration-guide.md

The new CKB Java SDK changes the representation of 32-byte hashes from `String` to `byte[]` to align with CKB's internal data types. This change affects all instances where hashes are used, requiring updates to variable types and method signatures.

```Java
// Before:
String hash = tx.computeHash();

// Now:
byte[] hash = tx.computeHash();
```

--------------------------------

### Handling CKB Numeric Types in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/docs/migration-guide.md

The new CKB Java SDK aligns numeric type representations with CKB RPC types: `Uint32` maps to `int`, `Uint64` to `long`, and `Uint128` to `BigInteger`. Since CKB numbers are unsigned and Java's `int` and `long` are signed, specific `Long` utility methods like `compareUnsigned` should be used for unsigned operations, especially for fields like `Capacity`.

```Java
// Before: capacity is a BigInteger
if (capacity.compareTo(BigInteger.valueOf(140L)) >= 0) {
    // do something
}

// Now: capacity is a long
if (Long.compareUnsigned(capacity, 140L) >= 0) {
    // do something  
}
```

--------------------------------

### Initialize CKB RPC API Client in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

Set up a CKB RPC API client instance to easily interact with a CKB node. This client allows calling any RPC APIs provided by CKB.

```Java
// Set up client.
CkbRpcApi ckbAPi = new Api("http://127.0.0.1:8114");
```

--------------------------------

### Sign and Send CKB Transaction with Java SDK

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

This snippet demonstrates the two-step process of signing a raw CKB transaction with a private key and then sending the signed transaction to a CKB node. It requires a prepared raw transaction instance of `TransactionWithScriptGroups` as input.

```Java
// 0. Set your private key
String privateKey = "0x6c9ed03816e31...";
// 1. Sign transaction with your private key
TransactionSigner.getInstance(Network.TESTNET).signTransaction(txWithScriptGroups, privateKey);
// 2. Send transaction to CKB node
byte[] txHash = ckbApi.sendTransaction(txWithScriptGroups.txView);
System.out.println(Numeric.toHexString(txHash));
```

--------------------------------

### Build CKB Transfer Transaction with Mercury API in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

Utilize the Mercury API to build a CKB transfer transaction. Mercury provides a high-level JSON-RPC interface for simplified transaction creation and asset management, requiring a deployed Mercury server.

```Java
String sender = "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq0yvcdtsu5wcr2jldtl72fhkruf0w5vymsp6rk9r";
String receiver = "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqvglkprurm00l7hrs3rfqmmzyy3ll7djdsujdm6z";

long ckbAmount = AmountUtils.ckbToShannon(100);   // Convert CKB to Shannon (1 CKB = 10^8 Shannon)
SimpleTransferPayloadBuilder builder = new SimpleTransferPayloadBuilder();
builder.addFrom(sender);
builder.addTo(receiver, ckbAmount);
builder.assetInfo(AssetInfo.newCkbAsset());

// Get an unsigned raw transaction with the help of Mercury
MercuryApi mercuryApi = new DefaultMercuryApi("http://127.0.0.1:8116", false);
TransactionWithScriptGroups txWithScriptGroups = mercuryApi.buildSimpleTransferTransaction(builder.build());
```

--------------------------------

### Retrieve Block Information by Hash in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

Use the initialized CKB RPC API client to fetch block details by its hash from the CKB node. The `Numeric.hexStringToByteArray` utility converts a hexadecimal string to a byte array.

```Java
byte[] blockHash = Numeric.hexStringToByteArray("0x77fdd22f6ae8a717de9ae2b128834e9b2a1424378b5fc95606ba017aab5fed75");
Block block = ckbApi.getBlock(blockHash);
```

--------------------------------

### Build CKB Transfer Transaction Manually in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

Construct a CKB transfer transaction using the `CkbTransactionBuilder`. This builder encapsulates common logic, freeing developers from script details, transaction fee calculation, and change output management.

```Java
String sender = "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsq2qf8keemy2p5uu0g0gn8cd4ju23s5269qk8rg4r";
String receiver = "ckt1qzda0cr08m85hc8jlnfp3zer7xulejywt49kt2rr0vthywaa50xwsqg958atl2zdh8jn3ch8lc72nt0cf864ecqdxm9zf";
Iterator<TransactionInput> iterator = new InputIterator(sender);
TransactionBuilderConfiguration configuration = new TransactionBuilderConfiguration(Network.TESTNET);
configuration.setFeeRate(1000);
TransactionWithScriptGroups txWithGroups = new CkbTransactionBuilder(configuration, iterator)
    .addOutput(receiver, 50100000000L)
    .setChangeOutput(sender)
    .build();
```

--------------------------------

### Convert Public Key to CKB secp256k1_blake160 Address in Java

Source: https://github.com/nervosnetwork/ckb-sdk-java/blob/master/README.md

This snippet illustrates how to convert an elliptic curve public key into a `secp256k1_blake160` CKB address. The public key should be provided as a 65-length hex string (compressed format) without the '0x' prefix.

```Java
// The public key sent is an elliptic curve public key of compressed format - a 65-length hex (not include hex prefix 0x).
byte[] publicKey = Numeric.hexStringToByteArray("0x24a501efd328e062c8675f2365970728c859c592beeefd6be8ead3d901330bc01");
Script script = Script.generateSecp256K1Blake160SignhashAllScript(publicKey);
Address address = new Address(script, Network.TESTNET);
System.out.println(address.encode());
```
Tokens:
Raw