IQ Gateway

A read-only HTTP cache for IQ Labs on-chain data. Fetches from the blockchain and serves it over HTTP with multi-tier caching. Anyone can run their own gateway.

One codebase, every chain. By default one process serves Solana plus every configured EVM network at once, with the chain picked per request. IQ_CHAIN locks a process to a single chain when you want fault isolation:

• unset or multi (default): Solana + all EVM networks in one process. The resolver picks the chain per request from the id shape (base58 vs 0x) or an explicit ?network= query param.
• IQ_CHAIN=solana: Solana only (devnet / mainnet-beta / testnet) via solana-sdk
• IQ_CHAIN=evm: one EVM network via ethereum-sdk

Cache, RPC queue, ETag/304, SSE, and the server shell are shared. See Architecture and Chains.

• No single point of failure - if one gateway goes down, spin up another
• Your own cache - faster for your users, your region
• Data is always recoverable - everything lives on-chain, any gateway can serve it
• No vendor lock-in - switch gateways anytime, same data

git clone https://github.com/IQCoreTeam/iq-gateway.git
cd iq-gateway
bun install
cp .env.example .env

Solana (.env):

IQ_CHAIN=solana
SOLANA_CLUSTER=mainnet-beta
SOLANA_RPC_ENDPOINT=https://api.mainnet-beta.solana.com
PORT=3000

Multi-chain (default; .env):

SOLANA_CLUSTER=mainnet-beta
SOLANA_RPC_ENDPOINT=https://api.mainnet-beta.solana.com
# optional per-network EVM RPC overrides; built-in defaults are used otherwise
# IQETH_RPC_MONAD=...
# IQETH_RPC_ROBINHOOD=...
PORT=3000

Locked EVM (.env):

IQ_CHAIN=evm
IQETH_NETWORK=sepolia                       # sepolia | monad | monadTestnet | robinhood
IQETH_RPC_ENDPOINT=https://rpc.sepolia.org
PORT=3000

Run:

bun run dev

That's it. Your gateway is live at http://localhost:3000.

In the default multi mode the chain is resolved per request:

1. ?network= wins (solana, sepolia, monad, monadTestnet, robinhood). An unknown value returns 400 with the valid list, never a silent wrong chain.
2. Otherwise the id shape decides: base58 32/64-byte ids route to Solana, everything else (a 0x hash/address or an arbitrary dbRootId string) routes to the default EVM network (IQETH_DEFAULT_NETWORK, default sepolia).
3. Id-less routes (/health, /dbroots, /table/dbroot, ...) default to Solana unless ?network= says otherwise.

Setting IQ_CHAIN locks a process to one chain instead (fault isolation; the network within it comes from SOLANA_CLUSTER or IQETH_NETWORK).

EVM networks:

Shared

Solana (IQ_CHAIN=solana)

EVM

Paths below use Solana identifiers ({sig}, {pda}). On IQ_CHAIN=evm the shapes change: {sig} → {txHash} (0x…), and {pda} → {dbRootId}/{tableName}. Two routes are Solana-only (Site Hosting, SNS); one is EVM-only (ENS). Everything else exists on both chains. The live /openapi.json and /docs always reflect the active chain.

Durable EVM row index. EVM has no getSignaturesForAddress, so enumerating a table normally means a strictly sequential walk of beforeDataTx pointers (one RPC round-trip per row, redone on cold cache). The gateway keeps a durable SQLite index of every row-write tx per (network, dbroot, table), fed by live reads, /notify, and a background eth_getLogs(DbCodeInEvent) backfill that scans the contract's indexed topics. Once a table is fully backfilled, deep before pagination and /index are answered from SQLite in one query, and the index also lists rows the pointer walk cannot reach (tails orphaned by the two-tx writeRow race). Unlike the LRU blob cache this index is never pruned. Operators can inspect or force a backfill via GET/POST /admin/evm-index (requires ADMIN_TOKEN).

EVM only (IQ_CHAIN=evm). Replaces the Solana SNS routes. Uses a dedicated mainnet RPC (ENS_RPC_ENDPOINT), cached 30 min.

Solana only. No EVM equivalent in v1 (no on-chain manifest convention established for the EVM SDK yet).

Supports both Iqoogle and gateway manifest formats. SPA fallback for unknown paths. Root-relative asset requests (e.g. /logo.webp) are resolved against the active manifest.

Deploy a site:

bun run scripts/deploy-site.ts ./my-site ./keypair.json

Three-tier cache with different TTLs:

The cache layer is chain-agnostic — the same SQLite store, LRU, and dedup serve both chains. In multi mode every cache key, disk path, and SQLite row carries a network dimension, so one CACHE_DIR safely serves all networks in one process. If you run several locked single-chain instances instead, give each its own CACHE_DIR volume.

Two things in cache.db are durable and never LRU-pruned: the FTS5 search catalog (catalog_fts) and the EVM row index (evm_row_index + evm_index_state). Both are derived from chain truth and rebuildable, but keeping them beats re-walking transaction chains.

