ERC-7774 Event-driven cache invalidation for web3 URLs (Cache invalidation in ERC-5219 mode Web3 URL)

Draft · Other · created 2024-09-20

An on-chain website opened via a web3:// address signals, through smart contract events, when its cache should be cleared, allowing a stored page to be reused without an RPC call as long as the content has not changed.

Why it is needed

Because a web3:// address fetches a web page from a smart contract, an RPC call to an Ethereum node is required every time the page is opened. This call costs computing resources if you run your own node, costs money if you use a paid external provider, and can disconnect the site if it hits a call rate limit. Normally the web reduces this burden with caching (storing content once received and reusing it), but the ERC-6944 approach does not pass request HTTP headers to the contract, so it cannot handle standard cache validation like If-None-Match or If-Modified-Since. As a result, only a validity period (max-age) can be used, and once that period expires, the entire response must be regenerated via an RPC call on every cache validation request.

What to implement

In depth

Conditions for using the evm-events directive

For an ERC-6944 resolve-mode website to use event-driven caching, it must satisfy three requirements. The response's Cache-Control header must include the evm-events directive, it must also include standard ETag or Cache-Control headers per existing RFC 9111 HTTP caching, and if the response output changes such that the cache needs to be cleared, the contract must emit a cache invalidation event for the affected path. evm-events follows the extension directive format defined in section 5.2.3 of RFC 9111.

Broadening the watch scope with directive values

The value of the evm-events directive is optional and is used to also listen for events from other contracts or other paths. If no value is given, the cache is cleared when the responding contract emits an event for the served path. Writing just a path, as in evm-events="/path/path2", also listens for events on that path, and prefixing a 20-byte contract address starting with 0x also listens for events from that contract. An address alone listens for events that contract emits for the paths it serves. Multiple entries can be listed separated by spaces, so evm-events="/path/path2 /path/path3" clears the cache when an event comes from either path.

The ClearPathCache event and path comparison rules

The cache invalidation event is defined by a single event ClearPathCache(string[] paths), which clears the cache for the paths contained in the array. Each path refers to the pathQuery portion as defined in the ERC-6860 ABNF. A path must not end with /, except when the entire path is the root / alone. Two paths are considered the same if their ERC-5219 resource entries are identical and their parameter values match regardless of order. For example, /test?a=1&b=2 and /test?b=2&a=1 are the same path.

Wildcard rules

Paths may use the * wildcard, but the rules are strict. In resource entries, * can only be used on its own; mixing it with other characters like /t*t causes that entire path to be ignored. * must match at least one character, so /* matches /test but not / or /test/abc, and /test/* matches /test/abc but not /test/ or /test/abc/def. The same rule applies to parameter values, so /abc?a=* matches /abc?a=zz but not /abc?a= or /abc?a=zz&b=cc, and /abc?a=z* is ignored. If the path is just a single *, it is a global wildcard that matches every path on that contract. This restriction to simple cases is meant to make an efficient path lookup implementation easy.

The client's two states and the cache mapping

A web3:// client is in one of two states per chain and contract. In the "listening for events" state, it must listen for cache invalidation events as close to real time as possible; in the "not listening" state (the default when this ERC is not implemented), it ignores all cache validation requests such as If-None-Match and If-Modified-Since. The state can be changed at any time, and heuristics for optimizing RPC usage may be applied. The cache is managed as a mapping keyed by (chain ID, contract address, ERC-6860 pathQuery) to a value of (last modified date, ETag), and it must be cleared when switching from the listening state to the not-listening state. In some cases, such as ERC-7618, the Accept-Encoding request header must also be added to the key.

Handling requests in the listening-for-events state

If there is no mapping entry, the contract is called, and if the response contains an evm-events directive and an ETag, an entry is created with that ETag. If it contains an evm-events directive and a max-age=XX directive, the last modified date is determined with priority given to the Last-Modified header, then the Date header, then the block timestamp at which the contract was queried, and an entry is created with that date; if both are present, a single entry is created containing both the ETag and the last modified date. When an entry exists, if the request's If-None-Match value matches the stored ETag, a 304 Not Modified is returned immediately, and if the stored last modified date is earlier than the If-Modified-Since date, a 304 is likewise returned immediately. If they do not match or neither header is present, the contract is called, the entry is deleted, and it is handled as if no entry existed. When an event arrives, the mapping entry whose path matches is deleted.

Why a separate directive was introduced

To stay as close as possible to standard HTTP, existing HTTP caching headers are reused, but the evm-events directive was added separately as a safeguard. If a website uses only traditional RFC 9111 caching headers and does not emit this ERC's events, a client implementing this ERC would show that site's stale content indefinitely. Limiting event-based caching to sites that explicitly specify the directive avoids this situation.

A proposal still at the draft stage

This ERC is an extension of the ERC-6944 resolve mode, and because it can be added without changing the interface it was attached to that mode; it assumes ERC-5219 and ERC-6944. Future resolve modes that forward request HTTP headers could also implement this ERC. It was registered in September 2024 as a proposal in Draft status, so its content may still change or stall.

Things to watch out for

Original ERC · ← ERCs