ERC-7087 Web3 URL Auto Mode MIME Specification (MIME type for Web3 URL in Auto Mode)

Draft · Other · created 2023-05-28

A standard that, when fetching contract data via a web3:// address, lets a query parameter appended after the address specify the data's format (MIME type) or have a data URL unwrapped for display.

Why it is needed

Web browsers decide whether to render received data as an image, text, or otherwise based on the format information (Content-Type) sent by the server. Without this information, data can be misinterpreted and displayed incorrectly. The web3:// protocol (ERC-6860) allows smart contracts to be accessed like web addresses, and it has manual and auto modes. Contracts in manual mode are built from the start for web3:// and report format information directly, but auto mode also applies to ordinary contracts that were not built with web3:// in mind, so there is no way for them to report format information. As a result, a gap arises where the browser cannot tell what format an image or JSON returned by a contract is in. This standard fills that gap by adding a query parameter on the URL side that specifies the format.

In depth

Background: ERC-6860's Two Modes and the Gap

The web3:// protocol (ERC-6860) has a manual mode and an auto mode. Manual mode is used for contracts that explicitly request that mode via an interface and are expected to report the MIME type of the returned data in the manner described in ERC-6860. Auto mode is used both for contracts that explicitly request that mode and for all other contracts that report nothing. Contracts that explicitly request auto mode can be expected to report a MIME type, but this cannot be expected from the rest. This standard fills that gap with a query parameter on the URL side.

mime.content: Directly Specifying the MIME Type

Used in the form mime.content=<contentType>, where <contentType> is a MIME type as defined in RFC 6838. If <contentType> does not follow the MIME type structure, the URL is not fetched and an error message is shown to the user. After URL decoding, <contentType> is set as the value of the response's Content-Type header. For example, attaching ?mime.content=image/svg%2Bxml sets the Content-Type to image/svg+xml.

mime.type: Specifying by File Extension

Used in the form mime.type=<fileType>, where <fileType> is a file extension used to determine the MIME type. If the extension is not recognized, the URL is not fetched and an error message is shown. If recognized, the corresponding MIME type is set as the value of the Content-Type header. For example, attaching ?mime.type=svg sets the Content-Type to image/svg+xml. Per the ABNF grammar, the value consists of one or more alphanumeric characters.

mime.dataurl: Decoding a Data URL

mime.dataurl is a flag indicating that the returned bytes should be decoded as an RFC 2397 data URL. After decoding, the unwrapped body is returned as the main output, and the MIME type specified within the data URL is used. If the data cannot be interpreted as a data URL, an error is returned. For example, if the contract returns data:application/json,["xx"], the output becomes ["xx"] and the Content-Type is set to application/json.

Parameter Priority Rule

If multiple mime-family query parameters are present, the last parameter applies. If none is specified, the Content-Type is determined as defined by ERC-6860. If the returns query parameter is specified, the mime.xxx parameters are ignored and the Content-Type is determined by ERC-6860. In terms of grammar, this extends ERC-6860's attribute definitions (returns, returnTypes) by adding three new ones: mimeCAttr, mimeTAttr, and mimeDAttr.

Why the Parameters Are Split into Three

The reason three parameters are used instead of one is to avoid confusion. Implementers and users can easily tell the expected return MIME type just by looking at the link. Also, in auto mode, query parameters are not used to construct the EVM message (e.g. calldata), so introducing new query parameters does not affect the contract call and is safe.

Proposal status

This standard is in Draft status. It is still under review and its content may change or progress may stall, so it is best to check the latest status before implementing or depending on it.

Things to watch out for

Original ERC · ← ERCs