Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Troubleshooting — Subgraph indexing lag · Boson Protocol
Skip to content

Subgraph indexing lag

Symptom

You just performed a write (commit, redeem, create offer, …), then immediately read state from the SDK or MCP, and got stale data — your new exchange isn't there, your new offer doesn't show up, etc.

Cause

The Boson subgraph (a Graph Protocol deployment) processes on-chain events asynchronously. It typically lags 1–3 blocks behind the chain head — sometimes more under load.

When you call sdk.getOffers(), mcp.getExchanges(), or any SDK / MCP read method that hits the subgraph, you're querying its current view — not the chain head.

Fix

After every write, call:

const tx = await sdk.commitToOffer(buyer, offerId)
const receipt = await tx.wait()
await sdk.waitForGraphNodeIndexing(receipt.blockNumber)
// safe to read now

waitForGraphNodeIndexing(blockNumber) polls the subgraph's _meta { block { number } } until it catches up to your tx's block, or until the timeout (default ~30 s).

For agents

Make this a mandatory step in your loop. See Build for AI agents → Idempotency & retry.

Alternative: read from RPC

If you need real-time state (e.g. "is the offer sold out?"), read directly from the Diamond:

// Build the Diamond contract yourself — there's no sdk.getDiamondContract() helper.
import { getConfigFromConfigId } from "@bosonprotocol/common"
import offerAbi from "@bosonprotocol/common/dist/cjs/abis/IBosonOfferHandler.json"
import { ethers } from "ethers"
 
const config = getConfigFromConfigId(CONFIG_ID)
const diamond = new ethers.Contract(config.contracts.protocolDiamond, offerAbi, provider)
const remaining = await diamond.getAvailableQuantity(offerId)

RPC reads are zero-lag but have lower throughput and no convenience joins.

When the lag persists

If waitForGraphNodeIndexing times out, the subgraph is genuinely behind. Check its health:

{ _meta { block { number } hasIndexingErrors } }

If hasIndexingErrors == true, report it in Boson Discord.

Related