blobstream-contracts 0.0.1-security → 3.3.3

package/src/lib/tree/Utils.sol

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+import "./Constants.sol";
+
+/// @notice Calculate the starting bit of the path to a leaf
+/// @param numLeaves : The total number of leaves in the tree
+/// @return startingBit : The starting bit of the path
+// solhint-disable-next-line func-visibility
+function getStartingBit(uint256 numLeaves) pure returns (uint256 startingBit) {
+    // Determine height of the left subtree. This is the maximum path length, so all paths start at this offset from the right-most bit
+    startingBit = 0;
+    while ((1 << startingBit) < numLeaves) {
+        startingBit += 1;
+    }
+    return Constants.MAX_HEIGHT - startingBit;
+}
+
+/// @notice Calculate the length of the path to a leaf
+/// @param key: The key of the leaf
+/// @param numLeaves: The total number of leaves in the tree
+/// @return pathLength : The length of the path to the leaf
+// solhint-disable-next-line func-visibility
+function pathLengthFromKey(uint256 key, uint256 numLeaves) pure returns (uint256 pathLength) {
+    if (numLeaves <= 1) {
+        // if the number of leaves of the tree is 1 or 0, the path always is 0.
+        return 0;
+    }
+    // Get the height of the left subtree. This is equal to the offset of the starting bit of the path
+    pathLength = Constants.MAX_HEIGHT - getStartingBit(numLeaves);
+
+    // Determine the number of leaves in the left subtree
+    uint256 numLeavesLeftSubTree = (1 << (pathLength - 1));
+
+    // If leaf is in left subtree, path length is full height of left subtree
+    if (key <= numLeavesLeftSubTree - 1) {
+        return pathLength;
+    }
+    // If left sub tree has only one leaf but key is not there, path has one additional step
+    else if (numLeavesLeftSubTree == 1) {
+        return 1;
+    }
+    // Otherwise, add 1 to height and recurse into right subtree
+    else {
+        return 1 + pathLengthFromKey(key - numLeavesLeftSubTree, numLeaves - numLeavesLeftSubTree);
+    }
+}
+
+/// @notice Returns the minimum number of bits required to represent `x`; the
+/// result is 0 for `x` == 0.
+/// @param x Number.
+function _bitsLen(uint256 x) pure returns (uint256) {
+    uint256 count = 0;
+
+    while (x != 0) {
+        count++;
+        x >>= 1;
+    }
+
+    return count;
+}
+
+/// @notice Returns the largest power of 2 less than `x`.
+/// @param x Number.
+function _getSplitPoint(uint256 x) pure returns (uint256) {
+    // Note: since `x` is always an unsigned int * 2, the only way for this
+    // to be violated is if the input == 0. Since the input is the end
+    // index exclusive, an input of 0 is guaranteed to be invalid (it would
+    // be a proof of inclusion of nothing, which is vacuous).
+    require(x >= 1);
+
+    uint256 bitLen = _bitsLen(x);
+    uint256 k = 1 << (bitLen - 1);
+    if (k == x) {
+        k >>= 1;
+    }
+    return k;
+}
+
+/// @notice Returns the size of the subtree adjacent to `begin` that does
+/// not overlap `end`.
+/// @param begin Begin index, inclusive.
+/// @param end End index, exclusive.
+function _nextSubtreeSize(uint256 begin, uint256 end) pure returns (uint256) {
+    uint256 ideal = _bitsTrailingZeroes(begin);
+    uint256 max = _bitsLen(end - begin) - 1;
+    if (ideal > max) {
+        return 1 << max;
+    }
+    return 1 << ideal;
+}
+
+/// @notice Returns the number of trailing zero bits in `x`; the result is
+/// 256 for `x` == 0.
+/// @param x Number.
+function _bitsTrailingZeroes(uint256 x) pure returns (uint256) {
+    uint256 mask = 1;
+    uint256 count = 0;
+
+    while (x != 0 && mask & x == 0) {
+        count++;
+        x >>= 1;
+    }
+
+    return count;
+}

