Added an example program to derive constraints on shielded reward parameters

[murisi]

Describe your changes

Wrote a Cargo example that derives constraints on shielded reward parameters in order to ensure that end-users get non-zero rewards. Essentially this example takes the native token supply, incentivisation threshold, target locked amount, and locked amount tolerance and computes bounds on inflation, token precision, and nominal proportional gain sufficient to yield non-zero rewards. See the formulas upon which this example program is based at: https://hackmd.io/oqLHjyvwRMaxSD5JJNrB2w#Setting-parameters-to-ensure-non-zero-rewards . This program can be run with the following command: cargo run --example shielded-rewards.

Checklist before merging

• If this PR has some consensus breaking changes, I added the corresponding breaking:: labels
  • This will require 2 reviewers to approve the changes
• If this PR requires changes to the docs or specs, a corresponding PR is opened in the namada-docs repo
  • Relevant PR if applies:
• If this PR affects services such as namada-indexer or namada-masp-indexer, a corresponding PR is opened in that repo
  • Relevant PR if applies:

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 0.00%. Comparing base (f2fb4c7) to head (0b3ae12).
Report is 137 commits behind head on main.

Additional details and impacted files

@@     Coverage Diff      @@
##   main   #4573   +/-   ##
============================
============================

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[batconjurer]

Some nits in the doc strings. Also, I know that this is just an example, but it might actually end up being fairly useful. It will be annoying to have to restart the entire flow because of malformed input. I would suggest two UX improvements: One allow parsing all inputs from a file optionally (this is once users have a rough idea of the inputs and just want to tweak things) and also, instead of eagerly erroring out on bad input, just loop until correct input is given.

[batconjurer]

C is defined below. Consider moving doc string up. Also, S seems to be missing a definition in the doc strings entirely.

[murisi]

Thanks, moved. I think S is defined at https://github.com/anoma/namada/blob/1cb9fccc857d2c0608f01a01fb72518bda9e5b2b/examples/shielded_rewards.rs#L81 .

[brentstone]

@murisi we should merge this if we can, is it ok?

[murisi]

@murisi we should merge this if we can, is it ok?

@brentstone This PR touches a file outside the examples directory in order to have greater control over decimal arithmetic, namely crates/core/src/token.rs. Even if the mathematics and computations in the examples are assumed to be correct (because they have been used successfully in the upgrades), we should try to get at least one approval to the changes in token.rs because an error there could be very problematic.

[brentstone]

@tzemanovic or @batconjurer would you mind reviewing?

[batconjurer]

This is the third time I've been asked to review this with my comments from the first review not being addressed. I'll say it again:
Also, I know that this is just an example, but it might actually end up being fairly useful. It will be annoying to have to restart the entire flow because of malformed input. I would suggest two UX improvements: One allow parsing all inputs from a file optionally (this is once users have a rough idea of the inputs and just want to tweak things) and also, instead of eagerly erroring out on bad input, just loop until correct input is given.

[murisi]

This is the third time I've been asked to review this with my comments from the first review not being addressed. I'll say it again: Also, I know that this is just an example, but it might actually end up being fairly useful. It will be annoying to have to restart the entire flow because of malformed input. I would suggest two UX improvements: One allow parsing all inputs from a file optionally (this is once users have a rough idea of the inputs and just want to tweak things) and also, instead of eagerly erroring out on bad input, just loop until correct input is given.

I really don't know how I missed that comment. My bad. Both ideas (file input and error recovery) are very good. The former is a little awkward to implement because the input range of certain variables depends on the value selected for earlier variables, but I think this can be achieved. Indeed file inputs (and outputs) would also allow us to keep (and share) a record of how the precision parameters were derived. And the latter idea would go with increased input validation (like making sure that numbers are within certain ranges). Thanks for bringing up these points - will work on them today or tomorrow.