@mikeatlast/ponder 0.16.1-fork.1

package/src/utils/checkpoint.ts

@@ -0,0 +1,203 @@
+import type { LightBlock, SyncBlock } from "@/internal/types.js";
+import { hexToBigInt } from "viem";
+
+export type Checkpoint = {
+  blockTimestamp: bigint;
+  chainId: bigint;
+  blockNumber: bigint;
+  transactionIndex: bigint;
+  eventType: number;
+  eventIndex: bigint;
+};
+
+// 10 digits for unix timestamp gets us to the year 2277.
+const BLOCK_TIMESTAMP_DIGITS = 10;
+// Chain IDs are uint256. As of writing the largest Chain ID on https://chainlist.org
+// is 13 digits. 16 digits should be enough (JavaScript's max safe integer).
+const CHAIN_ID_DIGITS = 16;
+// Same logic as chain ID.
+const BLOCK_NUMBER_DIGITS = 16;
+// Same logic as chain ID.
+const TRANSACTION_INDEX_DIGITS = 16;
+// At time of writing, we only have 2 event types planned, so one digit (10 types) is enough.
+const EVENT_TYPE_DIGITS = 1;
+// This could contain log index, trace index, etc. 16 digits should be enough.
+const EVENT_INDEX_DIGITS = 16;
+
+const CHECKPOINT_LENGTH =
+  BLOCK_TIMESTAMP_DIGITS +
+  CHAIN_ID_DIGITS +
+  BLOCK_NUMBER_DIGITS +
+  TRANSACTION_INDEX_DIGITS +
+  EVENT_TYPE_DIGITS +
+  EVENT_INDEX_DIGITS;
+
+export const EVENT_TYPES = {
+  transactions: 2,
+  blocks: 5,
+  logs: 5,
+  traces: 7,
+} as const;
+
+const encodedChainIds = new Map<number | bigint, string>();
+
+export const encodeCheckpoint = (
+  checkpoint: Checkpoint | { [K in keyof Checkpoint]: number | bigint },
+) => {
+  const {
+    blockTimestamp,
+    chainId,
+    blockNumber,
+    transactionIndex,
+    eventType,
+    eventIndex,
+  } = checkpoint;
+
+  if (eventType < 0 || eventType > 9) {
+    throw new Error(
+      `Got invalid event type ${eventType}, expected a number from 0 to 9`,
+    );
+  }
+
+  let encodedChainId = encodedChainIds.get(chainId);
+  if (encodedChainId === undefined) {
+    encodedChainId = chainId.toString().padStart(CHAIN_ID_DIGITS, "0");
+    encodedChainIds.set(chainId, encodedChainId);
+  }
+
+  const result = `${blockTimestamp.toString().padStart(BLOCK_TIMESTAMP_DIGITS, "0")}${encodedChainId}${blockNumber.toString().padStart(BLOCK_NUMBER_DIGITS, "0")}${transactionIndex.toString().padStart(TRANSACTION_INDEX_DIGITS, "0")}${eventType.toString()}${eventIndex.toString().padStart(EVENT_INDEX_DIGITS, "0")}`;
+
+  if (result.length !== CHECKPOINT_LENGTH) {
+    throw new Error(`Invalid stringified checkpoint: ${result}`);
+  }
+
+  return result;
+};
+
+export const decodeCheckpoint = (checkpoint: string): Checkpoint => {
+  let offset = 0;
+
+  const blockTimestamp = BigInt(
+    checkpoint.slice(offset, offset + BLOCK_TIMESTAMP_DIGITS),
+  );
+  offset += BLOCK_TIMESTAMP_DIGITS;
+
+  const chainId = BigInt(checkpoint.slice(offset, offset + CHAIN_ID_DIGITS));
+  offset += CHAIN_ID_DIGITS;
+
+  const blockNumber = BigInt(
+    checkpoint.slice(offset, offset + BLOCK_NUMBER_DIGITS),
+  );
+  offset += BLOCK_NUMBER_DIGITS;
+
+  const transactionIndex = BigInt(
+    checkpoint.slice(offset, offset + TRANSACTION_INDEX_DIGITS),
+  );
+  offset += TRANSACTION_INDEX_DIGITS;
+
+  const eventType = +checkpoint.slice(offset, offset + EVENT_TYPE_DIGITS);
+  offset += EVENT_TYPE_DIGITS;
+
+  const eventIndex = BigInt(
+    checkpoint.slice(offset, offset + EVENT_INDEX_DIGITS),
+  );
+  offset += EVENT_INDEX_DIGITS;
+
+  return {
+    blockTimestamp,
+    chainId,
+    blockNumber,
+    transactionIndex,
+    eventType,
+    eventIndex,
+  };
+};
+
+export const ZERO_CHECKPOINT: Checkpoint = {
+  blockTimestamp: 0n,
+  chainId: 0n,
+  blockNumber: 0n,
+  transactionIndex: 0n,
+  eventType: 0,
+  eventIndex: 0n,
+};
+
+export const MAX_CHECKPOINT: Checkpoint = {
+  blockTimestamp: 99999_99999n,
+  chainId: 9999_9999_9999_9999n,
+  blockNumber: 9999_9999_9999_9999n,
+  transactionIndex: 9999_9999_9999_9999n,
+  eventType: 9,
+  eventIndex: 9999_9999_9999_9999n,
+};
+
+export const ZERO_CHECKPOINT_STRING = encodeCheckpoint(ZERO_CHECKPOINT);
+export const MAX_CHECKPOINT_STRING = encodeCheckpoint(MAX_CHECKPOINT);
+
+/**
+/**
+ * Returns true if two checkpoints are equal.
+ */
+export const isCheckpointEqual = (a: Checkpoint, b: Checkpoint) =>
+  encodeCheckpoint(a) === encodeCheckpoint(b);
+
+/**
+ * Returns true if checkpoint a is greater than checkpoint b.
+ * Returns false if the checkpoints are equal.
+ */
+export const isCheckpointGreaterThan = (a: Checkpoint, b: Checkpoint) =>
+  encodeCheckpoint(a) > encodeCheckpoint(b);
+
+/**
+ * Returns true if checkpoint a is greater than or equal to checkpoint b.|
+ */
+export const isCheckpointGreaterThanOrEqualTo = (
+  a: Checkpoint,
+  b: Checkpoint,
+) => encodeCheckpoint(a) >= encodeCheckpoint(b);
+
+export const checkpointMax = (...checkpoints: Checkpoint[]) =>
+  checkpoints.reduce((max, checkpoint) => {
+    return isCheckpointGreaterThan(checkpoint, max) ? checkpoint : max;
+  });
+
+export const checkpointMin = (...checkpoints: Checkpoint[]) =>
+  checkpoints.reduce((min, checkpoint) => {
+    return isCheckpointGreaterThan(min, checkpoint) ? checkpoint : min;
+  });
+
+export const LATEST = MAX_CHECKPOINT_STRING;
+
+/** Compute the minimum checkpoint, filtering out undefined. */
+export const min = (...checkpoints: (string | undefined)[]) => {
+  return checkpoints.reduce((acc, cur) => {
+    if (cur === undefined) return acc;
+    if (acc === undefined) return cur;
+    if (acc < cur) return acc;
+    return cur;
+  })!;
+};
+
+/** Compute the maximum checkpoint, filtering out undefined. */
+export const max = (...checkpoints: (string | undefined)[]) => {
+  return checkpoints.reduce((acc, cur) => {
+    if (cur === undefined) return acc;
+    if (acc === undefined) return cur;
+    if (acc > cur) return acc;
+    return cur;
+  });
+};
+
+/** Convert `block` to a `Checkpoint`. */
+export const blockToCheckpoint = (
+  block: LightBlock | SyncBlock,
+  chainId: number,
+  rounding: "up" | "down",
+): Checkpoint => {
+  return {
+    ...(rounding === "up" ? MAX_CHECKPOINT : ZERO_CHECKPOINT),
+    blockTimestamp: hexToBigInt(block.timestamp),
+    chainId: BigInt(chainId),
+    blockNumber: hexToBigInt(block.number),
+  };
+};

