Validators: Make bid UX based on Net Reward instead of Reward Percent

[0o-de-lally]

The Proof of Fee design called for the bids to be set with units of coins (either the fee to enter, or the expected net reward).

This feature was never implemented. For expediency the internal variables of the auction (percentage of nominal reward) was exposed to the validators. This interface is a common source of confusion for validators.

Migrating to the default setting being Net Reward will be an improvement in the UX for the validators.

With the changes proposed below it would be easier to reason about the auction.

The auction picks the validators willing to receive the lowest net reward. And as such now the validators can bid with that variable, (instead of using the internal calculation variables).
The validator then must submit a bid that effectively answers: "What's the lowest reward I'm willing to receive as a validator?".
How much are other validators willing to receive.

Changes:

1. Update TX apis in Move proof_of_fee.move to receive the net reward as a variable.
2. Convert the net reward variable to percent bid, and thus reuse internal plumbing.
3. Create view functions so that the explorer can display a validators preferred net_reward (instead of bid).
4. Update Rust cli txs tools so that the net_reward variable is the default mode of bidding.

[0o-de-lally]

First draft:
https://github.com/0o-de-lally/libra-framework/tree/pof_bid_ux

[nelaturuk]

Requirements

Description

This task involves making changes to the Proof of Fee design to improve the user experience (UX) for validators in the 0L blockchain network. The main goal is to simplify how validators place their bids by allowing them to bid directly with the net reward they are willing to accept, instead of using internal percentage-based variables.

Net Reward Formula: In the network, after each epoch, a reward is distributed to the validators in that epoch, called the epoch reward. The net reward is defined as the epoch reward minus the entry fee.

Changes

1. Update Transaction APIs: Modify the proof_of_fee.move file in the Move smart contract to accept the net reward as a variable. This is the key improvement that will allow validators to specify the lowest reward they are willing to accept directly.

2. Convert Net Reward to Percentage: Internally, convert the net reward variable to a percentage bid so that existing internal calculations can still be used. This allows the system to maintain backward compatibility while simplifying the bidding interface.

3. Create View Functions: Add view functions to the smart contract so that explorers (blockchain explorers or any front-end interfaces) can display each validator’s preferred net reward. This makes it easier for validators and others to see the bids in terms of actual rewards rather than abstract percentages.

4. Update Rust CLI Tools: Modify the Rust-based CLI transaction tools to make the net reward variable the default mode of bidding. This simplifies the process for validators using the CLI, aligning with the goal of improving UX.

Acceptance Criteria

Happy Path Tests

1. Validator Bids with Net Reward:

   • Scenario: A validator submits a bid for the lowest net reward they are willing to accept (Net Reward = Epoch Reward - Entry Fee).
   • Expected Outcome: The transaction is successfully processed, and the bid is stored in the blockchain as expected.

2. Bid Conversion to Percentage:

   • Scenario: After the net reward is submitted, the smart contract internally converts it into a percentage bid.
   • Expected Outcome: The conversion is accurate, and the percentage bid is correctly used for internal calculations and comparisons between validators.

3. Validator Selection:

   • Scenario: Validators with the highest bids (lowest net reward) are selected for the next epoch.
   • Expected Outcome: Validators who submitted the most competitive bids (lowest net reward) are chosen, and this is reflected in the blockchain state.

4. View Functions Display Net Reward:

   • Scenario: A blockchain explorer or similar interface queries the validator’s preferred net reward using the new view functions.
   • Expected Outcome: The correct net reward for each validator is displayed, allowing users and validators to see the bids in an easy-to-understand format.

5. CLI Tool Submission:

   • Scenario: A validator uses the Rust CLI tool to submit a bid with the net reward as the default parameter.
   • Expected Outcome: The transaction is submitted successfully, and the validator’s bid is correctly reflected in the blockchain state.

6. Epoch Reward Distribution:

   • Scenario: After the epoch ends, the rewards are distributed to the selected validators based on their net reward bids.
   • Expected Outcome: Validators receive the correct net reward as expected, calculated as the Epoch Reward minus the Entry Fee.

7. Edge Case - Multiple Validators with Same Bid:

   • Scenario: Multiple validators submit the same bid for the net reward.
   • Expected Outcome: To be confimed

8. Edge Case - Validator Entry/Exit:

   • Scenario: Test scenarios where validators enter or exit the pool between epochs.
   • Expected Outcome: The bidding and selection process correctly handles changes in the validator set without errors or inconsistencies.

9. Edge Case - Minimum Net Reward:

   • Scenario: A validator submits a bid at the minimum net reward threshold (if implemented).
   • Expected Outcome: The bid is accepted if it meets the threshold; otherwise, it is rejected with an appropriate error message.

Unhappy Path

1. Invalid Net Reward Bids:

   • Scenario: A validator submits a bid with a net reward that is either negative, zero, or above the maximum allowable reward.
   • Expected Outcome: The system should reject the bid with an appropriate error message, indicating that the bid is invalid.

2. Bid Submission Failures:

   • Scenario: A validator attempts to submit a bid, but due to network issues, insufficient gas fees, or a malfunctioning wallet, the transaction fails.
   • Expected Outcome: The system should either reject the transaction with a clear error message or allow the validator to resubmit the bid once the issue is resolved.

3. Validator Misconfiguration:

   • Scenario: A validator submits a bid with a misconfigured wallet or incorrect account details.
   • Expected Outcome: The bid should be rejected with a clear error message, indicating that the validator's configuration is incorrect.

4. Insufficient Funds for Entry Fee:

   • Scenario: A validator submits a bid, but when the entry fee is deducted, they do not have enough funds in their account.
   • Expected Outcome: The bid should be rejected with a clear error message, and the validator should be informed that they need sufficient funds to participate.

5. Tie in Bids but Insufficient Slots:

   • Scenario: Multiple validators submit identical bids, but there are not enough slots for all of them to be selected for the next epoch.
   • Expected Outcome: The system should handle this situation according to the predefined tie-breaking rules (e.g., prioritize based on stake or submission time). Validators who are not selected should be notified accordingly.

6. Invalid CLI Input:

   • Scenario: A validator uses the CLI tool to submit a bid but inputs incorrect or malformed data (e.g., non-numeric values for the net reward).
   • Expected Outcome: The CLI should validate the input and return a clear error message, preventing the submission of invalid transactions.

7. Network Issues During Bidding:

   • Scenario: The network is congested when validators are submitting bids, leading to delayed or failed transactions.
   • Expected Outcome: The system should handle delayed transactions gracefully, providing validators with feedback and allowing them to retry if necessary.

Open Questions

1. Do we have a minimum net reward threshold?
2. Do we have references for the thermostat document?