Indexing with SQD

SOON integrates with SQD to provide powerful data indexing capabilities. This guide will walk you through using SQD’s Solana API to index and query data from SOON’s networks.

Available Networks

SOON’s data is accessible through these Subsquid archives:

const NETWORKS = {
  testnet: 'https://v2.archive.subsquid.io/network/soon-testnet',
  devnet: 'https://v2.archive.subsquid.io/network/soon-devnet'
  mainnet: 'https://v2.archive.subsquid.io/network/soon-mainnet'
}

Understanding SQD Architecture

SQD uses a distributed worker system to efficiently serve blockchain data. Each worker handles a specific range of blocks, and queries are routed to appropriate workers through a central gateway.

Core Concepts

Router: The main entry point that directs queries to specific workers
Workers: Distributed nodes that store and serve blockchain data
Block Ranges: Each worker handles a specific range of blocks
Archive Height: The latest block available in the archive

Query Flow

1. Check Archive Height

First, verify the current height of the archive:

async function getArchiveHeight() {
  const response = await fetch(
    'https://v2.archive.subsquid.io/network/soon-testnet/height'
  )
  const height = await response.text()
  return parseInt(height)
  // Returns: 366804 (example)
}

2. Get Worker Assignment

Request a worker URL for your desired block range:

async function getWorker(blockNumber: number) {
  const response = await fetch(
    `https://v2.archive.subsquid.io/network/soon-testnet/${blockNumber}/worker`
  )
  const workerUrl = await response.text()
  // Returns: https://lm07.sqd-archive.net/worker/query/czM6Ly9zb29uLXRlc3RuZXQtMQ
  return workerUrl
}

3. Query Data

Make your data request to the assigned worker:

async function queryData(workerUrl: string, fromBlock: number) {
  const response = await fetch(workerUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
    body: JSON.stringify({
      type: "solana",
      fromBlock: fromBlock,
      fields: {
        instruction: {
          programId: true,
          data: true
        }
      },
      instructions: [
        { isCommitted: true }
      ]
    })
  })
  
  const data = await response.json()
  return data
}

Example Response:

[
  {
    "header": {
      "number": 366800,
      "hash": "11111111111111111111111111111111"
    },
    "instructions": [
      {
        "transactionIndex": 0,
        "instructionAddress": [0],
        "programId": "L1BLockinfo11111111111111111111111111111111",
        "data": "2JyQzTaqty3gKAuyyDEir3yZird2V55..."
      }
    ]
  }
]

Additional Resources

For more advanced SQD features, configurations, and detailed API references, check out the SQD documentation. The official docs cover topics like:

Advanced query patterns and optimizations
Custom data transformations
Real-time subscriptions and webhooks
Performance tuning and monitoring
Integration with popular frameworks

Query Options

Instruction Queries

Filter and fetch specific instruction data:

const instructionQuery = {
  type: "solana",
  fromBlock: startBlock,
  fields: {
    instruction: {
      programId: true,
      data: true,
      accounts: true  // Include account information
    }
  },
  instructions: [
    {
      programId: ["YourProgramID"],  // Filter by program
      isCommitted: true
    }
  ]
}

Transaction Queries

Get full transaction details:

const transactionQuery = {
  type: "solana",
  fromBlock: startBlock,
  fields: {
    transaction: {
      feePayer: true,
      instructions: true,
      logs: true
    }
  },
  transactions: [
    {
      feePayer: ["SpecificFeePayer"]  // Optional filter
    }
  ]
}

Log Queries

Fetch program logs:

const logQuery = {
  type: "solana",
  fromBlock: startBlock,
  fields: {
    log: {
      programId: true,
      message: true
    }
  },
  logs: [
    {
      kind: ["log", "data"],  // Filter by log type
      programId: ["YourProgramID"]  // Filter by program
    }
  ]
}

Best Practices

Handling Pagination

For large datasets, implement pagination:

async function fetchAllData(startBlock: number, endBlock: number) {
  let currentBlock = startBlock
  const results = []
  
  while (currentBlock <= endBlock) {
    const workerUrl = await getWorker(currentBlock)
    const data = await queryData(workerUrl, currentBlock)
    
    results.push(...data)
    
    // Update current block to last received block + 1
    const lastBlock = data[data.length - 1].header.number
    currentBlock = lastBlock + 1
  }
  
  return results
}

Error Handling

Implement robust error handling:

async function fetchWithRetry(workerUrl: string, query: any, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await queryData(workerUrl, query)
      return response
    } catch (error) {
      if (i === retries - 1) throw error
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)))
    }
  }
}

Common Use Cases

Track Program Interactions

Monitor specific program activities:

const programQuery = {
  type: "solana",
  fromBlock: startBlock,
  fields: {
    instruction: {
      programId: true,
      data: true,
      accounts: true
    },
    transaction: {
      logs: true
    }
  },
  instructions: [
    {
      programId: ["YourProgramID"],
      isCommitted: true
    }
  ]
}

Monitor Account Activity

Track account changes and interactions:

const accountQuery = {
  type: "solana",
  fromBlock: startBlock,
  fields: {
    tokenBalance: {
      account: true,
      amount: true,
      owner: true
    }
  },
  tokenBalances: [
    {
      account: ["AccountToTrack"]
    }
  ]
}

Rate Limits and Performance

Keep block ranges reasonable (suggested: ≤1000 blocks per query)
Cache worker URLs when querying consecutive blocks
Implement exponential backoff for retries
Consider using webhooks for real-time updates

TypeScript Support

SQD provides TypeScript typings for better developer experience:

interface SQDQuery {
  type: 'solana'
  fromBlock: number
  fields: {
    instruction?: InstructionFields
    transaction?: TransactionFields
    log?: LogFields
  }
  instructions?: InstructionFilter[]
  transactions?: TransactionFilter[]
  logs?: LogFilter[]
}

// Use with your API calls
const query: SQDQuery = {
  type: 'solana',
  fromBlock: 366800,
  fields: {
    instruction: {
      programId: true,
      data: true
    }
  }
}

Using SOON

Building on SOON

SOON Node

Metaplex

Available Networks

Understanding SQD Architecture

Core Concepts

Query Flow

1. Check Archive Height

2. Get Worker Assignment

3. Query Data

Additional Resources

Query Options

Instruction Queries

Transaction Queries

Log Queries

Best Practices

Error Handling

Common Use Cases

Track Program Interactions

Monitor Account Activity

Rate Limits and Performance

TypeScript Support

​Available Networks

​Understanding SQD Architecture

​Core Concepts

​Query Flow

​1. Check Archive Height

​2. Get Worker Assignment

​3. Query Data

​Additional Resources

​Query Options

​Instruction Queries

​Transaction Queries

​Log Queries

​Best Practices

​Handling Pagination

​Error Handling

​Common Use Cases

​Track Program Interactions

​Monitor Account Activity

​Rate Limits and Performance

​TypeScript Support

Available Networks

Understanding SQD Architecture

Core Concepts

Query Flow

1. Check Archive Height

2. Get Worker Assignment

3. Query Data

Additional Resources

Query Options

Instruction Queries

Transaction Queries

Log Queries

Best Practices

Handling Pagination

Error Handling

Common Use Cases

Track Program Interactions

Monitor Account Activity

Rate Limits and Performance

TypeScript Support