Module 1 — V8 Engine Mechanics & Zero-Allocation Ingestion

delete obj.prop always forces a hidden class transition to a dictionary mode object — the worst possible state. Dictionary objects have no hidden class; every property access is a hash table lookup.

// BAD: delete creates a dictionary-mode object
delete tx.memo;
 
// GOOD: set to null/undefined instead
tx.memo = null;

---

V8 Heap Architecture

V8's heap is divided into regions with different garbage collection strategies. Understanding these regions is essential for writing ingestion code that doesn't trigger GC pauses at high throughput.

The Generational Hypothesis

V8's GC is based on the generational hypothesis: most objects die young. A transaction wrapper object created to parse one event and immediately discarded follows this pattern perfectly. If V8 can collect it quickly, without examining the entire heap, GC cost stays low.

V8 divides the heap accordingly:

New Space (Young Generation)

• Size: default --max-semi-space-size is 16MB per semi-space on current V8/Node LTS (total New Space ≈ 32MB) — this has changed across V8 versions, so treat it as tunable, not fixed
• Two semi-spaces: "From" space (active) and "To" space (empty)
• Collection: Scavenge (copying GC) — fast, typically < 1ms
• Collected frequently: triggered when From space fills up

Old Space (Old Generation)

• Size: bounded by --max-old-space-size, but the default (when you don't pass the flag) is not a flat constant — V8 computes it from available system memory at startup, so it varies by host (roughly 1.5–2GB on modest 64-bit hosts, higher on machines with more RAM). In containers this matters: V8 may size its default off the host's total memory rather than the container's cgroup limit, so don't rely on the default — set --max-old-space-size explicitly to match the container's actual memory ceiling
• Objects promoted from New Space after surviving 2 scavenges
• Collection: Mark-Compact — expensive, can pause for 10–100ms
• Collected infrequently: only when Old Space fills up or explicitly requested

Large Object Space

• Objects larger than 1MB (approximately) skip New Space entirely and go here
• Always Old Space collection behavior

The GC Pause Anatomy

During a Scavenge (Minor GC):

1. V8 stops all JavaScript execution (stop-the-world)
2. Scans From space for live objects (objects reachable from the root set)
3. Copies live objects to To space
4. Flips From/To roles
5. Resumes JavaScript

During a Mark-Compact (Major GC):

1. V8 begins marking live objects across Old Space — on current V8 (the Orinoco project), most of this work runs incrementally and concurrently on background threads while your JS keeps executing, so the bulk of the "10–80ms" of marking work does not, by itself, stop your code
2. A short atomic pause stops JS to finish marking anything mutated during the concurrent phase (V8 has to catch up before it's safe to compact)
3. Compacts Old Space by moving live objects together (reduces fragmentation) — this happens during the atomic pause, which is why compaction cost, not total marking time, tends to dominate the pause an application actually observes
4. Resumes JavaScript

The pause durations cited elsewhere in this module (e.g., the 78ms pause in the airdrop incident below) refer to this atomic pause, not the full marking phase — for an Old Space holding hundreds of MB of live data, the atomic portion alone can still run tens of milliseconds even though marking itself was mostly concurrent.

For an ingestion pipeline, a 50ms Major GC pause at 50K events/sec means 2,500 events are buffered (or dropped if buffers are bounded). This is the failure mode that appears as a latency spike with no obvious cause.

Timeline:
  t=0ms:   Event loop processes transaction events normally
  t=50ms:  Old Space fills → Major GC triggered
  t=50ms:  ALL JAVASCRIPT PAUSED
  t=100ms: GC completes, JavaScript resumes
  t=100ms: 2,500 events have been queued waiting
  t=100ms: Throughput spike as backlog clears
  t=150ms: Latency spike visible to WebSocket subscribers

Measuring GC Pressure

// Enable GC logging
// node --trace-gc your-indexer.js
// Output format:
// [5032:0x5580d1a00000]    50784 ms: Scavenge 256.7 (261.5) -> 15.3 (268.0) MB, 0.9 / 0.0 ms
// [5032:0x5580d1a00000]   110823 ms: Mark-Compact 1016.7 (1024.5) -> 509.3 (516.0) MB, 83.4 / 0.0 ms
//
// The numbers: current heap used → heap used after GC (heap capacity)
// The timing: wall clock ms for the GC pause
 
// Programmatic monitoring in production:
import { PerformanceObserver, constants } from 'node:perf_hooks';
 
const gcObserver = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    const gcType = entry.detail?.kind === constants.NODE_PERFORMANCE_GC_MINOR
      ? 'Minor (Scavenge)'
      : 'Major (Mark-Compact)';
    console.log(`GC: ${gcType} — ${entry.duration.toFixed(2)}ms`);
  }
});
gcObserver.observe({ entryTypes: ['gc'] });

