docs(security): document single-asset scope, verify caveat state isolation, and outline adapter boundaries

[mertcano]

Description

Addresses security considerations and caveat enforcement boundaries identified during the workspace audit of delegation-framework (Findings DF-1 through DF-5).

Specifically clarifies the balance tracking scope in ERC20BalanceChangeEnforcer, documents the reentrancy and period-accounting safety of MultiTokenPeriodEnforcer, evaluates caller-controlled batch iteration in DelegationManager, and highlights off-chain signature and slippage considerations in integration adapters.

Key Changes & Security Rationale

• Single-Asset Scope Clarification (DF-1 - src/enforcers/ERC20BalanceChangeEnforcer.sol):

  • Expanded the NatSpec @dev Security Notice to explicitly state that ERC20BalanceChangeEnforcer measures the balance delta of strictly one asset (the token specified in _terms).
  • Highlights that it does NOT provide total portfolio protection; unauthorized asset movements must be constrained by pairing this caveat with AllowedTargetsEnforcer, AllowedMethodsEnforcer, and calldata restriction caveats.

• Caveat State Isolation & Mutex Verification (DF-2 - ERC20BalanceChangeEnforcer.sol, MultiTokenPeriodEnforcer.sol):

  • Confirmed reentrancy safety in ERC20BalanceChangeEnforcer: isLocked[hashKey] is toggled in beforeHook and cleared in afterHook, where hashKey binds (msg.sender, token, delegationHash).
  • Confirmed state isolation in MultiTokenPeriodEnforcer: periodicAllowances maps to keccak256(abi.encode(msg.sender, token, delegationHash, index)), ensuring distinct token configurations and parallel delegations cannot cross-contaminate or deadlock allowance states.
  • Verified that atomic transaction execution ensures full rollback on revert without stale state retention.

• MetaSwap Adapter Signature Domain Separation (DF-3 - DelegationMetaSwapAdapter.sol):

  • Documented defense-in-depth recommendations for swapByDelegation API signatures: proposing EIP-712 domain binding and nonce tracking for off-chain quote validation to achieve parity with on-chain delegation replay guarantees.

• Veda Vault Minimum-Mint Slippage Boundaries (DF-4 - VedaAdapter.sol):

  • Documented slippage parameter boundaries in depositByDelegation: noted that passing minimumMint = 0 alongside perpetual max approvals (type(uint256).max) permits sub-optimal share conversion rates during vault distress. Recommended enforcing positive, quote-derived lower bounds.

• Batch Execution Resource Evaluation (DF-5 - src/DelegationManager.sol):

  • Validated that caller-controlled nested loops across permissionContexts, delegations, and caveats in redeemDelegations cannot produce external denial-of-service; transactions revert atomically and bounded limits remain naturally enforced by block gas ceilings.

Verification

• Verified Foundry build across core contracts and enforcers (forge build).
• Confirmed NatSpec formatting and parameter documentation.

---

Note

Low Risk
No executable or authorization logic changes appear in the diff; risk is limited to accidental non-whitespace edits if the normalization step altered file bytes.

Overview
The diff does not introduce observable logic, NatSpec, or API changes in any of the five touched files (DelegationManager, ERC721BalanceChangeEnforcer, MultiTokenPeriodEnforcer, DelegationMetaSwapAdapter, VedaAdapter). Each file is removed and re-added line-for-line with the same content, which usually indicates line-ending or encoding normalization rather than a functional or documentation update.

Reviewers should treat this as a no-op for behavior and security unless a byte-level diff shows otherwise. The PR description references audit documentation updates (e.g. ERC20BalanceChangeEnforcer, EIP-712 notes on MetaSwap) that are not present in this diff; those files are unchanged here.

^{Reviewed by Cursor Bugbot for commit 66e5a2d. Bugbot is set up for automated code reviews on this repo. Configure here.}