How to Run Stellar API Server?
Stellar is a decentralized and open network for transferring and storing money. Jed McCaleb, the founder of Stellar, developed Stellar intending to provide people with a way to share their fiat currency to crypto effortlessly.
Developers who build apps on the top of the Stellar network program using Stellar SDKs in their preferred programming languages. SDKs, in turn, interact with Horizon, Stellar-network API. Horizon provides a way to check accounts, subscribe to events and submit transactions.
This article provides a detailed insight into how to run the Stellar API server. The basic flow of this article includes:
- Prerequisites
- Installation
- Configuration
- Running
- Monitoring
Stellar ecosystem uses an API server named Horizon. It acts as an interface between Stellar Core and the applications on the Stellar network. It also provides HTTP API to data in the Stellar network. It takes data from the Stellar network and re-serves it in a form that is easy to consume.
There are various benefits for running Horizon with your infrastructure:
- Have complete operational control without any dependency on the Stellar Development Foundation
- Manage multiple instances for scalability and redundancy
- Disable request rate-limiting for guaranteed network access
Prerequisites
Horizon depends on the PostgreSQL server that it uses to store data processed and ingested from Stellar Core. PostgreSQL version 9.5 or above is required for Horizon.
Extra RAM is required to hold Captive Core’s in-memory database, which would be approximately 3 GB. The secondary requirement depends on the amount of the network’s history served from your Horizon instance. It could range from a few GBs to tens of TBs for the entire ingested ledger history.
Installation
Firstly, prebuilt binaries from Stellar repositories need to be installed before installing Horizon. If you don’t wish to install prebuilt releases, there’s another option. You’ll need to build Horizon from the source. A few developer tools need to be installed to accomplish this task:
- OS like Unix with common core commands like mkdir, cp, bash, etc.
- Go1.15 or later
- Git
A few additional binaries installation is required to install Captive Core separately from Horizon instances:
From repositories
Install following packages:
apt install stellar-captive-core stellar-captive-core-api
From source
Install bleeding edge from source:
git clone https://github.com/stellar/go monorepo && cd monorepo
go install -v ./exp/services/captivecore
sudo cp $(go env GOPATH)/bin/captivecore /usr/bin/stellar-captive-core-api
To test the installation, run stellar-horizon –help from the terminal. If the Horizon help page is displayed, your installation is successful.
Configuration
Parameters
Both command-line flags and environment variables can do Horizon’s configuration. Run the following command to see the list of available command-line flags, their default values and corresponding environmental variables:
horizon –help
The above command will display a large number of flags; however, only a handful are required. The three most important parameters are:
- –db-url: It specifies Horizon database and its value should be a valid PostgreSQL connection URL.
- –captive-core-config-append-path: It points to a Captive Core configuration stub.
- –stellar-core-binary-path: It is a file system path to a Stellar Core binary. Horizon searches PATH for stellar-core by default; if the environment is configured correctly, there would be no need to provide the path manually.
Prepare the database
Prepare the Horizon database before running the server. The database must store all the Horizon information, mainly historical information related to transactions over the Stellar network. A new blank database is created on the PostgreSQL server specifically for Horizon’s use. The next step is to install the schema by running horizon db init. In Postgre configuration set random_page_cost=1. It will allow query planners to make better use of indices, especially for JOIN queries. Moreover, this setting drastically improves speed for some queries.
Configure Captive Core
Here’s the working sample to configure Captive Core:
[[HOME_DOMAINS]]
HOME_DOMAIN=”testnet.stellar.org“
QUALITY=”HIGH”
[[VALIDATORS]]
NAME=”sdf_testnet_1″
HOME_DOMAIN=”testnet.stellar.org“
PUBLIC_KEY=”GDKXE2OZMJIPOSLNA6N6F2BVCI3O777I2OOC4BV7VOYUEHYX7RTRYA7Y”
ADDRESS=”core-testnet1.stellar.org“
HISTORY=”curl -sf | http://history.stellar.org/prd/core-testnet/core_testnet_001/{0} -o {1}” |
---|
[[VALIDATORS]]
NAME=”sdf_testnet_2″
HOME_DOMAIN=”testnet.stellar.org“
PUBLIC_KEY=”GCUCJTIYXSOXKBSNFGNFWW5MUQ54HKRPGJUTQFJ5RQXZXNOLNXYDHRAP”
ADDRESS=”core-testnet2.stellar.org“
HISTORY=”curl -sf | http://history.stellar.org/prd/core-testnet/core_testnet_002/{0} -o {1}” |
---|
[[VALIDATORS]]
NAME=”sdf_testnet_3″
HOME_DOMAIN=”testnet.stellar.org“
PUBLIC_KEY=”GC2V2EFSXN6SQTWVYA5EPJPBWWIMSD2XQNKUOHGEKB535AQE2I6IXV2Z”
ADDRESS=”core-testnet3.stellar.org“
HISTORY=”curl -sf | http://history.stellar.org/prd/core-testnet/core_testnet_003/{0} -o {1}” |
---|
Running
After properly setting up the Horizon database and Captive Core configuration, it’s time to run Horizon. Run stellar-horizon with the appropriate parameter set, start HTTP server and create a login. The output would be similar to:
INFO[…] Starting Horizon on 8000 pid=29011
Note that the numbers shown above may not be the same for your installation.
The above line announces that Horizon is ready to serve client requests. Load the root resource to confirm that Horizon is responding correctly. In this example, the URL would be http://127.0.0.1:8000/ and running curl http://127.0.0.1:8000/ will present root resource-loaded accurately:
{
“_links”: {
“account”: {
HISTORY= “href”: “ http://127.0.0.1:8000/accounts/{account_id}”, “templated”: true
},
“accounts”: {
“href”: “ http://127.0.0.1:8000/accounts{?signer,sponsor,asset,cursor,limit,order}”, “templated”: true
}
}
}
Ingesting transactions
Most of Horizon’s functions are performed on ingested data. However, by default, this option is disabled. To enable ingestion, either pass –ingest=true in cmd or set INGEST environment variable “True”. Run horizon db reingest range <start> <end> to ingest historical data from Stellar Core. To reingest old ledgers use horizon db reingest range <start> <end> command:
horizon1> horizon db reingest range 1 10000
horizon2> horizon db reingest range 10001 20000
horizon3> horizon db reingest range 20001 30000
# … etc.
Reading logs
Check logs to track the progress and status of ingestion. All records are tagged with service-ingest.
INFO[…] Starting ingestion system from empty state… pid=5965 service=ingest temp_set=”*io.MemoryTempSet”
INFO[…] Reading from History Archive Snapshot ledger=25565887 pid=5965 service=ingest
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=100000 pid=5965 service=ingest
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=200000 pid=5965 service=ingest
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=300000 pid=5965 service=ingest
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=400000 pid=5965 service=ingest
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=500000 pid=5965 service=ingest
After completing state ingestion, it will ingest the ledger.
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=5300000 pid=5965 service=ingest
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=5400000 pid=5965 service=ingest
INFO[…] Processing entries from History Archive Snapshot ledger=25565887 numEntries=5500000 pid=5965 service=ingest
INFO[…] Processed ledger ledger=25565887 pid=5965 service=ingest type=state_pipeline
INFO[…] Finished processing History Archive Snapshot duration=2145.337575904 ledger=25565887 numEntries=5529931 pid=5965 service=ingest shutdown=false
INFO[…] Reading new ledger ledger=25565888 pid=5965 service=ingest
INFO[…] Processing ledger ledger=25565888 pid=5965 service=ingest type=ledger_pipeline updating_database=true
INFO[…] Processed ledger ledger=25565888 pid=5965 service=ingest type=ledger_pipeline
INFO[…] Finished processing ledger duration=0.086024492 ledger=25565888 pid=5965 service=ingest shutdown=false transactions=14
INFO[…] Reading new ledger ledger=25565889 pid=5965 service=ingest
INFO[…] Processing ledger ledger=25565889 pid=5965 service=ingest type=ledger_pipeline updating_database=true
INFO[…] Processed ledger ledger=25565889 pid=5965 service=ingest type=ledger_pipeline
INFO[…] Finished processing ledger duration=0.06619956 ledger=25565889 pid=5965 service=ingest shutdown=false transactions=29
INFO[…] Reading new ledger ledger=25565890 pid=5965 service=ingest
INFO[…] Processing ledger ledger=25565890 pid=5965 service=ingest type=ledger_pipeline updating_database=true
INFO[…] Processed ledger ledger=25565890 pid=5965 service=ingest type=ledger_pipeline
INFO[…] Finished processing ledger duration=0.071039012 ledger=25565890 pid=5965 service=ingest shutdown=false transactions=20
Monitoring
Monitoring is essential to ensure that the instance of Horizon is performing correctly. Horizon will provide information about what requests are coming in. Moreover, warnings and errors will also be emitted by default, if any. A correctly running Horizon will not emit any error or warning log entries. All the metrics are continuously collected while the Horizon is running and exposed at the /metrics path.
Stellar is continuously gaining popularity due to its unique consensus protocol, connection with financial infrastructure and built-in order books. The immensely growing popularity of Stellar brings the need to learn the development and implementation of Stellar. Many big organizations have already adopted Stellar into their businesses.
Stellar is one of the most significant open-source projects that you might want to integrate into your business.
If you’re interested in getting a financial solution developed on the top of the Stellar Blockchain network, connect with our team of experts and discuss your requirements.
All information will be kept confidential.
Insights
Step-by-step Guide on How to develop an NFT Marketplace Platform
Here is a step-by-step tutorial on How to develop the NFT Marketplace Platform using the Flow blockchain platform and IPFS and what to consider when building it.
read moreTop IoT Development Companies 2021
Here are the top IoT development companies to explore in 2021 and IoT-enabled products that have been built by the top IoT companies.
read moreHow to create a safer workplace using IoT?
IoT-enabled solutions help protect workers’ well-being and ensure a safe work environment by providing real-time visibility, actionable insights and immediate alerts whenever needed.
read more