---

The New Space Saturation Problem

At high ingestion rates, your hot paths allocate objects continuously. If those objects are short-lived (transaction wrapper objects, parsed payload structs, intermediate arrays), they saturate New Space and trigger frequent Scavenges.

A Scavenge takes 0.5–3ms. At 50K events/sec, if a Scavenge triggers every 100ms, that's 30 pauses per second, each 0.5–3ms. Total pause time: 15–90ms/sec — measurable, but manageable.

The real danger: object promotion. When New Space fills up faster than it can be scavenged, V8 starts promoting young objects to Old Space prematurely. Those objects now survive, accumulate in Old Space, and eventually trigger an expensive Mark-Compact.

Diagnosing promotion pressure:

node --trace-gc --trace-gc-verbose your-indexer.js 2>&1 | grep "promotion"
# Look for: "Promoted X MB from new space to old space"
# High promotion rate = New Space too small or objects living too long

Solution 1: Increase New Space size

# Default semi-space is 16MB (total New Space = 32MB)
# For high-throughput ingestion, increase to 64–128MB
node --max-semi-space-size=64 your-indexer.js

Solution 2: Reduce allocation rate with object pooling

---

Zero-Allocation Patterns for Ingestion Pipelines

The highest-performance ingestion code avoids allocation entirely in the hot path. Instead of creating new objects for each event, it reuses pre-allocated objects from a pool.

Object Pooling

// Transaction object pool for a blockchain indexer
class TransactionPool {
  #pool = [];
  #size;
 
  constructor(size = 1000) {
    this.#size = size;
    // Pre-allocate all objects with stable hidden class
    for (let i = 0; i < size; i++) {
      this.#pool.push(this.#createEmpty());
    }
  }
 
  // Always same property order → stable hidden class
  #createEmpty() {
    return {
      hash: null,
      blockHeight: 0,
      sender: '',
      recipient: '',
      amount: 0n,
      status: '',
      timestamp: 0,
      payload: null,
      _pooled: true,  // internal marker, never deleted
    };
  }
 
  acquire() {
    return this.#pool.pop() ?? this.#createEmpty();
  }
 
  release(tx) {
    // Reset without deleting properties (hidden class preserved)
    tx.hash = null;
    tx.blockHeight = 0;
    tx.sender = '';
    tx.recipient = '';
    tx.amount = 0n;
    tx.status = '';
    tx.timestamp = 0;
    tx.payload = null;
    if (this.#pool.length < this.#size) {
      this.#pool.push(tx);
    }
  }
}
 
const txPool = new TransactionPool(2000);
 
// Hot path: zero allocation for the transaction object itself
function processEvent(rawEvent) {
  const tx = txPool.acquire();   // reuse pooled object
  tx.hash = rawEvent.hash;
  tx.blockHeight = rawEvent.blockHeight;
  tx.sender = rawEvent.sender;
  tx.amount = BigInt(rawEvent.amount);
  tx.timestamp = rawEvent.timestamp;
 
  writeToDatabase(tx)             // async, returns immediately
    .then(() => txPool.release(tx));  // return to pool after use
}

