[ECO-2618] Finalize emojicoin arena core logic design

[alnoki]

Description

This PR finalizes the Emojicoin Arena Move prototype, adding a README with a
comprehensive design overview.

Per extensive review, it adopts a lightweight data model that provides only the
minimal amount of information to required to enable comprehensive indexing,
as discussed in detail in the README.

Logic updates

1. Add assorted inner abstractions to ease the review process.
2. Eliminate SmartTable structs since they can be a DoS vector.
3. Remove fields, events that are not required for lightweight data model.
4. Require that if a user has locked in since their most recent to an empty
   escrow, they must select lock in on subsequent top-off operations.
5. Allow user to elect lock-in even if they do not ultimately get matched, to
   prevent unexpected abortions.
6. Add exchange rate calculations.
7. Reset available rewards for a melee when it is cranked out.
8. Use integers instead of aggregators since exchange rate calculations require
   queries against both markets and thus inhibit parallelism within a melee
   in the general case.
9. Refactor type checking logic since exchange rate calculations do type checks.
10. Add assorted abstractions, helpers.
11. Add view functions and return unpackers for all core structs.
12. Add test-only fixturing to enable comprehensive state/event mocking.

Test code

1. Add assorted mocking assertion functions.
2. Add additional test coin factories for init_module happy path tests.
3. Add init_module happy path tests for assorted pseudo-random seeds.
4. Add admin function happy path and expected failure tests

Housekeeping

1. Use term active instead of current to indicate a melee that hasn't ended.
2. Update doc comments to link to actual structs, e.g. "Escrow" instead of
   "escrow".
3. Take out error codes used for admin-level guard rails that have since been
   removed.
4. Use compound assignment operators now that they are supported by movefmt
5. Change default melee time to 20 hours for new linear interpolation matching.

Testing

From in src/move/emojicoin_arena:

git ls-files | entr -c sh -c " \
    aptos move compile --dev --move-2  &&
    aptos move fmt \
"

Checklist

• Did you check all checkboxes from the linked Linear task?

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
emojicoin-dot-fun	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 6, 2025 1:15am
emojicoin-dot-fun-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jan 6, 2025 1:15am

[CRBl69]

Look mostly good 👍

Just a couple of DX changes.

[CRBl69]

Could we have octas_initial_value (octas value at time of enter) and octas_current_value (currently octas_value) ?

This would mean that $\rm{octas\_gain} = \rm{octas\_current\_value} - \rm{octas\_initial\_value}$, so no need to include the three other fields (octas_{gain,loss,growth_q64}).

I think it will also be useful to have the initial amount in the frontend.

[alnoki]

Since users can enter multiple times, the initial_value descriptor isn't totally accurate, however I do understand the rationale for using a difference here and for including the reference value octas_entered for the frontend

Mainly the octas_gain field is because that is used for determining the top gains in top_exits fields

[alnoki]

@CRBl69 per the recent lightweight data model we discussed, this can all be done offchain. Note that I even added an example in the new README about indexing PnL and how all the information is there