Sui4J is a Java SDK designed specifically for the Sui blockchain, providing complete RPC client, BCS serialization, cryptocurrency functionality, and Pyth oracle integration.

• 🚀 Environment Requirements
• ⚙️ Installation and Configuration
• 🎯 Basic Usage
• 💎 Core Features
  • 🔗 RPC Client
  • 🔐 Cryptocurrency Module
  • 📦 BCS Serialization Module
  • 🌐 gRPC Client
• 🧪 Test Cases
• 📚 API Reference
• 🤝 Contributing Guide
• 📄 License
• 🔗 Official Documentation Links
• 💬 Support

• JDK: 21+
• Maven: 3.6+
• Network: HTTPS connection support

<dependency>
    <groupId>io.dipcoin</groupId>
    <artifactId>sui4j</artifactId>
    <version>0.1.7</version>
</dependency>

implementation 'io.dipcoin:sui4j:0.1.7'

The following is a complete usage example showing how to start from creating an HTTP service instance, generate Ed25519 key pairs, and finally call Pyth updatePrice PTB operations:

package io.dipcoin.sui;

import io.dipcoin.sui.bcs.types.gas.GasData;
import io.dipcoin.sui.bcs.types.gas.SuiObjectRef;
import io.dipcoin.sui.bcs.types.transaction.Argument;
import io.dipcoin.sui.bcs.types.transaction.Command;
import io.dipcoin.sui.bcs.types.transaction.ProgrammableMoveCall;
import io.dipcoin.sui.bcs.types.transaction.ProgrammableTransaction;
import io.dipcoin.sui.client.TransactionBuilder;
import io.dipcoin.sui.crypto.Ed25519KeyPair;
import io.dipcoin.sui.crypto.SuiKeyPair;
import io.dipcoin.sui.protocol.SuiClient;
import io.dipcoin.sui.protocol.http.HttpService;
import io.dipcoin.sui.pyth.core.PythClient;
import io.dipcoin.sui.pyth.model.PythNetwork;

import java.io.IOException;
import java.math.BigInteger;
import java.util.ArrayList;
import java.util.Arrays;

/**
 * @author : Same
 * @datetime : 2025/9/18 16:37
 * @Description : Sui4jBasicExample
 */
public class Sui4jBasicExample {

  public static void main(String[] args) throws IOException {
    // 1. Create HTTP service instance
    HttpService httpService = new HttpService("https://fullnode.testnet.sui.io:443");

    // 2. Build Sui client
    SuiClient suiClient = SuiClient.build(httpService);

    // 3. Create Pyth client
    PythClient pythClient = new PythClient(suiClient);

    // 4. Generate Ed25519 key pair
    SuiKeyPair keyPair = Ed25519KeyPair.generate();
    System.out.println("Generated address: " + keyPair.address());
    System.out.println("Private key: " + keyPair.encodePrivateKey());

    // 5. Prepare Pyth price update parameters
    String feedId = "0xf9c0172ba10dfa4d19088d94f5bf61d3b54d5bd7483a322a982e1373ee8ea31b";

    // 6. Build PTB update price transaction
    ProgrammableTransaction programmableTx = pythClient.updatePrice(feedId, PythNetwork.TESTNET);

    // 7. Add custom Move call (optional)
    ProgrammableMoveCall moveCall = new ProgrammableMoveCall(
            "0xb5f4bf7d29a8e82eb5de521cf556f1953c9fdd3d73e7f371a156c6e1ee64f24b",
            "main",
            "use_pyth_price",
            new ArrayList<>(),
            Arrays.asList(Argument.ofInput(2), Argument.ofInput(6))
    );

    Command useUpdateMoveCall = new Command.MoveCall(moveCall);
    programmableTx.addCommand(useUpdateMoveCall);

    // 8. Prepare Gas data (actual Gas object needed here)
    SuiObjectRef gasObject = new SuiObjectRef(
            "0x0b50fe6d7b86730f0f8d2e389d22d63c30a73a1034720a8a43bb5e322a9588e1",
            500452832L,
            "FZSJfo8uZMLjeppm4XSd1peiEnox8FYxMxPbZVmuUjqw"
    );

    GasData gasData = new GasData(
            Arrays.asList(gasObject),
            keyPair.address(),
            1000L,
            BigInteger.valueOf(10000000L)
    );

    // 9. Serialize transaction (using local BCS encoding)
    String transactionDataBase64 = TransactionBuilder.serializeTransactionBytes(
            programmableTx,
            keyPair.address(),
            gasData
    );

    System.out.println("Serialized transaction data: " + transactionDataBase64);

    // 10. Execute transaction (optional, requires actual Gas object)
    // suiClient.executeTransactionBlock(transactionDataBase64, keyPair);

    System.out.println("Pyth price update PTB transaction construction completed!");
  }
}

