Skip to content

ENS JSON API & Cloudflare Worker written in Rust. Try it out 👇

Notifications You must be signed in to change notification settings

v3xlabs/enstate

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

enstate.rs

📌 API Specification (OpenAPI)

The API specification is available on enstate.rs or locally at {your_site_here}/docs.

🌐 Hosted version

For demonstration purposes (and one-off usage), a hosted instance is made available at https://enstate.rs and a cloudflare worker at https://worker.enstate.rs. This instance is provided as-is and as a gift to the community. Please do not abuse it.

📌 Example

name/luc.eth          name/rescueorg.eth     name/antony.sh
image/vitalik.eth    name/khori.eth             name/helgesson.eth
bulk/address           sse/address                   header/luc.eth

🚀 Getting Started

We believe software should be simple and containerized. Enstate provides you with a lightweight docker container that you can run anywhere.

🐳 Docker

docker run \
  -p 3000:3000 \
  -e REDIS_URL=redis://0.0.0.0:6379 \
  -e RPC_URL=https://rpc.ankr.com/eth \
  ghcr.io/v3xlabs/enstate:1.0.5

🐳 Docker Compose

version: "3.8"
services:
    enstate:
        image: ghcr.io/v3xlabs/enstate:1.0.5
        ports:
            - 3000:3000
        environment:
            - REDIS_URL=redis://redis:6379
            - RPC_URL=https://rpc.ankr.com/eth
        depends_on:
            - redis
    redis:
        image: redis:6.2.5-alpine
        ports:
            - 6379:6379

🦀 Cloudflare Workers

cd worker

Run the worker locally

cp .dev.vars.example .dev.vars

Edit your .dev.vars file at this time to include environment variables for UNIVERSAL_RESOLVER, RPC_URL (optional) and OPENSEA_API_KEY (optional).

To run the worker locally you can now run:

pnpm dev

Deploying to Cloudflare Workers

Create a KV namespace via wrangler or the Cloudflare dashboard.

pnpm wrangler kv:namespace create <YOUR_NAMESPACE>

Copy the id of your newly created KV namespace to your wrangler.toml. The binding value should remain as enstate-1 regardless of what you named yours when you created it.

Deploy the worker:

pnpm wrangler deploy

Upload your secrets:

echo "https://rpc.ankr.com/eth/XXXXXX" | pnpm wrangler secret put RPC_URL
echo "XXXXX" | pnpm wrangler secret put OPENSEA_API_KEY

Additionally, there is a hosted instance available at worker.enstate.rs.

Contributing

Standalone Server

cd server && cargo run -p enstate

Cloudflare Worker

cd worker && pnpm dev

For more information on running the worker locally, please see running Cloudflare Workers locally.

Features

Here is a short summary of the features provided by the Enstate API including limitations.

Avatar & Header Images

An additional avatar field at the top level of the ENSProfile object is provided. This field is a URL to the avatar image, with optional gateway rewrites for IPFS and IPNS hashes.

You can also directly access the avatar image of a user by using the /i/{name} and /h/{name} endpoints.

Contenthash

Currently limited implementation. Only supports ipfs. TODO add support for ipns, swarm, arweave, onion, onion3, skynet

Common Records

For each profile we look up the following records: You can customize the records you want to query by adjusting the PROFILE_RECORDS environment variable. Scoping down the size of this list can drastically improve the performance of your requests.

Record Type Description
description Description
url URL to the profile
name Name of the profile
mail Email address
email Email address
avatar URL to the avatar
header URL to the header image
display Display name
location Location
timezone Timezone
language Language
pronouns Pronouns
com.github GitHub username
org.matrix Matrix username
com.twitter Twitter username
com.discord Discord username
social.bsky Bsky username
io.keybase Keybase username
org.telegram Telegram username
social.mastodon Mastodon username
network.dm3.profile DM3 profile
network.dm3.deliveryService DM3 delivery service

Multichain Support

By default we query profiles for an vast array of chains. You can customize the chains you want to query by adjusting the MULTICOIN_CHAINS environment variable. Forcing it to only chains of interest can drastically improve the performance of your requests.