프로덕션에서의 온체인 데이터: 아무도 말해주지 않는 것들

블록체인 데이터는 깨끗하지도, 신뢰할 수 있지도, 쉽지도 않습니다. RPC 속도 제한, 체인 재구성, BigInt 버그, 인덱싱 트레이드오프 — 실제 DeFi 제품을 출시하며 얻은 뼈아픈 교훈들.

온체인 데이터가 본질적으로 신뢰할 수 있다는 환상이 있습니다. 불변의 원장. 투명한 상태. 그냥 읽으면 끝.

저도 그렇게 믿었습니다. 그러다가 DeFi 대시보드를 프로덕션에 출시하고 토큰 잔액이 왜 틀린지, 이벤트 이력에 왜 빈틈이 있는지, 데이터베이스에 더 이상 존재하지 않는 블록의 트랜잭션이 왜 있는지 알아내는 데 3주를 보냈습니다.

온체인 데이터는 날것이고, 적대적이며, 사용자가 버그 리포트를 제출하기 전까지 눈치채지 못할 방식으로 애플리케이션을 망가뜨리는 엣지 케이스로 가득합니다. 이 포스트는 제가 힘들게 배운 모든 것을 다룹니다.

신뢰할 수 있는 데이터라는 환상#

아무도 말해주지 않는 첫 번째 사실: 블록체인은 데이터를 주지 않습니다. 상태 전이를 줍니다. SELECT * FROM transfers WHERE user = '0x...' 같은 건 없습니다. 로그, 영수증, 스토리지 슬롯, 콜 트레이스가 있을 뿐입니다 — 모두 해독하려면 컨텍스트가 필요한 형식으로 인코딩되어 있습니다.

Transfer 이벤트 로그는 from, to, value를 줍니다. 토큰 심볼은 알려주지 않습니다. 소수점 자릿수도 알려주지 않습니다. 이것이 정당한 전송인지 수수료-온-전송 토큰이 상단에서 3%를 빼가는 것인지도 알려주지 않습니다. 이 블록이 30초 후에도 존재할지도 알려주지 않습니다.

"불변"이라는 부분은 사실입니다 — 확정된 후에. 하지만 확정은 즉시 이루어지지 않습니다. 그리고 RPC 노드에서 돌아오는 데이터가 반드시 확정된 블록에서 온 것은 아닙니다. 대부분의 개발자는 latest를 쿼리하고 진실로 취급합니다. 그것은 기능이 아니라 버그입니다.

그리고 인코딩 문제가 있습니다. 모든 것이 hex입니다. 주소는 대소문자 혼합 체크섬이 적용되어 있거나 아닙니다. 토큰 금액은 을 곱한 정수입니다. $100의 USDC 전송은 온체인에서 으로 보입니다. USDC는 18이 아닌 6 소수점이기 때문입니다. 모든 ERC-20 토큰에 18 소수점을 가정한 프로덕션 코드를 본 적이 있습니다. 결과 잔액은 10^12 배 차이가 났습니다.

10^decimals

100000000

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); // DB 조회
 
    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}`;
}
 
// 또한 중요: 사용자 입력에는 parseFloat 대신 parseUnits를 사용
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"로 자동완성됨
// - balanceOf의 args는 [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