Typed Arrays for Numeric Ingestion

For high-frequency numeric data (price feeds, metrics, sensor readings), TypedArray objects are more efficient than regular arrays or objects:

// BAD: regular array with mixed types, V8 cannot optimize
const prices = [];
prices.push(1234.56);
prices.push(1235.00);
 
// GOOD: typed array, V8 knows exact memory layout
const priceBuffer = new Float64Array(10000);  // pre-allocated
let priceIndex = 0;
 
function recordPrice(price) {
  priceBuffer[priceIndex++ % 10000] = price;  // direct memory write, no GC
}

Pre-allocated String Buffers

String concatenation in hot paths creates intermediate strings that immediately become garbage:

// BAD: creates multiple intermediate string objects
function formatLogEntry(tx) {
  return 'TX:' + tx.hash + ':' + tx.sender + ':' + tx.amount;
}
 
// GOOD: template literal (V8 optimizes this well, single allocation)
function formatLogEntry(tx) {
  return `TX:${tx.hash}:${tx.sender}:${tx.amount}`;
}
 
// BEST for very hot paths: write directly to a Buffer (off-heap)
const logBuffer = Buffer.allocUnsafe(10 * 1024 * 1024);  // 10MB, off-heap
let logOffset = 0;
 
function writeLogEntry(tx) {
  const entry = `TX:${tx.hash}:${tx.sender}\n`;
  const written = logBuffer.write(entry, logOffset, 'utf8');
  logOffset += written;
  if (logOffset > 9 * 1024 * 1024) flushLogBuffer();
}

---

Diagnosing V8 Optimization State in Production

The --prof Flag and node --prof-process

# Generate V8 profiler output
node --prof --prof-process-delay=0 your-indexer.js &
 
# Wait for load
sleep 30 && kill -SIGUSR1 $(pgrep -f your-indexer)
 
# Process the profiler output
node --prof-process isolate-*.log > profile.txt
 
# Read the output:
# [Bottom up (heavy) profile]:
# ticks    total   nonlib   name
#  8432   43.2%   45.1%   v8::internal::Compiler::Optimize
# → 43% of CPU time in the optimizer = TurboFan working hard (good)
# → If you see your function name here with high %, it's a hot path

--trace-opt and --trace-deopt

# See which functions TurboFan optimizes
node --trace-opt your-indexer.js 2>&1 | grep "parseTransaction"
# [2847] Compiling method parseTransaction using TurboFan
 
# See which functions deoptimize and WHY
node --trace-deopt your-indexer.js 2>&1 | grep "parseTransaction"
# [2847] Deoptimizing function parseTransaction, reason: wrong type
# [2847]   at bytecode offset 42 in parseTransaction

The deoptimization reason tells you exactly what assumption was violated:

• wrong type — a different type arrived than expected
• out of bounds — array index out of bounds after optimization assumed bounds
• not a heap object — expected an object but received a primitive
• lost feedback — the inline cache was invalidated

Using %OptimizeFunctionOnNextCall

Node.js exposes V8 internals via --allow-natives-syntax:

// node --allow-natives-syntax your-test.js
function parseTransaction(raw) {
  return {
    hash: raw.hash,
    amount: raw.amount,
    blockHeight: raw.blockHeight,
  };
}
 
// Warm up with consistent shapes
const testTx = { hash: 'abc', amount: 1000n, blockHeight: 1000 };
parseTransaction(testTx);
parseTransaction(testTx);
parseTransaction(testTx);
 
// Force optimization
%OptimizeFunctionOnNextCall(parseTransaction);
parseTransaction(testTx);
 
// Check optimization status: 1 = optimized, 2 = not optimized
const status = %GetOptimizationStatus(parseTransaction);
console.log(status & 1 ? 'OPTIMIZED' : 'NOT OPTIMIZED');
 
// Now introduce a shape change and verify deoptimization
const badTx = { hash: 'abc', amount: 1000n, blockHeight: 1000, memo: 'extra' };
parseTransaction(badTx);
 
const statusAfter = %GetOptimizationStatus(parseTransaction);
console.log(statusAfter & 1 ? 'STILL OPTIMIZED' : 'DEOPTIMIZED');
// → DEOPTIMIZED if memo adds a new hidden class

---

The Production Incident: GC Pause Under Airdrop Load

Context: A blockchain indexer processing normal traffic at ~2,000 events/second. A network-wide token airdrop begins, pushing event rate to 48,000 events/second.

What happened:

The ingestion pipeline created a new transaction object for each event:

// The hot path that caused the incident
function processRawEvent(event) {
  const tx = {
    hash: event.hash,
    blockHeight: event.blockHeight,
    sender: event.sender,
    amount: BigInt(event.amount),
    receivedAt: Date.now(),  // ← added conditionally in one code path
  };
  // ... process and discard tx
}

At 2,000 events/sec, this created 2,000 objects/sec, each ~200 bytes. New Space (default 32MB) held ~160,000 objects before a Scavenge. Scavenges ran every 80 seconds, taking ~2ms each. Acceptable.

At 48,000 events/sec, 48,000 objects/sec with the same 32MB New Space. New Space now filled in ~3.3 seconds. Scavenges ran every 3.3 seconds. The receivedAt property was added in only one code path, creating two hidden classes — the parser function became polymorphic, doubling the cost of each property access.

Worse: at peak load, some objects survived Scavenges (they were referenced by the database write queue that was backing up). They were promoted to Old Space. After 3 minutes of peak load, Old Space held 800MB of transaction objects that had leaked from the queue backlog. Mark-Compact triggered: 78ms pause. All 48,000 events/sec halted for 78ms. The backlog: 3,744 events that were processed in a spike immediately after, causing a secondary latency surge.

The fix:

// Step 1: Eliminate the conditional property
function processRawEvent(event) {
  const tx = {
    hash: event.hash,
    blockHeight: event.blockHeight,
    sender: event.sender,
    amount: BigInt(event.amount),
    receivedAt: Date.now(),  // always present → stable hidden class
  };
  return tx;
}
 
// Step 2: Implement object pooling (shown above)
 
// Step 3: Increase New Space to handle peak load without constant scavenging
// node --max-semi-space-size=128 indexer.js
 
// Step 4: Fix the database write queue to not retain processed objects
// (the root cause of Old Space accumulation)

After the fix: at 48,000 events/sec, Scavenges ran every 3.2 seconds, taking ~4ms (larger pool to scan). Old Space never exceeded 200MB. No Major GC occurred during a 6-hour airdrop test. Maximum single event latency: 6ms.

---

V8 Flags Reference for Production Ingestion

# Memory tuning
--max-old-space-size=4096          # 4GB Old Space for heavy workloads
--max-semi-space-size=128          # 128MB semi-space for high allocation rate
 
# Diagnostic flags (do not use in production — high overhead)
--trace-gc                          # Log every GC event with timing
--trace-gc-verbose                  # Detailed GC internals
--trace-opt                         # Log TurboFan optimizations
--trace-deopt                       # Log deoptimizations with reasons
--prof                              # Generate V8 CPU profiler output
--allow-natives-syntax              # Enable %OptimizeFunctionOnNextCall etc.
 
# Observability (safe for production)
# Use PerformanceObserver with { entryTypes: ['gc'] } instead of flags

---

Summary

---

V8 runs your code, but it's not the only thing your code is fighting against. Module 2 goes into the event loop's internal phase structure and the precise mechanics of how concurrent ingestion can starve your own callbacks.

Next: Memory Leak Prevention Patterns →

---