feat(access): add on-chain enumeration via EnumerableSet

Author: peterargue

solidity/src/access/Allowlist.sol

@@ -2,24 +2,41 @@
 pragma solidity ^0.8.20;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
-import {IAllowlist} from "./IAllowlist.sol";
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {IAllowlistEnumerable} from "./IAllowlistEnumerable.sol";
 
 /// @title Allowlist
-/// @notice Mapping-backed allowlist of addresses, administered by a single owner.
+/// @notice Enumerable allowlist of addresses, administered by a single owner.
 /// @dev Idempotent edits: re-adding an existing entry (or removing an absent
 ///      one) does not revert and does not emit. Matches OpenZeppelin
 ///      `_grantRole` semantics.
-contract Allowlist is IAllowlist, Ownable {
-    mapping(address account => bool) private _allowed;
+contract Allowlist is IAllowlistEnumerable, Ownable {
+    using EnumerableSet for EnumerableSet.AddressSet;
+
+    EnumerableSet.AddressSet private _allowed;
 
     /// @dev The zero address cannot be allow-listed. (Disallowing the zero address is a no-op.)
     error ZeroAddress();
 
     constructor(address initialOwner) Ownable(initialOwner) {}
 
-    /// @inheritdoc IAllowlist
     function isAllowed(address account) external view returns (bool) {
-        return _allowed[account];
+        return _allowed.contains(account);
+    }
+
+    /// @inheritdoc IAllowlistEnumerable
+    function length() external view returns (uint256) {
+        return _allowed.length();
+    }
+
+    /// @inheritdoc IAllowlistEnumerable
+    function addressAt(uint256 index) external view returns (address) {
+        return _allowed.at(index);
+    }
+
+    /// @inheritdoc IAllowlistEnumerable
+    function values() external view returns (address[] memory) {
+        return _allowed.values();
     }
 
     function allow(address account) external onlyOwner {
@@ -44,15 +61,13 @@ contract Allowlist is IAllowlist, Ownable {
 
     function _allow(address account) internal {
         if (account == address(0)) revert ZeroAddress();
-        if (!_allowed[account]) {
-            _allowed[account] = true;
+        if (_allowed.add(account)) {
             emit AddressAllowed(account);
         }
     }
 
     function _disallow(address account) internal {
-        if (_allowed[account]) {
-            _allowed[account] = false;
+        if (_allowed.remove(account)) {
             emit AddressDisallowed(account);
         }
     }

solidity/src/access/IAllowlistEnumerable.sol

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.20;
+
+import {IAllowlist} from "./IAllowlist.sol";
+
+/// @title IAllowlistEnumerable
+/// @notice Extends IAllowlist with on-chain enumeration of allowed addresses.
+/// @dev Optional capability — consumers that only need membership checks
+///      (`isAllowed`) should depend on the narrower {IAllowlist} interface.
+interface IAllowlistEnumerable is IAllowlist {
+    /// @notice Returns the number of currently allowed addresses.
+    function length() external view returns (uint256);
+
+    /// @notice Returns the allowed address at `index`.
+    /// @dev Reverts on out-of-bounds. Index order is not stable across edits:
+    ///      removing an entry moves the last element into the freed slot
+    ///      (swap-and-pop), so indices should not be treated as identifiers.
+    function addressAt(uint256 index) external view returns (address);
+
+    /// @notice Returns the full set of currently allowed addresses.
+    /// @dev Gas-expensive for large sets. Prefer paginated reads via
+    ///      `length` + `addressAt` from on-chain callers. Safe off-chain via eth_call.
+    function values() external view returns (address[] memory);
+}

solidity/test/Allowlist.t.sol

@@ -239,4 +239,72 @@ contract AllowlistTest is Test {
 
         vm.stopPrank();
     }
+
+    /// @notice length() reflects the current number of allowed addresses.
+    function test_LengthReflectsAddsAndRemoves() public {
+        assertEq(allowlist.length(), 0);
+
+        vm.startPrank(owner);
+        allowlist.allow(alice);
+        assertEq(allowlist.length(), 1);
+        allowlist.allow(bob);
+        assertEq(allowlist.length(), 2);
+        allowlist.allow(alice); // idempotent: no length change
+        assertEq(allowlist.length(), 2);
+        allowlist.disallow(alice);
+        assertEq(allowlist.length(), 1);
+        allowlist.disallow(carol); // absent: no length change
+        assertEq(allowlist.length(), 1);
+        vm.stopPrank();
+    }
+
+    /// @notice addressAt(index) returns an allowed entry; index in [0, length()).
+    function test_AddressAtReturnsAllowedAddress() public {
+        vm.startPrank(owner);
+        allowlist.allow(alice);
+        allowlist.allow(bob);
+        vm.stopPrank();
+
+        address first = allowlist.addressAt(0);
+        address second = allowlist.addressAt(1);
+        // Order is implementation-defined; both must be allowed and distinct.
+        assertTrue(first == alice || first == bob);
+        assertTrue(second == alice || second == bob);
+        assertTrue(first != second);
+    }
+
+    /// @notice addressAt() reverts when index >= length().
+    function test_AddressAtRevertsOnOutOfBounds() public {
+        vm.expectRevert();
+        allowlist.addressAt(0);
+
+        vm.prank(owner);
+        allowlist.allow(alice);
+
+        vm.expectRevert();
+        allowlist.addressAt(1);
+    }
+
+    /// @notice values() returns the full set of allowed addresses (order unspecified).
+    function test_ValuesReturnsFullSet() public {
+        vm.startPrank(owner);
+        allowlist.allow(alice);
+        allowlist.allow(bob);
+        allowlist.allow(carol);
+        allowlist.disallow(bob);
+        vm.stopPrank();
+
+        address[] memory all = allowlist.values();
+        assertEq(all.length, 2);
+
+        bool foundAlice;
+        bool foundCarol;
+        for (uint256 i = 0; i < all.length; ++i) {
+            if (all[i] == alice) foundAlice = true;
+            if (all[i] == carol) foundCarol = true;
+            assertTrue(all[i] != bob);
+        }
+        assertTrue(foundAlice);
+        assertTrue(foundCarol);
+    }
 }