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 a single leaf node
    • With default mode (0644)
    • No mtime structure
    • Containing a file, named as described above, containing the SSZ-formatted Rewards Tree

Sample Data

A sample .ssz file can be downloaded here.

It has IPFS CID bafybeig4ofwnvou4bgehwzrc27nhfczd2cls5gzejsbliibrwm35owmaca.