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: 9 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 (even if empty)
    end_time: uint64 # Unix time of the last slot of the interval (even if empty)
    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 consensus_start_block
    execution_end_block: uint64 # Index of the execution block in consensus_end_block
    intervals_passed: uint64 # Number of rewards intervals contained in the file. Normally 1 for a full interval.
                             # If this file represents less than a full interval, the value will be 0.
    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
    node_rewards: List[NodeReward, 9223372036854775807] # Per-node 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 Node Operators (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 send to Node Operators in the Smoothing Pool (in wei)
    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 for Node Operators sent to this network (in wei)
    oracle_dao_rpl: uint256 # Amount of RPL for oDAO Operators sent to this network (in wei)
    smoothing_pool_eth: uint256 # Amount of ETH for Node Operators sent to this network (in wei)

class NodeReward(Container):
    address: Bytes20 # Address of the node that this object describes rewards for
    network: uint64 # The L1 or L2 id that the node will claim on
                    # Corresponds to a NetworkReward.network in the File.network_rewards list
                    # 0 means L1
    collateral_rpl: uint256 # RPL staking rewards earned by this node operator (in wei)
    oracle_dao_rpl: uint256 # RPL rewards earned by this oDAO member (in wei)
                            # If the node is not in the oDAO the expected value is 0
    smoothing_pool_eth: uint256 # Smoothing Pool ETH earned by this node operator (in wei)
                                # If the node was 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
    • Importing files with a fixed-size 1048576 byte chunking strategy and a balanced layout
    • 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.