Ksui - Multiplatform SDK for Sui

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.

Table of contents

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

Features

• 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

Modules

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

Module	Artifact	What it contains	Use it when
Core	xyz.mcxross.ksui:ksui-core	Models, errors, config, accounts, cryptography, BCS helpers, PTB construction, transaction data building, and signing primitives.	You need to build/sign transactions or share Sui types without taking a network client dependency.
GraphQL SDK	xyz.mcxross.ksui:ksui	GraphQL Client	You want to use the Sui GraphQL client.
gRPC SDK	xyz.mcxross.ksui:ksui-grpc	gRPC Client	You want to use the Sui gRPC client.

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.

Installation

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.

Kotlin Multiplatform

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")
        }
    }
}

Platform-specific Gradle projects

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.

Quick start

Account management

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)

GraphQL client

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.

Core-only transaction building

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")
    }
}

gRPC client

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..."))

What's included

Path	Description
core	Transport-independent core module: models, errors, config, accounts, crypto, BCS, helpers, PTB construction, and transaction signing primitives.
graphql	GraphQL SDK module published as ksui; contains the Sui entry point and GraphQL-backed APIs.
grpc	gRPC SDK module published as ksui-grpc; contains SuiGrpcClient, protobuf definitions, and gRPC APIs.
sample	Sample projects showing SDK usage.
skills	Development notes for working on Ksui with agent tooling.

For more information, see the documentation.

Contribution

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.

License

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.