EIP-7799 System logs
No call decision · Networking & nodes · EIP status Draft · created 2024-10-29
ETH balance changes not tied to a transaction, such as block rewards or withdrawals, are also recorded as block-level system logs, so that the entire history of balance changes can be viewed using eth_getLogs queries alone.
Why it is needed
With EIP-7708 applied, ETH transfers are recorded as logs, letting wallets track balance changes using only eth_getLogs (a function that filters and queries logs accumulated on a node by specified conditions). However, ETH balances can also change without a transaction. Block production rewards and validator withdrawals are prime examples. Because these changes leave no log, a wallet that wants to calculate its balance accurately has to download and check every block header and withdrawal list. This EIP has the protocol itself record a system log directly whenever such a block-level action occurs. As a result, the complete picture of ETH balance changes can be seen using eth_getLogs alone. Block rewards accumulated from priority fees can also be efficiently proven directly from the system log root, without processing and summing every receipt in the block.
What changes
Today
- ETH balance changes that occur without a transaction, such as block rewards and withdrawals, leave no log
- For a wallet to calculate its balance accurately, it must download every block header and withdrawal list
- Block rewards from priority fees can only be known by processing and summing every receipt in the block
After EIP-7799
- Fees, priority fee rewards, withdrawals, and genesis allocations are recorded as block-level system logs
- Wallets can track the entire history of ETH balance changes using only eth_getLogs queries
- Block rewards can be efficiently proven by obtaining them directly from the system log root
Who is affected
- Users: Wallets can view accurate balance change history, including block rewards and withdrawals.
- Wallet & app developers: Balance tracking can be simplified to just eth_getLogs. However, system logs have null transactionHash and transactionIndex, which must be handled.
- Client teams: New fields must be added to the block header, JSON-RPC, Engine API, and the consensus ExecutionPayload, and systemLogsRoot verification must be implemented.
- Validators: Withdrawals and priority fee receipts are recorded as logs, making earnings easier to track.
In depth
Fee payment log (Fee)
For every transaction, one log in the same format as LOG2 is issued, appended after all other logs produced by EVM execution. The amount is the full fee charged during transaction execution, including whatever may be the base fee, priority fee, and blob fee. address is SYSTEM_ADDRESS (0xfffffffffffffffffffffffffffffffffffffffe), topics[0] is 0x7bd3aa7d673767f759ebf216e7f6c12844986c661ae6e0f1d988cf7eb7394d1d, the keccak256 of 'Fee(address,uint256)', topics[1] is the from address (zero-padded to uint256 size), and data is the amount in Wei (big-endian uint256).
Changes to the system log list and block header
A new list, system_logs, is introduced to hold all block-level logs arising from system interactions. It uses the SSZ Log type from EIP-6466 and is defined as ProgressiveList[Log]. A new field, system-logs-root, is added to the execution block header, with the value system_logs.hash_tree_root(). A system_logs_root: Root field is also added to the consensus layer's ExecutionPayload type.
Three kinds of block-level logs: PriorityRewards, Withdrawal, and Genesis
First, when paying out batched priority fees under EIP-8115, a PriorityRewards log SHALL be added to the system log list. topics[0] is 0x5dfe9c0fd3043bb299f97cfece428f0396cf8b7890c525756e4ea5c0ff7d61b2, the keccak256 of 'PriorityRewards(address,uint256)'. Second, a Withdrawal log must be added for every EIP-4895 withdrawal, with topics[0] being 0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65, the keccak256 of 'Withdrawal(address,uint256)'. Third, a network adopting this EIP from genesis must add a Genesis log when creating the genesis block, with topics[0] being 0xba2f6409ffd24dd4df8e06be958ed8c1706b128913be6e417989c74969b0b55a, the keccak256 of 'Genesis(address,uint256)'. For all three logs, address is SYSTEM_ADDRESS, topics[1] is the to address, and data is the amount in Wei.
JSON-RPC API changes
systemLogsRoot (DATA, 32 bytes) is added to the block header object. The log object changes as follows. logIndex continues numbering on from the existing transaction receipt logs for system logs. transactionIndex is also null for system logs, and pending logs can still be distinguished by whether blockHash is null. transactionHash (DATA, 32 bytes) is also null for system logs.
Engine API and verification
systemLogsRoot (DATA, 32 bytes) is added to the version of ExecutionPayload corresponding to the fork adopting this EIP. As part of engine_forkchoiceUpdated, execution layer implementations SHALL verify that each block's systemLogsRoot matches the actual value computed from local processing. This verification is in addition to the existing receiptsRoot verification.
Design rationale and open alternatives
Used together with EIP-7708, wallets can calculate an accurate ETH balance from logs alone, without downloading every block header and withdrawal. Block rewards from priority fees can also be efficiently proven by obtaining them from the system log root, without summing every receipt. The original text also mentions alternatives. Since withdrawal information is duplicated between the existing withdrawals list and the system logs, there is an option to fold the necessary information into the Withdrawal log data and eliminate the withdrawals list itself. It also discusses the possibility that the log definitions themselves could change, aligning plain deposits with the ERC-20 format and withdrawal logs with the deposit log or EIP-7685 request log format.
Compatibility, security, and status
Since a new field is added to the block header, applications that assume a specific block header structure may need updates. Because the address of issued logs is SYSTEM_ADDRESS, it cannot collide with user-controlled smart contracts. This EIP is currently in Draft status, so its content may still change, and the original text itself notes that the log definitions may change. The referenced core developer call records contain no decision on whether to include this EIP in a fork.