Skip to main content

CCIP Gateway

The CCIP Gateway implements ERC-3668 (CCIP-Read) to enable off-chain ENS resolution for subnames.

Overview​

CCIP-Read allows ENS names to resolve to data stored off-chain (in our database) while maintaining the trustless verification properties of on-chain ENS. This enables:

  • Instant registration — No gas fees or blockchain transactions needed
  • Cheap subnames — Storage costs are minimal vs on-chain
  • Full ENS compatibility — Works with all ENS-aware applications

How It Works​

1. User queries alice.aboutme.eth via ENS
2. ENS resolver returns CCIP-Read URL pointing to our gateway
3. Client fetches signed data from gateway
4. Client verifies signature and uses the data

Gateway URL​

https://api.web3identity.com/ccip/\{sender\}/\{data\}.json

Endpoints​

MethodPathDescription
GET/ccip/\{sender\}/\{data\}.jsonCCIP-Read resolver (ERC-3668)
POST/ccipCCIP-Read resolver (alternative)
GET/ccip/healthGateway health check

GET /ccip/{sender}/{data}.json​

ERC-3668 compliant CCIP-Read endpoint. Called automatically by ENS-aware clients.

Parameters​

ParameterTypeLocationDescription
senderstringpathContract address making the request
datastringpathHex-encoded calldata

Response​

{
  "data": "0x...",
  "signature": "0x...",
  "validUntil": 1707580800
}

Example​

# This endpoint is typically called automatically by viem/ethers
curl "https://api.web3identity.com/ccip/0x1234.../0xabcd....json"

POST /ccip​

Alternative CCIP endpoint that accepts parameters in the body.

Request Body​

{
  "sender": "0x1234567890abcdef1234567890abcdef12345678",
  "data": "0xabcdef..."
}

Response​

Same as GET endpoint.

GET /ccip/health​

Check the health status of the CCIP gateway.

Response​

{
  "status": "healthy",
  "recordCount": 156,
  "dbPath": "/path/to/database.db",
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Example​

curl "https://api.web3identity.com/ccip/health"

Client Integration​

import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';
import { normalize } from 'viem/ens';

const client = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// CCIP-Read is handled automatically
const address = await client.getEnsAddress({
  name: normalize('alice.aboutme.eth'),
});

console.log(address); // 0x701B4937e6c943789ffA74CC8601813b2D87B454

ethers.js​

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(
  'https://eth.llamarpc.com',
  { name: 'mainnet', chainId: 1, ensAddress: '0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e' }
);

// CCIP-Read handled automatically
const address = await provider.resolveName('alice.aboutme.eth');
console.log(address);

Direct API (No ENS)​

If you don't need ENS integration, use our direct API:

// Get subname data directly
const response = await fetch(
  'https://api.web3identity.com/api/subnames/aboutme.eth/alice'
);
const data = await response.json();
console.log(data.owner); // 0x701B4937e6c943789ffA74CC8601813b2D87B454

Supported Records​

The CCIP gateway supports these ENS record types:

TypeFunctionDescription
Addressaddr(bytes32)Ethereum address
Texttext(bytes32,string)Text records (description, url, etc.)
Contenthashcontenthash(bytes32)IPFS/IPNS content

Security​

  • Signed responses — All data is cryptographically signed
  • Validity period — Signatures expire to prevent replay attacks
  • On-chain verification — Clients verify signatures against the resolver

Error Responses​

StatusCodeDescription
400CCIP_ERRORInvalid request or data
400INVALID_REQUESTMissing sender or data
500CCIP_ERRORInternal gateway error
500CCIP_HEALTH_ERRORHealth check failed