Configuring
For production, we recommend running Stellar RPC with a TOML configuration file rather than CLI flags. This is similar to creating a configuration file for Stellar-Core as we did previously. For example, using our docker image:
docker run -p 8001:8001 -p 8000:8000 \
-v <CONFIG_FOLDER>:/config stellar/stellar-rpc \
--config-path <RPC_CONFIG_FILENAME>
Use this Stellar RPC subcommand to generate a starter configuration file:
docker run stellar/stellar-rpc:latest gen-config-file > stellar-rpc-config.toml
The resulting configuration should look like this:
# Admin endpoint to listen and serve on. WARNING: this should not be accessible
# from the Internet and does not use TLS. "" (default) disables the admin server
# ADMIN_ENDPOINT = ""
# Populates database with `history-retention-window` ledgers synchronously on
# startup. This defaults to a week of ledgers if unspecified
# BACKFILL = false
# path to additional configuration for the Stellar Core configuration file used
# by captive core. It must, at least, include enough details to define a quorum
# set
# CAPTIVE_CORE_CONFIG_PATH = ""
# Storage location for Captive Core bucket data
CAPTIVE_CORE_STORAGE_PATH = "/"
# establishes how many ledgers exist between checkpoints, do NOT change this
# unless you really know what you are doing
CHECKPOINT_FREQUENCY = 64
# configures classic fee stats retention window expressed in number of ledgers
CLASSIC_FEE_STATS_RETENTION_WINDOW = 10
# SQLite DB path
DB_PATH = "stellar_rpc.sqlite"
# Default cap on the amount of events included in a single getEvents response
DEFAULT_EVENTS_LIMIT = 100
# Default cap on the amount of ledgers included in a single getLedgers response
DEFAULT_LEDGERS_LIMIT = 50
# Default cap on the amount of transactions included in a single getTransactions
# response
DEFAULT_TRANSACTIONS_LIMIT = 50
# Endpoint to listen and serve on
ENDPOINT = "localhost:8000"
# The friendbot URL to be returned by getNetwork endpoint
# FRIENDBOT_URL = ""
# comma-separated list of stellar history archives to connect with
HISTORY_ARCHIVE_URLS = []
# configures history retention window for transactions and events, expressed in
# number of ledgers, the default value is 120960 which corresponds to about 7
# days of history
HISTORY_RETENTION_WINDOW = 120960
# Ingestion Timeout when bootstrapping data (checkpoint and in-memory
# initialization) and preparing ledger reads
INGESTION_TIMEOUT = "50m0s"
# format used for output logs (json or text)
# LOG_FORMAT = "text"
# minimum log severity (debug, info, warn, error) to log
LOG_LEVEL = "info"
# Maximum amount of events allowed in a single getEvents response
MAX_EVENTS_LIMIT = 10000
# The maximum duration of time allowed for processing a getEvents request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_EVENTS_EXECUTION_DURATION = "10s"
# The maximum duration of time allowed for processing a getFeeStats request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_FEE_STATS_EXECUTION_DURATION = "5s"
# The maximum duration of time allowed for processing a getHealth request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_HEALTH_EXECUTION_DURATION = "5s"
# The maximum duration of time allowed for processing a getLatestLedger request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_LATEST_LEDGER_EXECUTION_DURATION = "5s"
# The maximum duration of time allowed for processing a getLedgers request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_LEDGERS_EXECUTION_DURATION = "10s"
# The maximum duration of time allowed for processing a getLedgerEntries
# request. When that time elapses, the rpc server would return -32001 and abort
# the request's execution
MAX_GET_LEDGER_ENTRIES_EXECUTION_DURATION = "5s"
# The maximum duration of time allowed for processing a getNetwork request. When
# that time elapses, the rpc server would return -32001 and abort the request's
# execution
MAX_GET_NETWORK_EXECUTION_DURATION = "5s"
# The maximum duration of time allowed for processing a getTransactions request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_TRANSACTIONS_EXECUTION_DURATION = "5s"
# The maximum duration of time allowed for processing a getTransaction request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_TRANSACTION_EXECUTION_DURATION = "5s"
# The maximum duration of time allowed for processing a getVersionInfo request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_GET_VERSION_INFO_EXECUTION_DURATION = "5s"
# maximum ledger latency (i.e. time elapsed since the last known ledger closing
# time) considered to be healthy (used for the /health endpoint)
MAX_HEALTHY_LEDGER_LATENCY = "30s"
# Maximum amount of ledgers allowed in a single getLedgers response
MAX_LEDGERS_LIMIT = 200
# The max request execution duration is the predefined maximum duration of time
# allowed for processing a request. When that time elapses, the server would
# return 504 and abort the request's execution
MAX_REQUEST_EXECUTION_DURATION = "25s"
# The maximum duration of time allowed for processing a sendTransaction request.
# When that time elapses, the rpc server would return -32001 and abort the
# request's execution
MAX_SEND_TRANSACTION_EXECUTION_DURATION = "15s"
# The maximum duration of time allowed for processing a simulateTransaction
# request. When that time elapses, the rpc server would return -32001 and abort
# the request's execution
MAX_SIMULATE_TRANSACTION_EXECUTION_DURATION = "15s"
# Maximum amount of transactions allowed in a single getTransactions response
MAX_TRANSACTIONS_LIMIT = 200
# Specifies the desired Stellar network, 'pubnet', 'testnet', or 'futurenet'.
# NETWORK = ""
# Network passphrase of the Stellar network transactions should be signed for.
# Commonly used values are "Test SDF Future Network ; October 2022", "Test SDF
# Network ; September 2015" and "Public Global Stellar Network ; September 2015"
# NETWORK_PASSPHRASE = ""
# Enable debug information in preflighting (provides more detailed errors). It
# should not be enabled in production deployments.
PREFLIGHT_ENABLE_DEBUG = true
# Number of workers (read goroutines) used to compute preflights for the
# simulateTransaction endpoint. Defaults to the number of CPUs.
PREFLIGHT_WORKER_COUNT = 8
# Maximum number of outstanding preflight requests for the simulateTransaction
# endpoint. Defaults to the number of CPUs.
PREFLIGHT_WORKER_QUEUE_SIZE = 8
# Maximum number of outstanding GetEvents requests
REQUEST_BACKLOG_GET_EVENTS_QUEUE_LIMIT = 1000
# Maximum number of outstanding GetFeeStats requests
REQUEST_BACKLOG_GET_FEE_STATS_QUEUE_LIMIT = 100
# Maximum number of outstanding GetHealth requests
REQUEST_BACKLOG_GET_HEALTH_QUEUE_LIMIT = 1000
# Maximum number of outstanding GetLatestsLedger requests
REQUEST_BACKLOG_GET_LATEST_LEDGER_QUEUE_LIMIT = 1000
# Maximum number of outstanding getLedgers requests
REQUEST_BACKLOG_GET_LEDGERS_QUEUE_LIMIT = 1000
# Maximum number of outstanding GetLedgerEntries requests
REQUEST_BACKLOG_GET_LEDGER_ENTRIES_QUEUE_LIMIT = 1000
# Maximum number of outstanding GetNetwork requests
REQUEST_BACKLOG_GET_NETWORK_QUEUE_LIMIT = 1000
# Maximum number of outstanding GetTransactions requests
REQUEST_BACKLOG_GET_TRANSACTIONS_QUEUE_LIMIT = 1000
# Maximum number of outstanding GetTransaction requests
REQUEST_BACKLOG_GET_TRANSACTION_QUEUE_LIMIT = 1000
# Maximum number of outstanding GetVersionInfo requests
REQUEST_BACKLOG_GET_VERSION_INFO_QUEUE_LIMIT = 1000
# Maximum number of outstanding requests
REQUEST_BACKLOG_GLOBAL_QUEUE_LIMIT = 5000
# Maximum number of outstanding SendTransaction requests
REQUEST_BACKLOG_SEND_TRANSACTION_QUEUE_LIMIT = 500
# Maximum number of outstanding SimulateTransaction requests
REQUEST_BACKLOG_SIMULATE_TRANSACTION_QUEUE_LIMIT = 100
# The request execution warning threshold is the predetermined maximum duration
# of time that a request can take to be processed before a warning would be
# generated
REQUEST_EXECUTION_WARNING_THRESHOLD = "5s"
# Fetch historical ledgers from the datastore if they're not available locally.
# SERVE_LEDGERS_FROM_DATASTORE = false
# configures soroban inclusion fee stats retention window expressed in number of
# ledgers
SOROBAN_FEE_STATS_RETENTION_WINDOW = 50
# HTTP port for Captive Core to listen on (0 disables the HTTP server)
STELLAR_CAPTIVE_CORE_HTTP_PORT = 11626
# HTTP port for Captive Core to listen on for high-performance queries like
# /getledgerentry (must not conflict with CAPTIVE_CORE_HTTP_PORT)
STELLAR_CAPTIVE_CORE_HTTP_QUERY_PORT = 11628
# Size of ledger history in Captive Core's high-performance query server (don't
# touch unless you know what you are doing)
STELLAR_CAPTIVE_CORE_HTTP_QUERY_SNAPSHOT_LEDGERS = 4
# path to stellar core binary
STELLAR_CORE_BINARY_PATH = "/usr/bin/stellar-core"
# Timeout used when submitting requests to stellar-core
STELLAR_CORE_TIMEOUT = "2s"
# URL used to query Stellar Core (local captive core by default)
# STELLAR_CORE_URL = ""
# Enable strict toml configuration file parsing. This will prevent unknown
# fields in the config toml from being parsed.
# STRICT = false
Note that the above generated configuration contains the default values and you need to substitute them with proper values to run the image. For instance, when using a container, it is recommended to create a volume for the Captive Core and RPC persistent storage and point CAPTIVE_CORE_STORAGE_PATH and DB_PATH to it accordingly.
Then, you should create a configuration file for Stellar Core. You can find sample configuration files for Testnet and Pubnet
When using docker, you should create and mount a volume mount a volume on your container where the above configuration is stored.
If you are running locally on a unix-style machine, you could create a folder in your home directory called ~/rpc-config
cd ~
mkdir rpc-config
Then you would add the following config files to that local directory:
- soroban-rpc-config.toml
- stellar-captive-core.cfg
Then you would mount that volume using by adding the following parameter: -v /Users/<USERNAME>/test-rpc-config:/opt/stellar to your docker run command.
Your running container would mount that volume at the path /opt/stellar
Backfilling History on Startup
Set BACKFILL = true to populate the database with a trailing window of history synchronously on startup, before live ingestion begins. This option was added in RPC v25.1.0 and defaults to false.
HISTORY_RETENTION_WINDOW sets the target size of that window. The default is 120960 ledgers, which is about 7 days.
RPC treats this value as a target, not an exact count. Datastore coverage, ledgers already in the local database, and checkpoint boundaries can each reduce what the node fetches.
BACKFILL also requires datastore serving. Set SERVE_LEDGERS_FROM_DATASTORE = true. If you enable BACKFILL alone, RPC fails to start with this error:
backfill requires serving ledgers from datastore to be enabled. See the `--serve-ledgers-from-datastore` flag
To set up the datastore, see Data Lake Integration. That page also explains which requests the datastore serves directly.
Next Step
After installation is complete, you are now ready to proceed to Running RPC!