CCIP-Read Gateway Reference Implementations

The ens-offchain-registrar repository and its associated gateway packages serve as the reference implementation for EIP-3668 (CCIP-Read) offchain resolution. This codebase is the foundation that operators use to serve name data from environments where onchain storage is impractical or cost-prohibitive, including Layer 2 networks, sidechains, and centralized databases. The gateway acts as a bridge between a client's CCIP-Read-capable library—such as ethers.js or viem—and the offchain data source, translating storage proofs and database queries into the signed responses that clients verify onchain.

Operational compatibility is the primary risk surface. Client libraries evolve their CCIP-Read handling to enforce stricter response validation, adjust gas limit estimation for callback transactions, and change how they interpret gateway errors. A gateway running an outdated version of the reference implementation may produce responses that newer client versions reject silently, causing end-user name resolution to fail without visible errors. This is particularly dangerous for wallets and exchanges where failed resolution can block asset transfers or display incorrect destination addresses.

The reference implementation defines the expected behavior for response signing, error formatting, and ABI-encoded callback data. When gateway operators deviate from this canonical behavior—whether through custom modifications or by lagging behind versioned releases—they introduce fragmentation into the resolution ecosystem. Chainscore Labs reviews gateway deployments against the current reference implementation to identify compatibility gaps, validate response signing logic, and ensure that resolution behavior remains consistent across all client libraries that users depend on.

The ens-offchain-registrar repository provides the canonical reference implementation for building a CCIP-Read (EIP-3668) gateway. This gateway acts as an HTTP intermediary that receives compressed calldata from a client—typically a wallet or dapp using ethers.js or viem—and translates it into a backend database lookup. For ENS, this mechanism is the foundation for resolving names registered on L2s and offchain databases, where the ENS registry on L1 stores only a pointer to the gateway's URL and a resolver address. The gateway must correctly decode the resolve calldata, query its local data store for the corresponding record, and return a signed or unsigned response that the client can verify against the onchain resolver contract.

The operational integrity of this mechanism depends on strict compatibility between the gateway's ABI encoding and the client library's expectations. The reference implementation defines the exact function signatures, response encoding formats, and error handling patterns that gateways must follow. A mismatch in the ABI-encoded response—such as an incorrectly formatted DNS-encoded name or a malformed text() record—causes the client's callback transaction to revert silently. Operators of L2 and offchain name services must track versioned releases of this codebase to ensure their gateways remain compatible with the latest CCIP-Read handling in major libraries. Incompatible gateways cause silent resolution failures for end users, where a name appears registered but returns empty data or a revert.

The gateway also implements the discovery mechanism defined in EIP-3668: the ENS registry entry for an offchain name contains a URL template that clients use to locate the gateway. The reference implementation expects this URL to point to an HTTPS endpoint serving the /{sender}/{data} path pattern. Gateway operators must ensure this endpoint is correctly configured with valid TLS certificates, proper CORS headers for browser-based wallets, and DNS records that match the URL stored onchain. Any mismatch between the onchain URL and the actual gateway endpoint breaks resolution for all users of that name. Chainscore Labs reviews gateway deployments for ABI compatibility, response signing correctness, and endpoint configuration to prevent these failure modes before they reach production.