ERC-6860 Web3 URL to EVM Call Transformation (Web3 URL to EVM Call Message Translation)

Draft · Other · created 2023-09-29

Defines rules for transforming an HTTP-like address such as web3://uniswap.eth/ into a read call on the Ethereum Virtual Machine (EVM). It allows on-chain content to be read directly through a single address, without an intermediary server.

Why it is needed

Today, viewing data stored on the blockchain mostly requires going through Web2-style intermediaries. Proxies such as dapp websites, node service providers, and explorers transform blockchain requests on the user's behalf, but these intermediaries are entities the user cannot control. If an intermediary goes down or displays different content, the user has no way to verify or avoid it. This standard defines a simple way for Web2 users to access on-chain content, especially on-chain web content such as SVG or HTML, directly through a web3:// style address without an intermediary. It also allows interoperation with existing standards that use addresses (URIs), such as SVG and HTML, and lets names, methods, and arguments be written in human-readable form instead of hard-to-read hexadecimal call data. This proposal is an updated version that makes small corrections and clarifications to the existing ERC-4804.

What to implement

In depth

URL structure and the meaning of each part

A Web3 URL is an ASCII string of the form schema "://" [ userinfo "@" ] contractName [ ":" chainid ] pathQuery [ "#" fragment ]. The schema is w3 or web3. userinfo is the From field of the EVM call message; if omitted, 0x0 is used as the sender address. contractName is the To field, either a 20-byte address starting with 0x or a domain name from a name service. For ENS, the method for converting a domain name to an address is defined in ERC-6821; other name services are covered in later ERCs. chainid specifies the chain on which name resolution and the call take place; if omitted, the default chain of the name service used is applied (e.g. 1 for eth), and if no name service is used, the default is 1. fragment is a string for referencing a resource, as in HTTP URLs, and is not passed to the smart contract. This specification defines only read-only semantics (Solidity view functions), leaving state-changing functions for a future extension.

Rules for determining the resolve mode

Once the To address and chainid are determined, the protocol calls the target address's resolveMode() method to check the mode. If the return value is the bytes32 "manual" (0x6d616e75616c0000...), it is manual mode. If the return value is "auto" (0x6175746f0000...), or 0x0000..., or the call itself errors (method not implemented or an internal error in the method), it is auto mode. For any other value, the protocol fails the request with an "unsupported resolve mode" error. In the example, the calldata for this call is keccak("resolveMode()")[0:4], i.e. 0xDD473FAE.

Manual mode: path used as calldata as-is

In manual mode, mPathQuery (the path and optional query), without percent-decoding, is used as-is as the message's calldata. If mPathQuery is empty, "/" (0x2f) is sent. The returned data is treated as ABI-encoded bytes, decoded, and the decoded bytes are returned to the frontend. The default MIME type is text/html, replaced by a type inferred from the fileExtension in the path if one is present. Relative URLs are supported similarly to HTTP, allowing both absolute and relative paths based on the current contract.

Auto mode: encoding methods and arguments with ABI

In auto mode, if aPath is empty or "/", the call is made with empty calldata. Otherwise, a form like /method/arg1/arg2 is encoded using the standard Solidity contract ABI. Arguments follow the grammar [ type "!" ] value, supporting the types bool, int, uint, int<X>, uint<X> (X from 8 to 256 in steps of 8), address, bytes<X> (X from 1 to 32), bytes, and string. If the type is omitted, it is inferred automatically in order: if the value is a number, uint256; if it is 0x plus 32 bytes, bytes32; if it is 0x plus 20 bytes, address; if what follows 0x is neither 20 nor 32 bytes long, bytes; if true/false, bool; otherwise it is treated as an address and resolved as a domain name, returning an unsupported name service error if resolution fails. Relative URLs in auto mode are limited to referring to itself (an empty value), the "/" path, or the full method and arguments only.

The returns attribute and handling of returned data

The returns attribute in the query specifies the format of the returned data and follows the argument-list grammar of an Ethereum ABI function signature (uint and int aliases allowed). If returns is absent or empty, the returned data is treated as ABI-encoded bytes, decoded, and the decoded bytes are returned; the MIME type is undefined by default, but if the last argument is of type string and has a fileExtension, the type is inferred from that extension. If returns=(), the raw bytes are returned as a JSON array of 0x-prefixed hex strings, in the form ["0xXXXXX"]. Otherwise, the data is ABI-decoded according to the specified types and encoded as JSON, following the Ethereum JSON-RPC format: bytes and address as 0x-prefixed hex, integers as the most compact hex form (0 as "0x0"), and booleans and strings using their native JSON types. If the returns attribute appears more than once, the last one applies. returnTypes is an alias for returns but is kept only for backward compatibility with ERC-4804 and its use is not recommended.

Changes from ERC-4804

This ERC is an updated version of ERC-4804. Corrections include fixing the rule that manual mode never parses the path, clarifying that it is parsed for the purpose of determining the MIME type, and fixing that when returns is absent in auto mode, the returned data is treated as bytes rather than bytes32. Clarifications include adding an ABNF grammar definition, detailing the rules for determining the resolve mode, detailing percent-encoding, returned data, and MIME handling in manual mode, and detailing argument encoding and returns handling in auto mode. Changes include removing the ethereum-web3:// and eth-web3:// protocol names, expanding the supported types (ERC-4804 supported only uint256, bytes32, address, bytes, and string), and changing integers to be encoded as 0x-prefixed hex rather than as strings when returns is specified.

Design principles

This standard proposes adding a decentralized presentation layer to Ethereum, using the EVM as a decentralized backend. There are four design principles. Human-readable: using names from a name service instead of addresses, and methods and arguments instead of hexadecimal calldata. Maximally compatible with HTTP URL standards: supporting relative paths, queries, fragments, and percent-encoding so existing browsers can be extended with minimal changes. Simple: instead of specifying types explicitly everywhere, types are inferred automatically using a maximum-likelihood principle, while explicit types are still supported when needed. Flexible: contracts can override the encoding rules to finely control how resources are resolved.

Proposal status

This document is currently in Draft status. It should be considered a proposal whose content may still change.

Original ERC · ← ERCs