Індексація 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 та десятки успішних інтеграцій гарантують результат. Замовте консультацію — ми підготуємо індивідуальну пропозицію.