1. Local BCS Encoding: All transactions use local BCS serialization without relying on external services
2. Type Safety: Uses strongly-typed Java objects to avoid string concatenation errors
3. Modular Design: Each functional module is independent and can be used as needed
4. High Performance: Optimized serialization performance supporting large-scale transaction processing

• Function: Pyth oracle PTB update price operation (local bcs encoding)
• Test Case: PythClientTest.testPtbUpdatePrice()

• Function: Perp Move call on-chain transaction (local bcs encoding)
• Test Case: PythClientTest.testMoveCallTrade()

• Function: Perp Move call deposit operation (local bcs encoding)
• Test Case: PythClientTest.testMoveCallDeposit()

• Function: Get dynamic field object information
• Test Case:
  • SuiClientTest.testGetDynamicFieldObject()
  • PythClientTest.testGetDynamicFieldObject()

• Function: Get list of objects owned by address
• Test Case: SuiClientTest.testGetOwnedObjects()

• Function: Get single owned object information
• Test Case: SuiClientTest.testGetOwnedObject()

• Function: Get reference gas price
• Test Case: SuiClientTest.testGetReferenceGasPrice()

• Function: Get detailed information of specified object
• Test Case: SuiClientTest.testGetObject()

• Function: Batch get multiple object information
• Test Case: SuiClientTest.testMultiGetObjects()

• Function: Get object base update fee
• Test Case: SuiClientTest.testGetObjectBaseUpdateFee()

• Function: Get Pyth package ID information
• Test Case: SuiClientTest.testGetPythPackageId()

• Function: Verify ZkLogin signature
• Test Case: SuiClientTest.testVerifyZkLoginSignature()

• Function: Get Move function parameter types
• Test Case: SuiClientTest.testGetMoveFunctionArgTypes()

• Function: Get normalized Move function information
• Test Case: SuiClientTest.testGetNormalizedMoveFunction()

• Function: Get Sui Move normalized module information
• Test Case:
  • SuiClientTest.testGetSuiMoveNormalizedModule()
  • SuiClientTest.testGetSuiMoveNormalizedModuleByPackage()

• Function: Get normalized Move struct information
• Test Case: SuiClientTest.testGetNormalizedMoveStruct()

• Function: Get chain identifier
• Test Case: SuiClientTest.testGetChainIdentifier()

• Function: Execute batch transaction requests
• Test Case: SuiClientTest.testBatchTransaction()

• Function: Get the sequence number of the latest checkpoint
• Test Case: SuiClientTest.testGetLatestCheckpointSequenceNumber()

• Function: Get the total number of known transaction blocks
• Test Case: SuiClientTest.testGetTotalTransactionBlocks()

• Function: Generate new Ed25519 key pair
• Test Case: Ed25519KeyPairTest.createSuiKeyPair()

• Function: Generate new Ed25519 key mnemonics
• Test Case: Ed25519KeyPairTest.createSuiKeyDerive()

• Function: Decode key pair from hexadecimal private key
• Test Case: Ed25519KeyPairTest.decodeBase64_shouldWorkWithValidKey()

• Function: Decode key pair from suiPrivateKey
• Test Case: Ed25519KeyPairTest.importSuiKeyDerive()

• Function: Generate correctly formatted address
• Test Case: Ed25519KeyPairTest.address_shouldGenerateCorrectFormat()

• Function: Encode private key to hexadecimal format
• Test Case: Ed25519KeyPairTest.encodePrivateKey_shouldReturnOriginalHex()

• Function: Get 32-byte public key
• Test Case: Ed25519KeyPairTest.publicKeyBytes_shouldReturn32Bytes()

• Function: Boundary condition key testing
• Test Case: Ed25519KeyPairTest.boundaryKeyTests()

• Function: Verify Ed25519 signatures (personal message / transaction data)
• Test Case: Ed25519KeyPairTest.verifySignature()

• Function: Generate new Secp256k1 key pair
• Test Case: Scep256k1KeyPairTest.createSuiKeyPair()

• Function: Generate new Secp256k1 key mnemonics
• Test Case: Scep256k1KeyPairTest.createSuiKeyDerive()

• Function: Decode key pair from hexadecimal private key
• Test Case: Scep256k1KeyPairTest.decodeBase64_shouldWorkWithValidKey()

• Function: Generate correctly formatted address
• Test Case: Scep256k1KeyPairTest.address_shouldGenerateCorrectFormat()

