Индексация блокчейна с The Graph: проектирование subgraph и оптимизация

Мы часто сталкиваемся с ситуацией, когда фронтенд делает десятки eth_call и getLogs при каждой загрузке страницы. На mainnet это занимает 2–3 секунды, на публичных RPC — ненадёжно, а когда нужна агрегация или исторические данные — просто невозможно через прямые вызовы. The Graph решает эту проблему правильно: один раз пишется subgraph, который индексирует события контракта, и получается GraphQL API с произвольными запросами за миллисекунды. Экономия на инфраструктуре может достигать 90% (до $2000 в месяц для типового DeFi-проекта), а скорость запросов возрастает в десятки раз. Ниже разберём, как спроектировать и написать subgraph, чтобы избежать типичных ошибок и получить максимум производительности.

Как спроектировать схему subgraph?

Subgraph состоит из трёх компонентов, и критически важно спроектировать схему под запросы фронтенда, а не под структуру событий.

• subgraph.yaml — манифест. Описывает источники данных: какие контракты слушать, с какого блока (startBlock), какие события и функции обрабатывать. Критически важно: startBlock должен быть блоком деплоя контракта, а не нулём — иначе индексация займёт дни.
• schema.graphql — типы сущностей. Это то, что будет доступно через GraphQL. Проектируется исходя из потребностей фронтенда, а не из структуры событий контракта — это разные вещи.
• mappings.ts — AssemblyScript обработчики. Трансформируют сырые события в сущности схемы.

Проектирование схемы

Самая частая ошибка — делать схему зеркалом событий контракта. Если событие Transfer(address from, address to, uint256 amount) — не нужна сущность TransferEvent. Нужно думать о запросах: «какой текущий баланс пользователя», «топ холдеров», «объём за 24 часа».

type Token @entity { id: ID! totalSupply: BigInt! holderCount: Int! } type Account @entity { id: Bytes! balance: BigInt! transfersIn: [Transfer!]! @derivedFrom(field: "to") transfersOut: [Transfer!]! @derivedFrom(field: "from") } type Transfer @entity(immutable: true) { id: Bytes! from: Account! to: Account! amount: BigInt! blockNumber: BigInt! timestamp: BigInt! } 

@entity(immutable: true) для Transfer — важная оптимизация. Immutable сущности не хранятся в undo-буфере, индексация быстрее на 30–40%.

Обработчики: шаги создания

В AssemblyScript нет полноценного TypeScript — нет null через ?., нет Array.from(), нет стандартных JS методов. Это частый источник ошибок для разработчиков, пришедших с фронтенда.

1. Определите событие, которое обрабатываете (например, Transfer).
2. Загрузите или создайте сущность с помощью Account.load(address) или new Account(address).
3. Обновите поля (баланс, ссылки).
4. Сохраните изменения через save().

// Правильная загрузка или создание сущности function getOrCreateAccount(address: Address): Account { let account = Account.load(address) if (account == null) { account = new Account(address) account.balance = BigInt.fromI32(0) } return account as Account } export function handleTransfer(event: TransferEvent): void { let from = getOrCreateAccount(event.params.from) let to = getOrCreateAccount(event.params.to) from.balance = from.balance.minus(event.params.value) to.balance = to.balance.plus(event.params.value) from.save() to.save() // Immutable — создаём один раз, не загружаем let transfer = new Transfer( event.transaction.hash.concatI32(event.logIndex.toI32()) ) transfer.from = from.id transfer.to = to.id transfer.amount = event.params.value transfer.blockNumber = event.block.number transfer.timestamp = event.block.timestamp transfer.save() } 

Call handlers и block handlers

Помимо событий, The Graph умеет обрабатывать вызовы функций (callHandlers) и каждый блок (blockHandlers). Call handlers нужны когда контракт не эмитит события для нужных операций — legacy контракты грешат этим. Block handlers — для периодических снапшотов (например, дневная статистика). Оба типа значительно замедляют индексацию, особенно block handlers — используйте только если без них не обойтись.

Почему The Graph быстрее прямых вызовов RPC?

Прямые вызовы RPC выполняются последовательно и загружают ноду. The Graph индексирует данные один раз и хранит их в оптимизированной базе, доступной через GraphQL. Запросы выполняются за миллисекунды (типичное время от 50 до 200 мс), а пагинация через first/skip работает до skip: 5000 — для больших датасетов используйте keyset pagination через id_gt. По данным документации The Graph, пропускная способность индексации может достигать 1000 событий в секунду на стандартном оборудовании. Экономия на инфраструктуре может достигать 90%, что подтверждается опытом крупных DeFi-проектов — например, Uniswap сократил затраты на RPC на $3000+ в месяц после перехода на subgraph.

Какой хостинг выбрать: Hosted Service, Decentralized или self-hosted?

Выбор варианта развёртывания subgraph зависит от требований к доступности, контролю и бюджету.

Наша команда с десятилетним опытом в блокчейне реализовала более 20 интеграций The Graph. Мы помогаем выбрать оптимальный вариант под ваш проект и избежать типичных проблем.

Типичные проблемы индексации

• Subgraph fails с "store error" — проверьте non-nullable поля.
• Индексация зависает на блоке — добавьте обработку реверсированных транзакций через receipt.status.
• Расхождение данных из-за reorgs — установите minEthereumBlockConfirmations.
• Чрезмерное потребление газа при записи — используйте @entity(immutable: true) для неизменяемых данных.

Что нужно знать о пагинации и фильтрации?

Keyset pagination предпочтительна для больших наборов данных — она быстрее и не имеет ограничения по skip.

Интеграция на фронтенде

Стандартный стек: Apollo Client или urql для React приложений. The Graph поддерживает subscriptions через WebSocket — для realtime обновлений без поллинга.

const POSITIONS_QUERY = gql` query UserPositions($account: Bytes!, $skip: Int!) { positions( where: { owner: $account, liquidity_gt: "0" } orderBy: createdAt orderDirection: desc first: 100 skip: $skip ) { id pool { token0 { symbol } token1 { symbol } feeTier } liquidity depositedToken0 depositedToken1 } } ` 

Сроки и что входит в работу

За 2–5 дней: проектирование схемы под задачи клиента, написание mappings для всех событий и calls, тестирование на форке, деплой на Hosted Service или настройка self-hosted ноды, базовая интеграция в существующий фронтенд или предоставление GraphQL endpoint. Стоимость рассчитывается индивидуально, но экономия на RPC-запросах оправдывает инвестиции — типичная окупаемость наступает в течение 1-3 месяцев.

Свяжитесь с нами, чтобы обсудить интеграцию The Graph в ваш проект. Опыт работы с The Graph и десятки успешных интеграций гарантируют результат. Закажите консультацию — мы подготовим индивидуальное предложение.