Skip to content

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Unicity State Transition SDK — Java

Build applications that mint, transfer, and verify digital assets on the Unicity Network. This Java SDK gives you control over tokens, ownership rules, and payments, with cryptographic verification built in.

Unicity combines private, off-chain token transactions with network-backed protection against double-spending. Token data stays with the parties you share it with, while unicity proofs let recipients verify that assets are spent only once. The network is designed to scale horizontally as demand grows.

  • Create digital assets: mint tokens with your own types and application data payload.
  • Move value: transfer tokens and split fungible tokens for payments.
  • Verify locally: validate token history and unicity proofs against the compact trust base.
  • Integrate with your application: choose ownership predicates, issuance policies, storage, and delivery channels.
  • Build for JVM and Android: use typed SDK objects and asynchronous network operations returning CompletableFuture.

Installation

Requires Java 11 or later. Android applications require Android 12+ (API level 31+) and core library desugaring.

To use this checkout, publish the SDK to your local Maven repository with the included Gradle wrapper:

git clone https://github.com/unicitynetwork/state-transition-sdk-java.git
cd state-transition-sdk-java
./gradlew publishToMavenLocal

Add the dependency to your application's build.gradle:

repositories {
    mavenLocal()
    mavenCentral()
}

dependencies {
    implementation 'org.unicitylabs:java-state-transition-sdk:4.0.0'
    implementation 'com.google.guava:guava:33.0.0-jre'
}

Guava must be supplied by the application. For Android, use 33.0.0-android instead of 33.0.0-jre and enable desugaring:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
        coreLibraryDesugaringEnabled true
    }
}

dependencies {
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.4'
}

Unicity Network

Mainnet is live. Start with testnet2; for production, use the mainnet gateway and matching trust base.

Network Gateway Network ID
Mainnet https://gateway.mainnet.unicity.network 1
Testnet2 https://gateway.testnet2.unicity.network 4

Pass your gateway API key as the second argument to JsonRpcAggregatorClient. The public testnet2 key is sk_ddc3cfcc001e4a28ac3fad7407f99590. Use your own mainnet key obtained from Sphere and keep it secure.

First connection

Add this class to your application and run it to check connectivity. Token verification also needs a trust-base history pinned to a known genesis; open it through a session using the mainnet, testnet2 or local setup.

import org.unicitylabs.sdk.StateTransitionClient;
import org.unicitylabs.sdk.api.JsonRpcAggregatorClient;

public class Connect {
    public static void main(String[] args) throws Exception {
        var aggregator = new JsonRpcAggregatorClient(
                "https://gateway.testnet2.unicity.network",
                "sk_ddc3cfcc001e4a28ac3fad7407f99590"); // Public testnet2 key
        var client = new StateTransitionClient(aggregator);
        System.out.println("Latest round: " + aggregator.getLatestBlockNumber().get());
    }
}

The example waits for the result with .get(). In asynchronous applications, compose the returned futures; on Android, keep blocking calls off the UI thread.

Work with tokens

The SDK handles cryptography and token encoding. Your application manages keys, stores tokens, and delivers them to recipients over your chosen transport.

Task SDK entry points Example
Mint a token MintTransaction.builder(), Token.mint() Mint helper
Transfer ownership TransferTransaction.create(), token.transfer() Transfer flow
Split a fungible token TokenSplit.split() Split flow
Verify a received token token.verify(context) Receive and verify

For minting and transfers, create the transaction, submit its CertificationData with client.submitCertificationRequest(), and check the response status. Use InclusionProofUtils.waitInclusionProof() to obtain the verified unicity proof, then transaction.toCertifiedTransaction() and Token.mint() or token.transfer() to produce the updated token. The proof type is named InclusionProof in the API.

waitInclusionProof() sends its first request immediately and, by default, asks the aggregator to hold each request while the state is pending (long polling). The proof then arrives soon after certification, usually within a single request. Aggregators without long polling are polled at the interval. The default budget is 15 seconds; adjust it, the interval, and the long-poll window with WaitOptions. Cancelling the returned future cancels the request in flight. See the API reference.

These examples are test code with local network configuration. When adapting them to a public network, use the matching gateway, key, and trust base, and pass trustBase.getNetworkId().get() when minting.

Store, send, and receive

Use token.toCbor() to save or send a token, and Token.fromCbor(bytes) to load it. Verify received tokens with your application's VerificationContext before accepting them:

import org.unicitylabs.sdk.transaction.Token;
import org.unicitylabs.sdk.util.verification.VerificationStatus;

// Inside your receive handler; see the examples for context setup.
var token = Token.fromCbor(bytes);
var result = token.verify(context);
if (result.getStatus() != VerificationStatus.OK) {
    throw new IllegalArgumentException("Token verification failed: " + result.getStatus());
}

Proof consolidation

Each transaction in a token's history has its own unicity proof, usually certified in a different round. Verifying the history in a constrained environment, such as a smart contract (EVM) or a zkVM guest, means authenticating every one of those certificates. Proof consolidation fetches new proofs for the token's history so that they share one unicity certificate, which then has to be authenticated only once. It is optional, runs only when you call it, and never signs or submits anything. See the API reference.

Non-inclusion proofs

A non-inclusion proof shows that a state ID was absent from the aggregator's state tree at one certified snapshot. It does not show that the state is absent now or that a token can be spent. StateTransitionClient.getNonInclusionProof() fetches the proof and NonInclusionVerifier.verify() verifies it and returns the authenticated snapshot. Before relying on the result, compare the snapshot's network and round with a checkpoint your application trusts independently. See the API reference.

Security

Unicity proofs provide independently verifiable evidence of certified state transitions being unique. This protects against double-spending without publishing token data to a public ledger.

Use the SDK's verification APIs with the authentic network trust base and your application's token issuance policies. A token's cryptographic validity and whether your application accepts its issuer are separate checks; register accepted token types with TokenIssuanceVerifierService. Keep private keys and token backups secure, and check that received tokens belong to the intended recipient.

Development

Use JDK 21 for the Gradle build, matching CI; the SDK still targets Java 11. Select it with JAVA_HOME if another JDK is your system default.

From a repository checkout:

./gradlew build
./gradlew test
./gradlew checkstyleMain

Run the integration tests, including Docker-based tests:

./gradlew integrationTest

The deployed-network test is enabled by AGGREGATOR_URL. Its setup opens the trust base history the aggregator under test serves (the local-network setup, for a deployment you run yourself; for a public network use a pinned session instead) and creates a client without an API key; configure both for your target network before running it.

Resources

License

MIT

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages