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 accountId)	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.
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.
GetNetworkResponse	getNetwork()	Fetches metadata about the network which Soroban-RPC is connected to.
GetTransactionResponse	getTransaction(String hash)	Fetch the details of a submitted transaction.
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 accountId)
                                     throws IOException,
AccountNotFoundException,
SorobanRpcErrorResponse

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:

accountId - The public address of the account to load.

Returns:

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

Throws:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

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

getHealth

public GetHealthResponse getHealth()
                            throws IOException,
SorobanRpcErrorResponse

General node health check.

Returns:

A GetHealthResponse object containing the health check result.

Throws:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• getHealth documentation

getContractData

public Optional<GetLedgerEntriesResponse.LedgerEntryResult> getContractData(String contractId,
 SCVal key,
 SorobanServer.Durability durability)
                                                                     throws IOException,
SorobanRpcErrorResponse

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:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

getLedgerEntries

public GetLedgerEntriesResponse getLedgerEntries(Collection<LedgerKey> keys)
                                          throws IOException,
SorobanRpcErrorResponse

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:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• getLedgerEntries documentation

getTransaction

public GetTransactionResponse getTransaction(String hash)
                                      throws IOException,
SorobanRpcErrorResponse

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:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• getTransaction documentation

getEvents

public GetEventsResponse getEvents(GetEventsRequest getEventsRequest)
                            throws IOException,
SorobanRpcErrorResponse

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:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• getEvents documentation

getNetwork

public GetNetworkResponse getNetwork()
                              throws IOException,
SorobanRpcErrorResponse

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

Returns:

A GetNetworkResponse object containing the network metadata.

Throws:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• getNetwork documentation

getLatestLedger

public GetLatestLedgerResponse getLatestLedger()
                                        throws IOException,
SorobanRpcErrorResponse

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:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• getLatestLedger documentation

simulateTransaction

public SimulateTransactionResponse simulateTransaction(Transaction transaction,
 @Nullable
 SimulateTransactionRequest.ResourceConfig resourceConfig)
                                                throws IOException,
SorobanRpcErrorResponse

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:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• simulateTransaction documentation

simulateTransaction

public SimulateTransactionResponse simulateTransaction(Transaction transaction)
                                                throws IOException,
SorobanRpcErrorResponse

An alias for simulateTransaction(Transaction, SimulateTransactionRequest.ResourceConfig) with no resource leeway.

Throws:

IOException

SorobanRpcErrorResponse

prepareTransaction

public Transaction prepareTransaction(Transaction transaction)
                               throws IOException,
SorobanRpcErrorResponse,
PrepareTransactionException

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.

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

prepareTransaction

public Transaction prepareTransaction(Transaction transaction,
 SimulateTransactionResponse simulateTransactionResponse)
                               throws PrepareTransactionException

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)
                                        throws IOException,
SorobanRpcErrorResponse

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:

IOException - If the request could not be executed due to cancellation, a connectivity problem or timeout. Because networks can fail during an exchange, it is possible that the remote server accepted the request before the failure.

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

See Also:

• sendTransaction documentation

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException