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
event ClearPathCache(string[] paths);: An event that signals the cache should be cleared for the paths contained in an array. Each path refers to the pathQuery portion as defined in ERC-6860.
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
- Serving stale content during the delay before an event is reflected: During the delay between when a user transaction that emits a cache deletion event occurs and when the web3:// client receives and processes that event, stale content is served.
- Indefinitely stale content if an event is missed: Websites must correctly implement cache invalidation events for every page that is cached. Otherwise stale content will be served indefinitely.
- Reverting state on a chain reorg: When a chain reorg occurs, the web3:// client must revert its caching state. Otherwise, the reverted content will continue to be served until the next cache deletion event arrives.