@towns-protocol/contracts 0.0.330 → 0.0.334

package/README.md

@@ -119,7 +119,7 @@ If you want to interact with anvil via a front end, you will need to add the loc
 **To deploy our contracts to your local base and river instances:**
 
 1. Duplicate `.env.localhost` file in the [contracts](.) folder of the project and rename it to `.env` (this is excluded from git via .gitignore)
-2. Run `export RIVER_ENV="local_multi"` from your terminal
+2. Run `export RIVER_ENV="local_dev"` from your terminal
 3. Execute `./scripts/deploy-contracts.sh` to deploy the entire suite of contracts to your local base-anvil and river-anvil chains
 
 ### Diamond Contract Deployment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towns-protocol/contracts",
-  "version": "0.0.330",
+  "version": "0.0.334",
   "packageManager": "yarn@3.8.0",
   "scripts": {
     "build": "forge build",
@@ -22,7 +22,7 @@
     "@openzeppelin/contracts": "^5.4.0",
     "@openzeppelin/contracts-upgradeable": "^5.4.0",
     "@prb/math": "^4.1.0",
-    "@towns-protocol/diamond": "^0.6.1",
+    "@towns-protocol/diamond": "^0.6.3",
     "@uniswap/permit2": "https://github.com/towns-protocol/permit2/archive/refs/tags/v1.0.0.tar.gz",
     "crypto-lib": "https://github.com/towns-protocol/crypto-lib/archive/refs/tags/v1.0.0.tar.gz",
     "solady": "^0.1.24"
@@ -33,7 +33,7 @@
     "@layerzerolabs/oapp-evm": "^0.3.2",
     "@openzeppelin/merkle-tree": "^1.0.8",
     "@prb/test": "^0.6.4",
-    "@towns-protocol/prettier-config": "^0.0.330",
+    "@towns-protocol/prettier-config": "^0.0.334",
     "@typechain/ethers-v5": "^10.1.1",
     "@wagmi/cli": "^2.2.0",
     "account-abstraction": "https://github.com/eth-infinitism/account-abstraction/archive/refs/tags/v0.7.0.tar.gz",
@@ -56,5 +56,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "f472a3c4a6f67a96e378db552e2880327eef42ba"
+  "gitHead": "8e35a9aabd11b73c165ed5200e0be0f76fdc84bc"
 }

package/scripts/deployments/diamonds/DeployAppRegistry.s.sol

@@ -13,7 +13,6 @@ import {LibString} from "solady/utils/LibString.sol";
 import {DeployMetadata} from "../facets/DeployMetadata.s.sol";
 import {DeployAppRegistryFacet} from "../facets/DeployAppRegistryFacet.s.sol";
 import {DeployUpgradeableBeacon} from "../facets/DeployUpgradeableBeacon.s.sol";
-import {DeploySimpleApp} from "../facets/DeploySimpleApp.s.sol";
 
 // contracts
 import {Diamond} from "@towns-protocol/diamond/src/Diamond.sol";
@@ -99,15 +98,13 @@ contract DeployAppRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
         facetHelper.add("MultiInit");
         facetHelper.add("UpgradeableBeaconFacet");
         facetHelper.add("AppRegistryFacet");
+        facetHelper.add("SimpleApp");
 
-        // Deploy all facets in a batch
         facetHelper.deployBatch(deployer);
 
-        vm.broadcast(deployer);
-        address simpleApp = DeploySimpleApp.deploy();
-
-        // Add feature facets
+        address simpleApp = facetHelper.getDeployedAddress("SimpleApp");
         address facet = facetHelper.getDeployedAddress("UpgradeableBeaconFacet");
+
         addFacet(
             makeCut(facet, FacetCutAction.Add, DeployUpgradeableBeacon.selectors()),
             facet,

package/scripts/deployments/diamonds/DeployBaseRegistry.s.sol

@@ -88,6 +88,9 @@ contract DeployBaseRegistry is IDiamondInitHelper, DiamondHelper, Deployer {
         facetHelper.add("NodeOperatorFacet");
         facetHelper.add("MetadataFacet");
         facetHelper.add("EntitlementChecker");
+
+        facetHelper.deployBatch(deployer);
+
         facetHelper.add("RewardsDistributionV2");
         facetHelper.add("SpaceDelegationFacet");
         facetHelper.add("MainnetDelegation");

package/scripts/deployments/diamonds/DeploySpace.s.sol

@@ -104,17 +104,21 @@ contract DeploySpace is IDiamondInitHelper, DiamondHelper, Deployer {
         facetHelper.add("MembershipFacet");
         facetHelper.add("MembershipMetadata");
         facetHelper.add("EntitlementDataQueryable");
-        facetHelper.add("EntitlementsManager");
-        facetHelper.add("Roles");
-        facetHelper.add("Channels");
 
         // Deploy the first batch of facets
         facetHelper.deployBatch(deployer);
 
+        facetHelper.add("EntitlementsManager");
+        facetHelper.add("Roles");
+        facetHelper.add("Channels");
         facetHelper.add("TokenPausableFacet");
         facetHelper.add("PrepayFacet");
         facetHelper.add("ReferralsFacet");
         facetHelper.add("ReviewFacet");
+
+        // Deploy the second batch of facets
+        facetHelper.deployBatch(deployer);
+
         facetHelper.add("SpaceEntitlementGated");
         facetHelper.add("SwapFacet");
         facetHelper.add("TippingFacet");
@@ -126,7 +130,7 @@ contract DeploySpace is IDiamondInitHelper, DiamondHelper, Deployer {
             facetHelper.add("MockLegacyMembership");
         }
 
-        // Deploy the second batch of facets
+        // Deploy the third batch of facets
         facetHelper.deployBatch(deployer);
 
         // deploy and add facets one by one to avoid stack too deep

package/scripts/deployments/diamonds/DeploySpaceFactory.s.sol

@@ -134,7 +134,7 @@ contract DeploySpaceFactory is IDiamondInitHelper, DiamondHelper, Deployer {
     }
 
     function diamondInitParams(address deployer) public returns (Diamond.InitParams memory) {
-        // Queue up all feature facets for batch deployment
+        // Queue up feature facets for batch deployment
         facetHelper.add("MultiInit");
         facetHelper.add("MetadataFacet");
         facetHelper.add("Architect");
@@ -145,6 +145,10 @@ contract DeploySpaceFactory is IDiamondInitHelper, DiamondHelper, Deployer {
         facetHelper.add("PricingModulesFacet");
         facetHelper.add("ImplementationRegistryFacet");
         facetHelper.add("SCL_EIP6565");
+
+        // Deploy the second batch of facets
+        facetHelper.deployBatch(deployer);
+
         facetHelper.add("WalletLink");
         facetHelper.add("EIP712Facet");
         facetHelper.add("PartnerRegistry");
@@ -157,7 +161,7 @@ contract DeploySpaceFactory is IDiamondInitHelper, DiamondHelper, Deployer {
             facetHelper.add("MockLegacyArchitect");
         }
 
-        // Deploy the feature facets in a batch
+        // Deploy the third batch of facets
         facetHelper.deployBatch(deployer);
 
         if (isAnvil()) {

package/scripts/interactions/InteractAlphaSparse.s.sol

@@ -5,19 +5,13 @@ pragma solidity ^0.8.23;
 import {IDiamondCut} from "@towns-protocol/diamond/src/facets/cut/IDiamondCut.sol";
 import {IDiamondInitHelper} from "../deployments/diamonds/IDiamondInitHelper.sol";
 
-import {DiamondHelper} from "@towns-protocol/diamond/scripts/common/helpers/DiamondHelper.s.sol";
-import {Diamond} from "@towns-protocol/diamond/src/Diamond.sol";
-
 // libraries
+import {console} from "forge-std/console.sol";
 import {stdJson} from "forge-std/StdJson.sol";
-import "forge-std/console.sol";
 
 // contracts
-
 import {AlphaHelper, DiamondFacetData, FacetData} from "scripts/interactions/helpers/AlphaHelper.sol";
-
 import {DeployBaseRegistry} from "scripts/deployments/diamonds/DeployBaseRegistry.s.sol";
-
 import {DeployRiverAirdrop} from "scripts/deployments/diamonds/DeployRiverAirdrop.s.sol";
 import {DeploySpace} from "scripts/deployments/diamonds/DeploySpace.s.sol";
 import {DeploySpaceFactory} from "scripts/deployments/diamonds/DeploySpaceFactory.s.sol";
@@ -99,7 +93,7 @@ contract InteractAlphaSparse is AlphaHelper {
         uint256 updatedDiamondLen = abi.decode(vm.parseJson(jsonData, ".numUpdated"), (uint256));
         DiamondFacetData[] memory diamonds = new DiamondFacetData[](updatedDiamondLen);
 
-        for (uint256 i = 0; i < updatedDiamondLen; i++) {
+        for (uint256 i; i < updatedDiamondLen; ++i) {
             // Decode diamond name and number of facets
             DiamondFacetData memory diamondData = abi.decode(
                 vm.parseJson(jsonData, string.concat("$.updated[", vm.toString(i), "]")),
@@ -143,7 +137,7 @@ contract InteractAlphaSparse is AlphaHelper {
         console.log("interact::diamonds decoded", diamonds.length);
 
         // Iterate over diamonds array and process each diamond
-        for (uint256 i = 0; i < diamonds.length; i++) {
+        for (uint256 i; i < diamonds.length; ++i) {
             console.log("interact::diamondName", diamonds[i].diamond);
             string memory diamondName = diamonds[i].diamond;
             address diamondDeployedAddress;
@@ -152,7 +146,7 @@ contract InteractAlphaSparse is AlphaHelper {
             string[] memory facetNames = new string[](numFacets);
             address[] memory facetAddresses = new address[](numFacets);
 
-            for (uint256 j = 0; j < numFacets; j++) {
+            for (uint256 j; j < numFacets; ++j) {
                 FacetData memory facetData = diamonds[i].facets[j];
                 facetAddresses[j] = facetData.deployedAddress;
                 facetNames[j] = facetData.facetName;

package/scripts/interactions/InteractBaseAlpha.s.sol

@@ -5,6 +5,7 @@ pragma solidity ^0.8.23;
 import {IDiamondCut} from "@towns-protocol/diamond/src/facets/cut/IDiamondCut.sol";
 
 // libraries
+import {console} from "forge-std/console.sol";
 
 // contracts
 import {DeployBaseRegistry} from "scripts/deployments/diamonds/DeployBaseRegistry.s.sol";
@@ -12,6 +13,7 @@ import {DeployRiverAirdrop} from "scripts/deployments/diamonds/DeployRiverAirdro
 import {DeploySpace} from "scripts/deployments/diamonds/DeploySpace.s.sol";
 import {DeploySpaceFactory} from "scripts/deployments/diamonds/DeploySpaceFactory.s.sol";
 import {DeploySpaceOwner} from "scripts/deployments/diamonds/DeploySpaceOwner.s.sol";
+import {DeployAppRegistry} from "scripts/deployments/diamonds/DeployAppRegistry.s.sol";
 import {AlphaHelper} from "scripts/interactions/helpers/AlphaHelper.sol";
 
 contract InteractBaseAlpha is AlphaHelper {
@@ -20,64 +22,153 @@ contract InteractBaseAlpha is AlphaHelper {
     DeployBaseRegistry deployBaseRegistry = new DeployBaseRegistry();
     DeploySpaceOwner deploySpaceOwner = new DeploySpaceOwner();
     DeployRiverAirdrop deployRiverAirdrop = new DeployRiverAirdrop();
+    DeployAppRegistry deployAppRegistry = new DeployAppRegistry();
 
     function __interact(address deployer) internal override {
+        vm.pauseGasMetering();
+
         address space = getDeployment("space");
         address spaceOwner = getDeployment("spaceOwner");
         address spaceFactory = getDeployment("spaceFactory");
         address baseRegistry = getDeployment("baseRegistry");
         address riverAirdrop = getDeployment("riverAirdrop");
-
-        vm.pauseGasMetering();
-        removeRemoteFacets(deployer, space);
-        removeRemoteFacets(deployer, spaceOwner);
-        removeRemoteFacets(deployer, spaceFactory);
-        removeRemoteFacets(deployer, baseRegistry);
-        removeRemoteFacets(deployer, riverAirdrop);
+        address appRegistry = getDeployment("appRegistry");
 
         deploySpaceCuts(deployer, space);
         deploySpaceOwnerCuts(deployer, spaceOwner);
         deploySpaceFactoryCuts(deployer, spaceFactory);
         deployBaseRegistryCuts(deployer, baseRegistry);
         deployRiverAirdropCuts(deployer, riverAirdrop);
+        deployAppRegistryCuts(deployer, appRegistry);
 
         vm.resumeGasMetering();
     }
 
     function deploySpaceCuts(address deployer, address space) internal {
+        console.log("[INFO]: === Upgrading Space diamond ===");
         deploySpace.diamondInitParams(deployer);
-        FacetCut[] memory newCuts = deploySpace.getCuts();
-        vm.broadcast(deployer);
-        IDiamondCut(space).diamondCut(newCuts, address(0), "");
+        FacetCut[] memory proposedCuts = deploySpace.getCuts();
+        FacetCut[] memory smartCuts = generateSmartCuts(space, proposedCuts);
+
+        console.log(
+            "[INFO]: Generated %d smart cuts from %d proposed cuts",
+            smartCuts.length,
+            proposedCuts.length
+        );
+
+        if (smartCuts.length > 0) {
+            vm.broadcast(deployer);
+            IDiamondCut(space).diamondCut(smartCuts, address(0), "");
+            console.log("[INFO]: \u2705 Space diamond upgrade completed");
+        } else {
+            console.log("[INFO]: Space diamond already up to date - no cuts needed");
+        }
     }
 
     function deploySpaceOwnerCuts(address deployer, address spaceOwner) internal {
+        console.log("[INFO]: === Upgrading SpaceOwner diamond ===");
         deploySpaceOwner.diamondInitParams(deployer);
-        FacetCut[] memory newCuts = deploySpaceOwner.getCuts();
-        vm.broadcast(deployer);
-        IDiamondCut(spaceOwner).diamondCut(newCuts, address(0), "");
+        FacetCut[] memory proposedCuts = deploySpaceOwner.getCuts();
+        FacetCut[] memory smartCuts = generateSmartCuts(spaceOwner, proposedCuts);
+
+        console.log(
+            "[INFO]: Generated %d smart cuts from %d proposed cuts",
+            smartCuts.length,
+            proposedCuts.length
+        );
+
+        if (smartCuts.length > 0) {
+            vm.broadcast(deployer);
+            IDiamondCut(spaceOwner).diamondCut(smartCuts, address(0), "");
+            console.log("[INFO]: \u2705 SpaceOwner diamond upgrade completed");
+        } else {
+            console.log("[INFO]: SpaceOwner diamond already up to date - no cuts needed");
+        }
     }
 
     function deploySpaceFactoryCuts(address deployer, address spaceFactory) internal {
+        console.log("[INFO]: === Upgrading SpaceFactory diamond ===");
         deploySpaceFactory.diamondInitParams(deployer);
-        FacetCut[] memory newCuts = deploySpaceFactory.getCuts();
-        address spaceFactoryInit = deploySpaceFactory.spaceFactoryInit();
-        bytes memory initData = deploySpaceFactory.spaceFactoryInitData();
-        vm.broadcast(deployer);
-        IDiamondCut(spaceFactory).diamondCut(newCuts, spaceFactoryInit, initData);
+        FacetCut[] memory proposedCuts = deploySpaceFactory.getCuts();
+        FacetCut[] memory smartCuts = generateSmartCuts(spaceFactory, proposedCuts);
+
+        console.log(
+            "[INFO]: Generated %d smart cuts from %d proposed cuts",
+            smartCuts.length,
+            proposedCuts.length
+        );
+
+        if (smartCuts.length > 0) {
+            address spaceFactoryInit = deploySpaceFactory.spaceFactoryInit();
+            bytes memory initData = deploySpaceFactory.spaceFactoryInitData();
+            vm.broadcast(deployer);
+            IDiamondCut(spaceFactory).diamondCut(smartCuts, spaceFactoryInit, initData);
+            console.log("[INFO]: \u2705 SpaceFactory diamond upgrade completed");
+        } else {
+            console.log("[INFO]: SpaceFactory diamond already up to date - no cuts needed");
+        }
     }
 
     function deployBaseRegistryCuts(address deployer, address baseRegistry) internal {
+        console.log("[INFO]: === Upgrading BaseRegistry diamond ===");
         deployBaseRegistry.diamondInitParams(deployer);
-        FacetCut[] memory newCuts = deployBaseRegistry.getCuts();
-        vm.broadcast(deployer);
-        IDiamondCut(baseRegistry).diamondCut(newCuts, address(0), "");
+        FacetCut[] memory proposedCuts = deployBaseRegistry.getCuts();
+        FacetCut[] memory smartCuts = generateSmartCuts(baseRegistry, proposedCuts);
+
+        console.log(
+            "[INFO]: Generated %d smart cuts from %d proposed cuts",
+            smartCuts.length,
+            proposedCuts.length
+        );
+
+        if (smartCuts.length > 0) {
+            vm.broadcast(deployer);
+            IDiamondCut(baseRegistry).diamondCut(smartCuts, address(0), "");
+            console.log("[INFO]: \u2705 BaseRegistry diamond upgrade completed");
+        } else {
+            console.log("[INFO]: BaseRegistry diamond already up to date - no cuts needed");
+        }
     }
 
     function deployRiverAirdropCuts(address deployer, address riverAirdrop) internal {
+        console.log("[INFO]: === Upgrading RiverAirdrop diamond ===");
         deployRiverAirdrop.diamondInitParams(deployer);
-        FacetCut[] memory newCuts = deployRiverAirdrop.getCuts();
-        vm.broadcast(deployer);
-        IDiamondCut(riverAirdrop).diamondCut(newCuts, address(0), "");
+        FacetCut[] memory proposedCuts = deployRiverAirdrop.getCuts();
+        FacetCut[] memory smartCuts = generateSmartCuts(riverAirdrop, proposedCuts);
+
+        console.log(
+            "[INFO]: Generated %d smart cuts from %d proposed cuts",
+            smartCuts.length,
+            proposedCuts.length
+        );
+
+        if (smartCuts.length > 0) {
+            vm.broadcast(deployer);
+            IDiamondCut(riverAirdrop).diamondCut(smartCuts, address(0), "");
+            console.log("[INFO]: \u2705 RiverAirdrop diamond upgrade completed");
+        } else {
+            console.log("[INFO]: RiverAirdrop diamond already up to date - no cuts needed");
+        }
+    }
+
+    function deployAppRegistryCuts(address deployer, address appRegistry) internal {
+        console.log("[INFO]: === Upgrading AppRegistry diamond ===");
+        deployAppRegistry.diamondInitParams(deployer);
+        FacetCut[] memory proposedCuts = deployAppRegistry.getCuts();
+        FacetCut[] memory smartCuts = generateSmartCuts(appRegistry, proposedCuts);
+
+        console.log(
+            "[INFO]: Generated %d smart cuts from %d proposed cuts",
+            smartCuts.length,
+            proposedCuts.length
+        );
+
+        if (smartCuts.length > 0) {
+            vm.broadcast(deployer);
+            IDiamondCut(appRegistry).diamondCut(smartCuts, address(0), "");
+            console.log("[INFO]: \u2705 AppRegistry diamond upgrade completed");
+        } else {
+            console.log("[INFO]: AppRegistry diamond already up to date - no cuts needed");
+        }
     }
 }

package/scripts/interactions/helpers/AlphaHelper.sol

@@ -9,9 +9,12 @@ import {IERC173} from "@towns-protocol/diamond/src/facets/ownable/IERC173.sol";
 import {IOwnablePending} from "@towns-protocol/diamond/src/facets/ownable/pending/IOwnablePending.sol";
 
 // libraries
+import {EnumerableSet} from "@openzeppelin/contracts/utils/structs/EnumerableSet.sol";
+import {DynamicArrayLib} from "solady/utils/DynamicArrayLib.sol";
 
 // contracts
 import {DiamondHelper} from "@towns-protocol/diamond/scripts/common/helpers/DiamondHelper.s.sol";
+import {DiamondCutStorage} from "@towns-protocol/diamond/src/facets/cut/DiamondCutStorage.sol";
 import {Diamond} from "@towns-protocol/diamond/src/Diamond.sol";
 import {Interaction} from "scripts/common/Interaction.s.sol";
 
@@ -31,6 +34,18 @@ struct FacetData {
 }
 
 abstract contract AlphaHelper is Interaction, DiamondHelper, IDiamondLoupeBase {
+    using DynamicArrayLib for DynamicArrayLib.DynamicArray;
+    using EnumerableSet for EnumerableSet.AddressSet;
+    using EnumerableSet for EnumerableSet.Bytes32Set;
+
+    struct DiamondInfo {
+        DiamondCutStorage.Layout layout;
+        mapping(bytes4 selector => bool isCore) coreSelectors;
+        mapping(bytes4 selector => bool isProposed) proposedSelectors;
+    }
+
+    mapping(address diamond => DiamondInfo info) private diamondInfos;
+
     /// @notice Get addresses of core facets that should never be removed
     /// @param diamond The diamond contract address
     /// @return coreFacets An array of core facet addresses
@@ -54,12 +69,7 @@ abstract contract AlphaHelper is Interaction, DiamondHelper, IDiamondLoupeBase {
         address facetAddress,
         address[] memory coreFacets
     ) internal pure returns (bool) {
-        for (uint256 i; i < coreFacets.length; ++i) {
-            if (facetAddress == coreFacets[i]) {
-                return true;
-            }
-        }
-        return false;
+        return contains(coreFacets, facetAddress);
     }
 
     /// @notice Execute a diamond cut to remove facets
@@ -88,13 +98,7 @@ abstract contract AlphaHelper is Interaction, DiamondHelper, IDiamondLoupeBase {
                 continue;
             }
 
-            addCut(
-                FacetCut({
-                    facetAddress: facet,
-                    action: FacetCutAction.Remove,
-                    functionSelectors: facets[i].selectors
-                })
-            );
+            addCut(FacetCut(facet, FacetCutAction.Remove, facets[i].selectors));
         }
 
         executeDiamondCut(deployer, diamond);
@@ -128,15 +132,137 @@ abstract contract AlphaHelper is Interaction, DiamondHelper, IDiamondLoupeBase {
             }
 
             if (contains(facetAddresses, facet)) {
-                addCut(
-                    FacetCut({
-                        facetAddress: facet,
-                        action: FacetCutAction.Remove,
-                        functionSelectors: facets[i].selectors
-                    })
-                );
+                addCut(FacetCut(facet, FacetCutAction.Remove, facets[i].selectors));
+            }
+        }
+    }
+
+    /// @notice Generate smart cuts by comparing proposed cuts with existing diamond state
+    function generateSmartCuts(
+        address diamond,
+        FacetCut[] memory proposedCuts
+    ) internal returns (FacetCut[] memory) {
+        buildDiamondInfo(diamond, proposedCuts);
+
+        // Collect cuts to execute
+        clearCuts();
+
+        for (uint256 i; i < proposedCuts.length; ++i) {
+            processFacetCut(diamond, proposedCuts[i]);
+        }
+
+        addRemovalCuts(diamond);
+
+        return baseFacets();
+    }
+
+    /// @notice Build diamond facet mapping from current state
+    function buildDiamondInfo(address diamond, FacetCut[] memory proposedCuts) internal {
+        DiamondInfo storage info = diamondInfos[diamond];
+
+        Facet[] memory facets = IDiamondLoupe(diamond).facets();
+        address[] memory coreFacetAddresses = getCoreFacetAddresses(diamond);
+
+        for (uint256 i; i < facets.length; ++i) {
+            address facetAddr = facets[i].facet;
+            bytes4[] memory selectors = facets[i].selectors;
+            bool isCore = contains(coreFacetAddresses, facetAddr);
+
+            info.layout.facets.add(facetAddr);
+
+            for (uint256 j; j < selectors.length; ++j) {
+                bytes4 selector = selectors[j];
+                info.layout.facetBySelector[selector] = facetAddr;
+                info.layout.selectorsByFacet[facetAddr].add(selector);
+
+                if (isCore) info.coreSelectors[selector] = true;
             }
         }
+
+        // Mark all selectors in proposed cuts as handled
+        for (uint256 i; i < proposedCuts.length; ++i) {
+            bytes4[] memory selectors = proposedCuts[i].functionSelectors;
+            for (uint256 j; j < selectors.length; ++j) {
+                info.proposedSelectors[selectors[j]] = true;
+            }
+        }
+    }
+
+    /// @notice Process a single facet cut by analyzing selector conflicts with existing diamond state
+    /// @dev Determines minimal diamond cuts needed by categorizing selectors as Add or Replace operations
+    /// @param diamond The diamond contract address to analyze against
+    /// @param cut The proposed facet cut to process
+    function processFacetCut(address diamond, FacetCut memory cut) internal {
+        DiamondInfo storage info = diamondInfos[diamond];
+        address newFacet = cut.facetAddress;
+        bytes4[] memory newSelectors = cut.functionSelectors;
+
+        // Skip if exact facet already exists (CREATE2 deterministic deployment)
+        // This prevents redundant cuts for already-deployed facets
+        if (info.layout.facets.contains(newFacet)) return;
+
+        // Create dynamic arrays for this facet's selectors
+        DynamicArrayLib.DynamicArray memory addSelectors = DynamicArrayLib.p();
+        DynamicArrayLib.DynamicArray memory replaceSelectors = DynamicArrayLib.p();
+
+        // Categorize each selector based on current diamond state
+        for (uint256 i; i < newSelectors.length; ++i) {
+            bytes4 selector = newSelectors[i];
+            address existingFacet = info.layout.facetBySelector[selector];
+
+            if (existingFacet == address(0)) {
+                // Selector doesn't exist - needs Add operation
+                addSelectors.p(selector);
+            } else if (existingFacet != newFacet) {
+                // Selector exists on different facet - needs Replace operation
+                replaceSelectors.p(selector);
+            }
+            // If existingFacet == newFacet, selector already points to correct facet - no action needed
+        }
+
+        // Generate Add cut for new selectors
+        if (addSelectors.length() > 0) {
+            addCut(FacetCut(newFacet, FacetCutAction.Add, asBytes4Array(addSelectors)));
+        }
+
+        // Generate Replace cut for conflicting selectors
+        if (replaceSelectors.length() > 0) {
+            addCut(FacetCut(newFacet, FacetCutAction.Replace, asBytes4Array(replaceSelectors)));
+        }
+    }
+
+    /// @notice Add removal cuts for orphaned selectors
+    function addRemovalCuts(address diamond) internal {
+        DiamondInfo storage info = diamondInfos[diamond];
+
+        address[] memory existingFacets = info.layout.facets.values();
+        for (uint256 i; i < existingFacets.length; ++i) {
+            address facetAddr = existingFacets[i];
+            bytes32[] memory existingSelectors = info.layout.selectorsByFacet[facetAddr].values();
+
+            // Create dynamic array for remove selectors
+            DynamicArrayLib.DynamicArray memory removeSelectors = DynamicArrayLib.p();
+
+            for (uint256 j; j < existingSelectors.length; ++j) {
+                bytes4 selector = bytes4(existingSelectors[j]);
+                if (!(info.proposedSelectors[selector] || info.coreSelectors[selector])) {
+                    removeSelectors.p(selector);
+                }
+            }
+
+            if (removeSelectors.length() > 0) {
+                addCut(FacetCut(address(0), FacetCutAction.Remove, asBytes4Array(removeSelectors)));
+            }
+        }
+    }
+
+    function asBytes4Array(
+        DynamicArrayLib.DynamicArray memory input
+    ) internal pure returns (bytes4[] memory selectors) {
+        bytes32[] memory selectors_ = input.asBytes32Array();
+        assembly ("memory-safe") {
+            selectors := selectors_
+        }
     }
 
     /// @notice Check if an address is in an array of addresses

package/src/factory/facets/feature/FeatureManagerBase.sol

@@ -7,9 +7,9 @@ import {IVotes} from "@openzeppelin/contracts/governance/utils/IVotes.sol";
 import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 // libraries
+import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
 import {FeatureManagerStorage} from "./FeatureManagerStorage.sol";
 import {FeatureCondition} from "./IFeatureManagerFacet.sol";
-import {CustomRevert} from "../../../utils/libraries/CustomRevert.sol";
 import {EnumerableSetLib} from "solady/utils/EnumerableSetLib.sol";
 import {LibCall} from "solady/utils/LibCall.sol";
 
@@ -19,6 +19,11 @@ abstract contract FeatureManagerBase is IFeatureManagerFacetBase {
     using EnumerableSetLib for EnumerableSetLib.Bytes32Set;
     using CustomRevert for bytes4;
 
+    /// @notice Creates or updates a feature condition based on the create flag
+    /// @dev Validates token interface compliance before storing the condition
+    /// @param featureId The unique identifier for the feature
+    /// @param condition The condition struct containing token, threshold, active status, and extra data
+    /// @param create True to create new feature, false to update existing
     function _upsertFeatureCondition(
         bytes32 featureId,
         FeatureCondition calldata condition,
@@ -27,97 +32,76 @@ abstract contract FeatureManagerBase is IFeatureManagerFacetBase {
         _validateToken(condition);
 
         FeatureManagerStorage.Layout storage $ = FeatureManagerStorage.getLayout();
-        if (create && !$.featureIds.add(featureId)) {
-            FeatureAlreadyExists.selector.revertWith();
-        } else if (!create && !$.featureIds.contains(featureId)) {
-            FeatureNotActive.selector.revertWith();
+        if (!create) {
+            if (!$.featureIds.contains(featureId)) FeatureNotActive.selector.revertWith();
+        } else {
+            if (!$.featureIds.add(featureId)) FeatureAlreadyExists.selector.revertWith();
         }
 
         $.conditions[featureId] = condition;
     }
 
+    /// @notice Disables a feature by setting its active flag to false
+    /// @dev This does not delete the condition, only deactivates it
+    /// @param featureId The unique identifier for the feature to disable
+    function _disableFeatureCondition(bytes32 featureId) internal {
+        FeatureCondition storage condition = _getFeatureCondition(featureId);
+        if (!condition.active) FeatureNotActive.selector.revertWith();
+        condition.active = false;
+    }
+
     /// @notice Retrieves the condition for a specific feature
     /// @dev Returns the complete condition struct with all parameters
     /// @param featureId The unique identifier for the feature
-    /// @return result The complete condition configuration for the feature
+    /// @return The complete condition configuration for the feature
     function _getFeatureCondition(
         bytes32 featureId
-    ) internal view returns (FeatureCondition memory result) {
-        FeatureManagerStorage.Layout storage $ = FeatureManagerStorage.getLayout();
-        assembly ("memory-safe") {
-            mstore(0x40, result)
-        }
-        result = $.conditions[featureId];
+    ) internal view returns (FeatureCondition storage) {
+        return FeatureManagerStorage.getLayout().conditions[featureId];
     }
 
     /// @notice Retrieves all feature conditions
     /// @dev Returns an array of all feature conditions
-    /// @return FeatureCondition[] An array of all feature conditions
-    function _getFeatureConditions() internal view returns (FeatureCondition[] memory) {
+    /// @return conditions An array of all feature conditions
+    function _getFeatureConditions() internal view returns (FeatureCondition[] memory conditions) {
         FeatureManagerStorage.Layout storage $ = FeatureManagerStorage.getLayout();
-        uint256 featureCount = $.featureIds.length();
+        // Use values() over at() for full iteration - avoids bounds checking overhead
+        bytes32[] memory ids = $.featureIds.values();
+        uint256 featureCount = ids.length;
 
-        FeatureCondition[] memory conditions = new FeatureCondition[](featureCount);
+        conditions = new FeatureCondition[](featureCount);
         for (uint256 i; i < featureCount; ++i) {
-            conditions[i] = $.conditions[$.featureIds.at(i)];
+            conditions[i] = $.conditions[ids[i]];
         }
-        return conditions;
     }
 
     /// @notice Retrieves all feature conditions for a specific space
     /// @dev Returns an array of all feature conditions that are active for the space
-    /// @return FeatureCondition[] An array of all feature conditions that are active for the space
+    /// @return conditions An array of all feature conditions that are active for the space
     function _getFeatureConditionsForSpace(
         address space
-    ) internal view returns (FeatureCondition[] memory) {
+    ) internal view returns (FeatureCondition[] memory conditions) {
         FeatureManagerStorage.Layout storage $ = FeatureManagerStorage.getLayout();
-        uint256 featureCount = $.featureIds.length();
+        // Use values() over at() for full iteration - avoids bounds checking overhead
+        bytes32[] memory ids = $.featureIds.values();
+        uint256 featureCount = ids.length;
 
-        FeatureCondition[] memory conditions = new FeatureCondition[](featureCount);
+        // Gas optimization: Allocate full array then resize (memory cheaper than storage reads)
+        conditions = new FeatureCondition[](featureCount);
         uint256 index;
 
         for (uint256 i; i < featureCount; ++i) {
-            bytes32 id = $.featureIds.at(i);
-            FeatureCondition storage cond = $.conditions[id];
+            FeatureCondition storage cond = $.conditions[ids[i]];
 
             if (_isValidCondition(cond, space)) {
                 conditions[index++] = cond;
             }
         }
 
+        // Resize array to actual number of valid conditions
         assembly ("memory-safe") {
             mstore(conditions, index)
         }
-
-        return conditions;
-    }
-
-    /// @notice Disables a feature by setting its active flag to false
-    /// @dev This does not delete the condition, only deactivates it
-    /// @param featureId The unique identifier for the feature to disable
-    function _disableFeatureCondition(bytes32 featureId) internal {
-        FeatureCondition storage condition = FeatureManagerStorage.getLayout().conditions[
-            featureId
-        ];
-        if (!condition.active) FeatureNotActive.selector.revertWith();
-        condition.active = false;
-    }
-
-    /// @notice Sets a feature condition (wrapper for upsert with create=true)
-    /// @param featureId The unique identifier for the feature
-    /// @param condition The condition struct containing token, threshold, active status, and extra data
-    function _setFeatureCondition(bytes32 featureId, FeatureCondition calldata condition) internal {
-        _upsertFeatureCondition(featureId, condition, true);
-    }
-
-    /// @notice Updates a feature condition (wrapper for upsert with create=false)
-    /// @param featureId The unique identifier for the feature
-    /// @param condition The condition struct containing token, threshold, active status, and extra data
-    function _updateFeatureCondition(
-        bytes32 featureId,
-        FeatureCondition calldata condition
-    ) internal {
-        _upsertFeatureCondition(featureId, condition, false);
     }
 
     function _validateToken(FeatureCondition calldata condition) internal view {
@@ -156,12 +140,13 @@ abstract contract FeatureManagerBase is IFeatureManagerFacetBase {
     /// @param space The space address to check against
     /// @return True if the condition should be included, false otherwise
     function _isValidCondition(
-        FeatureCondition memory condition,
+        FeatureCondition storage condition,
         address space
     ) internal view returns (bool) {
         if (!condition.active) return false;
-        if (condition.token == address(0)) return false;
-        uint256 votes = IVotes(condition.token).getVotes(space);
+        address token = condition.token;
+        if (token == address(0)) return false;
+        uint256 votes = IVotes(token).getVotes(space);
         return votes >= condition.threshold;
     }
 }

package/src/factory/facets/feature/FeatureManagerFacet.sol

@@ -39,11 +39,22 @@ contract FeatureManagerFacet is IFeatureManagerFacet, OwnableBase, Facet, Featur
         emit FeatureConditionSet(featureId, condition);
     }
 
+    /// @inheritdoc IFeatureManagerFacet
+    function disableFeatureCondition(bytes32 featureId) external onlyOwner {
+        _disableFeatureCondition(featureId);
+        emit FeatureConditionDisabled(featureId);
+    }
+
     /// @inheritdoc IFeatureManagerFacet
     function getFeatureCondition(
         bytes32 featureId
-    ) external view returns (FeatureCondition memory) {
-        return _getFeatureCondition(featureId);
+    ) external view returns (FeatureCondition memory result) {
+        // Gas optimization: Reclaim implicit memory allocation for return variable
+        // since we're loading from storage, not using the pre-allocated memory
+        assembly ("memory-safe") {
+            mstore(0x40, result)
+        }
+        result = _getFeatureCondition(featureId);
     }
 
     /// @inheritdoc IFeatureManagerFacet
@@ -58,12 +69,6 @@ contract FeatureManagerFacet is IFeatureManagerFacet, OwnableBase, Facet, Featur
         return _getFeatureConditionsForSpace(space);
     }
 
-    /// @inheritdoc IFeatureManagerFacet
-    function disableFeatureCondition(bytes32 featureId) external onlyOwner {
-        _disableFeatureCondition(featureId);
-        emit FeatureConditionDisabled(featureId);
-    }
-
     /// @inheritdoc IFeatureManagerFacet
     function checkFeatureCondition(bytes32 featureId, address space) external view returns (bool) {
         return _isValidCondition(_getFeatureCondition(featureId), space);

package/src/factory/facets/feature/FeatureManagerStorage.sol

@@ -4,9 +4,9 @@ pragma solidity ^0.8.23;
 // interfaces
 
 // libraries
+import {EnumerableSetLib} from "solady/utils/EnumerableSetLib.sol";
 
 // contracts
-import {EnumerableSetLib} from "solady/utils/EnumerableSetLib.sol";
 
 /// @notice Represents a condition for feature activation
 /// @dev Used to determine if a feature should be enabled based on token voting power

package/src/factory/facets/feature/IFeatureManagerFacet.sol

@@ -9,6 +9,15 @@ import {FeatureCondition} from "./FeatureManagerStorage.sol";
 /// @notice Base interface for the FeatureManager facet defining errors and events
 /// @dev Used by the FeatureManager facet and any other facets that need to access feature conditions
 interface IFeatureManagerFacetBase {
+    /// @notice Emitted when a feature condition is set or updated
+    /// @param featureId The unique identifier for the feature whose condition was set
+    /// @param condition The condition parameters that were set for the feature
+    event FeatureConditionSet(bytes32 indexed featureId, FeatureCondition condition);
+
+    /// @notice Emitted when a feature condition is disabled
+    /// @param featureId The unique identifier for the feature whose condition was disabled
+    event FeatureConditionDisabled(bytes32 indexed featureId);
+
     /// @notice Error thrown when a threshold exceeds the token's total supply
     error InvalidThreshold();
 
@@ -26,15 +35,6 @@ interface IFeatureManagerFacetBase {
 
     /// @notice Error thrown when a feature condition already exists
     error FeatureAlreadyExists();
-
-    /// @notice Emitted when a feature condition is set or updated
-    /// @param featureId The unique identifier for the feature whose condition was set
-    /// @param condition The condition parameters that were set for the feature
-    event FeatureConditionSet(bytes32 indexed featureId, FeatureCondition condition);
-
-    /// @notice Emitted when a feature condition is disabled
-    /// @param featureId The unique identifier for the feature whose condition was disabled
-    event FeatureConditionDisabled(bytes32 indexed featureId);
 }
 
 interface IFeatureManagerFacet is IFeatureManagerFacetBase {
@@ -50,6 +50,11 @@ interface IFeatureManagerFacet is IFeatureManagerFacetBase {
     /// @dev Only callable by the contract owner
     function updateFeatureCondition(bytes32 featureId, FeatureCondition memory condition) external;
 
+    /// @notice Disables a feature condition
+    /// @param featureId The unique identifier for the feature
+    /// @dev Only callable by the contract owner
+    function disableFeatureCondition(bytes32 featureId) external;
+
     /// @notice Gets the condition for a feature
     /// @param featureId The unique identifier for the feature
     /// @return The condition struct for the specified feature
@@ -66,11 +71,6 @@ interface IFeatureManagerFacet is IFeatureManagerFacetBase {
         address space
     ) external view returns (FeatureCondition[] memory);
 
-    /// @notice Disables a feature condition
-    /// @param featureId The unique identifier for the feature
-    /// @dev Only callable by the contract owner
-    function disableFeatureCondition(bytes32 featureId) external;
-
     /// @notice Checks if a space meets the condition for a feature
     /// @param featureId The unique identifier for the feature
     /// @param space The address of the space to check