package/src/utils/chunk.ts

@@ -0,0 +1,7 @@
+export const chunk = <T>(array: T[], size: number): T[][] => {
+  const chunks = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+};

package/src/utils/copy.ts

@@ -0,0 +1,151 @@
+import util from "node:util";
+
+/**
+ * Symbol used to mark objects that are copied on write.
+ */
+export const COPY_ON_WRITE = Symbol.for("ponder:copyOnWrite");
+
+/**
+ * Create a copy-on-write proxy for an object.
+ */
+export const copyOnWrite = <T extends object>(obj: T): T => {
+  let copiedObject: T | undefined;
+
+  // @ts-ignore
+  obj[util.inspect.custom] = () => {
+    return copiedObject ?? obj;
+  };
+
+  return new Proxy<T>(obj, {
+    get(target, prop, receiver) {
+      if (prop === COPY_ON_WRITE) {
+        return target;
+      }
+      let result = Reflect.get(copiedObject ?? target, prop, receiver);
+
+      if (
+        typeof result === "object" &&
+        result !== null &&
+        copiedObject === undefined
+      ) {
+        copiedObject = structuredClone(target);
+        result = Reflect.get(copiedObject, prop, receiver);
+      }
+
+      return result;
+    },
+    set(target, prop, newValue, receiver) {
+      if (copiedObject === undefined) {
+        copiedObject = structuredClone(target);
+      }
+      return Reflect.set(copiedObject!, prop, newValue, receiver);
+    },
+    deleteProperty(target, prop) {
+      if (copiedObject === undefined) {
+        copiedObject = structuredClone(target);
+      }
+      return Reflect.deleteProperty(copiedObject!, prop);
+    },
+    defineProperty(target, prop, descriptor) {
+      if (copiedObject === undefined) {
+        copiedObject = structuredClone(target);
+      }
+      return Reflect.defineProperty(copiedObject!, prop, descriptor);
+    },
+    ownKeys(target) {
+      return Reflect.ownKeys(copiedObject ?? target);
+    },
+    has(target, prop) {
+      return Reflect.has(copiedObject ?? target, prop);
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      return Reflect.getOwnPropertyDescriptor(copiedObject ?? target, prop);
+    },
+  });
+};
+
+/**
+ * Create a deep copy of an object.
+ *
+ * @dev This function supports copying objects that
+ * have been created with `copyOnWrite`.
+ */
+export const copy = <T>(obj: T): T => {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+
+  const hasProxy = (obj: any): boolean => {
+    if (obj === null || typeof obj !== "object") {
+      return false;
+    }
+
+    if (obj[COPY_ON_WRITE] !== undefined) {
+      return true;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.some((element) => hasProxy(element));
+    }
+
+    for (const value of Object.values(obj)) {
+      if (hasProxy(value)) {
+        return true;
+      }
+    }
+
+    return false;
+  };
+
+  const isDeeplyNested = (obj: any, depth = 0): boolean => {
+    if (obj === null || typeof obj !== "object") {
+      return false;
+    }
+
+    if (depth > 0) {
+      return true;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.some((element) => isDeeplyNested(element, depth + 1));
+    }
+
+    for (const value of Object.values(obj)) {
+      if (isDeeplyNested(value, depth + 1)) {
+        return true;
+      }
+    }
+
+    return false;
+  };
+
+  // @ts-expect-error
+  const proxy = obj[COPY_ON_WRITE];
+  if (proxy === undefined) {
+    if (Array.isArray(obj)) {
+      if (hasProxy(obj)) {
+        // @ts-expect-error
+        return obj.map((element) => copy(element));
+      }
+
+      if (isDeeplyNested(obj)) return structuredClone(obj);
+      return [...obj] as T;
+    }
+
+    if (hasProxy(obj)) {
+      const result = {} as T;
+      for (const [key, value] of Object.entries(obj)) {
+        // @ts-expect-error
+        result[key] = copy(value);
+      }
+
+      return result;
+    }
+
+    // Note: spread operator is significantly faster than `structuredClone`
+    if (isDeeplyNested(obj)) return structuredClone(obj);
+    return { ...obj };
+  }
+
+  return proxy;
+};

