RPIP-52: Rewards Specification v9

RPIPs/RPIP-52.md

@@ -0,0 +1,63 @@
+---
+rpip: 52
+title: Rewards Tree v9 Specification
+description: Specifies how RPL Inflation and Smoothing Pool rewards are allocated to node operators
+author: Jacob Shufro (@jshufro), Ramana Kumar (@xrchz), Joe Clapis (@jcrtp)
+discussions-to: https://dao.rocketpool.net/t/rewards-tree-spec-v9/2928
+status: Draft
+type: Protocol
+created: 2024-04-15
+---
+
+## Abstract
+This RPIP modifies the Rewards Tree Specification described in [RPIP-51](RPIP-51.md) to add formal specifications for the format of the Rewards Tree file.
+This file previously had an unspecified format- the Oracle DAO simply produced equivalent files by way of using the same implementation.
+
+If this RPIP is approved, the Oracle DAO will instead produce files in the manner that it describes.
+
+## Motivation
+Currently, the Oracle DAO arrives at consensus by submitting both a Merkle Root and an IPFS CID for each interval.
+The IPFS CID is determined by the implementation, which means the Oracle DAO must all use the same implementation.
+By specifying the format of Rewards Files, we enable future efforts to diversify Oracle DAO Rewards Tree implementations.
+
+
+## Specification
+
+The Rewards Calculation Specification is unmodified from RPIP-51, as is the Merkle Tree Specification.
+
+* [Rewards Calculation Specification](../assets/rpip-51/rewards-calculation-spec.md)
+* [Merkle Tree Specification](../assets/rpip-51/merkle-tree-spec.md)
+
+The Oracle DAO SHALL additionally implement the following specification for creating a SSZ file and computing its CID.
+
+* [Rewards File Specification](../assets/rpip-52/rewards-file-spec.md)
+
+The Oracle DAO SHALL use this CID in its submissions.
+
+The Oracle DAO SHOULD produce and make available four files during a transitionary phase:
+* The SSZ file
+* A JSON representation of it
+* A JSON Minipool Performance File
+* A compressed copy of the SSZ File
+
+The Oracle DAO SHOULD upload the SSZ File to IPFS.
+
+The Oracle DAO SHOULD upload all four files to a publicly accessible webserver, where individual Node Operators can retrieve them.
+
+The Oracle DAO MAY discontinue publishing the JSON Rewards File after a transitionary period to allow tooling to adopt the new format.
+
+## Rationale
+Currently, the Oracle DAO generates a _Minipool Performance File_ and a _Rewards File_ in JSON.
+Because the JSON is large, the Oracle DAO also compresses these files using a Golang ZSTD library.
+The library they currently use doesn't produce a stable output across versions, which means that the IPFS CID the Oracle DAO comes to consensus on is dependent on use of a specific version of a specific Golang ZSTD library.
+In order to correct this, we specify a format that does not require compression.
+SSZ was chosen for being compact and an Ethereum native format.
+
+Uncompressed SSZ files are about the same size as compressed JSON files for this purpose, with the added benefits of being faster to parse and serialize.
+
+## Reference Implementation
+This specification (Rewards Calculation v9) is implemented by [Treegen](), which is the reference implementation.
+It is also implemented by [Rockettree]().
+
+## Copyright
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

assets/rpip-52/rewards-file-spec.md

@@ -0,0 +1,102 @@
+# 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](../assets/rpip-52/simple-serialize.md) format respecting the following specification.
+
+## Containers
+
+### File
+
+```python
+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
+    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
+    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](https://github.com/ipfs/ipfs-docs/blob/d72c43a545da5e58277cbfb3677ec68d0c9ef568/docs/concepts/merkle-dag.md)
+  * With a [V1 CID Prefix](https://github.com/ipfs/ipfs-docs/blob/d72c43a545da5e58277cbfb3677ec68d0c9ef568/docs/concepts/content-addressing.md#version-1-v1)
+  * With a [UnixFS](https://github.com/ipfs/specs/blob/e4e5754ad4a4bfbb2ebe63f4c27631f573703de0/UNIXFS.md) 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](../assets/rpip-52/rp-rewards-holesky-155.ssz).
+
+It has IPFS CID `bafybeig4ofwnvou4bgehwzrc27nhfczd2cls5gzejsbliibrwm35owmaca`.