package/src/lib/tree/binary/BinaryMerkleMultiproof.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+/// @notice Merkle Tree Proof structure.
+struct BinaryMerkleMultiproof {
+    // List of side nodes to verify and calculate tree.
+    bytes32[] sideNodes;
+    // The (included) beginning key of the leaves to verify.
+    uint256 beginKey;
+    // The (excluded) ending key of the leaves to verify.
+    uint256 endKey;
+}

package/src/lib/tree/binary/BinaryMerkleProof.sol

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+/// @notice Merkle Tree Proof structure.
+struct BinaryMerkleProof {
+    // List of side nodes to verify and calculate tree.
+    bytes32[] sideNodes;
+    // The key of the leaf to verify.
+    uint256 key;
+    // The number of leaves in the tree
+    uint256 numLeaves;
+}

package/src/lib/tree/binary/BinaryMerkleTree.sol

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+import "../Constants.sol";
+import "../Utils.sol";
+import "./TreeHasher.sol";
+import "./BinaryMerkleProof.sol";
+import "./BinaryMerkleMultiproof.sol";
+
+/// @title Binary Merkle Tree.
+library BinaryMerkleTree {
+    /////////////////
+    // Error codes //
+    /////////////////
+
+    enum ErrorCodes {
+        NoError,
+        /// @notice The provided side nodes count is invalid for the proof.
+        InvalidNumberOfSideNodes,
+        /// @notice The provided proof key is not part of the tree.
+        KeyNotInTree,
+        /// @notice Invalid number of leaves in proof.
+        InvalidNumberOfLeavesInProof,
+        /// @notice The proof contains unexpected side nodes.
+        UnexpectedInnerHashes,
+        /// @notice The proof verification expected at least one inner hash.
+        ExpectedAtLeastOneInnerHash
+    }
+
+    ///////////////
+    // Functions //
+    ///////////////
+
+    /// @notice Verify if element exists in Merkle tree, given data, proof, and root.
+    /// @param root The root of the tree in which verify the given leaf.
+    /// @param proof Binary Merkle proof for the leaf.
+    /// @param data The data of the leaf to verify.
+    /// @return `true` is proof is valid, `false` otherwise.
+    /// @dev proof.numLeaves is necessary to determine height of subtree containing the data to prove.
+    function verify(bytes32 root, BinaryMerkleProof memory proof, bytes memory data)
+        internal
+        pure
+        returns (bool, ErrorCodes)
+    {
+        // Check proof is correct length for the key it is proving
+        if (proof.numLeaves <= 1) {
+            if (proof.sideNodes.length != 0) {
+                return (false, ErrorCodes.InvalidNumberOfSideNodes);
+            }
+        } else if (proof.sideNodes.length != pathLengthFromKey(proof.key, proof.numLeaves)) {
+            return (false, ErrorCodes.InvalidNumberOfSideNodes);
+        }
+
+        // Check key is in tree
+        if (proof.key >= proof.numLeaves) {
+            return (false, ErrorCodes.KeyNotInTree);
+        }
+
+        // A sibling at height 1 is created by getting the hash of the data to prove.
+        bytes32 digest = leafDigest(data);
+
+        // Null proof is only valid if numLeaves = 1
+        // If so, just verify hash(data) is root
+        if (proof.sideNodes.length == 0) {
+            if (proof.numLeaves == 1) {
+                return (root == digest, ErrorCodes.NoError);
+            } else {
+                return (false, ErrorCodes.NoError);
+            }
+        }
+
+        (bytes32 computedHash, ErrorCodes error) = computeRootHash(proof.key, proof.numLeaves, digest, proof.sideNodes);
+
+        if (error != ErrorCodes.NoError) {
+            return (false, error);
+        }
+
+        return (computedHash == root, ErrorCodes.NoError);
+    }
+
+    function verifyMulti(bytes32 root, BinaryMerkleMultiproof memory proof, bytes[] memory data)
+        internal
+        pure
+        returns (bool)
+    {
+        bytes32[] memory nodes = new bytes32[](data.length);
+        for (uint256 i = 0; i < data.length; i++) {
+            nodes[i] = leafDigest(data[i]);
+        }
+
+        return verifyMultiHashes(root, proof, nodes);
+    }
+
+    function verifyMultiHashes(bytes32 root, BinaryMerkleMultiproof memory proof, bytes32[] memory leafNodes)
+        internal
+        pure
+        returns (bool)
+    {
+        uint256 leafIndex = 0;
+        bytes32[] memory leftSubtrees = new bytes32[](proof.sideNodes.length);
+
+        for (uint256 i = 0; leafIndex != proof.beginKey && i < proof.sideNodes.length; ++i) {
+            uint256 subtreeSize = _nextSubtreeSize(leafIndex, proof.beginKey);
+            leftSubtrees[i] = proof.sideNodes[i];
+            leafIndex += subtreeSize;
+        }
+
+        uint256 proofRangeSubtreeEstimate = _getSplitPoint(proof.endKey) * 2;
+        if (proofRangeSubtreeEstimate < 1) {
+            proofRangeSubtreeEstimate = 1;
+        }
+
+        (bytes32 rootHash, uint256 proofHead,,) =
+            _computeRootMulti(proof, leafNodes, 0, proofRangeSubtreeEstimate, 0, 0);
+        for (uint256 i = proofHead; i < proof.sideNodes.length; ++i) {
+            rootHash = nodeDigest(rootHash, proof.sideNodes[i]);
+        }
+
+        return (rootHash == root);
+    }
+
+    function _computeRootMulti(
+        BinaryMerkleMultiproof memory proof,
+        bytes32[] memory leafNodes,
+        uint256 begin,
+        uint256 end,
+        uint256 headProof,
+        uint256 headLeaves
+    ) private pure returns (bytes32, uint256, uint256, bool) {
+        // reached a leaf
+        if (end - begin == 1) {
+            // if current range overlaps with proof range, pop and return a leaf
+            if (proof.beginKey <= begin && begin < proof.endKey) {
+                // Note: second return value is guaranteed to be `false` by
+                // construction.
+                return _popLeavesIfNonEmpty(leafNodes, headLeaves, leafNodes.length, headProof);
+            }
+
+            // if current range does not overlap with proof range,
+            // pop and return a proof node (leaf) if present,
+            // else return nil because leaf doesn't exist
+            return _popProofIfNonEmpty(proof.sideNodes, headProof, end, headLeaves);
+        }
+
+        // if current range does not overlap with proof range,
+        // pop and return a proof node if present,
+        // else return nil because subtree doesn't exist
+        if (end <= proof.beginKey || begin >= proof.endKey) {
+            return _popProofIfNonEmpty(proof.sideNodes, headProof, end, headLeaves);
+        }
+
+        // Recursively get left and right subtree
+        uint256 k = _getSplitPoint(end - begin);
+        (bytes32 left, uint256 newHeadProofLeft, uint256 newHeadLeavesLeft,) =
+            _computeRootMulti(proof, leafNodes, begin, begin + k, headProof, headLeaves);
+        (bytes32 right, uint256 newHeadProof, uint256 newHeadLeaves, bool rightIsNil) =
+            _computeRootMulti(proof, leafNodes, begin + k, end, newHeadProofLeft, newHeadLeavesLeft);
+
+        // only right leaf/subtree can be non-existent
+        if (rightIsNil == true) {
+            return (left, newHeadProof, newHeadLeaves, false);
+        }
+        bytes32 hash = nodeDigest(left, right);
+        return (hash, newHeadProof, newHeadLeaves, false);
+    }
+
+    function _popProofIfNonEmpty(bytes32[] memory nodes, uint256 headProof, uint256 end, uint256 headLeaves)
+        private
+        pure
+        returns (bytes32, uint256, uint256, bool)
+    {
+        (bytes32 node, uint256 newHead, bool isNil) = _popIfNonEmpty(nodes, headProof, end);
+        return (node, newHead, headLeaves, isNil);
+    }
+
+    function _popLeavesIfNonEmpty(bytes32[] memory nodes, uint256 headLeaves, uint256 end, uint256 headProof)
+        private
+        pure
+        returns (bytes32, uint256, uint256, bool)
+    {
+        (bytes32 node, uint256 newHead, bool isNil) = _popIfNonEmpty(nodes, headLeaves, end);
+        return (node, headProof, newHead, isNil);
+    }
+
+    function _popIfNonEmpty(bytes32[] memory nodes, uint256 head, uint256 end)
+        private
+        pure
+        returns (bytes32, uint256, bool)
+    {
+        if (nodes.length == 0 || head >= nodes.length || head >= end) {
+            bytes32 node;
+            return (node, head, true);
+        }
+        return (nodes[head], head + 1, false);
+    }
+
+    /// @notice Use the leafHash and innerHashes to get the root merkle hash.
+    /// If the length of the innerHashes slice isn't exactly correct, the result is nil.
+    /// Recursive impl.
+    function computeRootHash(uint256 key, uint256 numLeaves, bytes32 leafHash, bytes32[] memory sideNodes)
+        private
+        pure
+        returns (bytes32, ErrorCodes)
+    {
+        if (numLeaves == 0) {
+            return (leafHash, ErrorCodes.InvalidNumberOfLeavesInProof);
+        }
+        if (numLeaves == 1) {
+            if (sideNodes.length != 0) {
+                return (leafHash, ErrorCodes.UnexpectedInnerHashes);
+            }
+            return (leafHash, ErrorCodes.NoError);
+        }
+        if (sideNodes.length == 0) {
+            return (leafHash, ErrorCodes.ExpectedAtLeastOneInnerHash);
+        }
+        uint256 numLeft = _getSplitPoint(numLeaves);
+        bytes32[] memory sideNodesLeft = slice(sideNodes, 0, sideNodes.length - 1);
+        ErrorCodes error;
+        if (key < numLeft) {
+            bytes32 leftHash;
+            (leftHash, error) = computeRootHash(key, numLeft, leafHash, sideNodesLeft);
+            if (error != ErrorCodes.NoError) {
+                return (leafHash, error);
+            }
+            return (nodeDigest(leftHash, sideNodes[sideNodes.length - 1]), ErrorCodes.NoError);
+        }
+        bytes32 rightHash;
+        (rightHash, error) = computeRootHash(key - numLeft, numLeaves - numLeft, leafHash, sideNodesLeft);
+        if (error != ErrorCodes.NoError) {
+            return (leafHash, error);
+        }
+        return (nodeDigest(sideNodes[sideNodes.length - 1], rightHash), ErrorCodes.NoError);
+    }
+
+    /// @notice creates a slice of bytes32 from the data slice of bytes32 containing the elements
+    /// that correspond to the provided range.
+    /// It selects a half-open range which includes the begin element, but excludes the end one.
+    /// @param _data The slice that we want to select data from.
+    /// @param _begin The beginning of the range (inclusive).
+    /// @param _end The ending of the range (exclusive).
+    /// @return _ the sliced data.
+    function slice(bytes32[] memory _data, uint256 _begin, uint256 _end) internal pure returns (bytes32[] memory) {
+        if (_begin > _end) {
+            revert("Invalid range: _begin is greater than _end");
+        }
+        if (_begin > _data.length || _end > _data.length) {
+            revert("Invalid range: _begin or _end are out of bounds");
+        }
+        bytes32[] memory out = new bytes32[](_end - _begin);
+        for (uint256 i = _begin; i < _end; i++) {
+            out[i - _begin] = _data[i];
+        }
+        return out;
+    }
+}

package/src/lib/tree/binary/TreeHasher.sol

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.22;
+
+import "../Constants.sol";
+
+/// @notice Calculate the digest of a node.
+/// @param left The left child.
+/// @param right The right child.
+/// @return digest The node digest.
+/// @dev More details in https://github.com/celestiaorg/celestia-specs/blob/master/src/specs/data_structures.md#binary-merkle-tree
+// solhint-disable-next-line func-visibility
+function nodeDigest(bytes32 left, bytes32 right) pure returns (bytes32 digest) {
+    digest = sha256(abi.encodePacked(Constants.NODE_PREFIX, left, right));
+}
+
+/// @notice Calculate the digest of a leaf.
+/// @param data The data of the leaf.
+/// @return digest The leaf digest.
+/// @dev More details in https://github.com/celestiaorg/celestia-specs/blob/master/src/specs/data_structures.md#binary-merkle-tree
+// solhint-disable-next-line func-visibility
+function leafDigest(bytes memory data) pure returns (bytes32 digest) {
+    digest = sha256(abi.encodePacked(Constants.LEAF_PREFIX, data));
+}