Rename total balance change enforcers to multi operation balance enforcers

Author: MoMannn

documents/CaveatEnforcers.md

@@ -83,26 +83,26 @@ Balance Change Enforcers are ideal for:
 2. **No Aggregation**: Each enforcer operates independently and doesn't consider other enforcers in the chain
 3. **Delegation Chain Issues**: In complex delegation chains, the same balance change might satisfy multiple enforcers, potentially bypassing intended security measures
 
-**When to Use Regular vs Total Balance Enforcers**:
+**When to Use Regular vs Multi Operation Balance Enforcers**:
 - Use **Regular Balance Enforcers** for simple, single-enforcer scenarios
-- Use **Total Balance Enforcers** when multiple enforcers might track the same recipient in a delegation chain
+- Use **Multi Operation Balance Enforcers** when multiple enforcers might track the same recipient in a delegation chain
 
 
-### Total Balance Change Enforcers
+### Multi Operation Balance Enforcers
 
 This includes: 
-- `ERC20TotalBalanceChangeEnforcer`
-- `ERC721TotalBalanceChangeEnforcer`
-- `ERC1155TotalBalanceChangeEnforcer`
-- `NativeTokenTotalBalanceChangeEnforcer`
+- `ERC20MultiOperationBalanceEnforcer`
+- `ERC721MultiOperationBalanceEnforcer`
+- `ERC1155MultiOperationBalanceEnforcer`
+- `NativeTokenMultiOperationBalanceEnforcer`
 
 Use these when multiple total-balance constraints may apply to the same recipient and token within a single redemption, and you need a single, coherent end-of-redemption check.
 
 #### Key differences from Regular Balance Change Enforcers
 
 **Regular Balance Change Enforcers** (e.g., `NativeBalanceChangeEnforcer`) check deltas around one execution using `beforeHook`/`afterHook`. Because multiple enforcers watching the same recipient can be satisfied by the same balance movement, they are best for independent, per-delegation constraints.
 
-**Total Balance Change Enforcers** are designed for coordinated multi-step flows and now behave as follows:
+**Multi Operation Balance Enforcers** are designed for coordinated multi-step flows and now behave as follows:
 
 1. **Redemption-wide tracking**: Balance is tracked from the first `beforeAllHook` to the last `afterAllHook` for a given state key. The state key is defined by the recipient; for token-based variants it also includes the token address, and for ERC1155 it additionally includes the token ID. The state is scoped to the current `DelegationManager`. Any balance changes caused between those points (including by other enforcers, even those that modify state in `afterAllHook`, such as `NativeTokenPaymentEnforcer` even tho mixing with `NativeTokenPaymentEnforcer` is not recomended) are included in the final check.
 2. **Initialization rule**: The first enforcer that starts tracking must be created by the account whose balance is being constrained. In other words, for the first `beforeAllHook` on a state key, the delegator must equal the recipient. If this is not true, the enforcer reverts.
@@ -127,7 +127,7 @@ Use these when multiple total-balance constraints may apply to the same recipien
   - Alice → Bob: “Treasury can lose max 100 ETH”
   - Bob → Dave: “Treasury can lose max 50 ETH” (stricter)
   - With Regular enforcers, each delegation enforces its own limit, so the effective cap is 50 ETH.
-- **Coordinated multi-operation transactions (one complex flow with multiple steps)**: Use Total Balance Change Enforcers. Example: a swap + fee + settlement that together must result in a minimum net profit for a recipient, or must not exceed a net loss cap across the whole flow. The owner may aggregate multiple requirements; redelegations can only make them stricter.
+- **Coordinated multi-operation transactions (one complex flow with multiple steps)**: Use Multi Operation Balance Enforcers. Example: a swap + fee + settlement that together must result in a minimum net profit for a recipient, or must not exceed a net loss cap across the whole flow. The owner may aggregate multiple requirements; redelegations can only make them stricter.
 
 Why accumulation is appropriate in coordinated flows: the intention is to verify the final end state of the recipient after all steps complete, not to enforce separate independent limits. In contrast, for independent limits, prefer Regular enforcers so each delegation remains self-contained.
 

script/DeployCaveatEnforcers.s.sol

@@ -38,10 +38,10 @@ import { RedeemerEnforcer } from "../src/enforcers/RedeemerEnforcer.sol";
 import { SpecificActionERC20TransferBatchEnforcer } from "../src/enforcers/SpecificActionERC20TransferBatchEnforcer.sol";
 import { TimestampEnforcer } from "../src/enforcers/TimestampEnforcer.sol";
 import { ValueLteEnforcer } from "../src/enforcers/ValueLteEnforcer.sol";
-import { ERC20TotalBalanceChangeEnforcer } from "../src/enforcers/ERC20TotalBalanceChangeEnforcer.sol";
-import { ERC721TotalBalanceChangeEnforcer } from "../src/enforcers/ERC721TotalBalanceChangeEnforcer.sol";
-import { ERC1155TotalBalanceChangeEnforcer } from "../src/enforcers/ERC1155TotalBalanceChangeEnforcer.sol";
-import { NativeTokenTotalBalanceChangeEnforcer } from "../src/enforcers/NativeTokenTotalBalanceChangeEnforcer.sol";
+import { ERC20MultiOperationBalanceEnforcer } from "../src/enforcers/ERC20MultiOperationBalanceEnforcer.sol";
+import { ERC721MultiOperationBalanceEnforcer } from "../src/enforcers/ERC721MultiOperationBalanceEnforcer.sol";
+import { ERC1155MultiOperationBalanceEnforcer } from "../src/enforcers/ERC1155MultiOperationBalanceEnforcer.sol";
+import { NativeTokenMultiOperationBalanceEnforcer } from "../src/enforcers/NativeTokenMultiOperationBalanceEnforcer.sol";
 
 /**
  * @title DeployCaveatEnforcers
@@ -170,17 +170,17 @@ contract DeployCaveatEnforcers is Script {
         deployedAddress = address(new ValueLteEnforcer{ salt: salt }());
         console2.log("ValueLteEnforcer: %s", deployedAddress);
 
-        deployedAddress = address(new ERC20TotalBalanceChangeEnforcer{ salt: salt }());
-        console2.log("ERC20TotalBalanceChangeEnforcer: %s", deployedAddress);
+        deployedAddress = address(new ERC20MultiOperationBalanceEnforcer{ salt: salt }());
+        console2.log("ERC20MultiOperationBalanceEnforcer: %s", deployedAddress);
 
-        deployedAddress = address(new ERC721TotalBalanceChangeEnforcer{ salt: salt }());
-        console2.log("ERC721TotalBalanceChangeEnforcer: %s", deployedAddress);
+        deployedAddress = address(new ERC721MultiOperationBalanceEnforcer{ salt: salt }());
+        console2.log("ERC721MultiOperationBalanceEnforcer: %s", deployedAddress);
 
-        deployedAddress = address(new ERC1155TotalBalanceChangeEnforcer{ salt: salt }());
-        console2.log("ERC1155TotalBalanceChangeEnforcer: %s", deployedAddress);
+        deployedAddress = address(new ERC1155MultiOperationBalanceEnforcer{ salt: salt }());
+        console2.log("ERC1155MultiOperationBalanceEnforcer: %s", deployedAddress);
 
-        deployedAddress = address(new NativeTokenTotalBalanceChangeEnforcer{ salt: salt }());
-        console2.log("NativeTokenTotalBalanceChangeEnforcer: %s", deployedAddress);
+        deployedAddress = address(new NativeTokenMultiOperationBalanceEnforcer{ salt: salt }());
+        console2.log("NativeTokenMultiOperationBalanceEnforcer: %s", deployedAddress);
 
         vm.stopBroadcast();
     }

script/verification/verify-enforcer-contracts.sh

@@ -53,10 +53,10 @@ ENFORCERS=(
   "SpecificActionERC20TransferBatchEnforcer"
   "TimestampEnforcer"
   "ValueLteEnforcer"
-  "ERC20TotalBalanceChangeEnforcer"
-  "ERC721TotalBalanceChangeEnforcer"
-  "ERC1155TotalBalanceChangeEnforcer"
-  "NativeTokenTotalBalanceChangeEnforcer"
+  "ERC20MultiOperationBalanceEnforcer"
+  "ERC721MultiOperationBalanceEnforcer"
+  "ERC1155MultiOperationBalanceEnforcer"
+  "NativeTokenMultiOperationBalanceEnforcer"
 )
 
 ADDRESSES=(

…rs/ERC1155TotalBalanceChangeEnforcer.sol …ERC1155MultiOperationBalanceEnforcer.solsrc/enforcers/ERC1155TotalBalanceChangeEnforcer.sol renamed to src/enforcers/ERC1155MultiOperationBalanceEnforcer.sol src/enforcers/ERC1155TotalBalanceChangeEnforcer.sol renamed to src/enforcers/ERC1155MultiOperationBalanceEnforcer.sol

@@ -7,18 +7,20 @@ import { CaveatEnforcer } from "./CaveatEnforcer.sol";
 import { ModeCode } from "../utils/Types.sol";
 
 /**
- * @title ERC1155TotalBalanceChangeEnforcer
+ * @title ERC1155MultiOperationBalanceEnforcer
  * @notice Enforces that a recipient's ERC1155 token balance changes within expected limits across multiple delegations.
  * Tracks balance changes from the first beforeAllHook call to the last afterAllHook call within a redemption.
- * 
+ *
  * For balance increases: ensures the final balance is at least the initial balance plus the expected increase.
  * For balance decreases: ensures the final balance is at least the initial balance minus the expected decrease.
- * 
- * @dev This enforcer operates in delegation chains where multiple delegations may affect the same recipient/token/tokenID combination.
- * State is shared between enforcers watching the same recipient/token/tokenID combination and is cleared after transaction execution.
- * 
+ *
+ * @dev This enforcer operates in delegation chains where multiple delegations may affect the same recipient/token/tokenID
+ * combination.
+ * State is shared between enforcers watching the same recipient/token/tokenID combination and is cleared after transaction
+ * execution.
+ *
  * @dev Only operates in default execution mode (ModeCode 0).
- * 
+ *
  * @dev Security considerations:
  * - State is shared between enforcers watching the same recipient/token/tokenID combination
  * - Balance changes are tracked by comparing first beforeAll/last afterAll balances in batch delegations
@@ -28,7 +30,7 @@ import { ModeCode } from "../utils/Types.sol";
  * - Delegator must equal recipient for first delegation in a chain of delegations
  * - Only if delegator is equal to recipient do the amounts aggregate
  */
-contract ERC1155TotalBalanceChangeEnforcer is CaveatEnforcer {
+contract ERC1155MultiOperationBalanceEnforcer is CaveatEnforcer {
     ////////////////////////////// Events //////////////////////////////
 
     event TrackedBalance(
@@ -107,13 +109,13 @@ contract ERC1155TotalBalanceChangeEnforcer is CaveatEnforcer {
         onlyDefaultExecutionMode(_mode)
     {
         TermsData memory terms_ = getTermsInfo(_terms);
-        require(terms_.amount > 0, "ERC1155TotalBalanceChangeEnforcer:zero-expected-change-amount");
+        require(terms_.amount > 0, "ERC1155MultiOperationBalanceEnforcer:zero-expected-change-amount");
         bytes32 hashKey_ = _getHashKey(msg.sender, terms_.token, terms_.recipient, terms_.tokenId);
         uint256 balance_ = IERC1155(terms_.token).balanceOf(terms_.recipient, terms_.tokenId);
         BalanceTracker memory balanceTracker_ = balanceTracker[hashKey_];
 
         if (balanceTracker_.expectedIncrease == 0 && balanceTracker_.expectedDecrease == 0) {
-            require(terms_.recipient == _delegator, "ERC1155TotalBalanceChangeEnforcer:invalid-delegator");
+            require(terms_.recipient == _delegator, "ERC1155MultiOperationBalanceEnforcer:invalid-delegator");
             balanceTracker_.balanceBefore = balance_;
             emit TrackedBalance(msg.sender, terms_.recipient, terms_.token, terms_.tokenId, balance_);
         }
@@ -131,15 +133,15 @@ contract ERC1155TotalBalanceChangeEnforcer is CaveatEnforcer {
                 // For decreases: new amount must be <= existing amount (more restrictive)
                 require(
                     terms_.amount <= balanceTracker_.expectedDecrease,
-                    "ERC1155TotalBalanceChangeEnforcer:decrease-must-be-more-restrictive"
+                    "ERC1155MultiOperationBalanceEnforcer:decrease-must-be-more-restrictive"
                 );
                 // Override instead of aggregate
                 balanceTracker_.expectedDecrease = terms_.amount;
             } else {
                 // For increases: new amount must be >= existing amount (more restrictive)
                 require(
                     terms_.amount >= balanceTracker_.expectedIncrease,
-                    "ERC1155TotalBalanceChangeEnforcer:increase-must-be-more-restrictive"
+                    "ERC1155MultiOperationBalanceEnforcer:increase-must-be-more-restrictive"
                 );
                 // Override instead of aggregate
                 balanceTracker_.expectedIncrease = terms_.amount;
@@ -193,12 +195,13 @@ contract ERC1155TotalBalanceChangeEnforcer is CaveatEnforcer {
             expected_ = balanceTracker_.expectedIncrease - balanceTracker_.expectedDecrease;
             require(
                 balance_ >= balanceTracker_.balanceBefore + expected_,
-                "ERC1155TotalBalanceChangeEnforcer:insufficient-balance-increase"
+                "ERC1155MultiOperationBalanceEnforcer:insufficient-balance-increase"
             );
         } else {
             expected_ = balanceTracker_.expectedDecrease - balanceTracker_.expectedIncrease;
             require(
-                balance_ >= balanceTracker_.balanceBefore - expected_, "ERC1155TotalBalanceChangeEnforcer:exceeded-balance-decrease"
+                balance_ >= balanceTracker_.balanceBefore - expected_,
+                "ERC1155MultiOperationBalanceEnforcer:exceeded-balance-decrease"
             );
         }
 
@@ -219,7 +222,7 @@ contract ERC1155TotalBalanceChangeEnforcer is CaveatEnforcer {
      * enforceDecrease)
      */
     function getTermsInfo(bytes calldata _terms) public pure returns (TermsData memory) {
-        require(_terms.length == 105, "ERC1155TotalBalanceChangeEnforcer:invalid-terms-length");
+        require(_terms.length == 105, "ERC1155MultiOperationBalanceEnforcer:invalid-terms-length");
         return TermsData({
             enforceDecrease: _terms[0] != 0,
             token: address(bytes20(_terms[1:21])),

…cers/ERC20TotalBalanceChangeEnforcer.sol …s/ERC20MultiOperationBalanceEnforcer.solsrc/enforcers/ERC20TotalBalanceChangeEnforcer.sol renamed to src/enforcers/ERC20MultiOperationBalanceEnforcer.sol src/enforcers/ERC20TotalBalanceChangeEnforcer.sol renamed to src/enforcers/ERC20MultiOperationBalanceEnforcer.sol

@@ -6,18 +6,18 @@ import { CaveatEnforcer } from "./CaveatEnforcer.sol";
 import { ModeCode } from "../utils/Types.sol";
 
 /**
- * @title ERC20TotalBalanceChangeEnforcer
+ * @title ERC20MultiOperationBalanceEnforcer
  * @notice Enforces that a recipient's token balance changes within expected limits across multiple delegations.
  * Tracks balance changes from the first beforeAllHook call to the last afterAllHook call within a redemption.
- * 
+ *
  * For balance increases: ensures the final balance is at least the initial balance plus the expected increase.
  * For balance decreases: ensures the final balance is at least the initial balance minus the expected decrease.
- * 
+ *
  * @dev This enforcer operates in delegation chains where multiple delegations may affect the same recipient/token pair.
  * State is shared between enforcers watching the same recipient/token pair and is cleared after transaction execution.
- * 
+ *
  * @dev Only operates in default execution mode (ModeCode 0).
- * 
+ *
  * @dev Security considerations:
  * - State is shared between enforcers watching the same recipient/token pair
  * - Balance changes are tracked by comparing first beforeAll/last afterAll balances in batch delegations
@@ -27,7 +27,7 @@ import { ModeCode } from "../utils/Types.sol";
  * - Delegator must equal recipient for first delegation in a chain of delegations
  * - Only if delegator is equal to recipient do the amount aggragate
  */
-contract ERC20TotalBalanceChangeEnforcer is CaveatEnforcer {
+contract ERC20MultiOperationBalanceEnforcer is CaveatEnforcer {
     ////////////////////////////// Events //////////////////////////////
 
     event TrackedBalance(address indexed delegationManager, address indexed recipient, address indexed token, uint256 balance);
@@ -88,14 +88,14 @@ contract ERC20TotalBalanceChangeEnforcer is CaveatEnforcer {
         onlyDefaultExecutionMode(_mode)
     {
         (bool enforceDecrease_, address token_, address recipient_, uint256 amount_) = getTermsInfo(_terms);
-        require(amount_ > 0, "ERC20TotalBalanceChangeEnforcer:zero-expected-change-amount");
+        require(amount_ > 0, "ERC20MultiOperationBalanceEnforcer:zero-expected-change-amount");
 
         bytes32 hashKey_ = _getHashKey(msg.sender, token_, recipient_);
         BalanceTracker memory balanceTracker_ = balanceTracker[hashKey_];
 
         uint256 currentBalance_ = IERC20(token_).balanceOf(recipient_);
         if (balanceTracker_.expectedDecrease == 0 && balanceTracker_.expectedIncrease == 0) {
-            require(_delegator == recipient_, "ERC20TotalBalanceChangeEnforcer:invalid-delegator");
+            require(_delegator == recipient_, "ERC20MultiOperationBalanceEnforcer:invalid-delegator");
             balanceTracker_.balanceBefore = currentBalance_;
             emit TrackedBalance(msg.sender, recipient_, token_, currentBalance_);
         }
@@ -114,15 +114,15 @@ contract ERC20TotalBalanceChangeEnforcer is CaveatEnforcer {
                 // For decreases: new amount must be <= existing amount (more restrictive)
                 require(
                     amount_ <= balanceTracker_.expectedDecrease,
-                    "ERC20TotalBalanceChangeEnforcer:decrease-must-be-more-restrictive"
+                    "ERC20MultiOperationBalanceEnforcer:decrease-must-be-more-restrictive"
                 );
                 // Override instead of aggregate
                 balanceTracker_.expectedDecrease = amount_;
             } else {
                 // For increases: new amount must be >= existing amount (more restrictive)
                 require(
                     amount_ >= balanceTracker_.expectedIncrease,
-                    "ERC20TotalBalanceChangeEnforcer:increase-must-be-more-restrictive"
+                    "ERC20MultiOperationBalanceEnforcer:increase-must-be-more-restrictive"
                 );
                 // Override instead of aggregate
                 balanceTracker_.expectedIncrease = amount_;
@@ -174,13 +174,13 @@ contract ERC20TotalBalanceChangeEnforcer is CaveatEnforcer {
             expected_ = balanceTracker_.expectedIncrease - balanceTracker_.expectedDecrease;
             require(
                 currentBalance_ >= balanceTracker_.balanceBefore + expected_,
-                "ERC20TotalBalanceChangeEnforcer:insufficient-balance-increase"
+                "ERC20MultiOperationBalanceEnforcer:insufficient-balance-increase"
             );
         } else {
             expected_ = balanceTracker_.expectedDecrease - balanceTracker_.expectedIncrease;
             require(
                 currentBalance_ >= balanceTracker_.balanceBefore - expected_,
-                "ERC20TotalBalanceChangeEnforcer:exceeded-balance-decrease"
+                "ERC20MultiOperationBalanceEnforcer:exceeded-balance-decrease"
             );
         }
 
@@ -202,7 +202,7 @@ contract ERC20TotalBalanceChangeEnforcer is CaveatEnforcer {
         pure
         returns (bool enforceDecrease_, address token_, address recipient_, uint256 amount_)
     {
-        require(_terms.length == 73, "ERC20TotalBalanceChangeEnforcer:invalid-terms-length");
+        require(_terms.length == 73, "ERC20MultiOperationBalanceEnforcer:invalid-terms-length");
         enforceDecrease_ = _terms[0] != 0;
         token_ = address(bytes20(_terms[1:21]));
         recipient_ = address(bytes20(_terms[21:41]));