Server

Server

Handles the network connection to a Soroban RPC instance, exposing an interface for requests to that instance.

Constructor

new Server(serverURL, optsopt)

Soroban RPC Server URL (ex. http://localhost:8000/soroban/rpc).

Source:
See:
Parameters:
Name Type Attributes Description
serverURL string

Soroban-RPC Server URL (ex. http://localhost:8000/soroban/rpc).
opts object <optional>

Options object

Name Type Attributes Description
allowHttp boolean <optional>

allows connecting to insecure http servers (default: false). This must be set to false in production deployments! You can also use Config class to set this globally.
headers Record.<string, string> <optional>

allows setting custom headers

Methods

(async) getAccount(address) → {Promise.<Account>}

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.

Source:
See:
Parameters:
Name Type Description
address string

The public address of the account to load.
Returns:
Type:
Promise.<Account>

a promise to the Account object with a populated sequence number

Example
const accountId = "GBZC6Y2Y7Q3ZQ2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4";
server.getAccount(accountId).then((account) => {
  console.log("sequence:", account.sequence);
});

(async) getContractData(contract, key, durabilityopt) → {Promise.<SorobanRpc.LedgerEntryResult>}

Reads the current value of contract data ledger entries directly.

Allows you to directly inspect the current state of a contract. This is a backup way to access your contract data which may not be available via events or Server.simulateTransaction.

Source:
See:
Parameters:
Name Type Attributes Default Description
contract string | Address | Contract

the contract ID containing the data to load as a strkey (C... form), a Contract, or an Address instance
key xdr.ScVal

the key of the contract data to load
durability Durability <optional>
 Durability.Persistent

the "durability keyspace" that this ledger key belongs to, which is either 'temporary' or 'persistent' (the default), see Durability.
Returns:
Type:
Promise.<SorobanRpc.LedgerEntryResult>

the current data value

Example
const contractId = "CCJZ5DGASBWQXR5MPFCJXMBI333XE5U3FSJTNQU7RIKE3P5GN2K2WYD5";
const key = xdr.ScVal.scvSymbol("counter");
server.getContractData(contractId, key, Durability.Temporary).then(data => {
  console.log("value:", data.val);
  console.log("liveUntilLedgerSeq:", data.liveUntilLedgerSeq);
  console.log("lastModified:", data.lastModifiedLedgerSeq);
  console.log("latestLedger:", data.latestLedger);
});

(async) getEvents(request) → {Promise.<SorobanRpc.GetEventsResponse>}

Fetch all events that match a given set of filters.

The given filters (see SorobanRpc.EventFilter for detailed fields) are combined only in a logical OR fashion, and all of the fields in each filter are optional.

To page through events, use the pagingToken field on the relevant SorobanRpc.EventResponse object to set the cursor parameter.

Source:
See:
Parameters:
Name Type Description
request Server.GetEventsRequest

event filters
Returns:
Type:
Promise.<SorobanRpc.GetEventsResponse>

a paginatable set of the events matching the given event filters

Example
server.getEvents({
   startLedger: 1000,
   filters: [
    {
     type: "contract",
     contractIds: [ "deadb33f..." ],
     topics: [[ "AAAABQAAAAh0cmFuc2Zlcg==", "AAAAAQB6Mcc=", "*" ]]
    }, {
     type: "system",
     contractIds: [ "...c4f3b4b3..." ],
     topics: [[ "*" ], [ "*", "AAAAAQB6Mcc=" ]]
    }, {
     contractIds: [ "...c4f3b4b3..." ],
     topics: [[ "AAAABQAAAAh0cmFuc2Zlcg==" ]]
    }, {
     type: "diagnostic",
     topics: [[ "AAAAAQB6Mcc=" ]]
    }
   ],
   limit: 10,
});

(async) getHealth() → {Promise.<SorobanRpc.GetHealthResponse>}

General node health check.

Source:
See:
Returns:
Type:
Promise.<SorobanRpc.GetHealthResponse>

a promise to the SorobanRpc.GetHealthResponse object with the status of the server (e.g. "healthy").

Example
server.getHealth().then((health) => {
  console.log("status:", health.status);
});

(async) getLatestLedger() → {Promise.<SorobanRpc.GetLatestLedgerResponse>}

Fetch the latest ledger meta info from network which this Soroban RPC server is connected to.

Source:
See:
Returns:
Type:
Promise.<SorobanRpc.GetLatestLedgerResponse>

metadata about the latest ledger on the network that this RPC server is connected to

Example
server.getLatestLedger().then((response) => {
  console.log("hash:", response.id);
  console.log("sequence:", response.sequence);
  console.log("protocolVersion:", response.protocolVersion);
});

(async) getLedgerEntries(…keys) → {Promise.<SorobanRpc.GetLedgerEntriesResponse>}

Reads the current value of arbitrary ledger entries directly.

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

To fetch a contract's WASM byte-code, built the appropriate xdr.LedgerKeyContractCode ledger entry key (or see Contract.getFootprint).

Source:
See:
Parameters:
Name Type Attributes Description
keys Array.<xdr.ScVal> <repeatable>

one or more ledger entry keys to load
Returns:
Type:
Promise.<SorobanRpc.GetLedgerEntriesResponse>

the current on-chain values for the given ledger keys

Example
const contractId = "CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD2KM";
const key = xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
  contractId: StrKey.decodeContract(contractId),
  key: xdr.ScVal.scvSymbol("counter"),
}));

