Package org.stellar.sdk

Class SorobanServer

java.lang.Object

org.stellar.sdk.SorobanServer

All Implemented Interfaces:

Closeable, AutoCloseable

public class SorobanServer
extends Object
implements 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	Description
static enum	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.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
void	close()
TransactionBuilderAccount	getAccount(String address)	Fetch a minimal set of current info about a Stellar account.
Optional<GetLedgerEntriesResponse.LedgerEntryResult>	getContractData(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(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.
GetTransactionResponse	getTransaction(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.
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) with no resource leeway.
SimulateTransactionResponse	simulateTransaction(Transaction transaction, SimulateTransactionRequest.ResourceConfig resourceConfig)	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 Details

SorobanServer

public SorobanServer(String serverURI)

Creates a new SorobanServer instance.

Parameters:

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

SorobanServer

public SorobanServer(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 Details

getAccount

public TransactionBuilderAccount getAccount(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 Optional<GetLedgerEntriesResponse.LedgerEntryResult> getContractData(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(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:

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(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

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)

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.

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) with no resource leeway.

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) 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

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException