feat: Total Balance change enforcers

[hanzel98]

What?

• Added 4 new enforcers:
  ERC20TotalBalanceChangeEnforcer
ERC721TotalBalanceChangeEnforcer
ERC1155TotalBalanceChangeEnforcer
NativeTotalBalanceChangeEnforcer
  These enforcers can enforce balance change across a delegation chain where multiple same enforcers are present.
• Included deployment script for all of them

Why?

• Current balance change enforcers balance changes by comparing the recipient's balance before and after execution. Since enforcers watching the same recipient share state, a single balance modification may satisfy multiple enforcers simultaneously. This can lead to unintended behavior in delegation chains. The total balance change enforcers are introduce to address this issue.

How?

• Using beforeAllHook and afterAllHook: These hooks enable proper handling of inner delegations and ensure all enforcers in the chain are processed together.
• Accumulating Expected Changes: Each enforcer maintains a BalanceTracker struct that accumulates the expected increases and decreases for a specific recipient + token combination across all enforcers in the delegation chain.
• State Isolation: The hash key is generated using the delegation manager address and recipient (plus token address and token ID for ERC1155), ensuring that different delegation managers don't interfere with each other.
• Aggregated Validation: The final validation in afterAllHook combines all expected changes and validates the total net change against the actual balance change.

[hanzel98]

@MoMannn Please add the deployment script for the new caveats that you create, and add them to the verification scripts too

[hanzel98]

Please add any documentation needed to explain how the enforced outcomes can be achieved with this enforcer and what is expected when people don't want to use Gators.

Also please explain how the total enforcer works when mixing decrease and increase

[hanzel98]

Please add a brief explanation comment in each of the test

[McOso]

Looking good! Just a little check to short circuit if the amount in terms is greater than 0. Not critical, but might prevent some improper use

[cursor]

Bug: Script Fails Verifying Contracts at Zero Addresses

The script/verification/verify-enforcer-contracts.sh script adds four new Total Balance Change Enforcers to the ENFORCERS array and corresponding placeholder zero addresses (0x0000000000000000000000000000000000000000) to the ADDRESSES array. The script then attempts to verify contracts at these zero addresses, which causes verification failures.

script/verification/verify-enforcer-contracts.sh#L92-L96

delegation-framework/script/verification/verify-enforcer-contracts.sh

Lines 92 to 96 in 73ca695

	"0x92Bf12322527cAA612fd31a0e810472BBB106A8F"
	"0x0000000000000000000000000000000000000000"
	"0x0000000000000000000000000000000000000000"
	"0x0000000000000000000000000000000000000000"
	"0x0000000000000000000000000000000000000000"

Fix in Cursor • Fix in Web

---

Bug: Unreachable Hooks and Missing Prank Directive

Multiple afterAllHook calls are unreachable as they immediately follow an expectRevert statement. Additionally, one of these unreachable calls is missing a vm.prank(dm) directive, which would lead to an incorrect msg.sender and flawed BalanceTracker logic if the code were reachable.

test/enforcers/ERC20TotalBalanceChangeEnforcer.t.sol#L376-L380

delegation-framework/test/enforcers/ERC20TotalBalanceChangeEnforcer.t.sol

Lines 376 to 380 in 73ca695

	token.transfer(delegator, 21);
	vm.prank(dm);
	vm.expectRevert("ERC20TotalBalanceChangeEnforcer:exceeded-balance-decrease");
	enforcer.afterAllHook(terms_, hex"", singleDefaultMode, mintExecutionCallData, bytes32(0), delegator, delegate);
	enforcer.afterAllHook(terms_, hex"", singleDefaultMode, mintExecutionCallData, bytes32(0), delegator, delegate);

test/enforcers/ERC20TotalBalanceChangeEnforcer.t.sol#L442-L445

delegation-framework/test/enforcers/ERC20TotalBalanceChangeEnforcer.t.sol

Lines 442 to 445 in 73ca695

	vm.prank(dm);
	vm.expectRevert("ERC20TotalBalanceChangeEnforcer:insufficient-balance-increase");
	enforcer.afterAllHook(termsIncrease_, hex"", singleDefaultMode, mintExecutionCallData, bytes32(0), delegator, delegate);
	enforcer.afterAllHook(termsDecrease_, hex"", singleDefaultMode, mintExecutionCallData, bytes32(0), delegator, delegate);

test/enforcers/ERC20TotalBalanceChangeEnforcer.t.sol#L467-L470

delegation-framework/test/enforcers/ERC20TotalBalanceChangeEnforcer.t.sol

Lines 467 to 470 in 73ca695

	vm.prank(dm);
	vm.expectRevert("ERC20TotalBalanceChangeEnforcer:exceeded-balance-decrease");
	enforcer.afterAllHook(termsIncrease_, hex"", singleDefaultMode, mintExecutionCallData, bytes32(0), delegator, delegate);
	enforcer.afterAllHook(termsDecrease_, hex"", singleDefaultMode, mintExecutionCallData, bytes32(0), delegator, delegate);

Fix in Cursor • Fix in Web

---

Was this report helpful? Give feedback by reacting with 👍 or 👎

[hanzel98]

I can't approve it because I created the PR, but it looks good to me. Thanks @MoMannn