Specification for Rewards Tree Files
Specification for Rewards Tree Files
This documents serves as a formal specification for the format and naming of Rewards Tree Files. These files were generated by the oDAO in an implicit format, prior to this specification. This specification serves to define their expected format, naming convention, and CID calcuation methodology.
Contents
The oDAO shall save Rewards Trees in ssz format respecting the following specification.
Containers
File
class File(Container):
magic: Bytes4 # Magic Header identifying this file as a Rewards Tree
# Expected value: 0x52 0x50 0x52 0x54
rewards_file_version: uint64 # Expected value: 3
ruleset_version: uint64 # Expected value: 10 or higher
network: uint64 # Chain ID for the network, e.g., 1 for Mainnet or 17000 for Holešky
# devnet deploys should use a unique id
index: uint64 # Rewards interval index
start_time: uint64 # Unix time of the first slot of the interval
end_time: uint64 # Unix time of the last slot of the interval
consensus_start_block: uint64 # Index of the first non-empty slot of the interval
consensus_end_block: uint64 # Index of the last non-empty slot of the interval
execution_start_block: uint64 # Index of the execution block in ConsensusStartBlock
execution_end_block: uint64 # Index of the execution block in ConsensusEndBlock
intervals_passed: uint64 # Number of rewards intervals contained in the file
merkle_root: Bytes32 # Merkle Tree root of the Rewards Tree
total_rewards: TotalRewards # Aggregate data on values of contained rewards
network_rewards: List[NetworkReward, 128] # L1 and L2 rewards destinations and aggregate amounts
# Sorted ascending by network
claimer_rewards: List[ClaimerReward, 9223372036854775807] # Per-claimer rewards
# Sorted in ascending unsigned numerical order by address
class TotalRewards(Container):
protocol_dao_rpl: uint256 # Amount of RPL sent to the pDAO (in wei)
total_collateral_rpl: uint256 # Amount of RPL sent to claimers for minipool operation (in wei)
total_oracle_dao_rpl: uint256 # Amount of RPL sent to oDAO members (in wei)
total_smoothing_pool_eth: uint256 # Amount of ETH in the Smoothing Pool (in wei)
pool_staker_smoothing_pool_eth: uint256 # Amount of ETH sent to the rETH contract (in wei)
node_operator_smoothing_pool_eth: uint256 # Amount of ETH sent to claimers for Smoothing Pool rewards (in wei)
# The name is retained for backwards compatibility with previous specs
total_node_weight: uint256 # Total Node Weight as defined by RPIP-30 (in wei)
class NetworkReward(Container):
network: uint64 # The L1 or L2 id that this object describes rewards for
# Currently, only mainnet is supported, with id of 0
collateral_rpl: uint256 # Amount of RPL sent to this network for minipool operation (in wei)
oracle_dao_rpl: uint256 # Amount of RPL sent to this network for Oracle DAO rewards (in wei)
smoothing_pool_eth: uint256 # Amount of ETH sent to this network for Smoothing Pool rewards (in wei)
class ClaimerReward(Container):
address: Bytes20 # Address of the claimer that this object describes rewards for
network: uint64 # The L1 or L2 id that the claimer will claim on
# Corresponds to a NetworkReward.network in the File.network_rewards list
# 0 means L1
collateral_rpl: uint256 # RPL staking rewards claimable by this claimer (in wei)
oracle_dao_rpl: uint256 # RPL rewards claimable by this claimer (in wei)
# If all nodes corresponding to this claimer are not in the oDAO, the expected value is 0
smoothing_pool_eth: uint256 # Smoothing Pool ETH claimable by this claimer (in wei)
# If all nodes corresponding to this claimer were not in the smoothing pool during the
# interval, the expected value is 0
Naming
The file SHALL be serialized with the binary representation of the above specified format.
The file SHALL be named rp-rewards-{NETWORK}-{INTERVAL}.ssz
with the following substitutions:
- Substitute the name of the network from the below table for {NETWORK}
- Substitute the number of the interval, in decimal with no leading zeroes, for {INTERVAL}
Networks
Network | {NETWORK} |
---|---|
Mainnet | mainnet |
Holešky | holesky |
devnet | devnet |
CID Calculation
The Oracle DAO SHALL calculate an IPFS CID when submitting the Merkle Root for consensus to the rocketRewardsContract.
The IPFS CID shall be computed with:
- A Merkle DAG
- With a V1 CID Prefix
- With a UnixFS directory node at the root
- With default
mode
(0755) - No
mtime
structure
- With default
- With a single leaf node
- With default
mode
(0644) - No
mtime
structure - Containing a file, named as described above, containing the SSZ-formatted Rewards Tree
- With default
Sample Data
A sample .ssz file can be downloaded here.
It has IPFS CID bafybeig4ofwnvou4bgehwzrc27nhfczd2cls5gzejsbliibrwm35owmaca
.