• Function: Encode private key to hexadecimal format
• Test Case: Scep256k1KeyPairTest.encodePrivateKey_shouldReturnOriginalHex()

• Function: Verify Secp256k1 signatures (personal message / transaction data)
• Test Case: Scep256k1KeyPairTest.verifySignature()

• Function: Serialize 8-bit unsigned integer
• Test Case: BcsSerializerTest.testWriteU8()

• Function: Serialize 16-bit unsigned integer
• Test Case: BcsSerializerTest.testWriteU16()

• Function: Serialize 32-bit unsigned integer
• Test Case: BcsSerializerTest.testWriteU32()

• Function: Serialize 64-bit unsigned integer
• Test Case: BcsSerializerTest.testWriteU64()

• Function: Serialize 128-bit unsigned integer
• Test Case: BcsSerializerTest.testWriteU128()

• Function: Serialize 256-bit unsigned integer
• Test Case: BcsSerializerTest.testWriteU256()

• Function: Serialize boolean values
• Test Case: BcsSerializerTest.testWriteBool()

• Function: Serialize strings
• Test Case: BcsSerializerTest.testWriteString()

• Function: Serialize byte arrays
• Test Case: BcsSerializerTest.testWriteBytes()

• Function: Serialize vector types
• Test Case: BcsSerializerTest.testWriteVector()

• Function: Serialize optional values
• Test Case: BcsSerializerTest.testWriteOption()

• Function: Complex type combination serialization
• Test Case: BcsSerializerTest.testComplexSerialization()

• Function: Reset serializer state
• Test Case: BcsSerializerTest.testReset()

• Function: Basic BCS type serialization
• Test Case: BcsIndexTest.testBasicTypesSerialization()

• Function: Address and Sui object serialization
• Test Case: BcsIndexTest.testAddressAndObjectSerialization()

• Function: Type tag serialization
• Test Case: BcsIndexTest.testTypeTagSerialization()

• Function: Transaction data serialization
• Test Case: BcsIndexTest.testTransactionSerialization()

• Function: Move call deposit transaction serialization
• Test Case: BcsIndexTest.testMoveCallDepositSerialization()

• Function: Move call transaction serialization
• Test Case: BcsIndexTest.testMoveCallTradeSerialization()

• Function: PTB update price transaction serialization
• Test Case: BcsIndexTest.testPtbUpdatePriceSerialization()

• Function: Complex transaction combination serialization
• Test Case: BcsIndexTest.testComplexTransactionSerialization()

• Function: Intent message serialization
• Test Case: BcsIndexTest.testIntentSerialization()

• Function: Intent string serialization
• Test Case: BcsIndexTest.testIntentStringSerialization()

• Function: Signature data serialization
• Test Case: BcsIndexTest.testSignatureSerialization()

• Function: Owner information serialization
• Test Case: BcsIndexTest.testOwnerSerialization()

• Function: Authentication information serialization
• Test Case: BcsIndexTest.testAuthSerialization()

• Function: Transaction data message serialization
• Test Case: IntentBcsTest.testTransactionDataMessage()

• Function: Personal message serialization
• Test Case: IntentBcsTest.testPersonalMessage()

• Function: Gas cost summary serialization
• Test Case: EffectsBcsTest.testGasCostSummarySerialization()

• Function: Transaction effects V1 serialization
• Test Case: EffectsBcsTest.testTransactionEffectsV1Serialization()

• Function: Transaction effects serialization
• Test Case: EffectsBcsTest.testTransactionEffectsSerialization()

• Function: Serialize results to Base64
• Test Case: EffectsBcsTest.testSerializeToBase64()

• Function: Deserialize from Base64
• Test Case: EffectsBcsTest.testDeserializeFromBase64()

• Function: Failed execution status serialization
• Test Case: EffectsBcsTest.testFailedExecutionStatus()

• Function: Empty object lists serialization
• Test Case: EffectsBcsTest.testEmptyObjectLists()

• Function: Large object lists serialization
• Test Case: EffectsBcsTest.testLargeObjectLists()

• Function: Unsupported version handling
• Test Case: EffectsBcsTest.testUnsupportedVersion()

• Function: Serialization-deserialization round-trip testing
• Test Case: EffectsBcsTest.testRoundTripSerialization()

• Function: Sui object reference serialization
• Test Case: SuiBcsTest.testSuiObjectRefSerialization()

• Function: Shared object reference serialization
• Test Case: SuiBcsTest.testSharedObjectRefSerialization()

