[Certora] OfferTree Soundness

certora/confs/OfferTreeMembership.conf

@@ -0,0 +1,21 @@
+{
+  "files": [
+    "certora/helpers/OfferTree.sol"
+  ],
+  "verify": "OfferTree:certora/specs/OfferTreeMembership.spec",
+  "solc": "solc-0.8.34",
+  "solc_via_ir": true,
+  "solc_optimize": "200",
+  "solc_evm_version": "osaka",
+  "optimistic_loop": true,
+  "loop_iter": 3,
+  "optimistic_hashing": true,
+  "hashing_length_bound": 1024,
+  "rule_sanity": "basic",
+  "smt_timeout": 7200,
+  "prover_args": [
+    "-splitParallel true",
+    "-s [z3:def{randomSeed=1},z3:def{randomSeed=2},z3:def{randomSeed=3},z3:def{randomSeed=4},z3:def{randomSeed=5}]"
+  ],
+  "msg": "Offer Tree Membership"
+}

certora/confs/OfferTreeWellFormed.conf

@@ -0,0 +1,21 @@
+{
+  "files": [
+    "certora/helpers/OfferTree.sol"
+  ],
+  "verify": "OfferTree:certora/specs/OfferTreeWellFormed.spec",
+  "solc": "solc-0.8.34",
+  "solc_via_ir": true,
+  "solc_optimize": "200",
+  "solc_evm_version": "osaka",
+  "optimistic_loop": true,
+  "loop_iter": 3,
+  "optimistic_hashing": true,
+  "hashing_length_bound": 1024,
+  "rule_sanity": "basic",
+  "smt_timeout": 7200,
+  "prover_args": [
+    "-splitParallel true",
+    "-s [z3:def{randomSeed=1},z3:def{randomSeed=2},z3:def{randomSeed=3},z3:def{randomSeed=4},z3:def{randomSeed=5}]"
+  ],
+  "msg": "OfferTreeWellFormed"
+}

certora/helpers/GenerateRoot.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (c) 2025 Morpho Association
+pragma solidity ^0.8.0;
+
+import {OfferTree} from "./OfferTree.sol";
+import {Offer} from "../../src/interfaces/IMidnight.sol";
+import {HashLib} from "../../src/ratifiers/libraries/HashLib.sol";
+
+contract GenerateRoot is OfferTree {
+    // Build a perfect tree from a non-empty power-of-two list. Duplicate hashes share nodes.
+    function generateRoot(Offer[] memory leaves) public returns (bytes32) {
+        require(leaves.length > 0 && (leaves.length & (leaves.length - 1)) == 0, "invalid leaves length");
+
+        bytes32[] memory level = new bytes32[](leaves.length);
+        for (uint256 i = 0; i < leaves.length; i++) {
+            bytes32 leafHash = HashLib.hashOffer(leaves[i]);
+            if (isEmpty(tree[leafHash])) {
+                newLeaf(leaves[i]);
+            } else {
+                require(isLeafNode(leafHash), "leaf id collision");
+            }
+            level[i] = leafHash;
+        }
+
+        uint256 levelLength = level.length;
+        while (levelLength > 1) {
+            levelLength /= 2;
+            for (uint256 i = 0; i < levelLength; i++) {
+                bytes32 left = level[2 * i];
+                bytes32 right = level[2 * i + 1];
+                bytes32 nodeHash = HashLib.hashNode(left, right);
+                Node storage n = tree[nodeHash];
+                if (isEmpty(n)) {
+                    newInternalNode(nodeHash, left, right);
+                } else {
+                    require(n.left == left && n.right == right && n.hash == nodeHash, "internal node id collision");
+                }
+                level[i] = nodeHash;
+            }
+        }
+
+        return level[0];
+    }
+}

certora/helpers/OfferTree.sol

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+// Copyright (c) 2025 Morpho Association
+pragma solidity ^0.8.0;
+
+import {Offer} from "../../src/interfaces/IMidnight.sol";
+import {HashLib, OFFER_TYPEHASH} from "../../src/ratifiers/libraries/HashLib.sol";
+
+// Fixed-size pre-image of HashLib.hashOffer. Dynamic fields are stored as hashes so CVL can re-hash a leaf
+// without iterating over dynamic data.
+struct Leaf {
+    bytes32 marketHash; // = HashLib.hashMarket(offer.market)
+    bool buy;
+    address maker;
+    uint256 start;
+    uint256 expiry;
+    uint256 tick;
+    bytes32 group;
+    address callback;
+    bytes32 callbackDataHash; // = keccak256(offer.callbackData)
+    address receiverIfMakerIsSeller;
+    address ratifier;
+    bool reduceOnly;
+    uint256 maxUnits;
+    uint256 maxAssets;
+    uint256 continuousFeeCap;
+}
+
+contract OfferTree {
+    struct Node {
+        bytes32 left;
+        bytes32 right;
+        Leaf leaf;
+        // Offer hash for leaves and hash of the children for internal nodes.
+        bytes32 hash;
+    }
+
+    // Leaf ids are offer hashes. Internal node ids may be arbitrary.
+    mapping(bytes32 => Node) internal tree;
+
+    function newLeaf(Offer memory offer) public {
+        bytes32 id = HashLib.hashOffer(offer);
+        require(id != 0, "id is the zero bytes");
+        Node storage n = tree[id];
+        require(isEmpty(n), "leaf is not empty");
+        Leaf storage l = n.leaf;
+        l.marketHash = HashLib.hashMarket(offer.market);
+        l.buy = offer.buy;
+        l.maker = offer.maker;
+        l.start = offer.start;
+        l.expiry = offer.expiry;
+        l.tick = offer.tick;
+        l.group = offer.group;
+        l.callback = offer.callback;
+        l.callbackDataHash = keccak256(offer.callbackData);
+        l.receiverIfMakerIsSeller = offer.receiverIfMakerIsSeller;
+        l.ratifier = offer.ratifier;
+        l.reduceOnly = offer.reduceOnly;
+        l.maxUnits = offer.maxUnits;
+        l.maxAssets = offer.maxAssets;
+        l.continuousFeeCap = offer.continuousFeeCap;
+        n.hash = id;
+    }
+
+    function newInternalNode(bytes32 id, bytes32 left, bytes32 right) public {
+        require(id != 0, "zero id");
+        Node storage n = tree[id];
+        require(isEmpty(n), "node already populated");
+        bytes32 leftHash = tree[left].hash;
+        bytes32 rightHash = tree[right].hash;
+        require(leftHash != 0, "left empty");
+        require(rightHash != 0, "right empty");
+        bytes32 hash = HashLib.hashNode(leftHash, rightHash);
+        require(hash != 0, "zero hash");
+        n.left = left;
+        n.right = right;
+        n.hash = hash;
+    }
+
+    function isEmpty(Node storage n) internal view returns (bool) {
+        return n.hash == 0;
+    }
+
+    function isEmpty(bytes32 id) public view returns (bool) {
+        return isEmpty(tree[id]);
+    }
+
+    function getHash(bytes32 id) public view returns (bytes32) {
+        return tree[id].hash;
+    }
+
+    function isLeafNode(bytes32 id) public view returns (bool) {
+        return tree[id].left == 0 && tree[id].right == 0 && tree[id].hash != 0;
+    }
+
+    function hashOffer(Offer memory offer) public pure returns (bytes32) {
+        return HashLib.hashOffer(offer);
+    }
+
+    function isLeaf(bytes32 root, bytes32 leafHash, uint256 leafIndex, bytes32[] memory proof)
+        public
+        pure
+        returns (bool)
+    {
+        return HashLib.isLeaf(root, leafHash, leafIndex, proof);
+    }
+
+    // Reconstruct HashLib.hashOffer from the stored pre-image.
+    function hashLeaf(Leaf storage l) internal view returns (bytes32) {
+        return keccak256(
+            abi.encode(
+                OFFER_TYPEHASH,
+                l.marketHash,
+                l.buy,
+                l.maker,
+                l.start,
+                l.expiry,
+                l.tick,
+                l.group,
+                l.callback,
+                l.callbackDataHash,
+                l.receiverIfMakerIsSeller,
+                l.ratifier,
+                l.reduceOnly,
+                l.maxUnits,
+                l.maxAssets,
+                l.continuousFeeCap
+            )
+        );
+    }
+
+    // A node is empty, a correctly hashed leaf, or a correctly hashed internal node with two children.
+    function isWellFormed(bytes32 id) public view returns (bool) {
+        Node storage n = tree[id];
+        if (isEmpty(n)) return n.left == 0 && n.right == 0;
+        if (n.left == 0 && n.right == 0) {
+            bytes32 expected = hashLeaf(n.leaf);
+            return n.hash == expected && id == expected;
+        }
+        if (n.left != 0 && n.right != 0) {
+            bytes32 leftHash = tree[n.left].hash;
+            bytes32 rightHash = tree[n.right].hash;
+            return leftHash != 0 && rightHash != 0 && n.hash == HashLib.hashNode(leftHash, rightHash);
+        }
+        return false;
+    }
+
+    // Check the path selected by leafIndex.
+    function wellFormedPath(bytes32 id, uint256 leafIndex, uint256 depth) public view returns (bool) {
+        for (uint256 i = depth;;) {
+            require(isWellFormed(id));
+
+            if (i == 0) break;
+
+            --i;
+            id = ((leafIndex >> i) & 1 == 0) ? tree[id].left : tree[id].right;
+        }
+        return true;
+    }
+}

certora/specs/OfferTreeMembership.spec

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+methods {
+    function getHash(bytes32) external returns (bytes32) envfree;
+    function hashOffer(OfferTree.Offer) external returns (bytes32) envfree;
+    function isLeaf(bytes32, bytes32, uint256, bytes32[]) external returns (bool) envfree;
+    function isLeafNode(bytes32) external returns (bool) envfree;
+    function wellFormedPath(bytes32, uint256, uint256) external returns (bool) envfree;
+}
+
+// Soundness: if a Merkle proof verifies along a well-formed path, hashOffer(offer) must be a leaf node.
+rule membershipSoundness(OfferTree.Offer offer, bytes32 root, uint256 leafIndex, bytes32[] proof) {
+    bytes32 node;
+    require getHash(node) == root, "root is the hash of node";
+    require wellFormedPath(node, leafIndex, proof.length), "the path from the root to the leaf is well-formed";
+    bytes32 leafId = hashOffer(offer);
+    require isLeaf(root, leafId, leafIndex, proof), "Merkle proof verifies the offer";
+
+    assert isLeafNode(leafId);
+}

certora/specs/OfferTreeWellFormed.spec

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+// Leaves store a fixed-size pre-image so isWellFormed can re-hash them without dynamic loops.
+
+methods {
+    function isEmpty(bytes32) external returns (bool) envfree;
+    function isWellFormed(bytes32) external returns (bool) envfree;
+}
+
+// The zero node remains empty.
+strong invariant zeroIsEmpty()
+    isEmpty(to_bytes32(0));
+
+// Every node remains well-formed.
+strong invariant wellFormed(bytes32 id)
+    isWellFormed(id)
+    {
+        preserved {
+            requireInvariant zeroIsEmpty();
+        }
+    }