If you're building apps with Immutable, please use Immutable's Unified SDK
The Immutable X Core SDK Kotlin/JVM provides convenient access to the Immutable API's for applications written on the Immutable X platform.
See the developer guides for information on building on Immutable X.
See the API reference documentation for more information on our API's.
- Sample code - see the sample folder for examples of key SDK functionality.
- Add Maven Central to your repositories
repositories {
mavenCentral()
}- Add dependency to your app
build.gradlefile
dependencies {
implementation 'com.immutable.sdk:imx-core-sdk-kotlin-jvm:$version'
}- Set the correct environment (defaults to Production)
val immutableX = ImmutableX(ImmutableXBase.Sandbox)| 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 |
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"
)OR
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.
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
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.
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 }
}
}Use StarkKey.generateStarkPrivateKey() to create an instance of StandardStarkSigner, an implementation of StarkSigner.
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)Parts of the Core SDK are automagically generated.
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.
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() })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)
}
}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.0If 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.
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:
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.
You can also join the conversation, connect with other projects, and ask questions in our Immutable X Discourse forum.
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.
ImmutableX Core SDK Kotlin/JVM repository is distributed under the terms of the Apache License (Version 2.0).