• Function: Object parameter serialization
• Test Case:
  • SuiBcsTest.testObjectArgImmOrOwnedObjectSerialization()
  • SuiBcsTest.testObjectArgSharedObjectSerialization()
  • SuiBcsTest.testObjectArgReceivingSerialization()

• Function: Call parameter serialization
• Test Case:
  • SuiBcsTest.testCallArgPureSerialization()
  • SuiBcsTest.testCallArgObjectArgSerialization()

• Function: Type tag serialization
• Test Case: SuiBcsTest.testTypeTagSerialization()

• Function: Serialize results to Base64
• Test Case: SuiBcsTest.testSerializeToBase64()

• Function: Complex type tag serialization
• Test Case: SuiBcsTest.testComplexTypeTagSerialization()

• Function: Large parameter list serialization
• Test Case: SuiBcsTest.testLargeArgumentsList()

• Function: Empty parameter list serialization
• Test Case: SuiBcsTest.testEmptyArgumentsList()

• Function: Invalid Base64 deserialization handling
• Test Case: SuiBcsTest.testInvalidBase64Deserialization()

• Function: Serialization-deserialization round-trip testing
• Test Case: SuiBcsTest.testRoundTripSerialization()

• Function: Special character string serialization
• Test Case: SuiBcsTest.testSpecialCharactersInStrings()

• Function: TransactionKind serialization and deserialization
• Test Case: SuiBcsTest.testTransactionKind()

• Function: Deserialize Base64 transaction data into a transaction object and round-trip serialize it
• Test Case: SuiBcsTest.testTransactionData()

• Function: Primitive type serialization.
• Test Case: PureBcsTest.testBasicTypeSerialization()

• Function: Vector type serialization
• Test Case: PureBcsTest.testVectorTypeSerialization()

• Function: Serialize results to Base64
• Test Case: PureBcsTest.testSerializeToBase64()

• Function: Deserialize from Base64
• Test Case: PureBcsTest.testDeserializeFromBase64()

• Function: Empty vector serialization
• Test Case: PureBcsTest.testEmptyVectorSerialization()

• Function: Large vector serialization
• Test Case: PureBcsTest.testLargeVectorSerialization()

• Function: Serialization-deserialization round-trip testing
• Test Case: PureBcsTest.testRoundTripSerialization()

• Function: Special character string serialization
• Test Case: PureBcsTest.testSpecialCharactersInStrings()

• Function: Zero value serialization
• Test Case: PureBcsTest.testZeroValues()

• Function: Maximum value serialization
• Test Case: PureBcsTest.testMaxValues()

• Function: Multiple serialization testing
• Test Case: PureBcsTest.testMultipleSerializations()

• Function: BCS serialization performance testing
• Test Case: BcsIndexTest.testPerformance()

A high-performance client built on the Sui gRPC (v2) API, offering capabilities on par with JSON-RPC while supporting both synchronous and asynchronous calls as well as server-side streaming subscriptions.

• Function: Get gRPC service info (sync / async)
• Test Case:
  • GrpcSuiClientTest.testGetServiceInfo()
  • GrpcSuiClientTest.testGetServiceInfoAsync()

• Function: Get single / batch object info (sync / async)
• Test Case:
  • GrpcSuiClientTest.testGetObject()
  • GrpcSuiClientTest.testGetObjectAsync()
  • GrpcSuiClientTest.testBatchGetObjects()
  • GrpcSuiClientTest.testBatchGetObjectsAsync()

• Function: Get single / batch transaction info (sync / async)
• Test Case:
  • GrpcSuiClientTest.testGetTransaction()
  • GrpcSuiClientTest.testGetTransactionAsync()
  • GrpcSuiClientTest.testBatchGetTransactions()
  • GrpcSuiClientTest.testBatchGetTransactionsAsync()

• Function: Get the latest checkpoint / get a checkpoint by sequence number (sync / async)
• Test Case:
  • GrpcSuiClientTest.testGetLatestCheckpoint()
  • GrpcSuiClientTest.testGetCheckpointBySequenceNumber()
  • GrpcSuiClientTest.testGetCheckpointAsync()

• Function: Get current epoch info (sync / async)
• Test Case:
  • GrpcSuiClientTest.testGetCurrentEpoch()
  • GrpcSuiClientTest.testGetEpochAsync()

• Function: List dynamic fields (sync / async)
• Test Case:
  • GrpcSuiClientTest.testListDynamicFields()
  • GrpcSuiClientTest.testListDynamicFieldsAsync()

• Function: List objects owned by an address (sync / async)
• Test Case:
  • GrpcSuiClientTest.testListOwnedObjects()
  • GrpcSuiClientTest.testListOwnedObjectsAsync()

