Solana Portal stream - SQD Documentation

@subsquid/solana-stream is the Portal-native Solana data source for Squid SDK. DataSourceBuilder.build() returns a source that you can pass to run() or Processor, or consume directly.

SolanaBatchProcessor, SolanaRpcClient, setGateway(), setRpc(), and setRpcEndpoint() are not part of @subsquid/[email protected]. Use setPortal().

Complete example

import {run, type FinalDatabase} from '@subsquid/batch-processor'
import {DataSourceBuilder, type FieldSelection} from '@subsquid/solana-stream'

const JUPITER = 'JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4'
const TEST_SLOT = 432_825_258

const fields = {
  block: {parentNumber: true, timestamp: true},
  instruction: {programId: true, accounts: true, data: true},
  transaction: {signatures: true, err: true, computeUnitsConsumed: true},
  log: {programId: true, kind: true, message: true},
} satisfies FieldSelection

const dataSource = new DataSourceBuilder()
  .setPortal('https://portal.sqd.dev/datasets/solana-mainnet')
  .setBlockRange({from: TEST_SLOT, to: TEST_SLOT})
  .setFields(fields)
  .addInstruction({
    where: {programId: [JUPITER]},
    include: {transaction: true, logs: true, innerInstructions: true},
  })
  .build()

let checkpoint = {
  height: TEST_SLOT - 1,
  hash: '4YqZcfbBdoADF7FDtmWFpGKwYmasi1mXzdqu7yeAE9dX',
}
const db: FinalDatabase<void> = {
  async connect() {
    return checkpoint
  },
  async transact({nextHead}, cb) {
    await cb(undefined)
    checkpoint = nextHead
  },
}

run(dataSource, db, async (ctx) => {
  for (const block of ctx.blocks) {
    console.log(block.header.number, block.instructions.length)
  }
})

The fixed range makes this a bounded example that exits after processing one slot. Its in-memory checkpoint is intentionally temporary; use a persistent Database implementation for an indexer that must resume after a restart. The batch context contains {store, blocks, isHead}. It does not inject ctx.log.

Builder methods

setPortal(portal) is required and accepts a URL, PortalClientOptions, or PortalClient. build() throws Portal settings not set when it is omitted. setBlockRange({from, to?}) applies a global range. Solana ranges use slot numbers, the same values returned as block.header.number. includeAllBlocks(range?) includes blocks without matching items. setFields(fields) has no default optional fields. The selector sections are block, transaction, instruction, log, balance, tokenBalance, and reward. addQuery(query) accepts a Query or QueryBuilder when several filters share one range. The builder also provides these shorthands:

Method	`where` filters	`include` relations
`addTransaction()`	`feePayer`	`instructions`, `logs`, `balances`, `tokenBalances`
`addInstruction()`	`programId`, `d1`, `d2`, `d3`, `d4`, `d8`, `discriminator`, `a0` through `a9`, `isCommitted`	`transaction`, `transactionBalances`, `transactionTokenBalances`, `transactionInstructions`, `logs`, `innerInstructions`
`addLog()`	`programId`, `kind`	`transaction`, `instruction`
`addBalance()`	`account`	`transaction`, `transactionInstructions`
`addTokenBalance()`	`account`, `preProgramId`, `postProgramId`, `preMint`, `postMint`, `preOwner`, `postOwner`	`transaction`, `transactionInstructions`
`addReward()`	`pubkey`	none

Instruction discriminators are 0x-prefixed hexadecimal byte prefixes. The d1, d2, d3, d4, and d8 filters require exactly that many bytes; discriminator accepts any prefix length.

`build()`

Returns the Solana data source. Pass it to run() or Processor for restart-safe processing. You can also call getHead(), getFinalizedHead(), getStream(), getFinalizedStream(), and the optional getBlocksCountInRange() helper directly. See Read a data source directly.

Block data

Each block has header, transactions, instructions, logs, balances, tokenBalances, and rewards. Required header fields are:

type BlockHeader = {
  number: number      // slot number
  hash: string
  parentHash: string
  parentNumber?: number
  timestamp?: number // Unix milliseconds when selected
}

slot and parentSlot are not field names. Use number and parentNumber.

@subsquid/[email protected] accepts height in the TypeScript field selection, but the Portal source does not return it. Use number for the Solana slot and for setBlockRange() values.

The stream converts Portal’s raw Solana block time from seconds to milliseconds. Pass timestamp directly to new Date(timestamp) without multiplying it by 1000. Balances use one account per item:

type Balance = {
  transactionIndex: number
  account: string
  pre?: bigint
  post?: bigint
}

Token balances can contain pre-state, post-state, or both. pre* fields describe the value before the transaction and post* fields describe it after the transaction.

Prometheus

Pass a PrometheusServer through the fourth run() argument:

import {PrometheusServer, run} from '@subsquid/batch-processor'

const prometheus = new PrometheusServer()
prometheus.setPort(3000)
run(dataSource, db, handler, {prometheus})

Without an explicit server, PROCESSOR_PROMETHEUS_PORT takes precedence over PROMETHEUS_PORT. Metrics are disabled if neither variable is set.

Solana typegen

@subsquid/solana-typegen accepts an Anchor IDL file, an HTTP(S) IDL URL, or a program address. For addresses it checks the chain and the SolanaFM registry.

npx squid-solana-typegen src/abi ./abi/program.json --clean
npx squid-solana-typegen src/abi https://example.com/program.json#program
npx squid-solana-typegen src/abi <PROGRAM_ADDRESS> --solana-rpc-endpoint https://api.mainnet-beta.solana.com

Generated modules include instruction and event definitions. @subsquid/solana-stream also exports getInstructionData() and getInstructionDescriptor() for working with generated instruction metadata.

​Complete example

​Builder methods

​build()

​Block data

​Prometheus

​Solana typegen

Complete example

Builder methods

`build()`

Block data

Prometheus

Solana typegen