Fix potential collisions with merkle map indicies

[MartinMinkov]

Summary

This PR fixes an issue where computing the key of a MerkleMap can lead to a collision between two different field elements. This is because the key is computed with bit reversal, so the key 1 is bit reversed to be 10..000, i.e. 2^254. This can lead to potential collisions since the pasta field is smaller than 2^255 and multiple distinct indices may be associated to multiple keys.

Changes

• Modified the MerkleMap._keyToIndex function to check the size of the key computed and throw an error if it's greater than 2^254
• Modified the property testing unit test for MerkleMaps to expect failure if the input field is greater than 2^254
• Added @example tags to the MerkleMap class

[mitschabaude]

This change will prevent honest users from using keys bigger than 2^254, but we also have to protect against attackers which could go in and modify o1js e.g. remove the assertion you added @MartinMinkov.

So we also have to put the restriction on key size into constraints. The provable part of Merkle maps is MerkleMapWitness with computeRootAndKey().

The easiest option to adapt those is probably to add a new computeRootAndKeyV2() (and deprecate the old version) which contains an additional assertion:

isLefts[0].assertTrue()

All the leaves are "left" nodes because we know the bit vector computed from the key starts with a zero.

To make it more obvious that this forces the computed key to be < 2^254, you could also hard-code what happens in the 0th iteration outside the loop (i.e. the key is still 0), and only start the loop at i=1.

Btw, your change so far is not breaking IMO because keys were always random and < 2^254 in practice and because circuits aren't changed so far.

[mitschabaude]

The eventual fix IMO is to just make MerkleMap a tree of height 255 (instead of 256), and change the witness length from 255 to 254. But that would require us to create complete V2 versions of MerkleMap and MerkleMapWitness, so maybe let's do that at the next version upgrade, when this breaking change is ok and we don't have to maintain the old height-256 version.