RPC

The RPC service allows you to communicate directly with Soroban via a JSON RPC interface.

For example, you can build an application and have it send a transaction, get ledger and event data or simulate transactions.

Alternatively, you can use one of Soroban's client SDKs such as the js-soroban-client, which will need to communicate with an RPC instance to access the network.

Run Your Own Instance

Download and run a local instance via Docker Quickstart and run a standalone network or communicate with a live development Testnet.

For local development, an RPC service can run on a standard laptop with 16GB of RAM and has minimal storage and CPU requirements.

The Quickstart image is a single container that runs everything you need to test against a fully featured network. It contains:

• Stellar Core - Node software that runs the network, coordinates consensus, and finalizes ledgers.
• Soroban RPC server - JSON RPC server for interacting with Soroban contracts.
• Horizon server - HTTP API for access ledger state and historical transactions.
• Friendbot server - HTTP API for creating and funding new accounts on test networks.

info

It's also possible to run a contract in the local sandbox environment without a network using just Soroban CLI. See Run on Sandbox for more details.

Standalone

To run a local standalone network with the Stellar Quickstart Docker image, run the following command, double-checking that the sha256 matches the latest on the Releases page:

docker run --rm -it \
    -p 8000:8000 \
    --name stellar \
    stellar/quickstart:testing@sha256:1c98f895f8b69cc843eeaa5230d67044dbeb390a5529d51dd7762d8ff685c3f8 \
    --standalone \
    --enable-soroban-rpc

Once the image is started you can check its status by querying the Horizon API:

curl "http://localhost:8000"

You can interact with this local node using Soroban CLI. First, add it as a configured network:

soroban config network add standalone \
    --rpc-url "http://localhost:8000/soroban/rpc" \
    --network-passphrase "Standalone Network ; February 2017"

Then generate a unique identity (public/private keypair) to use with it:

soroban config identity generate alice

Test-only Identities

It's a good practice to never use the same keys for testing and development that you use do for the public Stellar network. Generate new keys for testing and development and avoid ever using them for other purposes.

Finally, fund your new account on the local sandbox environment by making a request to the local Friendbot:

curl "http://localhost:8000/friendbot?addr=$(soroban config identity address alice)"

Command Expansion $(...)

This uses command expansion, which only works with bash-compatible shells. If you are using Windows or some other shell, you will need to copy the output of soroban config… and paste it into the curl command, or figure out how command expansion works in your shell.

Now that you have a configured network and a funded identity, you can use these within other Soroban CLI commands. For example, deploying a contract:

soroban contract deploy \
    --wasm target/wasm32-unknown-unknown/release/[project_name].wasm \
    --source alice \
    --network standalone

Or invoking a contract:

soroban contract invoke \
    --id C... \
    --source alice \
    --network standalone \
    -- \
    hello \
    --to friend

When you're done with your Standalone node, you can close it with ctrlc (not cmd). This will fully remove the container (that's what the --rm option to the docker command does), which means you will need to re-deploy your contract and re-fund your identity next time you start it. If you work with local nodes often, you may want to create scripts to make these initialization steps easier. For example, see the example dapp's initialize.sh.

Testnet

Running your own Testnet node works much the same way as running a Quickstart node, described above. You will need minor modifications for a few commands. First, you need --testnet for the docker instance, rather than --standalone:

docker run --rm -it \
    -p 8000:8000 \
    --name stellar \
    stellar/quickstart:testing@sha256:1c98f895f8b69cc843eeaa5230d67044dbeb390a5529d51dd7762d8ff685c3f8 \
    --testnet \
    --enable-soroban-rpc

And you'll want to configure it for use with the --network flag in Soroban CLI:

soroban config network add testnet \
    --rpc-url "http://localhost:8000/soroban/rpc" \
    --network-passphrase "Test SDF Network ; September 2015"

Replace testnet in that command with the name of your choice, if you want to leave the name testnet available for use with a public RPC provider (see below). Or make clever use of --global configs for public providers and local configs (made with the undecorated network add command above) for local nodes.

The alice identity suggested for your Standalone network will still work here, since it's just a public/private keypair, but you'll need to remember to fund it for the Testnet network:

curl "https://friendbot.stellar.org/?addr=$(soroban config identity address alice)"

Now you can replace --network standalone with --network testnet (or whatever you named it) in all your commands that need a network, like the deploy and invoke commands shown above.

Futurenet

You can also develop your Soroban contracts against the Futurenet network. You may choose this if you want to test more bleeding edge features that haven't made it to the Testnet yet. Running your own Futurenet node works just like running a Testnet node, described above.

docker run --rm -it \
    -p 8000:8000 \
    --name stellar \
    stellar/quickstart:soroban-dev \
    --futurenet \
    --enable-soroban-rpc

And you'll want to configure it for use with the --network flag in Soroban CLI:

soroban config network add futurenet \
    --rpc-url "http://localhost:8000/soroban/rpc" \
    --network-passphrase "Test SDF Future Network ; October 2022"

Replace futurenet in that command with the name of your choice, if you want to leave the name futurenet available for use with a public RPC provider (see below). Or make clever use of --global configs for public providers and local configs (made with the undecorated network add command above) for local nodes.

The alice identity suggested for your Standalone and Testnet networks will still work here, since it's just a public/private keypair, but you'll need to remember to fund it for the Futurenet network:

