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 log in. 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: { 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.