org.stellar.sdk

Class SorobanServer

java.lang.Object

org.stellar.sdk.SorobanServer

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class SorobanServer
extends java.lang.Object
implements java.io.Closeable

Main class used to connect to the Soroban-RPC instance and exposes an interface for requests to that instance.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SorobanServer.Durability Represents the "durability keyspace" that this ledger key belongs to, check getContractData(java.lang.String, org.stellar.sdk.xdr.SCVal, org.stellar.sdk.SorobanServer.Durability) for more details.
static interface	SorobanServer.SleepStrategy Strategy for sleeping between retries in a retry loop.

Constructor Summary

Constructors

Constructor and Description
SorobanServer(java.lang.String serverURI) Creates a new SorobanServer instance.
SorobanServer(java.lang.String serverURI, okhttp3.OkHttpClient httpClient) Creates a new SorobanServer instance.

Method Summary

Modifier and Type	Method and Description
static Transaction	assembleTransaction(Transaction transaction, SimulateTransactionResponse simulateTransactionResponse)
void	close()
TransactionBuilderAccount	getAccount(java.lang.String address) Fetch a minimal set of current info about a Stellar account.
java.util.Optional<GetLedgerEntriesResponse.LedgerEntryResult>	getContractData(java.lang.String contractId, SCVal key, SorobanServer.Durability durability) Reads the current value of contract data ledger entries directly.
GetEventsResponse	getEvents(GetEventsRequest getEventsRequest) Fetches all events that match the given GetEventsRequest.
GetFeeStatsResponse	getFeeStats() Get statistics for charged inclusion fees.
GetHealthResponse	getHealth() General node health check.
GetLatestLedgerResponse	getLatestLedger() Fetches the latest ledger meta info from network which Soroban-RPC is connected to.
GetLedgerEntriesResponse	getLedgerEntries(java.util.Collection<LedgerKey> keys) Reads the current value of ledger entries directly.
GetLedgersResponse	getLedgers(GetLedgersRequest getLedgersRequest) Gets a detailed list of ledgers starting from the user specified starting point that you can paginate as long as the pages fall within the history retention of their corresponding RPC provider.
GetNetworkResponse	getNetwork() Fetches metadata about the network which Soroban-RPC is connected to.
GetSACBalanceResponse	getSACBalance(java.lang.String contractId, Asset asset, Network network) Fetches the balance of a specific asset for a contract.
GetTransactionResponse	getTransaction(java.lang.String hash) Fetch the details of a submitted transaction.
GetTransactionsResponse	getTransactions(GetTransactionsRequest getTransactionsRequest) Gets a detailed list of transactions starting from the user specified starting point that you can paginate as long as the pages fall within the history retention of their corresponding RPC provider.
GetVersionInfoResponse	getVersionInfo() Fetches version information about the RPC and Captive core.
GetTransactionResponse	pollTransaction(java.lang.String hash) An alias for pollTransaction(String, int, SleepStrategy) with default parameters, which maxAttempts is set to 30, and the sleep strategy is set to a default strategy that sleeps for 1 second between attempts.
GetTransactionResponse	pollTransaction(java.lang.String hash, int maxAttempts, SorobanServer.SleepStrategy sleepStrategy) Polls the transaction status until it is completed or the maximum number of attempts is reached.
Transaction	prepareTransaction(Transaction transaction) Submit a trial contract invocation, first run a simulation of the contract invocation as defined on the incoming transaction, and apply the results to a new copy of the transaction which is then returned.
Transaction	prepareTransaction(Transaction transaction, SimulateTransactionResponse simulateTransactionResponse) Prepare the transaction using the simulateTransaction obtained by the user in advance, apply the simulateTransaction results to a new copy of the transaction which is then returned.
SendTransactionResponse	sendTransaction(Transaction transaction) Submit a real transaction to the Stellar network.
SimulateTransactionResponse	simulateTransaction(Transaction transaction) An alias for simulateTransaction(Transaction, SimulateTransactionRequest.ResourceConfig, SimulateTransactionRequest.AuthMode) with no resource leeway, and no auth mode set.
SimulateTransactionResponse	simulateTransaction(Transaction transaction, SimulateTransactionRequest.ResourceConfig resourceConfig, SimulateTransactionRequest.AuthMode authMode) Submit a trial contract invocation to get back return values, expected ledger footprint, expected authorizations, and expected costs.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SorobanServer

public SorobanServer(java.lang.String serverURI)

Creates a new SorobanServer instance.

Parameters:

serverURI - The URI of the Soroban-RPC instance to connect to.

SorobanServer

public SorobanServer(java.lang.String serverURI,
                     okhttp3.OkHttpClient httpClient)

Creates a new SorobanServer instance.

Parameters:

serverURI - The URI of the Soroban-RPC instance to connect to.

httpClient - The OkHttpClient instance to use for requests.

Method Detail

getAccount

public TransactionBuilderAccount getAccount(java.lang.String address)

Fetch a minimal set of current info about a Stellar account. Needed to get the current sequence number for the account, so you can build a successful transaction with TransactionBuilder.

Parameters:

address - The address of the account to load, muxed accounts are supported.

Returns:

An Account object containing the sequence number and current state of the account.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

AccountNotFoundException - If the account does not exist on the network. You may need to fund it first.

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

getHealth

public GetHealthResponse getHealth()

General node health check.

Returns:

A GetHealthResponse object containing the health check result.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getHealth documentation

getFeeStats

public GetFeeStatsResponse getFeeStats()

Get statistics for charged inclusion fees.

Returns:

A GetFeeStatsResponse object containing the fee stats.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getFeeStats documentation

getContractData

public java.util.Optional<GetLedgerEntriesResponse.LedgerEntryResult> getContractData(java.lang.String contractId,
                                                                                      SCVal key,
                                                                                      SorobanServer.Durability durability)

Reads the current value of contract data ledger entries directly.

Parameters:

contractId - The contract ID containing the data to load. Encoded as Stellar Contract Address. e.g. "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5"

key - The key of the contract data to load.

durability - The "durability keyspace" that this ledger key belongs to, which is either SorobanServer.Durability.TEMPORARY or SorobanServer.Durability.PERSISTENT.

Returns:

A GetLedgerEntriesResponse.LedgerEntryResult object containing the ledger entry result.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

getLedgerEntries

public GetLedgerEntriesResponse getLedgerEntries(java.util.Collection<LedgerKey> keys)

Reads the current value of ledger entries directly.

Allows you to directly inspect the current state of contracts, contract's code, or any other ledger entries.

Parameters:

keys - The key of the contract data to load, at least one key must be provided.

Returns:

A GetLedgerEntriesResponse object containing the current values.

Throws:

java.lang.IllegalArgumentException - If the keys collection is empty or invalid.

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getLedgerEntries documentation

getTransaction

public GetTransactionResponse getTransaction(java.lang.String hash)

Fetch the details of a submitted transaction.

When submitting a transaction, client should poll this to tell when the transaction has completed.

Parameters:

hash - The hash of the transaction to check. Encoded as a hex string.

Returns:

A GetTransactionResponse object containing the transaction status, result, and other details.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getTransaction documentation

pollTransaction

public GetTransactionResponse pollTransaction(java.lang.String hash)
                                       throws java.lang.InterruptedException

An alias for pollTransaction(String, int, SleepStrategy) with default parameters, which maxAttempts is set to 30, and the sleep strategy is set to a default strategy that sleeps for 1 second between attempts.

Parameters:

hash - The hash of the transaction to poll for.

Returns:

A GetTransactionResponse object after a "found" response, (which may be success or failure) or the last response obtained after polling the maximum number of specified attempts.

Throws:

java.lang.InterruptedException - If the thread is interrupted while sleeping between attempts.

pollTransaction

public GetTransactionResponse pollTransaction(java.lang.String hash,
                                              int maxAttempts,
                                              SorobanServer.SleepStrategy sleepStrategy)
                                       throws java.lang.InterruptedException

Polls the transaction status until it is completed or the maximum number of attempts is reached.

After submitting a transaction, clients can use this to poll for transaction completion and return a definitive state of success or failure.

Parameters:

hash - The hash of the transaction to poll for.

maxAttempts - The number of attempts to make before returning the last-seen status.

sleepStrategy - A strategy to determine the sleep duration between attempts. It should take the current attempt number and return the sleep duration in milliseconds.

Returns:

A GetTransactionResponse object after a "found" response, (which may be success or failure) or the last response obtained after polling the maximum number of specified attempts.

Throws:

java.lang.IllegalArgumentException - If maxAttempts is less than or equal to 0.

java.lang.InterruptedException - If the thread is interrupted while sleeping between attempts.

getTransactions

public GetTransactionsResponse getTransactions(GetTransactionsRequest getTransactionsRequest)

Gets a detailed list of transactions starting from the user specified starting point that you can paginate as long as the pages fall within the history retention of their corresponding RPC provider.

Parameters:

getTransactionsRequest - The GetTransactionsRequest to use for the request.

Returns:

A GetTransactionsResponse object containing the transactions that match the request.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getTransactions documentation

getLedgers

public GetLedgersResponse getLedgers(GetLedgersRequest getLedgersRequest)

Gets a detailed list of ledgers starting from the user specified starting point that you can paginate as long as the pages fall within the history retention of their corresponding RPC provider.

Parameters:

getLedgersRequest - The GetLedgersRequest to use for the request.

Returns:

A GetLedgersResponse object containing the ledgers that match the request.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getLedgers documentation

getEvents

public GetEventsResponse getEvents(GetEventsRequest getEventsRequest)

Fetches all events that match the given GetEventsRequest.

Parameters:

getEventsRequest - The GetEventsRequest to use for the request.

Returns:

A GetEventsResponse object containing the events that match the request.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getEvents documentation

getVersionInfo

public GetVersionInfoResponse getVersionInfo()

Fetches version information about the RPC and Captive core.

Returns:

A GetVersionInfoResponse object containing the version information.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getVersionInfo documentation

getNetwork

public GetNetworkResponse getNetwork()

Fetches metadata about the network which Soroban-RPC is connected to.

Returns:

A GetNetworkResponse object containing the network metadata.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getNetwork documentation

getLatestLedger

public GetLatestLedgerResponse getLatestLedger()

Fetches the latest ledger meta info from network which Soroban-RPC is connected to.

Returns:

A GetLatestLedgerResponse object containing the latest ledger meta info.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

getLatestLedger documentation

simulateTransaction

public SimulateTransactionResponse simulateTransaction(Transaction transaction,
                                                       @Nullable
                                                       SimulateTransactionRequest.ResourceConfig resourceConfig,
                                                       @Nullable
                                                       SimulateTransactionRequest.AuthMode authMode)

Submit a trial contract invocation to get back return values, expected ledger footprint, expected authorizations, and expected costs.

Parameters:

transaction - The transaction to simulate. It should include exactly one operation, which must be one of InvokeHostFunctionOperation, ExtendFootprintTTLOperation, or RestoreFootprintOperation. Any provided footprint will be ignored.

resourceConfig - Additional resource include in the simulation.

authMode - Explicitly allows users to opt-in to non-root authorization in recording mode.

Returns:

A SimulateTransactionResponse object containing the cost, footprint, result/auth requirements (if applicable), and error of the transaction.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

simulateTransaction documentation

simulateTransaction

public SimulateTransactionResponse simulateTransaction(Transaction transaction)

An alias for simulateTransaction(Transaction, SimulateTransactionRequest.ResourceConfig, SimulateTransactionRequest.AuthMode) with no resource leeway, and no auth mode set.

prepareTransaction

public Transaction prepareTransaction(Transaction transaction)

Submit a trial contract invocation, first run a simulation of the contract invocation as defined on the incoming transaction, and apply the results to a new copy of the transaction which is then returned. Setting the ledger footprint and authorization, so the resulting transaction is ready for signing and sending.

The returned transaction will also have an updated fee that is the sum of fee set on incoming transaction with the contract resource fees estimated from simulation. It is advisable to check the fee on returned transaction and validate or take appropriate measures for interaction with user to confirm it is acceptable.

You can call the simulateTransaction(org.stellar.sdk.Transaction, org.stellar.sdk.requests.sorobanrpc.SimulateTransactionRequest.ResourceConfig, org.stellar.sdk.requests.sorobanrpc.SimulateTransactionRequest.AuthMode) method directly first if you want to inspect estimated fees for a given transaction in detail first, if that is of importance.

Parameters:

transaction - The transaction to prepare. It should include exactly one operation, which must be one of InvokeHostFunctionOperation, ExtendFootprintTTLOperation, or RestoreFootprintOperation. Any provided footprint will be ignored. You can use Transaction.isSorobanTransaction() to check if a transaction is a Soroban transaction. Any provided footprint will be overwritten. However, if your operation has existing auth entries, they will be preferred over ALL auth entries from the simulation. In other words, if you include auth entries, you don't care about the auth returned from the simulation. Other fields (footprint, etc.) will be filled as normal.

Returns:

Returns a copy of the Transaction, with the expected authorizations (in the case of invocation) and ledger footprint added. The transaction fee will also automatically be padded with the contract's minimum resource fees discovered from the simulation.

Throws:

PrepareTransactionException - If preparing the transaction fails.

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

prepareTransaction

public Transaction prepareTransaction(Transaction transaction,
                                      SimulateTransactionResponse simulateTransactionResponse)

Prepare the transaction using the simulateTransaction obtained by the user in advance, apply the simulateTransaction results to a new copy of the transaction which is then returned. Setting the ledger footprint and authorization, so the resulting transaction is ready for signing and sending.

The returned transaction will also have an updated fee that is the sum of fee set on incoming transaction with the contract resource fees estimated from simulation. It is advisable to check the fee on returned transaction and validate or take appropriate measures for interaction with user to confirm it is acceptable.

Parameters:

transaction - The transaction to prepare. It should include exactly one operation, which must be one of InvokeHostFunctionOperation, ExtendFootprintTTLOperation, or RestoreFootprintOperation. Any provided footprint will be ignored. You can use Transaction.isSorobanTransaction() to check if a transaction is a Soroban transaction. Any provided footprint will be overwritten. However, if your operation has existing auth entries, they will be preferred over ALL auth entries from the simulation. In other words, if you include auth entries, you don't care about the auth returned from the simulation. Other fields (footprint, etc.) will be filled as normal.

simulateTransactionResponse - The SimulateTransactionResponse to use for preparing the transaction.

Returns:

Returns a copy of the Transaction, with the expected authorizations (in the case of invocation) and ledger footprint added. The transaction fee will also automatically be padded with the contract's minimum resource fees discovered from the simulation.

Throws:

PrepareTransactionException - If preparing the transaction fails.

sendTransaction

public SendTransactionResponse sendTransaction(Transaction transaction)

Submit a real transaction to the Stellar network. This is the only way to make changes "on-chain". Unlike Horizon, Soroban-RPC does not wait for transaction completion. It simply validates the transaction and enqueues it. Clients should call getTransaction(java.lang.String) to learn about transaction's status.

Parameters:

transaction - The transaction to submit.

Returns:

A SendTransactionResponse object containing some details about the transaction that was submitted.

Throws:

NetworkException - All the exceptions below are subclasses of NetworkError

SorobanRpcException - If the Soroban-RPC instance returns an error response.

RequestTimeoutException - If the request timed out.

ConnectionErrorException - When the request cannot be executed due to cancellation or connectivity problems, etc.

See Also:

sendTransaction documentation

getSACBalance

public GetSACBalanceResponse getSACBalance(java.lang.String contractId,
                                           Asset asset,
                                           Network network)

Fetches the balance of a specific asset for a contract. This is useful for checking the balance of a contract in a specific asset.

Parameters:

contractId - The contract ID containing the asset balance. Encoded as Stellar Contract Address. e.g. CAB...

asset - The asset to check the balance for. This should be a valid asset object.

network - The network to use for the asset.

Returns:

A GetSACBalanceResponse which will contain the balance entry details if and only if the request returned a valid balance ledger entry. If it doesn't, the balanceEntry field will not exist.

See Also:

Stellar Asset Contract (SAC) documentation

assembleTransaction

public static Transaction assembleTransaction(Transaction transaction,
                                              SimulateTransactionResponse simulateTransactionResponse)

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException