eth-compress

A compact client-side module for compressing Ethereum JSON-RPC requests, targeting lower latency and gas-efficient read-only calls with large calldata.

It combines RFC 9110-compliant negotiation for client-to-server compression, with optional JIT-compiled calldata compression.

Plug 'n' play with viem and a simple API

Scope

• Read-only eth_calls.
• Min. input threshold: > 1150 bytes.
• HTTP: Uses RFC 9110-compliant Content-Encoding negotiation (gzip/deflate).
• EVM/JIT: Routes eth_calls through a transient decompressor contract.

Installation

npm i eth-compress

HTTP request compression

Transparently compresses request bodies using the CompressionStream API.

import { compressModule } from 'eth-compress';

const response = await compressModule('https://rpc.example.org', {
  method: 'POST',
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_call',
    params: [/* ... */],
  }),
});

Compression modes

| Mode | Behavior | |------|----------| | 'passive' | Discover support from response Accept-Encoding header | | 'proactive' | Send gzip; discover alternative / lacking support via Accept-Encoding response header, error or success | | 'gzip' / 'deflate' | Use specified encoding directly | | (payload) => ... | Custom transform; server expected to understand |

viem integration

Passive (default):

import { createPublicClient, http } from 'viem';
import { compressModule } from 'eth-compress';

const client = createPublicClient({
  chain: base,
  transport: http(rpcUrl, { fetchFn: compressModule }),
});

Known gzip support:

import { compressModule } from 'eth-compress';

const client = createPublicClient({
  chain: base,
  transport: http(rpcUrl, {
    fetchFn: (url, init) => compressModule(url, init, 'gzip'),
  }),
});

JIT calldata compression:

import { compressModule } from 'eth-compress';
import { compress_call } from 'eth-compress/compressor';

const client = createPublicClient({
  chain: base,
  transport: http(rpcUrl, {
    fetchFn: (url, init) => compressModule(url, init, compress_call),
  }),
});

Compatibility

• Preserves viem semantics: responses and error handling are unchanged; only the request body is compressed.
• Works in Node and modern browsers that support the CompressionStream API. Chrome/Edge ≥ 80; Firefox ≥ 113; Safari/iOS ≥ 16.4

Calldata compression for eth_call

Eligible eth_calls are routed through a transient decompressor contract (injected via stateDiff).

import { compress_call } from 'eth-compress/compressor';

const payload = {
  method: 'eth_call',
  params: [{ to: '0x…', data: '0x…' }, 'latest'],
};

const compressedPayload = compress_call(payload);

Signature

compress_call(payload, alg?, forward?, revert?, clean_env?)

| Param | Type | Default | Description | |---|---|---|---| | payload | any | — | JSON-RPC eth_call payload | | alg | 'jit' \| 'flz' \| 'cd' | auto | Force a specific compression algorithm | | forward | ForwardMode | 'call' | How the decompressor forwards to the target contract | | revert | boolean | false | If true, output data is returned via REVERT instead of RETURN | | clean_env | boolean | false | JIT-only: disable environment opcode substitutions (SELFBALANCE, ADDRESS, CALLER, CALLDATASIZE) |

Forward modes

ForwardMode controls what the generated decompressor bytecode does after decompression. All three algorithms (JIT, FLZ, CD) support the same forward modes.

| forward | revert | Behavior | |---|---|---| | 'call' | false | CALL target contract, RETURN its returndata | | 'call' | true | CALL target contract, REVERT with its returndata | | 'staticcall' | false | STATICCALL target, RETURN its returndata | | 'staticcall' | true | STATICCALL target, REVERT with its returndata | | 'delegatecall' | false | DELEGATECALL target, RETURN its returndata | | 'delegatecall' | true | DELEGATECALL target, REVERT with its returndata | | 'none' | false | RETURN the decompressed data directly (no forwarding) | | 'none' | true | REVERT with the decompressed data directly (no forwarding) |

When forward is 'none', clean_env is forced on — environment opcode substitutions are disabled since there is no forwarded call context.

Examples

Default (CALL + RETURN):

compress_call(payload);

STATICCALL forwarding with FLZ:

compress_call(payload, 'flz', 'staticcall');

DELEGATECALL, revert with returndata:

compress_call(payload, undefined, 'delegatecall', true);

Get decompressed calldata back via REVERT (useful as initcode or for off-chain extraction):

compress_call(payload, 'jit', 'none', true);

Algorithm selection

compress_call can be passed directly to compressModule as a custom transform. For eligible eth_calls, it chooses between:

• JIT: Compiles a one-off decompressor contract that reconstructs calldata word-by-word.

• FLZ: Uses LibZip.flzCompress from solady for FastLZ (LZ77) compression.

• CD: Uses LibZip.cdCompress from solady for calldata run-length encoding.

• Size gating:

  • < 1150 bytes: no compression.
  • ≥ 1150 bytes: compression considered.
  • < ~3000 or ≥ ~8000 bytes: JIT preferred (best ratio at small and large sizes).
  • ~3000 – ~8000 bytes: best of JIT, FLZ, and CD is picked.

• Algorithm choice:

  • For mid-sized payloads, FLZ and CD are tried and the smaller output is chosen.
  • For larger ones, JIT is used directly, prioritizing gas efficiency.
  • The thresholds are tuned for total request size, aiming for the Ethernet MTU.

Important considerations

The calldata compressor is experimental and intended for auxiliary/bulk dApp read-only eth_calls. Use two viem clients to separate concerns.

Compression Ratio & Gas

| Tx Size Range | # Txns | Avg. Tx Size | JIT Ratio | FLZ Ratio | CD Ratio | JIT Gas | FLZ Gas | CD Gas | |---|---|---|---|---|---|---|---|---| | > 8 KB | 129 | 14.92 kb | 2.99x | 3.63x | 2.90x | 8.02k | 211.87k | 78.02k | | 3–8 KB | 260 | 4.82 kb | 2.79x | 2.61x | 2.29x | 4.45k | 89.41k | 29.40k | | 1.15–3 KB | 599 | 2.02 kb | 2.99x | 1.99x | 1.80x | 3.38k | 46.16k | 13.62k |

Excludes txns not compressible to <70% of its original size.

Compression flavors

• JIT calldata compiler: Views calldata as a zero‑initialized memory image and synthesizes bytecode that rebuilds it word-by-word in-place.

  In the first pass it walks the data in 32-byte slices, detects non-zero segments per word, and for each word chooses the cheapest of three strategies: store a literal tail, assemble segments using SHL/OR, or reuse an earlier word via MLOAD/MSTORE.

  In the second pass it materializes this plan into concrete PUSH/MSTORE/SHL/OR/DUP opcodes, pre-seeds the stack with frequently used constants, and appends a small CALL/RETURNDATA stub that forwards the reconstructed calldata to the original to address.

  The 4‑byte selector is right‑aligned in the first 32‑byte slot so that the rest of the calldata can be reconstructed on mostly word‑aligned boundaries, with the decompressor stateDiff being placed at 0xe0 to obtain this common offset from ADDRESS with a single opcode instead of PUSH1 + literal.

• FastLZ (FLZ) and calldata-RLE (CD) forwarders are minimally adapted from Solady's LibZip.sol and inlined as raw bytecode compiled from pure Yul. Both support all forwarding modes (call, staticcall, delegatecall) and the revert flag, with the target address patched into the bytecode at generation time.