Implementation for fixReducedOffersV1 amendment

[scottschurr]

High Level Overview of Change

The goal of this amendment is to curtail the occurrence of order books that are blocked by reduced offers.

This commit identifies three ways in which offers can be reduced:

1. A new offer can be partially crossed by existing offers, so the new offer is reduced when placed in the ledger.

2. An in-ledger offer can be partially crossed by a new offer in a transaction. So the in-ledger offer is reduced by the new offer.

3. An in-ledger offer may be under-funded. In this case the in-ledger offer is scaled down to match the available funds.

Reduced offers can block order books if the effective quality of the reduced offer is worse than the quality of the original offer (from the perspective of the taker). It turns out that, for small values, the quality of the reduced offer can be significantly affected by the rounding mode used during scaling computations.

This commit adjusts some rounding modes so that the quality of a reduced offer is always at least as good (from the taker's perspective) as the original offer.

These rounding changes are on an amendment because they will affect transaction outcomes. The amendment is titled fixReducedOffersV1 because additional ways of producing reduced offers may come to light. So there may be a future need for a V2 amendment.

Context of Change

Occasional blocked order books have been a long-standing low-level irritant with the DEX. There has been at least one patch that helped to manage the problem. But the patch did not really make the problem go away. This pull request goes to the root of these blockages and just makes them go away.

First, it's important to recognize that both XRP and IOUs have finite representations in the ledger. For example, it is not possible to represent fractions of drops. IOUs also have a finite representation that becomes apparent with very small or very large numbers. So when a number cannot be precisely represented in XRP or by an IOU it must be rounded.

This pull request changes the rounding mode that is used when calculating a reduced offer. The rounding is changed so that the quality of the reduced offer is always the same or better than the quality of the original offer (viewing the offer's quality from the taker's perspective).

Note that this change affects the values that offers in the ledger contain. However the change in representation is at most either...

1. One drop of XRP or
2. 1e-81 of an IOU.

As the values in offers get tiny, rounding effects can have an outsize influence on the quality of an offer. But the offers are only being adjusted by minute amounts of actual funds.

Type of Change

• [x] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] Tests (tests for the changes are included in this pull request)
• [x] Documentation Updates

I'm calling this a breaking change because outcomes on the DEX are affected. People who care deeply about the specifics of DEX corner cases would do well to understand the consequences of this pull request. The pull request also includes an amendment, which can cause amendment blockage.

I'm unsure whether the Doc team will want to include discussion of the details of this change. But they should be aware of the change and decide for themselves.

[scottschurr]

Rebased to 1.10.0-b1.

[scottschurr]

Thanks for the review @seelabs! I've addressed your comment. I also rebased to 1.10.0-b2 so I could test syncing without being amendment blocked.

[intelliot]

@scottschurr assuming this is still worth doing, could you resolve merge conflicts?

Also, unless @seelabs agrees otherwise, I think we'll want one more C++ reviewer's approval on this PR before merging.

[scottschurr]

@intelliot, this is absolutely worth doing. However after rebasing a number of the tests are failing. I suspect there's fallout from the Number class merge and unification, but I haven't proven that yet. Would you like me to close this until I have the unit tests passing again?

[intelliot]

Yes. Feel free to reach out to Howard if that may be helpful, of course.

[scottschurr]

Closing until newly introduced test failures are resolved.

[intelliot]

Updated to be compatible with Number and opened as a new PR: https://github.com/XRPLF/rippled/pull/4512