Ksui, /keɪˈsuːiː/ (pronounced "kay-soo-ee"), is a Kotlin Multiplatform SDK for integrating with the Sui blockchain.

It is designed to be type-safe, client-configurable, coroutine based, and usable across Android, iOS, JS, JVM, and native Kotlin targets.

• Features
• Modules
• Installation
• Quick start
• What's included
• Contribution
• License

• Multiplatform Kotlin API
• gRPC and GraphQL clients
• Type-safe Sui models
• Account and key management
• BCS serialization helpers
• Programmable Transaction Block (PTB) builder
• Coroutine based async APIs

Ksui is split into transport-independent core code and transport-specific client modules.

This split keeps the dependency graph explicit so you can add only what you need:

• ksui-core is the stable foundation. It has no GraphQL or gRPC transport dependency, so it can be used from tests, shared libraries, Android apps, and other SDK layers without dragging in client stacks.
• ksui is the GraphQL distribution. It keeps Sui as the main entry point and wires core transaction building to GraphQL object resolution.
• ksui-grpc is the gRPC client module.

The current snapshot version is:

val ksuiVersion = "2.2.8-SNAPSHOT"

For snapshots, add Sonatype's snapshot repository:

repositories {
    mavenCentral()
    maven("https://central.sonatype.com/repository/maven-snapshots")
}

For released versions, mavenCentral() is enough.

Add the module you need to the appropriate source set. In most applications, ksui is the right starting point.

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("xyz.mcxross.ksui:ksui:2.2.8-SNAPSHOT")
        }
    }
}

Use ksui-core when you only need models, accounts, crypto, serialization, PTB building, and transaction signing primitives:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("xyz.mcxross.ksui:ksui-core:2.2.8-SNAPSHOT")
        }
    }
}

Use ksui-grpc when you want the gRPC client:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("xyz.mcxross.ksui:ksui-grpc:2.2.8-SNAPSHOT")
        }
    }
}

You can depend on more than one module when needed:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("xyz.mcxross.ksui:ksui:2.2.8-SNAPSHOT")
            implementation("xyz.mcxross.ksui:ksui-grpc:2.2.8-SNAPSHOT")
        }
    }
}

For a non-KMP Android app:

dependencies {
    implementation("xyz.mcxross.ksui:ksui-android:2.2.8-SNAPSHOT")
}

For a JVM-only project:

dependencies {
    implementation("xyz.mcxross.ksui:ksui-jvm:2.2.8-SNAPSHOT")
}

Platform artifacts are also published for the split modules. For example:

dependencies {
    implementation("xyz.mcxross.ksui:ksui-core-android:2.2.8-SNAPSHOT")
    implementation("xyz.mcxross.ksui:ksui-grpc-android:2.2.8-SNAPSHOT")
}

dependencies {
    implementation("xyz.mcxross.ksui:ksui-core-jvm:2.2.8-SNAPSHOT")
    implementation("xyz.mcxross.ksui:ksui-grpc-jvm:2.2.8-SNAPSHOT")
}

The GraphQL module supports Android, iOS, JS, JVM, macOS, tvOS, and watchOS targets. The gRPC module is available on the targets supported by kotlinx-rpc gRPC in this repo: Android, JVM, iOS, macOS, tvOS, and watchOS. JS is not currently a gRPC target.

Generate a new Sui account:

val account = Account.create()

Import an account from a private key:

val privateKey = PrivateKey.fromEncoded("suipri...8cpv0g")
val account = Account.import(privateKey)

Or import directly from an encoded private key:

val account = Account.import("suipri...8cpv0g")

Ksui follows the standard Sui private key Bech32 format proposed in SIP-15.

You can also import an account from a mnemonic:

val mnemonic = "abandon salad ..."
val account = Account.import(mnemonic)

The GraphQL SDK keeps Sui as the high-level entry point.

val sui = Sui()

Configure the network:

val config = SuiConfig(settings = SuiSettings(network = Network.MAINNET))
val sui = Sui(config)

Read from the chain:

val balance =
    sui.getBalance(
        AccountAddress("0x4afc81d797fd02bd7e923389677352eb592d55a00b65067fa582c05f62b4788b")
    )

Build, sign, and execute a PTB:

val alice = Account.import("suipri...8cpv0g")

val ptb = ptb {
    val coins = splitCoins {
        coin = Argument.GasCoin
        into = listOf(pure(100_000_000UL))
    }

    transferObjects {
        objects = coins
        to = address("0xbf...cde")
    }
}

val transaction = sui.signAndExecuteTransactionBlock(alice, ptb)

When using the GraphQL ptb helper, object-string inputs are resolved through the configured Sui client before the transaction is built.

ksui-core can construct and sign transactions without depending on GraphQL or gRPC. If a PTB uses unresolved object IDs, resolve them with a transport-specific resolver before calling the strict build() path.

val tx = xyz.mcxross.ksui.core.ptb.ptb {
    transferObjects {
        objects = listOf(`object`(objectReference))
        to = address("0xbf...cde")
    }
}

Use SuiGrpcClient from ksui-grpc when you want to use Sui's gRPC API while sharing the same core models, config, account, crypto, and transaction-building types.

val config =
    SuiConfig(
        settings = SuiSettings(network = Network.TESTNET)
    )

val client = SuiGrpcClient.fromConfig(config)
val balance = client.getBalance(AccountAddress("0x..."))

For more information, see the documentation.

All contributions to Ksui are welcome. Before opening a PR, please submit an issue detailing the bug or feature. When opening a PR, ensure that your contribution builds on the KMP toolchain, has been formatted with ktfmt, and contains tests when applicable. For more information, see the contribution guidelines.

Copyright 2024 McXross

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.