🚨 This library is no longer maintained 🚨

If you're building apps with Immutable, please use Immutable's Unified SDK

Immutable X Core SDK Kotlin/JVM

The Immutable X Core SDK Kotlin/JVM provides convenient access to the Immutable API's for applications written on the Immutable X platform.

Documentation

See the developer guides for information on building on Immutable X.

See the API reference documentation for more information on our API's.

Examples

Sample code - see the sample folder for examples of key SDK functionality.

Installation

Add Maven Central to your repositories

repositories {
    mavenCentral()
}

Add dependency to your app build.gradle file

dependencies {
    implementation 'com.immutable.sdk:imx-core-sdk-kotlin-jvm:$version'
}

Set the correct environment (defaults to Production)

val immutableX = ImmutableX(ImmutableXBase.Sandbox)

Environments

Environment	Description
`ImmutableXBase.Sandbox`	The default test network (currently, it is Goërli)
`ImmutableXBase.Ropsten`	Ropsten test network (to be deprecated soon)
`ImmutableXBase.Production`	Ethereum network

Quickstart

Standard API Requests

The Core SDK includes functions that interact with the Immutable X APIs.

e.g. Get a list of collections ordered by name in ascending order

val response = immutableX.listCollections(
    pageSize = 20,
    orderBy = "name",
    direction = "asc"
)

val response = immutableX.collectionsApi.listCollections(
    pageSize = 20,
    orderBy = "name",
    direction = "asc"
)

View the OpenAPI spec for a full list of API requests available in the Core SDK.

Workflow Functions

Utility functions that will chain necessary API calls to complete a process or perform a transaction.

Register a user with Immutable X
Buy cryptocurrency via Moonpay
Buy ERC721
Sell ERC721
Cancel order
Transfer ERC20/ERC721/ETH
Deposit ERC20/ERC721/ETH
Withdraw ERC20/ERC721/ETH
Check if user is registered on chain

Wallet Connection

In order to call authorised API and use workflow functions, you will need to pass in the connected wallet provider. This means you will need to implement your own Wallet L1 Signer and L2 StarkSigner.

L1 Signer

Example implementation of the L1 Signer using web3j:

class L1Signer(private val credentials: Credentials) : Signer {

    val web3j = Web3j.build(HttpService(NODE_URL))

    override fun getAddress(): CompletableFuture<String> {
        return CompletableFuture.completedFuture(credentials.address)
    }

    override fun signMessage(message: String): CompletableFuture<String> {
        val signatureData = Sign.signPrefixedMessage(message.toByteArray(), credentials.ecKeyPair)
        val retval = ByteArray(65)
        System.arraycopy(signatureData.r, 0, retval, 0, 32)
        System.arraycopy(signatureData.s, 0, retval, 32, 32)
        System.arraycopy(signatureData.v, 0, retval, 64, 1)
        val signed = Numeric.toHexString(retval)
        return CompletableFuture.completedFuture(signed)
    }

    @Suppress("TooGenericExceptionCaught")
    override fun sendTransaction(rawTransaction: RawTransaction): CompletableFuture<String> {
        val signedTransaction = TransactionEncoder.signMessage(rawTransaction, credentials)
        return web3j.ethSendRawTransaction(Numeric.toHexString(signedTransaction)).sendAsync()
            .thenApply { it.transactionHash }
    }
}

L2 StarkSigner

Use StarkKey.generateStarkPrivateKey() to create an instance of StandardStarkSigner, an implementation of StarkSigner.

🚨🚨🚨 Warning 🚨🚨🚨

You will have to persist the Stark private key. The key is randomly generated so cannot be deterministically re-generated.

val starkPrivateKey = StarkKey.generateStarkPrivateKey()
val starkSigner = StandardStarkSigner(starkPrivateKey)

Autogenerated Code

Parts of the Core SDK are automagically generated.

API Autogenerated Code

We use OpenAPI (formally known as Swagger) to auto-generate the API clients that connect to the public APIs.

The OpenAPI spec is retrieved from https://api.x.immutable.com/openapi and also saved in the repo here.

When updating the org.openapi.generator plugin ensure that any custom templates are appropriately modified or removed. These can be found in the .openapi-generator/templates directory.

The generation always happens on preBuild so triggering a project build will regenerate them.

Wrapping CompletableFuture

RxJava

Rx provides a fromFuture method that will trigger future.get() which is a blocking call so it must be moved off the main thread.

Disposing the resulting observable will not cancel the future so that needs to be done manually using doOnDispose.

val future = immutableX.cancelOrder(orderId)
Observable.fromFuture(future)
    .subscribeOn(Schedulers.io())
    .doOnDispose { future.cancel(true) }
    .subscribe({ handleSuccess() }, { handleError() })

Coroutines

The Kotlin team has a set of packages for jdk8 that provide an easy extension for using CompletableFuture.

First add this import to your project:

implementation "org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:$coroutines_version"

Then simply call .await() on the workflow CompletableFuture and wrap it with a try/catch to handle any exceptions.

launch(Dispatchers.Default) {
    try {
        val id = immutableX.cancelOrder(orderId).await()
    } catch (e: Exception) {
        handleError(e)
    }
}

Changelog Management

The following headings should be used as appropriate

Added
Changed
Deprecated
Removed
Fixed

What follows is an example with all the change headings, for real world use only use headings when appropriate. This goes at the top of the CHANGELOG.md above the most recent release.

...

## [Unreleased]

### Added

for new features.

### Changed

for changes in existing functionality.

### Deprecated

for soon-to-be removed features.

### Removed

for now removed features.

### Fixed

for any bug fixes.

...

The version.yml will hold the value of the previous release

version: 0.1.0

Contributing

If you would like to contribute, please read the following:

We use the Conventional Commits specification when writing our commit messages. Why use Conventional Commits? Read here.

Maintainers

How to release

Getting Help

Immutable X is open to all to build on, with no approvals required. If you want to talk to us to learn more, or apply for developer grants, click below:

Project Support

To get help from other developers, discuss ideas, and stay up-to-date on what's happening, become a part of our community on Discord.

Join us on Discord

You can also join the conversation, connect with other projects, and ask questions in our Immutable X Discourse forum.

Visit the forum

Still need help?

You can also apply for marketing support for your project. Or, if you need help with an issue related to what you're building with Immutable X, click below to submit an issue. Select I have a question or issue related to building on Immutable X as your issue type.

Contact support

License

ImmutableX Core SDK Kotlin/JVM repository is distributed under the terms of the Apache License (Version 2.0).

immutable / imx-core-sdk-kotlin-jvm

readme