# 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

2. GET `/router/single-quote?tokenIn=<tokenIn>&tokenOutDenom=<tokenOutDenom>`

Description: returns the best quote it can compute w/o performing route splits,
performing single direct route estimates only.

Parameters:
- `tokenIn` the string representation of the sdk.Coin for the token in
- `tokenOutDenom` the string representing the denom of the token out

3. GET `/router/routes?tokenIn=<tokenIn>&tokenOutDenom=<tokenOutDenom>`

Description: returns all routes that can be used for routing from tokenIn to tokenOutDenom

Parameters:
- `tokenIn` the string representation of the denom of the token in
- `tokenOutDenom` the string representing the denom of the token out

4. GET `/router/custom-quote?tokenIn=<tokenIn>&tokenOutDenom=<tokenOutDenom>&poolIDs=<poolIDs>`

Description: returns the quote over route with the given poolIDs. If such route does not exist, returns error.

Parameters:
- `tokenIn` the string representation of the sdk.Coin for the token in
- `tokenOutDenom` the string representing the denom of the token out
- `poolIDs` comma-separated list of pool IDs

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

1. GET `/pools/all`

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

Parameters: none

### 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.
Staging: `https://sqs-stage.osmosis.zone`
- Automatically deployed from the release branch. For example, if the current Osmosis release like is v20, then the deployment branch is `v20.x`

## 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. Sync a mainnet node ([ref](https://docs.osmosis.zone/overview/validate/joining-mainnet))
2. Get on the current mainnet Osmosis release branch.
3. Start Redis
4. Rebuild the binary and start it

git checkout v20.x

# Starts a detached redis container, to stop: 'make redis-stop'
make redis-start

# Rebuild the binary and start the node with sqs enabled in-process
make sqs-start

### Suggested Configuration Parameters

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

See the recommended enabled configuration below:

###############################################################################
###              Osmosis Sidecar Query Server Configuration                 ###
###############################################################################

[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"

# Defines the web server configuration.
server-address = ":9092"
timeout-duration-secs = "2"

# Defines the logger configuration.
logger-filename = "sqs.log"
logger-is-production = "true"
logger-level = "info"

# Defines the gRPC gateway endpoint of the chain.
grpc-gateway-endpoint = "http://localhost:26657"

# The list of preferred poold IDs in the router.
# These pools will be prioritized in the candidate route selection, ignoring all other
# heuristics such as TVL.
preferred-pool-ids = []

# The maximum number of pools to be included in a single route.
max-pools-per-route = "4"

# The maximum number of routes to be returned in candidate route search.
max-routes = "20"

# The maximum number of routes to be split across. Must be smaller than or
# equal to max-routes.
max-split-routes = "3"

# The maximum number of iterations to split a route across.
max-split-iterations = "10"

# The minimum liquidity of a pool to be included in a route.
min-osmo-liquidity = "10000"

# The height interval at which the candidate routes are recomputed and updated in
# Redis
route-update-height-interval = "0"

# Whether to enable candidate route caching in Redis.
route-cache-enabled = "true"

## Sources

- [Chain Ingest](https://github.com/osmosis-labs/osmosis/tree/main/ingest)
- [SQS Web Server](https://github.com/osmosis-labs/osmosis/tree/main/ingest/sqs)
- [Router Component](https://github.com/osmosis-labs/osmosis/tree/main/ingest/sqs/router)