chore: Create AuctionStateLens contract to allow for up to date offchain state reads

src/lens/AuctionStateLens.sol

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {IContinuousClearingAuction} from '../interfaces/IContinuousClearingAuction.sol';
+import {Checkpoint} from '../libraries/CheckpointLib.sol';
+
+/// @notice The state of the auction containing the latest checkpoint
+/// as well as the currency raised, total cleared, and whether the auction has graduated
+struct AuctionState {
+    Checkpoint checkpoint;
+    uint256 currencyRaised;
+    uint256 totalCleared;
+    bool isGraduated;
+}
+
+/// @title AuctionStateLens
+/// @notice Lens contract for reading the state of the Auction contract
+contract AuctionStateLens {
+    /// @notice Error thrown when the checkpoint fails
+    error CheckpointFailed();
+    /// @notice Error thrown when the revert reason is not the correct length
+    error InvalidRevertReasonLength();
+
+    /// @notice Function which can be called from offchain to get the latest state of the auction
+    function state(IContinuousClearingAuction auction) external returns (AuctionState memory) {
+        try this.revertWithState(auction) {}
+        catch (bytes memory reason) {
+            return parseRevertReason(reason);
+        }
+    }
+
+    /// @notice Function which checkpoints the auction, gets global values and encodes them into a revert string
+    function revertWithState(IContinuousClearingAuction auction) external {
+        try auction.checkpoint() returns (Checkpoint memory checkpoint) {
+            AuctionState memory _state = AuctionState({
+                checkpoint: checkpoint,
+                currencyRaised: auction.currencyRaised(),
+                totalCleared: auction.totalCleared(),
+                isGraduated: auction.isGraduated()
+            });
+            bytes memory dump = abi.encode(_state);
+
+            assembly {
+                revert(add(dump, 32), mload(dump))
+            }
+        } catch {
+            revert CheckpointFailed();
+        }
+    }
+
+    /// @notice Function which parses the revert reason and returns the AuctionState
+    function parseRevertReason(bytes memory reason) internal pure returns (AuctionState memory) {
+        if (reason.length != 288) {
+            // Bubble up the revert reason if possible
+            if (reason.length > 32) {
+                assembly {
+                    revert(add(reason, 32), mload(reason))
+                }
+            } else {
+                // If the revert reason is too short revert
+                revert InvalidRevertReasonLength();
+            }
+        }
+        return abi.decode(reason, (AuctionState));
+    }
+}

test/lens/AuctionStateLens.t.sol

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+import {IContinuousClearingAuction} from '../../src/interfaces/IContinuousClearingAuction.sol';
+import {AuctionState, AuctionStateLens} from '../../src/lens/AuctionStateLens.sol';
+import {Checkpoint} from '../../src/libraries/CheckpointLib.sol';
+import {FixedPoint96} from '../../src/libraries/FixedPoint96.sol';
+import {AuctionUnitTest} from '../unit/AuctionUnitTest.sol';
+import {Test} from 'forge-std/Test.sol';
+
+contract AuctionStateLensTest is AuctionUnitTest {
+    AuctionStateLens public lens;
+
+    function setUp() public {
+        setUpMockAuction();
+        lens = new AuctionStateLens();
+    }
+
+    function test_state_succeeds() public {
+        uint256 snapshotId = vm.snapshot();
+        Checkpoint memory checkpoint = mockAuction.checkpoint();
+        uint256 expectedCurrencyRaised = mockAuction.currencyRaised();
+        uint256 expectedTotalCleared = mockAuction.totalCleared();
+        bool expectedIsGraduated = mockAuction.isGraduated();
+
+        // Revert to before the checkpoint was created
+        vm.revertTo(snapshotId);
+        // Check that there is no checkpoint on the auction
+        assertEq(mockAuction.lastCheckpointedBlock(), 0);
+        (bool success, bytes memory reason) =
+            address(lens).call(abi.encodeCall(lens.state, (IContinuousClearingAuction(address(mockAuction)))));
+
+        assertEq(success, true);
+        AuctionState memory state = abi.decode(reason, (AuctionState));
+        assertEq(state.checkpoint, checkpoint);
+        assertEq(state.currencyRaised, expectedCurrencyRaised);
+        assertEq(state.totalCleared, expectedTotalCleared);
+        assertEq(state.isGraduated, expectedIsGraduated);
+    }
+
+    function test_state_mirrors_checkpoint() public {
+        uint256 demand = 1e18 << FixedPoint96.RESOLUTION;
+        uint256 price = params.floorPrice + params.tickSpacing;
+        mockAuction.uncheckedSetSumDemandAboveClearing(demand);
+        mockAuction.uncheckedInitializeTickIfNeeded(params.floorPrice, price);
+        mockAuction.uncheckedUpdateTickDemand(price, demand);
+        mockAuction.uncheckedSetNextActiveTickPrice(price);
+
+        vm.roll(block.number + 1);
+
+        uint256 snapshotId = vm.snapshot();
+        Checkpoint memory checkpoint = mockAuction.checkpoint();
+        uint256 expectedCurrencyRaised = mockAuction.currencyRaised();
+        uint256 expectedTotalCleared = mockAuction.totalCleared();
+        bool expectedIsGraduated = mockAuction.isGraduated();
+
+        // Revert to before the checkpoint was created
+        vm.revertTo(snapshotId);
+        // Check that there is no checkpoint on the auction
+        assertEq(mockAuction.lastCheckpointedBlock(), 0);
+        (bool success, bytes memory reason) =
+            address(lens).call(abi.encodeCall(lens.state, (IContinuousClearingAuction(address(mockAuction)))));
+        assertEq(success, true);
+        AuctionState memory state = abi.decode(reason, (AuctionState));
+        assertEq(state.checkpoint, checkpoint);
+        assertEq(state.currencyRaised, expectedCurrencyRaised);
+        assertEq(state.totalCleared, expectedTotalCleared);
+        assertEq(state.isGraduated, expectedIsGraduated);
+    }
+}