☕ starknet jvm ☕

StarkNet SDK for JVM languages:

• Java
• Kotlin
• Scala
• Clojure
• Groovy

Table of contents

• Installation
• Documentation
• Example usages
  • Making synchronous requests
  • Making asynchronous requests
• Development
  • Hooks
  • Ensuring idiomatic Java code
• Building documentation

Installation

Select the latest version from the list and follow installation instructions.

Documentation

Documentation is provided in two formats:

• Java and other jvm languages
• Kotlin

Example usages

Making synchronous requests

import com.swmansion.starknet.account.Account;
import com.swmansion.starknet.account.StandardAccount;
import com.swmansion.starknet.data.types.BlockTag;
import com.swmansion.starknet.data.types.Felt;
import com.swmansion.starknet.provider.Provider;
import com.swmansion.starknet.provider.Request;
import com.swmansion.starknet.provider.gateway.GatewayProvider;

public class Main {
    public static void main(String[] args) {
        // Create a provider for interacting with StarkNet
        Provider provider = GatewayProvider.makeTestnetClient();

        // Create an account interface
        Felt accountAddress = Felt.fromHex("0x13241455");
        Felt privateKey = Felt.fromHex("0x425125");
        Account account = new StandardAccount(provider, accountAddress, privateKey);

        // Make a request
        Felt contractAddress = Felt.fromHex("0x42362362436");
        Felt storageKey = Felt.fromHex("0x13241253414");
        Request<Felt> request = account.getStorageAt(contractAddress, storageKey, BlockTag.LATEST);
        Felt response = request.send();

        System.out.println(response);
    }
}

Making asynchronous requests

import com.swmansion.starknet.account.Account;
import com.swmansion.starknet.account.StandardAccount;
import com.swmansion.starknet.data.types.BlockTag;
import com.swmansion.starknet.data.types.Felt;
import com.swmansion.starknet.provider.Provider;
import com.swmansion.starknet.provider.Request;
import com.swmansion.starknet.provider.gateway.GatewayProvider;

import java.util.concurrent.CompletableFuture;

public class Main {
    public static void main(String[] args) {
        // Create a provider for interacting with StarkNet
        Provider provider = GatewayProvider.makeTestnetClient();

        // Create an account interface
        Felt accountAddress = Felt.fromHex("0x13241455");
        Felt privateKey = Felt.fromHex("0x425125");
        Account account = new StandardAccount(provider, accountAddress, privateKey);

        // Make a request
        Felt contractAddress = Felt.fromHex("0x42362362436");
        Felt storageKey = Felt.fromHex("0x13241253414");
        Request<Felt> request = account.getStorageAt(contractAddress, storageKey, BlockTag.LATEST);
        CompletableFuture<Felt> response = request.sendAsync();

        response.thenAccept(System.out::println);
    }
}

Reusing http clients

Make sure you don't create a new provider every time you want to use one. Instead, you should reuse existing instance. This way you reuse connections and thread pools.

✅ Do:

var provider = GatewayProvider.makeTestnetClient();
var account1 = new StandardAccount(provider, accountAddress1, privateKey1);
var account2 = new StandardAccount(provider, accountAddress2, privateKey2);

❌ Don't:

var provider1 = GatewayProvider.makeTestnetClient();
var account1 = new StandardAccount(provider1, accountAddress1, privateKey1);
var provider2 = GatewayProvider.makeTestnetClient();
var account2 = new StandardAccount(provider2, accountAddress2, privateKey2);

Development

Hooks

Run

./gradlew addKtlintFormatGitPreCommitHook
./gradlew addKtlintCheckGitPreCommitHook

Running tests

Running tests requires to have both cairo-lang and starknet-devnet installed. These are distributed as python packages. Run

pip install -r requirements.txt

to install required dependencies.

Ensuring idiomatic Java code

We want this library to be used by both kotlin & java users. In order to ensure a nice API for java always follow those rules:

1. When using file level functions use @file:JvmName(NAME) to ensure a nice name without Kt suffix.
2. When using a companion object mark every property/function with @JvmStatic. This way they are accessible as static from the class. Without it Class.INSTANCE would have to be used.
3. When defining an immutable constant use @field:JvmField. This makes them static properties without getters/setters in java.
4. If you are not sure how something would work in java just create a new java class, import your code and check yourself.
5. Avoid using default arguments. It is better to overload a function and specify defaults there.

Building documentation

Documentation is written in Kdoc format and markdown and is generated using Dokka. Execute following commands from /lib to build docs.

• ./gradlew dokkaHtml to build kotlin format docs
• ./gradlew dokkaHtmlJava to build java format docs

Generated documentation can be found in their respective folders inside /build/dokka.