• Function: Query coin metadata, single-coin balance, and balance lists (sync / async)
• Test Case:
  • GrpcSuiClientTest.testGetCoinInfo()
  • GrpcSuiClientTest.testGetCoinInfoAsync()
  • GrpcSuiClientTest.testGetBalance()
  • GrpcSuiClientTest.testGetBalanceAsync()
  • GrpcSuiClientTest.testListBalances()
  • GrpcSuiClientTest.testListBalancesAsync()

• Function: Query Move packages, datatypes, functions, and package versions (sync / async)
• Test Case:
  • GrpcSuiClientTest.testGetPackage()
  • GrpcSuiClientTest.testGetPackageAsync()
  • GrpcSuiClientTest.testGetDatatype()
  • GrpcSuiClientTest.testGetDatatypeAsync()
  • GrpcSuiClientTest.testGetFunction()
  • GrpcSuiClientTest.testGetFunctionAsync()
  • GrpcSuiClientTest.testListPackageVersions()
  • GrpcSuiClientTest.testListPackageVersionsAsync()

• Function: Forward / reverse name resolution (sync / async)
• Test Case:
  • GrpcSuiClientTest.testLookupName()
  • GrpcSuiClientTest.testLookupNameAsync()
  • GrpcSuiClientTest.testReverseLookupName()
  • GrpcSuiClientTest.testReverseLookupNameAsync()

• Function: Verify signature validity, covering invalid-signature and address-mismatch cases (sync / async)
• Test Case:
  • GrpcSuiClientTest.testVerifySignatureValid()
  • GrpcSuiClientTest.testVerifySignatureValidAsync()
  • GrpcSuiClientTest.testVerifySignatureWithInvalidSignature()
  • GrpcSuiClientTest.testVerifySignatureWithAddressMismatch()

• Function: Subscribe to the checkpoint stream, with support for querying transactions after subscribing
• Test Case:
  • GrpcSuiClientTest.testSubscribeCheckpoints()
  • GrpcSuiClientTest.testSubscribeCheckpointsAndQueryTxs()

• Function: Subscribe to the event stream
• Test Case: GrpcSuiClientTest.testSubscribeEvent()

• Function: Execute a transaction / simulate a transaction
• Test Case:
  • GrpcSuiClientTest.testExecuteTransaction()
  • GrpcSuiClientTest.testSimulateTransaction()

• Function: Verify that the synchronous and asynchronous APIs return consistent results
• Test Case: GrpcSuiClientTest.testSyncAndAsyncReturnConsistentResults()

• Function: Custom gRPC options and metadata request headers
• Test Case:
  • GrpcSuiClientTest.testCustomGrpcOptions()
  • GrpcSuiClientTest.testMetadataHeadersInOptions()

mvn test

# RPC client tests
mvn test -Dtest=SuiClientTest
mvn test -Dtest=PythClientTest

# gRPC client tests
mvn test -Dtest=GrpcSuiClientTest

# Cryptocurrency tests
mvn test -Dtest=Ed25519KeyPairTest
mvn test -Dtest=Scep256k1KeyPairTest

# BCS serialization tests
mvn test -Dtest=BcsIndexTest
mvn test -Dtest=SuiBcsTest
mvn test -Dtest=EffectsBcsTest
mvn test -Dtest=IntentBcsTest
mvn test -Dtest=PureBcsTest
mvn test -Dtest=BcsSerializerTest

• SuiClient - Sui RPC client
• GrpcSuiClient - Sui gRPC client
• PythClient - Pyth oracle client
• BcsSerializer - BCS serializer
• BcsDeserializer - BCS deserializer
• Ed25519KeyPair - Ed25519 key pair
• Secp256k1KeyPair - Secp256k1 key pair
• CommandBuilder - Command builder
• TransactionBuilder - Transaction builder
• QueryBuilder - Query builder

• Testnet: https://fullnode.testnet.sui.io:443
• Mainnet: https://fullnode.mainnet.sui.io:443

We welcome community contributions! Please follow these steps:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

# Clone the project
git clone https://github.com/dipcoinlab/sui4j.git
cd sui4j

# Install dependencies
mvn install

# Run tests
mvn test

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

This project includes code derived from Web3j, licensed under the Apache License 2.0.

• Sui Official Documentation
• Pyth Network Documentation
• BCS Serialization Specification

If you encounter problems or have questions, please:

1. Check Issues
2. Create a new Issue
3. Contact the maintenance team

Note: This is a project under development, and APIs may change. Please test thoroughly before using in production environments.