Soroswap SubQuery Indexer

A SubQuery indexer implementation for the Soroswap project on Stellar Soroban. SubQuery is a powerful and flexible open-source indexing framework that provides custom APIs for web3 projects, enabling efficient and structured data retrieval.

🚀 Features

• Indexes Soroswap-specific data on the Stellar Soroban network.
• Provides a GraphQL API for querying indexed data.
• Efficiently processes and stores blockchain data for easy access.
• Docker-based setup for streamlined deployment.

📌 Prerequisites

Ensure you have the following installed before setting up the project:

• Docker ``
• Node.js (Recommended: v18+)
• NPM
• Subql CLO npm i -g @subql/cli

⚙️ Setup and Configuration

1️⃣ Clone the Repository

sudo apt install git-all
git clone https://github.com/soroswap/subql.git
cd subql
cp .env.example .env
docker network create soroswap-network

2️⃣ Clean Previous Installation (If Necessary)

To ensure a clean setup, remove previous configurations:

npm run reset

3️⃣ Install Dependencies

npm install

4️⃣ Run Initial Scripts

Prepare the environment by executing:

npm run prestart

5️⃣ Start the Indexer

Launch the indexer in development mode:

npm run dev

Run this on a VM

# one-time install (Debian/Ubuntu)
sudo apt-get update && sudo apt-get install -y tmux

tmux new -s indexer          # start a new session
# …run whatever commands you like…
npm run reset
npm install
npm run prestart
npm run dev
Ctrl-b  d                      # detach (session keeps running)

#later
tmux attach -t indexer       # re-attach
tmux ls                        # list sessions

---

Extenral Ports.

This will run 3 docker containters called, subql-graphql-engine-1, subql-subquery-node-1 and postgres. The one you will pay attention are

• 7000 for the subql-graphql-engine
• 5432 for the postgres

If you are calling the indexer from a local docker container of the same network, you will need to use: GRAPHQL_INDEXER_MAINNET=http://graphql-engine:7000

6️⃣ Deploy to OnFinality

To deploy to OnFinality, you first need to get the Token from OnFinality. Once you have the token, add it to your .env file under SUBQL_ACCESS_TOKEN and run:

npm run build
npm run subql-publish

This will build and upload the project to IPFS and return a hash that will be used in OnFinality's deployment.

Important! Dont forget to enable unsafe flag!

🛠 Project Structure

The project consists of the following key files:

• schema.graphql: Defines the GraphQL data schema.
• project.ts: Contains project-specific configurations and mapping handlers.
• mapping.ts: Implements data transformation logic for indexing.

Project Configuration and Event Handlers

The project.ts file configures the events to be indexed and how they will be processed. We specifically track events that provide token reserve information across different protocols. Each protocol emits different events that we need to capture to maintain accurate pool data.

Protocol Event Handlers

Soroswap:

• Events: new_pair and sync
• Purpose: Track new pair creation and reserve updates
• References:
  • New Pair Topics
  • Sync Topics

AQUA:

• Events: add_pool, trade, withdraw, and deposit
• Purpose: Monitor pool creation and liquidity changes
• References:
  • Event Functions
  • Topics

COMET:

• Events: swap, deposit, withdraw, exit_pool, join_pool, and new_pool
• Purpose: Track pool activities and reserve changes
• References:
  • Event Functions
  • Topics

🗂 Pair Table Schema

The following entity schema is used to index liquidity pairs:

type SoroswapPair @entity {
  id: ID! # Contract address
  ledger: Int!
  date: Date!
  tokenA: String! @index
  tokenB: String! @index
  reserveA: BigInt!
  reserveB: BigInt!
}

type AquaPair @entity {
  id: ID! # User or Address
  ledger: Int! @index
  date: Date! @index
  address: String! @index
  tokenA: String! @index
  tokenB: String! @index
  poolType: String!
  reserveA: BigInt!
  reserveB: BigInt!
}

type phoenixPair @entity {
  id: ID! # Contract address
  ledger: Int!
  date: Date!
  tokenA: String! @index
  tokenB: String! @index
  reserveA: BigInt!
  reserveB: BigInt!
  reserveLp: BigInt
  stakeAddress: String
  totalFeeBps: Int
}

📡 Accessing the GraphQL API

Once the indexer is running, access the GraphQL Playground at:

http://localhost:7000

You can also access from: https://studio.apollographql.com/sandbox/explorer, with sandbox http://localhost:7000

🔍 Example Query

Retrieve the latest indexed pairs:

query GetPairsSoroswap {
  soroswapPairs(orderBy: DATE_DESC) {
    totalCount
    nodes {
      id
      tokenA
      tokenB
      reserveA
      reserveB
      ledger
      date
    }
  }
}
query GetPairsAqua {
  aquaPairs(orderBy: DATE_DESC) {
    totalCount
    nodes {
			id
      idx
      ledger
      date
      tokenA
      tokenB
      tokenC
      reserveA
      reserveB
      reserveC
      poolType
      fee
      futureA
      futureATime
      initialA
      initialATime
      precisionMulA
      precisionMulB
      precisionMulC
    }
  }
}
query GetPairsPhoenix{
  phoenixPairs (orderBy: DATE_DESC){
    totalCount
    nodes {
      id
      tokenA
      tokenB
      reserveA
      reserveB
      reserveLp
      stakeAddress
      totalFeeBps
      ledger
      date
    }
  }
}

📚 Resources

• 📖 SubQuery Documentation
• 💬 SubQuery Discord Support (Channel: #technical-support)
• 🔗 Soroswap Documentation

📄 License

This project is licensed under the MIT License. See LICENSE for details.