Sidecar Query Server: Integrator Guide

Introduction

Sidecar Query Server (SQS) is an off-chain server tailored to performing expensive query tasks.

The high-level architecture is that the chain reads data at the end of the block, parses it, and then writes it into a Redis instance. There is no persistent storage. All data gets cleared and overwritten at the end of the block.

The sidecar query server then reads the parsed data from Redis and serves it to the client via HTTP endpoints.

The goal is to perform computationally and data-intensive tasks outside of nodes or clients. For example, swap routing falls under this category because it requires all pool data for performing a complex routing algorithm.

Osmosis Swap Router

Indeed, swap router is the main functionality currently present in SQS.

Find the available endpoints below:

1. GET /router/quote?tokenIn=<tokenIn>&tokenOutDenom=<tokenOutDenom>

Description: returns the best quote it can compute for the given tokenIn and tokenOutDenom

Parameters:

• tokenIn the string representation of the sdk.Coin for the token in
• tokenOutDenom the string representing the denom of the token out

Additionally, there is an endpoint for retrieving all pools instrumented with TVL data:

2. GET /pools

Description: returns all pools in the chain state instrumented with denoms and TVL if available

Parameters: IDs - list of specific pool IDs to retrieve.

Disclaimer

The swap router component is in an early stage. In some instances, competing implementations may provide more optimal quotes. We are still perfecting the quote quality and will announce stability in the subsequent releases.

Public APIs

For power clients, we recommend running an in-house infrastructure of SQS. Our public endpoints are designed to handle only the Osmosis frontend traffic. However, you can find the public APIs below for simple integrations:

Production: https://sqs.osmosis.zone

• Stable. Manually deployed by the Osmosis team.

This is a geo-distributed deployment across 3 regions that is used by the production application https://app.osmosis.zone.

It operates on data from osmosis-1 mainnet.

Staging: https://sqs.stage.osmosis.zone

• Not stable. Manually deployed by the Osmosis team.

This is a deployment that is used by our stage app https://stage.osmosis.zone/. It is less stable and may experience downtime due to experimental features.

It operates on data from osmosis-1 mainnet.

Testnet: https://sqs.testnet.osmosis.zone

This is a testnet deployment made against osmo-test-5 testnet state.

This environment exposes all endpoints listed below.

Running Your SQS

Running your own SQS requires a mainnet node for data ingest at
the end of every block. In the future, we will separate the two
into separate binaries. Currently, SQS is enabled via
config when running a chain node.

To begin the process:

1. Install Docker

   • Will be needed for the Redis service.

2. Sync a mainnet node on the current mainnet Osmosis release (ref)

   • Stop once synched

3. Enable SQS ingest in app.toml

[osmosis-sqs]

# SQS service is disabled by default.
is-enabled = "true"

# The hostname and address of the sidecar query server storage.
db-host = "localhost"
db-port = "6379"

2. Run all services

# From root of https://github.com/osmosis-labs/sqs
#
# Runs osmosisd binary, redis and SQS web server
make all-start

Suggested Web Server Configuration Parameters

The router has several configuration parameters that are set via app.toml.

See the recommended enabled configuration below:

{
    "debug": false,
    // Redis host.
    "db-host": "localhost",
    // Redis port.
    "db-port": "6379",
    // Web server port.
    "server-address": ":9092",
    // Endpoint timeout duration.
    "timeout-duration-secs": 2,
    // Log file to write to.
    "logger-filename": "sqs.log",
    // Flag indicating whether this is a production logger.
    "logger-is-production": true,
    // Log level
    "logger-level": "info",
    // RPC endpoint
    "grpc-gateway-endpoint": "http://localhost:26657",
    // Chain ID
    "chain-id": "osmosis-1",
    // Router-specific configuration
    "router": {
      // Pool IDs that are prioritized in the router.
      "preferred-pool-ids": [],
      // Maximum number of pools in one route.
      "max-pools-per-route": 4,
      // Maximum number of routes to search for.
      "max-routes": 20,
      // Maximum number of routes to split across.
      "max-split-routes": 3,
      // Maximum number of iterations to split a route across.
      "max-split-iterations": 10,
      // Minimum liquidity for a pool to be included in the router
      // denominated in OSMO.
      "min-osmo-liquidity": 100,
      // Whether to enable route caching
      "route-cache-enabled": true,
      // How long the route is cached for before expiry in seconds.
      "route-cache-expiry-seconds": 600
    },
    "pools": {
        // Code IDs of Transmuter CosmWasm pools that
        // are supported
        "transmuter-code-ids": [148, 254],
        // Code IDs of generalized CosmWasm pools that
        // are suported. Note that these pools make network
        // requests to chain for quote estimation. As a result,
        // they are excluded from split routes.
        "general-cosmwasm-code-ids": []
    },
    // Whether to enable routes cache overwrite. An overwrite can be set via
    // the following endpoint: POST `/router/overwrite-route`
    "enable-overwrite-routes-cache": false
}

Sources

• Chain Ingest
• SQS Web Server
• Router Component