Web3:// Gateway

A gateway implementation of the web3 access protocol (web3://) that can serve HTTP-style web3 URL for blockchain resource access.

Feature list

• Implements EIP-4804: Web3 URL to EVM Call Message Translation
• Supports EIP-6821: ENS Name for Web3 URL
• Supports contract address or ENS name as the subdomain of a URL
• Supports EIP-5219/EIP-6944: access to contracts with certain interface
• Supports BTC ordinals access by both ordinals id or number
• A Grafana dashboard backed by influxdb
• Caches resolved domain name to save RPC access cost

Build the source

make

Configurations

Before running any test or a product server, you need a copy of config.toml based on config.toml.template, and make changes of your own.

Run all tests

 make test

Running a customized server

You can run the server with parameters that will override configurations in config.toml.

Example 1: w3eth.io (handles ENS on Ethereum mainnet only)

./server \
  -port xx \
  -defaultChain 1 \
  -homePage https://web3url.w3eth.io/ \
  -dbToken xxxxxx

Example 2: w3link.io (for general web3 links)

./server \
  -homePage https://web3url.eth.1.w3link.io/ \
  -dbToken xxxxxx

Supported chains on w3link.io and web3gateway.dev:

ChainID	Chain Name	Short Name
1	Ethereum Mainnet	eth
11155111	Ethereum Testnet Sepolia	sep
100011	QuarkChain L2 Mainnet	qkc-l2
100001	QuarkChain Mainnet Shard 0	qkc-s0
110001	QuarkChain Devnet Shard 0	qkc-d-s0
110011	QuarkChain SWC Delta Testnet	qkc-l2-t
333	EthStorage Mainnet	es-m
3333	EthStorage Testnet	es-t
3337	EthStorage SWC Beta Testnet	es-d
10	Optimism	oeth
11155420	Optimism Sepolia	opsep
42161	Arbitrum One	arb1
9001	Evmos	evmos
9000	Evmos Testnet	evmos-testnet
42170	Arbitrum Nova	arb-nova
56	Binance Smart Chain Mainnet	bnb
97	Binance Smart Chain Testnet	bnbt
43114	Avalanche C-Chain	avax
43113	Avalanche Fuji Testnet	fuji
250	Fantom Opera	ftm
4002	Fantom Testnet	tftm
1666600000	Harmony Mainnet Shard 0	hmy-s0
1666700000	Harmony Testnet Shard 0	hmy-b-s0
137	Polygon Mainnet	matic
80001	Mumbai	maticmum
1402	Polygon zkEVM Testnet	zkevmtest
1088	Metis Andromeda Mainnet	metis-andromed
534351	Scroll L1 Testnet	scr-testl1
534354	Scroll L2 Testnet	scr-prealpha
1513	Story Protocol Testnet	storyprotocoltest
1776	Injective EVM Mainnet	injective
8453	Base Mainnet	base
84532	Base Sepolia	basesep

How to create a wildcard certificate for web3gateway.dev

The gateway now has the capability to generate domain certificates on-the-fly using autocert. However, the wildcard certificates are not supported in this way.

To use a wildcard certificate, we can create it beforehand using certbot.

The steps are as follows:

1. Install certbot and DNS plugin for DigitalOcean

snap install --classic certbot
ln -s /snap/bin/certbot /usr/bin/certbot
snap set certbot trust-plugin-with-root=ok
snap install certbot-dns-digitalocean

Refer to this instruction for detailed information.

2. Setup DigitalOcean API credentials used by Certbot

Go to DigitalOcean website to generate an API token

Create a file /root/.secrets/certbot/digitalocean.ini with the following content:

# DigitalOcean API credentials used by Certbot
dns_digitalocean_token = <digitalocean-token>

Authorize permissions to the file:

chmod 600 /root/.secrets/certbot/digitalocean.ini

3. create certificate：

Before generate certificates by executing the following command, you can update certs.sh to reflect any changes required for the supported chains.

./certs.sh

If successful, some messages like the following will appear where you can find the location of the private key and certificates:

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/1.web3gateway.dev/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/1.web3gateway.dev/privkey.pem
This certificate expires on 2024-12-11.
These files will be updated when the certificate renews.
Certbot has set up a scheduled task to automatically renew this certificate in the background.

By default, the certificate will be renewed 30 days before expiration.

Check if the renew service is running normally：

  certbot renew --dry-run

Autocert configuration

To enable autocert, modify the config.toml file by setting RunAsHttp to false:

RunAsHttp = false

Currently, the autocert module is activated on the web3gateway.dev gateway, using the system certificate and private key generated by certbot:

SystemCertDir = "/etc/letsencrypt/live/1.web3gateway.dev"
KeyFile = "/etc/letsencrypt/live/1.web3gateway.dev/privkey.pem"

In contrast, w3link.io and w3eth.io are running with RunAsHttp set to true, which indicates autocert service is not utilized.

HTTP/HTTPS Proxy Configuration

When running the web3:// gateway behind an HTTPS proxy (such as a reverse proxy or load balancer), you need to configure the IsBehindHttpsProxy setting to ensure proper URL generation.

Configuration Options

• RunAsHttp: Controls whether the server itself runs on HTTP or HTTPS
• IsBehindHttpsProxy: Indicates if the HTTP server is behind an HTTPS proxy

Usage Scenarios

Scenario 1: Direct HTTPS server

RunAsHttp = false
IsBehindHttpsProxy = false

Use this when the server directly handles HTTPS connections with its own certificates.

Scenario 2: Direct HTTP server

RunAsHttp = true
IsBehindHttpsProxy = false

Use this for local development or when the server only handles HTTP traffic.

Scenario 3: HTTP server behind HTTPS proxy

RunAsHttp = true
IsBehindHttpsProxy = true

Use this when the server runs as HTTP internally but is accessed through an HTTPS proxy. This ensures that web3:// URLs are converted to HTTPS gateway URLs instead of HTTP, maintaining proper protocol consistency for end users.