mcxross/ksui

Kotlin Multiplatform Client Library for Sui.

Ksui - KMP Library for Sui

Ksui, /keɪˈsuːiː/ (pronounced as "kay-soo-ee"), is a collection of Kotlin Multiplatform JSON-RPC wrapper and crypto utilities for interacting with a Sui Full node.

This library is intended to be the highest quality publicly available library for interacting with Sui on any Kotlin-supported platform by epitomizing expressiveness, conciseness and aesthetics

Table of contents

• Features
• Quick start
• What's included
• Projects using Ksui
• Contribution

Features

• Implements all functions
• HTTP and WebSocket Clients
• Crypto wrappers
• Client Configurable
• Multiplatform

Quick Start

Installation

Multiplatform

Add the Ksui dependency to the common sourceSet

implementation("xyz.mcxross.ksui:ksui:<$ksui_version>")

Platform specific (Android, JS, Native, JVM)

Add the Ksui dependency to the Project's dependency block

Generic:

implementation("xyz.mcxross.ksui:<ksui-[platform]>:<$ksui_version>")

For example for Android and JS

Android:

implementation("xyz.mcxross.ksui:ksui-android:<$ksui_version>")

JS:

implementation("xyz.mcxross.ksui:ksui-js:<$ksui_version>")

RPC HTTP Client

Create a new instance of the Sui RPC HTTP Client. The client can be configured with the following options:

• endpoint: The Sui endpoint to connect to. Defaults to EndPoint.DEVNET
• agentName: The name of the agent making the request. Defaults to KSUI/0.0.1
• maxRetries: The maximum number of times to retry a request. Defaults to 5
• and many more. Check documentation for more details.

After the client is configured, it can be used to invoke remote procedures e.g. getBalance, getCheckpoints and getCoins. Check the Sui JSON-RPC documentation for a list of available RPCs.

The client supports both DSL and command-query styles for client creation and RPC calls respectively as shown below:

//Configure Client, DSL Style
val suiHttpClient = suiHttpClient {
    endpoint = EndPoint.DEVNET
    agentName = "KSUI/1.3.2"
    maxRetries = 10
}
//Invoke remote procedure, command-query style
val balance = suiHttpClient.getBalance(SuiAddress("0x4afc81d797fd02bd7e923389677352eb592d55a00b65067fa582c05f62b4788b"))
val coinMetadata = suiHttpClient.getCoinMetadata("0x2::sui::SUI")

RPC WebSocket Client

Create a new instance of the Sui RPC WebSocket Client. The client can be configured similarly to the http client. After the client is configured, subscribe to events with subscribeEvent

//Configure Client, DSL Style
val suiWSClient = suiWebSocketClient { endpoint = EndPoint.MAINNET }

suiWSClient.subscribeEvent(
        eventFilterFor<EventFilterMutable.Combined> { operator = Operator.ALL },
        onSubscribe = {},
        onError = {}) {
    // This block of code is a trailing lambda that will be executed whenever an event occurs.
    // It has access to the `eventEnvelope` object, which represents the details of the event.
}

For more information, please see the documentation.

What's included

File/Folder	Description
lib	Library implementation folder. It contains the code for Ksui that can be used across multiple platforms
sample	Samples on how to use the exported APIs

Projects using Ksui

• Sui Cohesive

Contribution

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

ksui's Issues

Missing values in TransactionBlockResponse

I'm getting this error when calling attempting to run a paySui transaction through the executeTransactionBlock function:

Exception in thread "main" kotlinx.serialization.MissingFieldException: Fields [timestampMs, checkpoint] are required for type with serial name 'xyz.mcxross.ksui.model.TransactionBlockResponse', but they were missing at path: $

Upon further inspection, I saw that my output payload didn't include those fields at all (as expected from the error). I looked at the Sui source code, and it appears that those fields are optional: https://github.com/MystenLabs/sui/blob/acbf77f807ecc04cb0c44c521abf5c2bbc1a2a9d/crates/sui-json-rpc-types/src/sui_transaction.rs#L209

I believe the fix is to modify the TransactionBlockResponse class to make timestampMs and checkpoint nullable Long? fields. I'm still very new to Sui, so I may be doing something wrong that is perhaps causing these fields to be missing when they shouldn't be. Any insights into this issue would be incredibly valuable to me! Thank you.