HowTo Examples

Here you can find helpful tutorials and examples how to use the substrate-client-java library.

Setup

This tutorial provides information about the initial steps you have to take in order to configure you application to use our substrate-client-java library.

1. Add dependencies

In order to use the substrate-client-java library you need to add it to you application.

First, setup the necessary repositories:

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
    maven {
        name = "GitHubPackages"
        url = "https://maven.pkg.github.com/strategyobject/substrate-client-java"
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
            password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
        }
    }
}

Second, add substrate-client-java library's dependencies:

def substrateClientVersion = '0.2.0'

dependencies {
        implementation "com.strategyobject.substrateclient:common:${substrateClientVersion}"
        implementation "com.strategyobject.substrateclient:crypto:${substrateClientVersion}"
        implementation "com.strategyobject.substrateclient:scale:${substrateClientVersion}"
        implementation "com.strategyobject.substrateclient:transport:${substrateClientVersion}"
        implementation "com.strategyobject.substrateclient:rpc:${substrateClientVersion}"
        implementation "com.strategyobject.substrateclient:rpc-api:${substrateClientVersion}"
        implementation "com.strategyobject.substrateclient:pallet:${substrateClientVersion}"
        implementation "com.strategyobject.substrateclient:api:${substrateClientVersion}"

        annotationProcessor "com.strategyobject.substrateclient:scale-codegen:${substrateClientVersion}"
        annotationProcessor "com.strategyobject.substrateclient:rpc-codegen:${substrateClientVersion}"
        annotationProcessor "com.strategyobject.substrateclient:pallet-codegen:${substrateClientVersion}"
}

2. Initialize API

In order to communicate with a blockchain node, we need to instantiate a component responsible for the transport layer.

Here we use the same concept of providers used in polkadot{.js}.

Currently the WebSocket provider is the only type that is implemented by our Java API. You can use it like shown in this example:

Supplier<ProviderInterface> wsProvider = WsProvider.builder().setEndpoint("ws://127.0.0.1:9944");

Use the Api.with method to create the API, as shown below:

Api api = Api.with(wsProvider);

Now we have the API initialized.

Access Storage Items

This tutorial provides an example how to read a storage structures from a pallet.

Our API uses a declarative approach and code generation. In order to access a substrate pallet, you have to describe it with a Java interface.

You can find more information about describing and reading a pallet's storage here.

The code below shows an example in Rust defining a BlockHash storage item in the System pallet.

/// Map of block numbers to block hashes.
#[pallet::storage]
#[pallet::getter(fn block_hash)]
pub type BlockHash<T: Config> =
    StorageMap<_, Twox64Concat, T::BlockNumber, T::Hash, ValueQuery>;

The above definition written in Java looks like this:

@Pallet("System")
public interface SystemPallet {
    @Storage(
            value = "BlockHash",
            keys = {
                    @StorageKey(
                            type = @Scale(BlockNumber.class),
                            hasher = StorageHasher.TWOX_64_CONCAT
                    )
            })
    StorageNMap<BlockHash> blockHash();
}

As you can see it is quite similar to the original definition in Rust. The implementation of the interface will be generated automatically at compilation time.

Next, we need to instantiate the pallet with our Java API so we can start executing queries. The code for creating the pallet is:

System systemPallet = api.pallet(System.class);

After we have initialized the pallet, we can now access its storage items. Example query for accessing the BlockHash storage:

BlockHash blockHash = systemPallet
        .blockHash()
        .get(BlockNumber.GENESIS)
        .join();