Rows head pages use the table account's lastTimestamp as a cheap change gate. If the timestamp is unchanged, the gateway can keep serving the cached head page; if it changed, the background refresh catches up new signatures and stamps the fresh timestamp once the indexed signature list overlaps the cache.

Individual rows are cached for 24 hours (on-chain data is immutable). Head page responses are cached for 60 seconds with throttled background refresh.

With a paid Helius plan (HELIUS_API_KEY), the gateway automatically uses:

• gTFA (getTransactionsForAddress) — 100 full transactions per call, ~100x faster reads for session files
• Batch JSON-RPC — multiple getTransaction calls in one POST for table row reads
• Backfill — pre-cache all historical IQ Labs transactions on startup (set BACKFILL_FROM_SLOT)

Without Helius, everything still works using standard Solana RPC — just slower for large files.

The gateway ships as a chain-agnostic container (see the repo Dockerfile). How you run it — bare VPS, docker compose, Kubernetes, Akash, anything — is up to your infra. The gateway only asks for the following contract:

Minimal local run:

docker build -t iq-gateway .
docker run -d -p 3000:3000 -v iq-cache:/app/cache --env-file .env --restart unless-stopped iq-gateway

That's the whole contract — port, env, a persistent CACHE_DIR, and a proxy in front. Everything else is your platform's concern, not the gateway's.

Public read-only snapshot of the gateway's disk cache so a cold peer can bootstrap from a hot one without re-fetching every entry from Solana. The snapshot streams tar -czf - directly — first byte arrives quickly even for large caches, and Cloudflare's 100s edge timeout doesn't bite.

# warm a cold gateway from a peer's hot cache
./scripts/bootstrap-cache-from-peer.sh https://gateway.iqlabs.dev ./cache
# then start (or restart) your gateway

curl -sS https://peer-gateway/cache/snapshot | tar -xz -C ./cache

The gateway is read-only by design — no POST /cache/restore or /sync-from-peer. Operators write to their own cache directory directly (filesystem op on their own host); they don't write across the network.

The explorer endpoints are intentionally paginated/read-only so a separate site can browse cache contents without asking the gateway to dump a multi-GB cache as one JSON response. Responses use opaque entry ids and never expose the local cache filesystem path. Disk previews are byte-bounded; memory value previews are smaller and process-local because memory cache is only the current gateway process state.

The gateway is a read-only cache layer. It never writes to chain. All data is public and recoverable from chain, so multiple gateways serve the same data independently.

The only real divergence between chains lives in src/chain/. A ChainReader interface (src/chain/types.ts) is the seam; two adapters implement it:

src/chain/
  types.ts     # ChainReader interface (the shared intersection)
  solana/      # web3.js + Helius + SNS    → implements ChainReader
  evm/         # ethers + Alchemy + ENS    → implements ChainReader
  index.ts     # picks ONE adapter by IQ_CHAIN, re-exports its surface
src/routes/
  *.ts         # Solana route set
  evm/         # EVM route set (per-request wrapper via ctx)
src/cache/     # shared store/LRU/dedup; catalog + durable EVM row index
src/resolver.ts # per-request chain/network resolution (multi mode)
src/server.ts  # boots multi (default) or one locked chain by IQ_CHAIN

Importing the inactive adapter is side-effect-free (no top-level RPC or env throw); EVM defers its provider/network wiring into initEvm(), called from initChain() only when IQ_CHAIN=evm.

Solana only. On IQ_CHAIN=evm these routes are not mounted — EVM uses ENS instead.

The gateway resolves Solana Name Service (SNS) domains to on-chain IQ manifests at request time. One URL record on a .sol domain powers three browser surfaces — no server-side coordination required.

On your .sol domain via sns.id, set:

Record.URL = https://gateway.iqlabs.dev/site/<your-sig>/<your-index-file>

Per the SNS web-resolution spec, the URL record is the canonical "this is my website" pointer. Brave's native .sol resolver and sol-domain.org check it first.

$ curl -L https://gateway.iqlabs.dev/sns/<your-name>/record
# → 302 → /site/<sig>/<your-index-file> → on-chain content

The resolver accepts the domain bare (/sns/nubs/record) or with the .sol / .sol.site suffix.

For the prettier <name>.sol.site URL, also set a CNAME via the "Configure Sol.site" UI on sns.id:

Record.CNAME = sns.iqlabs.dev

sns.iqlabs.dev is a direct A record to the gateway origin (no Cloudflare proxy). Sol.site materialises the CNAME as DNS → traffic reaches the gateway → host middleware reads the URL record → manifest served.

The URL record can be:

• A full URL: https://gateway.iqlabs.dev/site/<sig>/<file> (recommended — works for Brave AND our gateway)
• A bare 86–90 char Solana tx signature (works for our gateway only)

The resolver also reads Record.TXT as a fallback.

Lookups are cached 5 minutes (memory + disk, both positive and negative). Concurrent cold-cache requests for the same domain are deduplicated so only one Solana RPC call fires.