Ончейн-дані у продакшені: про що вам ніхто не розповість

Блокчейн-дані не є чистими, надійними чи простими. Ліміти RPC, реорганізації ланцюга, баги BigInt та компроміси індексації — важкі уроки зі створення реальних DeFi продуктів.

Існує така фантазія, що ончейн-дані за своєю природою заслуговують довіри. Незмінний леджер. Прозорий стан. Просто прочитай — і все готово.

Я теж у це вірив. А потім випустив DeFi дашборд у продакшен і три тижні з'ясовував, чому баланси токенів були неправильними, в історії подій були прогалини, а в базі даних містилися транзакції з блоків, які більше не існували.

Ончейн-дані — сирі, ворожі і повні крайніх випадків, які зламають ваш додаток так, що ви не помітите, поки користувач не подасть баг-репорт. Цей пост охоплює все, чого я навчився на власних помилках.

Ілюзія надійних даних#

Ось перше, чого вам ніхто не скаже: блокчейн не дає вам дані. Він дає вам переходи стану. Немає ніякого SELECT * FROM transfers WHERE user = '0x...'. Є логи, квитанції, слоти зберігання та трейси викликів — все закодоване у форматах, які потребують контексту для декодування.

typescript

import { createPublicClient, fallback, http } from "viem";
import { mainnet } from "viem/chains";
 
const client = createPublicClient({
  chain: mainnet,
  transport: fallback(
    [
      http("https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY", {
        retryCount: 3,
        retryDelay: 1500,
        timeout: 15_000,
      }),
      http("https://mainnet.infura.io/v3/YOUR_KEY", {
        retryCount: 3,
        retryDelay: 1500,
        timeout: 15_000,
      }),
      http("https://rpc.ankr.com/eth", {
        retryCount: 2,
        retryDelay: 2000,
        timeout: 20_000,
      }),
    ],
    { rank: true },
  ),
});

typescript

interface IndexedBlock {
  number: bigint;
  hash: `0x${string}`;
  parentHash: `0x${string}`;
}
 
async function detectReorg(
  client: PublicClient,
  lastIndexed: IndexedBlock,
): Promise<{ reorged: boolean; depth: number }> {
  const currentBlock = await client.getBlock({
    blockNumber: lastIndexed.number,
  });
 
  if (currentBlock.hash === lastIndexed.hash) {
    return { reorged: false, depth: 0 };
  }
 
  // Йдемо назад, щоб знайти, де ланцюг розійшовся
  let depth = 1;
  let checkNumber = lastIndexed.number - 1n;
 
  while (checkNumber > 0n && depth < 128) {
    const onChain = await client.getBlock({ blockNumber: checkNumber });
    const inDb = await getIndexedBlock(checkNumber); // ваш запит до БД
 
    if (onChain.hash === inDb?.hash) {
      return { reorged: true, depth };
    }
 
    depth++;
    checkNumber--;
  }
 
  return { reorged: true, depth };
}

typescript

import type { PublicClient, Log, AbiEvent } from "viem";
 
async function fetchLogsInChunks<T extends AbiEvent>(
  client: PublicClient,
  params: {
    address: `0x${string}`;
    event: T;
    fromBlock: bigint;
    toBlock: bigint;
    maxBlockRange?: bigint;
  },
): Promise<Log<bigint, number, false, T, true>[]> {
  const { address, event, fromBlock, toBlock, maxBlockRange = 2000n } = params;
  const allLogs: Log<bigint, number, false, T, true>[] = [];
 
  let currentFrom = fromBlock;
 
  while (currentFrom <= toBlock) {
    const currentTo = currentFrom + maxBlockRange - 1n > toBlock ? toBlock : currentFrom + maxBlockRange - 1n;
 
    try {
      const logs = await client.getLogs({
        address,
        event,
        fromBlock: currentFrom,
        toBlock: currentTo,
      });
 
      allLogs.push(...logs);
      currentFrom = currentTo + 1n;
    } catch (error) {
      // Якщо діапазон завеликий (забагато результатів), ділимо навпіл
      if (isRangeTooLargeError(error) && currentTo > currentFrom) {
        const mid = currentFrom + (currentTo - currentFrom) / 2n;
        const firstHalf = await fetchLogsInChunks(client, {
          address,
          event,
          fromBlock: currentFrom,
          toBlock: mid,
          maxBlockRange,
        });
        const secondHalf = await fetchLogsInChunks(client, {
          address,
          event,
          fromBlock: mid + 1n,
          toBlock: currentTo,
          maxBlockRange,
        });
        allLogs.push(...firstHalf, ...secondHalf);
        currentFrom = currentTo + 1n;
      } else {
        throw error;
      }
    }
  }
 
  return allLogs;
}
 
function isRangeTooLargeError(error: unknown): boolean {
  const message = error instanceof Error ? error.message : String(error);
  return (
    message.includes("Log response size exceeded") ||
    message.includes("query returned more than") ||
    message.includes("exceed maximum block range")
  );
}