server.getLedgerEntries([key]).then(response => {
  const ledgerData = response.entries[0];
  console.log("key:", ledgerData.key);
  console.log("value:", ledgerData.val);
  console.log("liveUntilLedgerSeq:", ledgerData.liveUntilLedgerSeq);
  console.log("lastModified:", ledgerData.lastModifiedLedgerSeq);
  console.log("latestLedger:", response.latestLedger);
});

(async) getNetwork() → {Promise.<SorobanRpc.GetNetworkResponse>}

Fetch metadata about the network this Soroban RPC server is connected to.

Source:
See:
Returns:
Type:
Promise.<SorobanRpc.GetNetworkResponse>

metadata about the current network this RPC server is connected to

Example
server.getNetwork().then((network) => {
  console.log("friendbotUrl:", network.friendbotUrl);
  console.log("passphrase:", network.passphrase);
  console.log("protocolVersion:", network.protocolVersion);
});

(async) getTransaction(hash) → {Promise.<SorobanRpc.GetTransactionResponse>}

Fetch the details of a submitted transaction.

After submitting a transaction, clients should poll this to tell when the transaction has completed.

Source:
See:
Parameters:
Name Type Description
hash string

hex-encoded hash of the transaction to check
Returns:
Type:
Promise.<SorobanRpc.GetTransactionResponse>

the status, result, and other details about the transaction

Example
const transactionHash = "c4515e3bdc0897f21cc5dbec8c82cf0a936d4741cb74a8e158eb51b9fb00411a";
server.getTransaction(transactionHash).then((tx) => {
  console.log("status:", tx.status);
  console.log("envelopeXdr:", tx.envelopeXdr);
  console.log("resultMetaXdr:", tx.resultMetaXdr);
  console.log("resultXdr:", tx.resultXdr);
});

(async) prepareTransaction(transaction, networkPassphraseopt) → {Promise.<(Transaction|FeeBumpTransaction)>}

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 & 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 adviseable 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 Server.simulateTransaction method directly first if you want to inspect estimated fees for a given transaction in detail first, then re-assemble it manually or via assembleTransaction.

Source:
See:
Parameters:
Name Type Attributes Description
transaction Transaction | FeeBumpTransaction

the transaction to prepare. It should include exactly one operation, which must be one of xdr.InvokeHostFunctionOp, xdr.ExtendFootprintTTLOp, or xdr.RestoreFootprintOp.

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.
networkPassphrase string <optional>

explicitly provide a network passphrase (default: requested from the server via Server.getNetwork).
Throws:

if simulation fails

Type
jsonrpc.Error.<any> | Error
Returns:
Type:
Promise.<(Transaction|FeeBumpTransaction)>

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

Example
const contractId = 'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE';
const contract = new SorobanClient.Contract(contractId);

// Right now, this is just the default fee for this example.
const fee = SorobanClient.BASE_FEE;
const transaction = new SorobanClient.TransactionBuilder(account, { fee })
  // Uncomment the following line to build transactions for the live network. Be
  // sure to also change the horizon hostname.
  //.setNetworkPassphrase(SorobanClient.Networks.PUBLIC)
  .setNetworkPassphrase(SorobanClient.Networks.FUTURENET)
  .setTimeout(30) // valid for the next 30s
  // Add an operation to call increment() on the contract
  .addOperation(contract.call("increment"))
  .build();

const preparedTransaction = await server.prepareTransaction(transaction);

// Sign this transaction with the secret key
// NOTE: signing is transaction is network specific. Test network transactions
// won't work in the public network. To switch networks, use the Network object
// as explained above (look for SorobanClient.Network).
const sourceKeypair = SorobanClient.Keypair.fromSecret(sourceSecretKey);
preparedTransaction.sign(sourceKeypair);

