web3protocol

Parse and execute ERC-6860 / ERC-4804 web3:// protocol URLs. Used by EVM Browser to browse web3:// on-chain websites.

Usage

import { Client } from 'web3protocol';
import { getDefaultChainList } from 'web3protocol/chains';

// Get a prepared chain list that you can optionally alter, or provide your own
let chainList = getDefaultChainList()

// Configure a client with these chains definitions
let web3Client = new Client(chainList)

let fetchedWeb3Url = await web3Client.fetchUrl("web3://0xA5aFC9fE76a28fB12C60954Ed6e2e5f8ceF64Ff2/resourceName")
// Returns:
// fetchedWeb3Url.httpCode == 200
// fetchedWeb3Url.httpHeaders == {}
// fetchedWeb3Url.output == ReadableStream returning bytes [ 63, 63, 63 ]

Fetch a web3:// URL, get an HTTP status code, HTTP response headers and a ReadableStream.

getDefaultChainList() is provided as a quick way to launch (mix of RPC URLs provided by the Viem.sh library and the chainid.network website), but be aware this could sometimes get out of date.

Apps using web3protocol : web3curl, a simple CURL-like app; EVM Browser, a web3:// electron-based web browser.

Supported standards

Implemented features

ERC-6860 (draft) : the base web3:// protocol with auto and manual mode, basic ENS support. This updates ERC-4804 (final) with clarifications, small fixes and changes.
ERC-6821 (draft) : ENS resolution : support for the contentcontract TXT field to point to a contract in another chain
ERC-6944 (draft) / ERC-5219 (final) : New mode offloading some parsing processing on the browser side
ERC-7617 (draft): Add chunk support in ERC-6944 resource request mode
ERC-7618 (draft): Add Content-encoding handling in ERC-6944 resource request mode
Not standard : Linagee .og domain names

Partially implemented features

ERC-7087 (draft) : Auto mode : Add MIME type support (dataURLs not supported yet)

Options

The client takes the following options:

let web3Client = new Client(chainList, {
  multipleRpcMode: "fallback",
  domainNameResolverCache: {
    maxEntries: 256,
    maxAgeSeconds: 30 * 60,
  },
  resolveModeDeterminatorCache: {
    maxEntries: 256,
    maxAgeSeconds: 30 * 60,
  },
})

multipleRpcMode (fallback or parallel) : If a chain have multiple RPC configured, by default the fallback mode is used (first one is used, then if failure, the second one, and so on). In the parallel mode, a call is sent simultaneously to all RPCs, and the first one answering is used.
domainNameResolverCache: An object of options for domain name resolution caching. May be null to use default options. Otherwise, the object may specify:
- maxEntries: The maximum number of cached entries. After this, the least-recently-used entry is dropped. Use zero to disable caching.
- maxAgeSeconds: The maximum number of seconds before a resolution result is no longer considered valid.
resolveModeDeterminatorCache: An object of options for resolve mode determination caching. May be null to use default options. Otherwise, the object may specify:
- maxEntries: The maximum number of cached entries. After this, the least-recently-used entry is dropped. Use zero to disable caching.
- maxAgeSeconds: The maximum number of seconds before a determination result is no longer considered valid.

If you want to edit the chain list from getDefaultChainList(), to, for example, edit the RPCs of a chain, edit the chain list before giving it to the client :

let chainList = getDefaultChainList()
chainList.find(chain => chain.id == <chainId>).rpcUrls = ['https://<yourRPC>', 'https://<yourSecondRPC>', ...];
let web3Client = new Client(chainList)

Testing

Web3:// test files are located in their own git repository and are imported as a git submodule. After cloning, please run git submodule init and then git submodule update.

Testing is then launched with yarn test