Remove redundant memory usage in Checkpoints

[0xVolosnikov]

Some optimizations, as i wrote in #4512 (comment)

• removed redundant memory usage

Fixes LIB-1187

• Tests
• Documentation
• Changeset entry (run npx changeset add)

[changeset-bot]

🦋 Changeset detected

Latest commit: 6ad3f63

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
openzeppelin-solidity	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[0xVolosnikov]

@Amxx (I apologize for the tagging, this is originally your code, judging by the Git Blame)

I'm very interested in why the library relies on non-strictly increasing order everywhere, like here:

openzeppelin-contracts/contracts/utils/structs/Checkpoints.sol

Line 164 in b2e7bab

if (_unsafeAccess(self, mid)._key > key) {

Based on the descriptions of the functions, it looks like they were created with the expectation that there may be elements with the same keys:

openzeppelin-contracts/contracts/utils/structs/Checkpoints.sol

Line 151 in b2e7bab

* @dev Return the index of the last (most recent) checkpoint with key lower or equal than the search key, or `high` if there is none.

At the same time, the insertion implementation does not allow adding multiple elements with the same key. This, of course, can be done manually by forcibly adding an element to the array. But you can also add an incorrect element (with a decreasing key) in such way. So it doesn't look like there should be multiple elements with the same key in an array in normal use of the library.

If the array is strictly ordered, then it is strange that the search does not handle the case when it hits the desired key (the case of equality). In the worst case, if the array is N long and the target is exactly in the middle, the current implementation will do something like log2(n) - 1 excessive reads of cold storage slots (~2100 gas each).

So with simple example like (keys) [2, 3, 5, 7, 11, 12, 13, 14] i tried two implementations of lowerLookup: current and with separate handling of equality. Gas estimations for lowerLookup(11) (including 21000 “base fee”):
current version: 31712
modified version: 26762

I'm interested if there's a reason not to make such changes.

UPD: created a separate PR for this question: #4544

[Amxx]

I'm very interested in why the library relies on non-strictly increasing order everywhere

That is an interresting question. We always try to be on the safe(r) side. Given that the simplest version of the code (the one that doesn't handle equality) is the safest (it works with more structure) it felt like the better option.

Now, it may reasonable to assume that this will only be used with structures produced using _insert, and in that case we can indeed optimise some runtime cost, at the expense of more complexe code (and some more deployment cost)

@frangio WDYT?

[0xVolosnikov]

force-pushed: removed unchecked blocks for safe arithmetic, since this is a standalone change and would probably be better done in another pull request

[0xVolosnikov]

Created a separate pull request for this question:
#4544

[Amxx]

@frangio Do we merge that for 5.0, or is 5.0 frozen and that goes into 5.1?

[frangio]

I would put this in the bin for 5.1 with other optimizations we haven't merged yet.

[ernestognw]

LGTM, will wait on @Amxx since a couple of changes were made after 5.0