البيانات على السلسلة في بيئة الإنتاج: ما لا يخبرك به أحد

بيانات البلوكتشين ليست نظيفة ولا موثوقة ولا سهلة. حدود معدل RPC، إعادة تنظيم السلسلة، أخطاء BigInt، ومقايضات الفهرسة — دروس صعبة من إطلاق منتجات DeFi حقيقية.

هناك وهم بأن البيانات على السلسلة جديرة بالثقة بطبيعتها. سجل غير قابل للتغيير. حالة شفافة. اقرأها فقط وانتهى الأمر.

صدقت ذلك أيضا. ثم أطلقت لوحة تحكم DeFi في بيئة الإنتاج وأمضيت ثلاثة أسابيع أحاول معرفة لماذا أرصدة التوكنات خاطئة، ولماذا سجل الأحداث يحتوي على فجوات، ولماذا قاعدة بياناتنا تحتوي على معاملات من كتل لم تعد موجودة.

البيانات على السلسلة خام وعدائية ومليئة بالحالات الحدية التي ستكسر تطبيقك بطرق لن تلاحظها حتى يقدم مستخدم بلاغ خطأ. تغطي هذه التدوينة كل ما تعلمته بالطريقة الصعبة.

وهم البيانات الموثوقة#

إليك أول شيء لا يخبرك به أحد: البلوكتشين لا يعطيك بيانات. يعطيك تحولات حالة. لا يوجد SELECT * FROM transfers WHERE user = '0x...'. هناك سجلات ووصولات تخزين وتتبعات استدعاءات — كلها مشفرة بتنسيقات تتطلب سياقا لفك تشفيرها.

سجل حدث Transfer يعطيك from و to و value. لا يخبرك باسم التوكن. لا يخبرك بالكسور العشرية. لا يخبرك إذا كان هذا تحويلا مشروعا أم توكن برسوم على التحويل يقتطع 3% من القيمة. لا يخبرك إذا كانت هذه الكتلة ستظل موجودة بعد 30 ثانية.

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, // دقيقة واحدة افتراضيا
});
 
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