Sava | Solana Java SDK

GitHub Repository

Dependencies

java.net.http
systems.comodal.json_iterator
software.sava.core

Features

Every active HTTP RPC method with typed response records.
WebSocket subscriptions which automatically re-subscribe on re-connection, including a generic passthrough for provider-specific methods.
Typed, sealed error hierarchies: known TransactionError and InstructionError variants and supported custom JSON-RPC error codes parse to their own types, with Unknown fallbacks for unrecognized variants or codes.
Asynchronous by default, every request returns a CompletableFuture.

HTTP

See the official Solana docs for context on each HTTP RPC method.

Create Client

try (var httpClient = HttpClient.newHttpClient()) {
    var rpcClient = SolanaRpcClient.build()
        .endpoint(SolanaNetwork.MAIN_NET.getEndpoint())
        .httpClient(httpClient)
        .createClient();
    // The examples below assume an rpcClient within this scope.
}

Fetch & Parse Accounts

var accountInfo = rpcClient.getAccountInfo(
    PublicKey.fromBase58Encoded("6T6vqb3VykNToz4sqY5C29Psb8iNUuVZPAqJXbAgorVF")
).join();

byte[] tableData = accountInfo.data();
var table = AddressLookupTable.read(accountInfo.pubKey(), tableData);
System.out.println(table);

var accountInfo = rpcClient.getAccountInfo(
    PublicKey.fromBase58Encoded("6T6vqb3VykNToz4sqY5C29Psb8iNUuVZPAqJXbAgorVF"),
    AddressLookupTable.FACTORY
).join();

AddressLookupTable table = accountInfo.data();
System.out.println(table);

Query Program Accounts with Filters

Note: You will need access to an RPC node which has getProgramAccounts enabled, such as Helius.

Retrieve all lookup tables which are active and frozen.

byte[] stillActive = new byte[Long.BYTES];
ByteUtil.putInt64LE(stillActive, 0, Clock.MAX_SLOT);
var activeFilter = Filter.createMemCompFilter(DEACTIVATION_SLOT_OFFSET, stillActive);
var noAuthorityFilter = Filter.createMemCompFilter(AUTHORITY_OPTION_OFFSET, new byte[]{0});

var accountInfoFuture = rpcClient.getProgramAccounts(
    SolanaAccounts.MAIN_NET.addressLookupTableProgram(),
    List.of(
        activeFilter,
        noAuthorityFilter
    ),
    AddressLookupTable.FACTORY
);

var accountInfoList = accountInfoFuture.join();
accountInfoList.stream().map(AccountInfo::data).forEach(System.out::println);
System.out.format("Retrieved %d tables which are active and frozen.%n", accountInfoList.size());

Fetch Transactions & Blocks

The built-in client automatically requests maxSupportedTransactionVersion: 1 for getTransaction and for getBlock with BlockTxDetails.full. Both requests use Base64 transaction bytes. Other block-detail modes omit the version ceiling; request full to retrieve serialized transactions. The destination node and cluster still determine which transaction versions are available. Given a transaction signature, inspect its wire version and v1 configuration:

var tx = rpcClient.getTransaction(signature).join();
if (tx != null) {
    var skeleton = tx.skeleton();
    if (skeleton != null) {
        System.out.println("Version: " + skeleton.version());
        if (skeleton.version() == 1) {
            System.out.println("Priority fee (lamports): " + skeleton.priorityFeeLamports());
            System.out.println("Compute-unit limit: " + skeleton.computeUnitLimit());
            System.out.println("Account-data limit (bytes): " + skeleton.accountDataSizeLimit());
            System.out.println("Heap request (bytes): " + skeleton.heapSize());
        }
    }
}

For a block slot, each BlockTx also exposes skeleton():

var block = rpcClient.getBlock(slot, BlockTxDetails.full).join();
if (block != null) {
    for (var entry : block.transactions()) {
        var skeleton = entry.skeleton();
        if (skeleton != null) {
            System.out.println(skeleton.id() + ": version " + skeleton.version());
        }
    }
}

version() is 1 for v1, 0 for v0, and negative for legacy. Both skeleton helpers deserialize on each call and return null when transaction bytes are absent or empty. BlockTx reads the version from those bytes through its skeleton. Execution results, such as the fee and consumed compute units, are available through meta() when present.

Version Errors & Submission Results

These failures describe different stages of a request:

Situation	Typed result
A fetched transaction exceeds the requesting client’s version ceiling	`JsonRpcException` with code `-32015` and `RpcCustomError.UnsupportedTransactionVersion`
Simulation rejects a version unsupported by the destination runtime	`TxSimulation.error()` is `TransactionError.UnsupportedVersion`
Submission preflight rejects the transaction	`JsonRpcException` with code `-32002` and `RpcCustomError.SendTransactionPreflightFailure`; inspect its `simulation().error()`

For a JSON-RPC error, join() throws a CompletionException whose cause is a JsonRpcException. Preserve an Unknown case when handling error variants. A successful sendTransaction response supplies a transaction signature. Check its confirmation status and execution error afterward; skipping preflight can return a signature even when the runtime will reject the transaction. See the transaction lifecycle guide for building, simulation, signing, and submission, including how to adjust v1 limits after simulation.

Request Encodings

Use RpcEncoding.base64, or RpcEncoding.base64_zstd (base64+zstd) for account requests that support compression. Transaction fetch, simulation, and submission use Base64. Account parsing remains client-side through the typed account factories; jsonParsed is intentionally absent.

WebSocket

See the official Solana docs for context on each WebSocket RPC method.

Create Client

try (var httpClient = HttpClient.newHttpClient()) {
    var webSocket = SolanaRpcWebsocket.build()
        .webSocketBuilder(httpClient.newWebSocketBuilder())
        .uri(SolanaNetwork.MAIN_NET.getWebSocketEndpoint())
        .solanaAccounts(SolanaAccounts.MAIN_NET)
        .commitment(Commitment.CONFIRMED)
        .onOpen(ws -> System.out.println("Websocket connected to " + ws.endpoint()))
        .onClose((_, statusCode, reason) -> System.out.format("%d: %s%n", statusCode, reason))
        .onError((_, throwable) -> throwable.printStackTrace())
        .create();

    webSocket.connect();
}

Stream Program Accounts

Token Accounts

var solanaAccounts = SolanaAccounts.MAIN_NET;
var tokenProgram = solanaAccounts.tokenProgram();
var tokenOwner = PublicKey.fromBase58Encoded("");

webSocket.programSubscribe(
    tokenProgram,
    List.of(
        Filter.createDataSizeFilter(TokenAccount.BYTES),
        Filter.createMemCompFilter(TokenAccount.OWNER_OFFSET, tokenOwner)
    ),
    accountInfo -> {
        var tokenAccount = TokenAccount.read(accountInfo.pubKey(), accountInfo.data());
        System.out.println(tokenAccount);
    }
);

Address Lookup Tables

var solanaAccounts = SolanaAccounts.MAIN_NET;
var addressLookupTableProgram = solanaAccounts.addressLookupTableProgram();

webSocket.programSubscribe(addressLookupTableProgram, accountInfo -> {
    var table = AddressLookupTable.read(accountInfo.pubKey(), accountInfo.data());
    System.out.println(table);
});

Provider Specific Subscriptions

Subscription methods which are not part of the standard Solana API, or not supported by public RPC infrastructure, are reachable via the generic subscribe passthrough. You provide the method names, request parameters JSON, and a response parser; subscriptions are replayed if the connection is re-established. See HeliusRpcWebsocket for a complete example wrapping Helius’ transactionSubscribe.

webSocket.subscribe(
    "transactionSubscribe", "transactionUnsubscribe", "transactionNotification",
    subscriptionKey,
    paramsJson,
    TransactionNotification::parse,
    notification -> System.out.println(notification)
);

Get Started

Libraries

Guides

Utilities

Releases

Project

RPC

GitHub Repository

Dependencies

Features

HTTP

Create Client

Fetch & Parse Accounts

Query Program Accounts with Filters

Fetch Transactions & Blocks

Version Errors & Submission Results

Request Encodings

WebSocket

Create Client

Stream Program Accounts

Token Accounts

Address Lookup Tables

Provider Specific Subscriptions

GitHub Repository

​Dependencies

​Features

​HTTP

​Create Client

​Fetch & Parse Accounts

​Query Program Accounts with Filters

​Fetch Transactions & Blocks

​Version Errors & Submission Results

​Request Encodings

​WebSocket

​Create Client

​Stream Program Accounts

​Token Accounts

​Address Lookup Tables

​Provider Specific Subscriptions

Dependencies

Features

HTTP

Create Client

Fetch & Parse Accounts

Query Program Accounts with Filters

Fetch Transactions & Blocks

Version Errors & Submission Results

Request Encodings

WebSocket

Create Client

Stream Program Accounts

Token Accounts

Address Lookup Tables

Provider Specific Subscriptions