curl "https://friendbot-futurenet.stellar.org/?addr=$(soroban config identity address alice)"

Now you can replace --network standalone with --network futurenet (or whatever you named it) in all your commands that need a network, like the deploy and invoke commands shown above.

Public RPC Providers

These providers host a publicly available RPC endpoint that you can connect to. The following currently support Futurenet and Testnet (with more to come).

Stellar Development Foundation (SDF)

Provider	Endpoint	Friendbot	Network
SDF	https://rpc-futurenet.stellar.org	https://friendbot-futurenet.stellar.org	Futurenet
SDF	https://soroban-testnet.stellar.org	https://friendbot.stellar.org	Testnet

Blockdaemon

Provider	Endpoint	Friendbot
Blockdaemon	Sign Up	N/A

You can signup to join the waitlist for Blockdaemon's RPC endpoint on Mainnet.

Blockdaemon offers access to an institutional-grade RPC endpoint that will support Soroban's Mainnet. As one of the largest independent blockchain infrastructure providers, Blockdaemon provides institutional-grade SLAs, 99.9% uptime, 24/7 support, and decentralized data centers with SOC2-compliance.

You can apply to receive a 1-month free “Starter” tier, and up to five months at the reduced price.

Deploy your own RPC instance

If your target deployment environment includes Kubernetes infrastructure, you can utilize soroban rpc helm chart for an automated deployment on the cluster. Install the Helm cli tool, minimum of version 3 if you haven't already on your workstation. Next, add the Stellar repo to the helm client's list of repos, update it to the latest published versions:

helm repo add stellar https://helm.stellar.org/charts
helm repo update stellar

Deploy rpc to kubernetes using the helm chart:

helm install my-rpc stellar/soroban-rpc \
--namespace my-rpc-namespace-on-cluster \
--set global.image.sorobanRpc.tag=20.0.0-rc3-39 \
--set sorobanRpc.ingress.host=myrpc.example.org \
--set sorobanRpc.persistence.enabled=true \
--set sorobanRpc.persistence.storageClass=default \
--set sorobanRpc.resources.limits.cpu=1 \
--set sorobanRpc.resources.limits.memory=2560Mi

This example of helm chart usage, highlights some key aspects:

• Set the global.image.sorobanRpc.tag to a tag from the soroban rpc dockerhub repo for the image version you want to run. Refer to the releases page to find the correct tag to use for the soroban release you are running.

• The RPC server stores a revolving window of recent data from network ledgers to disk. The sizing of that data will vary depending on the network and it's transaction volumes, estimated range between 10 to 100 MB. To ensure the RPC pod has consistent access to disk storage space and read/write throughput, this example demonstrates how to optionally enable the helm chart deployment to use a PersistentVolumeClaim (PVC) of 100MB from default storage class on kubernetes by enabling these persistence parameters:

--set sorobanRpc.persistence.enabled=true
--set sorobanRpc.persistence.storageClass=default

By default, this is disabled (sorobanRpc.persistence.enabled=false) and the RPC deployment will use ephemeral pod storage via emptyDir which will likely be adequate for futurenet and testnet transaction volumes, but it's worth highlighting the trade-off, which is size limitations enforced from the cluster, most likely lower than 100MB.

• Network presets are defined in values.yaml, which currently sets network configuration specific to futurenet. You can override this default and use other "canned" values.yaml files which have been published for other networks. For example, there is a testnet-values.yaml file to configure deployment of RPC server with the testnet network. Include this --values parameter in your helm install your to specify the desired network:

--values https://raw.githubusercontent.com/stellar/helm-charts/main/charts/soroban-rpc/testnet-values.yaml

• Configuring RPC to use other custom networks can be accomplished by downloading the values.yaml locally and updating settings under sorobanRpc.sorobanRpcConfig and sorobanRpc.coreConfig. This is applicable when needing to connect to specific networks other than the "canned" values.yaml files available, such as your own standalone network. Include the local values.yaml in helm install:

--values my-custom-values.yaml

• Verify the LimitRange defaults in the target namespace in kubernetes for deployment. LimitRange is optional on the cluster config, if defined, ensure that the defaults provide at least minimum RPC server resource limits of 2.5Gi of memory and 1 CPU. Otherwise, include the limits explicitly on the helm install command via the sorobanRpc.resources.limits.* parameters.

--set sorobanRpc.resources.limits.cpu=1
--set sorobanRpc.resources.limits.memory=2560Mi

If kubernetes is not an option, the manifests generated by the charts may still be a good reference for showing how to configure and run Soroban RPC as a docker container. Just run the helm template command to print the container configuration to screen:

helm template my-rpc stellar/soroban-rpc

Use the RPC Instance

You can configure Soroban CLI to use a remote RPC endpoint:

soroban config network add --global testnet \
    --rpc-url https://soroban-testnet.stellar.org:443 \
    --network-passphrase 'Test SDF Network ; September 2015'

And fund your accounts/identities with the publicly hosted Friendbot:

curl "https://friendbot.stellar.org/?addr=$(soroban config identity address alice)"

See the tip above about command expansion (that's the note about $(...)) if you're not using a bash-based shell.

caution

When interacting with the network in production you should run your own soroban-rpc or use a third party infrastructure provider.