server.sendTransaction(transaction).then(result => {
  console.log("hash:", result.hash);
  console.log("status:", result.status);
  console.log("errorResultXdr:", result.errorResultXdr);
});

(async) requestAirdrop(address, friendbotUrlopt) → {Promise.<Account>}

Fund a new account using the network's friendbot faucet, if any.

Source:
See:
Parameters:
Name Type Attributes Description
address string | Account

the address or account instance that we want to create and fund with friendbot
friendbotUrl string <optional>

optionally, an explicit address for friendbot (by default: this calls the Soroban RPC Server.getNetwork method to try to discover this network's Friendbot url).
Throws:

if Friendbot is not configured on this network or request failure

Returns:
Type:
Promise.<Account>

an Account object for the created account, or the existing account if it's already funded with the populated sequence number (note that the account will not be "topped off" if it already exists)

Example
server
   .requestAirdrop("GBZC6Y2Y7Q3ZQ2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4QZJ2XZ3Z5YXZ6Z7Z2Y4")
   .then((accountCreated) => {
     console.log("accountCreated:", accountCreated);
   }).catch((error) => {
     console.error("error:", error);
   });

(async) sendTransaction(transaction) → {Promise.<SorobanRpc.SendTransactionResponse>}

Submit a real transaction to the Stellar network.

Unlike Horizon, Soroban RPC does not wait for transaction completion. It simply validates the transaction and enqueues it. Clients should call Server.getTransactionStatus to learn about transaction success/failure.

Source:
See:
Parameters:
Name Type Description
transaction Transaction | FeeBumpTransaction

to submit
Returns:
Type:
Promise.<SorobanRpc.SendTransactionResponse>

the transaction id, status, and any error if available

Example
const contractId = 'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE';
const contract = new SorobanClient.Contract(contractId);

// Right now, this is just the default fee for this example.
const fee = SorobanClient.BASE_FEE;
const transaction = new SorobanClient.TransactionBuilder(account, { fee })
  // Uncomment the following line to build transactions for the live network. Be
  // sure to also change the horizon hostname.
  //.setNetworkPassphrase(SorobanClient.Networks.PUBLIC)
  .setNetworkPassphrase(SorobanClient.Networks.FUTURENET)
  .setTimeout(30) // valid for the next 30s
  // Add an operation to call increment() on the contract
  .addOperation(contract.call("increment"))
  .build();

// Sign this transaction with the secret key
// NOTE: signing is transaction is network specific. Test network transactions
// won't work in the public network. To switch networks, use the Network object
// as explained above (look for SorobanClient.Network).
const sourceKeypair = SorobanClient.Keypair.fromSecret(sourceSecretKey);
transaction.sign(sourceKeypair);

server.sendTransaction(transaction).then((result) => {
  console.log("hash:", result.hash);
  console.log("status:", result.status);
  console.log("errorResultXdr:", result.errorResultXdr);
});

(async) simulateTransaction(transaction) → {Promise.<SorobanRpc.SimulateTransactionResponse>}

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

Source:
See:
Parameters:
Name Type Description
transaction Transaction | FeeBumpTransaction

the transaction to simulate, which should include exactly one operation (one of xdr.InvokeHostFunctionOp, xdr.ExtendFootprintTTLOp, or xdr.RestoreFootprintOp). Any provided footprint or auth information will be ignored.
Returns:
Type:
Promise.<SorobanRpc.SimulateTransactionResponse>

an object with the cost, footprint, result/auth requirements (if applicable), and error of the transaction

Example
const contractId = 'CA3D5KRYM6CB7OWQ6TWYRR3Z4T7GNZLKERYNZGGA5SOAOPIFY6YQGAXE';
const contract = new SorobanClient.Contract(contractId);

// Right now, this is just the default fee for this example.
const fee = SorobanClient.BASE_FEE;
const transaction = new SorobanClient.TransactionBuilder(account, { fee })
  // Uncomment the following line to build transactions for the live network. Be
  // sure to also change the horizon hostname.
  //.setNetworkPassphrase(SorobanClient.Networks.PUBLIC)
  .setNetworkPassphrase(SorobanClient.Networks.FUTURENET)
  .setTimeout(30) // valid for the next 30s
  // Add an operation to call increment() on the contract
  .addOperation(contract.call("increment"))
  .build();

server.simulateTransaction(transaction).then((sim) => {
  console.log("cost:", sim.cost);
  console.log("result:", sim.result);
  console.log("error:", sim.error);
  console.log("latestLedger:", sim.latestLedger);
});