Struct Server

pub struct Server { /* private fields */ }

The main struct to use to interact with the stellar RPC

Implementations

impl Server

pub fn new(server_url: &str, opts: Options) -> Result<Self, Error>

Instantiate a new Server

use soroban_client::*;
let rpc = Server::new("https://soroban-testnet.stellar.org", Options::default());

pub async fn get_events( &self, ledger: Pagination, filters: Vec<EventFilter>, limit: impl Into<Option<u32>>, ) -> Result<GetEventsResponse, Error>

Call to RPC method getEvents

Clients can request a filtered list of events emitted by a given ledger range.

Stellar-RPC will support querying within a maximum 7 days of recent ledgers.

Note, this could be used by the client to only prompt a refresh when there is a new ledger with relevant events. It should also be used by backend Dapp components to “ingest” events into their own database for querying and serving.

If making multiple requests, clients should deduplicate any events received, based on the event’s unique id field. This prevents double-processing in the case of duplicate events being received.

By default stellar-rpc retains the most recent 24 hours of events.

Example

// Fetch 12 events from ledger 67000 for contract "CAA..."
let events = server.get_events(
    Pagination::From(67000),
    vec![
        EventFilter::new(EventType::All).contract("CAA...")
    ],
    12
).await?;

pub async fn get_fee_stats(&self) -> Result<GetFeeStatsResponse, Error>

Call to RPC method getFeeStats

Statistics for charged inclusion fees. The inclusion fee statistics are calculated from the inclusion fees that were paid for the transactions to be included onto the ledger. For Soroban transactions and Stellar transactions, they each have their own inclusion fees and own surge pricing. Inclusion fees are used to prevent spam and prioritize transactions during network traffic surge.

pub async fn get_health(&self) -> Result<GetHealthResponse, Error>

Call to RPC method getHealth

General node health check.

pub async fn get_latest_ledger(&self) -> Result<GetLatestLedgerResponse, Error>

Call to RPC method getLatestLedger

For finding out the current latest known ledger of this node. This is a subset of the ledger info from Horizon.

pub async fn get_ledger_entries( &self, keys: Vec<LedgerKey>, ) -> Result<GetLedgerEntriesResponse, Error>

Call to RPC method getLedgerEntries

For reading the current value of ledger entries directly.

This method enables the retrieval of various ledger states, such as accounts, trustlines, offers, data, claimable balances, and liquidity pools. It also provides direct access to inspect a contract’s current state, its code, or any other ledger entry. This serves as a primary method to access your contract data which may not be available via events or simulate_transaction.

To fetch contract wasm byte-code, use the ContractCode ledger entry key.

pub async fn get_ledgers( &self, ledger: Pagination, limit: impl Into<Option<u32>>, ) -> Result<GetLedgersResponse, Error>

Call to RPC method getLedgers

The getLedgers method returns 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.

pub async fn get_network(&self) -> Result<GetNetworkResponse, Error>

Call to RPC method getNetwork

General information about the currently configured network. This response will contain all the information needed to successfully submit transactions to the network this node serves.

pub async fn get_transaction( &self, hash: &str, ) -> Result<GetTransactionResponse, Error>

Call to RPC method getTransaction

The getTransaction method provides details about the specified transaction.

Clients are expected to periodically query this method to ascertain when a transaction has been successfully recorded on the blockchain. The stellar-rpc system maintains a restricted history of recently processed transactions, with the default retention window set at 24 hours.

For private soroban-rpc instances, it is possible to modify the retention window value by adjusting the transaction-retention-window configuration setting, but we do not recommend values longer than 7 days. For debugging needs that extend beyond this timeframe, it is advisable to index this data yourself, employ a third-party indexer, or query Hubble (our public BigQuery data set).

pub async fn get_transactions( &self, ledger: Pagination, limit: impl Into<Option<u32>>, ) -> Result<GetTransactionsResponse, Error>

Call to RPC method getTransactions

The getTransactions method return 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.

In [Pagination::FromTo(start, end)], the end has no effect for get_transactions.

pub async fn get_version_info(&self) -> Result<GetVersionInfoResponse, Error>

Call to RPC method getVersionInfo

Version information about the RPC and Captive core. RPC manages its own, pared-down version of Stellar Core optimized for its own subset of needs. we’ll refer to this as a “Captive Core” instance.

pub async fn send_transaction( &self, transaction: Transaction, ) -> Result<SendTransactionResponse, Error>

Call to RPC method sendTransaction

Submit a real transaction to the Stellar network. This is the only way to make changes on-chain.

Unlike Horizon, this does not wait for transaction completion. It simply validates and enqueues the transaction. Clients should call getTransaction to learn about transaction success/failure.

This supports all transactions, not only smart contract-related transactions.

pub async fn simulate_transaction( &self, transaction: Transaction, addl_resources: Option<ResourceLeeway>, ) -> Result<SimulateTransactionResponse, Error>

Call to RPC method simulateTransaction

Submit a trial contract invocation to simulate how it would be executed by the network. This endpoint calculates the effective transaction data, required authorizations, and minimal resource fee. It provides a way to test and analyze the potential outcomes of a transaction without actually submitting it to the network.

pub async fn get_account(&self, address: &str) -> Result<Account, Error>

Fetch an Account to be used to build a transaction

It uses Server::get_ledger_entries to fetch the LedgerKey::Account

pub async fn get_contract_data( &self, contract: &str, key: ScVal, durability: Durability, ) -> Result<LedgerEntryResult, Error>

Fech the ledger entry specified by the key of the contract

This can be used to inspect the contract state without using Server::simulate_transaction or to fetch data not available otherwise.

pub async fn prepare_transaction( &self, transaction: Transaction, ) -> Result<Transaction, Error>

Prepare a transaction to be submited to the network.

If the transaction simulation is successful, a new transaction is built using the returned footprint and authorizations.

The fees are adapted based on the initial fees and the contract resource fees estimated from the simulation.

If the simulation returns a restore preamble, this method will return a Error::RestorationRequired. This error should be used to build a stellar_baselib::xdr::OperationBody::RestoreFootprint

pub async fn request_airdrop(&self, account_id: &str) -> Result<Account, Error>

Fund the account using the network’s friendbot faucet (testnet)

The friendbot URL is retrieved first from the Options::friendbot_url if provided or from the Server::get_network method. There is no friendbot faucet on mainnet.

Trait Implementations

impl Debug for Server

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.