package/src/utils/date.ts

@@ -0,0 +1,26 @@
+/** Formats a unix timestamp into a short date format (e.g. "Jan 1, 2021")
+ *
+ * @param unixTimestamp Unix timestamp to format
+ * @returns Formatted date string
+ */
+export function formatShortDate(unixTimestamp: number) {
+  const date = new Date(unixTimestamp * 1000);
+  const year = date.getFullYear();
+  const months = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+  ];
+  const month = months[date.getMonth()];
+  const day = date.getDate();
+  return `${month} ${day}, ${year}`;
+}

package/src/utils/debug.ts

@@ -0,0 +1,110 @@
+import type { Address, Hash, Hex, LogTopic } from "viem";
+
+/** @see https://github.com/alloy-rs/alloy/blob/main/crates/rpc-types-trace/src/geth/call.rs */
+/** @see https://github.com/alloy-rs/alloy/blob/main/crates/rpc-types-trace/src/common.rs */
+/** @see https://github.com/paradigmxyz/reth/blob/main/crates/rpc/rpc/src/debug.rs */
+
+/** Result type for geth style transaction trace. */
+export type Trace = {
+  /** Transaction hash. */
+  txHash: Hex;
+  /** Trace results produced by the tracer.  */
+  result: CallFrame;
+};
+
+/**
+ * The response object for `debug_traceBlockByNumber` and `debug_traceBlockByHash`
+ * with `"tracer": "callTracer"`.
+ */
+type CallFrame = {
+  /** The type of the call. */
+  type:
+    | "CALL"
+    | "CALLCODE"
+    | "DELEGATECALL"
+    | "STATICCALL"
+    | "CREATE"
+    | "CREATE2"
+    | "SELFDESTRUCT";
+  /** The address of that initiated the call. */
+  from: Address;
+  /** The address of the contract that was called. */
+  to?: Address;
+  /** How much gas was left before the call. */
+  gas: Hex;
+  /** How much gas was used by the call. */
+  gasUsed: Hex;
+  /** Calldata input. */
+  input: Hex;
+  /** Output of the call, if any. */
+  output?: Hex;
+  /** Error message, if any. */
+  error?: string;
+  /** Why this call reverted, if it reverted. */
+  revertReason?: string;
+  /** Recorded child calls. */
+  calls?: CallFrame[];
+  /** Logs emitted by this call. */
+  logs?: CallLogFrame[];
+  /** Value transferred. */
+  value?: Hex;
+};
+
+/** Represents a recorded log that is emitted during a trace call. */
+type CallLogFrame = {
+  /** The address of the contract that was called. */
+  address: Address;
+  /** The topics of the log. */
+  topics: LogTopic[];
+  /** The data of the log. */
+  data: Hex;
+  /** The position of the log relative to subcalls within the same trace. */
+  position: number;
+};
+
+/** The configuration for the call tracer. */
+type CallConfig = {
+  /** When set to true, this will only trace the primary (top-level) call and not any sub-calls. */
+  onlyTopCall?: boolean;
+  /** When set to true, this will include the logs emitted by the call. */
+  withLog?: boolean;
+};
+
+export type DebugRpcSchema = [
+  /**
+   * @description Returns tracing results by executing all transactions in the block specified by the block hash
+   *
+   * @example
+   * provider.request({ method: 'debug_traceBlockByHash', params: ['0x...', { tracer: "callTracer" }] })
+   * // => {
+   * //   txHash: '0x5a42...',
+   * //   result: [...],
+   * // }
+   */
+  {
+    Method: "debug_traceBlockByHash";
+    Parameters: [
+      hash: Hash,
+      tracingOptions: { tracer: "callTracer"; tracerConfig?: CallConfig },
+    ];
+    ReturnType: Trace[];
+  },
+  /**
+   * @description Returns tracing results by executing all transactions in the block specified by the block hash
+   *
+   * @example
+   * provider.request({ method: 'debug_traceBlockByNumber', params: ['0x1b4', { tracer: "callTracer" }] })
+   * // => {
+   * //   txHash: '0x5a42...',
+   * //   result: [...],
+   * // }
+   */
+  {
+    Method: "debug_traceBlockByNumber";
+    Parameters: [
+      block: Hex,
+      tracingOptions: { tracer: "callTracer"; tracerConfig?: CallConfig },
+    ];
+    ReturnType: Trace[];
+  },
+];