typescript

// БАГ: Виглядає нешкідливо, але ні
function formatTokenAmount(amount: bigint, decimals: number): string {
  return (Number(amount) / Math.pow(10, decimals)).toFixed(4);
}
 
// Для малих сум це працює нормально:
formatTokenAmount(1000000n, 6); // "1.0000" -- правильно
 
// Для великих сум ламається тихо:
formatTokenAmount(123456789012345678n, 18);
// Повертає "0.1235" -- НЕПРАВИЛЬНО, фактичну точність втрачено
// Number(123456789012345678n) === 123456789012345680
// Останні дві цифри округлені IEEE 754

typescript

import { formatUnits, parseUnits } from "viem";
 
// Правильно: оперує BigInt, повертає рядок
function formatTokenAmount(amount: bigint, decimals: number, displayDecimals: number = 4): string {
  const formatted = formatUnits(amount, decimals);
 
  // formatUnits повертає рядок повної точності, наприклад "0.123456789012345678"
  // Обрізаємо (не округлюємо) до потрібної точності відображення
  const [whole, fraction = ""] = formatted.split(".");
  const truncated = fraction.slice(0, displayDecimals).padEnd(displayDecimals, "0");
 
  return `${whole}.${truncated}`;
}
 
// Також критично: використовуйте parseUnits для введення користувача, ніколи parseFloat
function parseTokenInput(input: string, decimals: number): bigint {
  // parseUnits коректно обробляє перетворення рядка в BigInt
  return parseUnits(input, decimals);
}

typescript

// Серіалізатор відповіді API
function serializeForApi(data: Record<string, unknown>): string {
  return JSON.stringify(data, (_, value) => (typeof value === "bigint" ? value.toString() : value));
}

typescript

import { LRUCache } from "lru-cache";
 
const memoryCache = new LRUCache<string, unknown>({
  max: 10_000,
  ttl: 1000 * 60, // 1 хвилина за замовчуванням
});
 
type CacheTier = "immutable" | "short" | "volatile";
 
const TTL_MAP: Record<CacheTier, number> = {
  immutable: 1000 * 60 * 60 * 24, // 24 години в пам'яті, постійно в Redis
  short: 1000 * 60 * 5, // 5 хвилин
  volatile: 1000 * 15, // 15 секунд
};
 
async function cachedRpcCall<T>(key: string, tier: CacheTier, fetcher: () => Promise<T>): Promise<T> {
  // Спершу перевіряємо пам'ять
  const cached = memoryCache.get(key) as T | undefined;
  if (cached !== undefined) return cached;
 
  // Потім Redis (якщо є)
  // const redisCached = await redis.get(key);
  // if (redisCached) { ... }
 
  const result = await fetcher();
  memoryCache.set(key, result, { ttl: TTL_MAP[tier] });
 
  return result;
}
 
// Використання:
const receipt = await cachedRpcCall(`receipt:${txHash}`, "immutable", () =>
  client.getTransactionReceipt({ hash: txHash }),
);

typescript

// Немає виведення типів — args це unknown[], повернення unknown
const result = await client.readContract({
  address: "0x...",
  abi: JSON.parse(abiString), // парситься в рантаймі = немає інформації про типи
  functionName: "balanceOf",
  args: ["0x..."],
});

typescript

// Визначте ABI як const для повного виведення типів
const erc20Abi = [
  {
    name: "balanceOf",
    type: "function",
    stateMutability: "view",
    inputs: [{ name: "account", type: "address" }],
    outputs: [{ name: "balance", type: "uint256" }],
  },
  {
    name: "transfer",
    type: "function",
    stateMutability: "nonpayable",
    inputs: [
      { name: "to", type: "address" },
      { name: "amount", type: "uint256" },
    ],
    outputs: [{ name: "success", type: "bool" }],
  },
] as const;
 
// Тепер TypeScript знає:
// - functionName автодоповнює до "balanceOf" | "transfer"
// - args для balanceOf це [address: `0x${string}`]
// - тип повернення для balanceOf це bigint
const balance = await client.readContract({
  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  abi: erc20Abi,
  functionName: "balanceOf",
  args: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
});
// typeof balance = bigint -- повністю типізований

Ончейн-дані у продакшені: про що вам ніхто не розповість

Ілюзія надійних даних#

Ліміти RPC-запитів зіпсують вам вихідні#

Реорганізації: баг, якого ви не побачите#

Проблема індексації: обирайте свій біль#

Прямі RPC-виклики#

The Graph (сабграфи)#

Кастомні індексери (Ponder, Envio)#

getLogs небезпечніший, ніж здається#

BigInt вас смирить#

Стратегія кешування: що, як довго та коли інвалідувати#

TypeScript та ABI контрактів: правильний підхід#

Незручна правда#

Схожі записи

TypeScript Compiler API: Building Custom Linters, Codemods, and Type Analyzers

JSON to TypeScript Guide: Create Safer API Types From Real Payloads