|
| 1 | +--- |
| 2 | +description: Learn about caveat enforcers and how they restrict delegations. |
| 3 | +sidebar_position: 4 |
| 4 | +--- |
| 5 | + |
| 6 | +# Caveat enforcers |
| 7 | + |
| 8 | +The MetaMask Delegation Toolkit provides *caveat enforcers*, which are smart contracts that implement rules and restrictions (*caveats*) on delegations. |
| 9 | +They serve as the underlying mechanism that enables conditional execution within the [Delegation Framework](delegation.md#delegation-framework). |
| 10 | + |
| 11 | +A caveat enforcer acts as a gate that validates whether a delegation can be used for a particular execution. When a delegate attempts to execute an action on behalf of a delegator, each caveat enforcer specified in the delegation evaluates whether the execution meets its defined criteria. |
| 12 | + |
| 13 | +:::warning Important |
| 14 | +- Without caveat enforcers, a delegation has infinite and unbounded authority to make any execution the original account can make. |
| 15 | + We strongly recommend using caveat enforcers. |
| 16 | +- Caveat enforcers safeguard the execution process but do not guarantee a final state post-redemption. |
| 17 | + Always consider the full impact of combined caveat enforcers. |
| 18 | +::: |
| 19 | + |
| 20 | +## Smart contract interface |
| 21 | + |
| 22 | +Caveat enforcers are Solidity contracts that implement the [`ICaveatEnforcer`](https://github.com/MetaMask/delegation-framework/blob/main/src/interfaces/ICaveatEnforcer.sol) interface: |
| 23 | + |
| 24 | +```solidity |
| 25 | +// SPDX-License-Identifier: MIT AND Apache-2.0 |
| 26 | +pragma solidity 0.8.23; |
| 27 | +
|
| 28 | +import { ModeCode } from "../utils/Types.sol"; |
| 29 | +
|
| 30 | +/** |
| 31 | + * This is an abstract contract that exposes pre and post Execution hooks during delegation redemption. |
| 32 | + */ |
| 33 | +interface ICaveatEnforcer { |
| 34 | + /** |
| 35 | + * Enforces conditions before any actions in a batch redemption process begin. |
| 36 | + */ |
| 37 | + function beforeAllHook( |
| 38 | + bytes calldata _terms, // The terms to enforce set by the delegator. |
| 39 | + bytes calldata _args, // An optional input parameter set by the redeemer at time of invocation. |
| 40 | + ModeCode _mode, // The mode of execution for the executionCalldata. |
| 41 | + bytes calldata _executionCalldata, // The data representing the execution. |
| 42 | + bytes32 _delegationHash, // The hash of the delegation. |
| 43 | + address _delegator, // The address of the delegator. |
| 44 | + address _redeemer // The address that is redeeming the delegation. |
| 45 | +) |
| 46 | + external; |
| 47 | +
|
| 48 | + /** |
| 49 | + * Enforces conditions before the execution tied to a specific delegation in the redemption process. |
| 50 | + */ |
| 51 | + function beforeHook( |
| 52 | + bytes calldata _terms, |
| 53 | + bytes calldata _args, |
| 54 | + ModeCode _mode, |
| 55 | + bytes calldata _executionCalldata, |
| 56 | + bytes32 _delegationHash, |
| 57 | + address _delegator, |
| 58 | + address _redeemer |
| 59 | + ) |
| 60 | + external; |
| 61 | +
|
| 62 | + /** |
| 63 | + * Enforces conditions after the execution tied to a specific delegation in the redemption process. |
| 64 | + */ |
| 65 | + function afterHook( |
| 66 | + bytes calldata _terms, |
| 67 | + bytes calldata _args, |
| 68 | + ModeCode _mode, |
| 69 | + bytes calldata _executionCalldata, |
| 70 | + bytes32 _delegationHash, |
| 71 | + address _delegator, |
| 72 | + address _redeemer |
| 73 | + ) |
| 74 | + external; |
| 75 | +
|
| 76 | + /** |
| 77 | + * Enforces conditions after all actions in a batch redemption process have been executed. |
| 78 | + */ |
| 79 | + function afterAllHook( |
| 80 | + bytes calldata _terms, |
| 81 | + bytes calldata _args, |
| 82 | + ModeCode _mode, |
| 83 | + bytes calldata _executionCalldata, |
| 84 | + bytes32 _delegationHash, |
| 85 | + address _delegator, |
| 86 | + address _redeemer |
| 87 | + ) |
| 88 | + external; |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +The interface consists of four key hook functions that are called at different stages of the delegation redemption process: |
| 93 | + |
| 94 | +1. **`beforeAllHook`**: Called before any actions in a batch redemption process begin. This can be used to verify conditions that must be true for the entire batch execution. |
| 95 | + |
| 96 | +2. **`beforeHook`**: Called before the execution tied to a specific delegation. This allows for pre-execution validation of conditions specific to that delegation. |
| 97 | + |
| 98 | +3. **`afterHook`**: Called after the execution tied to a specific delegation completes. This can verify post-execution state changes or effects specific to that delegation. |
| 99 | + |
| 100 | +4. **`afterAllHook`**: Called after all actions in a batch redemption process have completed. This enables verification of final conditions after the entire batch has executed. |
| 101 | + |
| 102 | +Each of these hooks receives comprehensive information about the execution context, including: |
| 103 | +- The caveat terms specified by the delegator. |
| 104 | +- Optional arguments provided by the redeemer. |
| 105 | +- The execution mode and calldata. |
| 106 | +- The delegation hash. |
| 107 | +- The delegator and redeemer addresses. |
| 108 | + |
| 109 | +### Caveat enforcer rejection |
| 110 | + |
| 111 | +The most important safety feature of these hooks is their ability to block executions: |
| 112 | + |
| 113 | +- If any hook determines its conditions aren't met, it will **revert** (throw an exception). |
| 114 | +- When a reversion occurs, the entire delegation redemption process is canceled. |
| 115 | +- This prevents partial or invalid executions from occurring. |
| 116 | +- No state changes from the attempted execution will be committed to the blockchain. |
| 117 | + |
| 118 | +This "all-or-nothing" approach ensures that delegations only execute exactly as intended by their caveats. |
| 119 | + |
| 120 | +## Caveat builder |
| 121 | + |
| 122 | +While caveat enforcers operate at the smart contract level, most developers interact with them through the [`CaveatBuilder`](../how-to/create-delegation/restrict-delegation.md) interface in the MetaMask Delegation Toolkit. |
| 123 | + |
| 124 | +The `CaveatBuilder` provides a developer-friendly TypeScript API that: |
| 125 | + |
| 126 | +- Abstracts away the complexity of correctly formatting and encoding caveat terms. |
| 127 | +- Provides type-checking and validation for caveat parameters. |
| 128 | +- Handles the creation of the `caveats` array needed when creating a delegation. |
| 129 | + |
| 130 | +Each [caveat type](../how-to/create-delegation/restrict-delegation.md#caveat-types) in the `CaveatBuilder` |
| 131 | +corresponds to a specific caveat enforcer contract. For example, when you use: |
| 132 | + |
| 133 | +```typescript |
| 134 | +caveatBuilder.addCaveat("allowedTargets", ["0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92"]); |
| 135 | +``` |
| 136 | + |
| 137 | +The builder is creating a caveat that references the |
| 138 | +[`AllowedTargetsEnforcer`](../how-to/create-delegation/restrict-delegation.md#allowedtargets) contract address and |
| 139 | +properly encodes the provided addresses as terms for that enforcer. |
| 140 | + |
| 141 | +## Caveat enforcer best practices |
| 142 | + |
| 143 | +When designing delegations with caveats, consider these best practices: |
| 144 | + |
| 145 | +- **Combine caveat enforcers appropriately** - Use multiple caveat enforcers to create comprehensive restrictions. |
| 146 | + |
| 147 | +- **Consider caveat enforcer order** - When using caveat enforcers that modify external contract states, the order matters. |
| 148 | + For example, using [`NativeTokenPaymentEnforcer`](../how-to/create-delegation/restrict-delegation.md#nativetokenpayment) before |
| 149 | + [`NativeBalanceChangeEnforcer`](../how-to/create-delegation/restrict-delegation.md#nativebalancechange) might cause validation failures. |
| 150 | + |
| 151 | +- **Be careful with unbounded delegations** - Always include appropriate caveat enforcers to limit what a delegate can do. |
| 152 | + |
| 153 | +## Available caveat enforcers |
| 154 | + |
| 155 | +The Delegation Toolkit provides [many out-of-the-box caveat enforcers](../how-to/create-delegation/restrict-delegation.md#caveat-types) |
| 156 | +for common restriction patterns, including: |
| 157 | + |
| 158 | +- Limiting target addresses and methods. |
| 159 | +- Setting time or block number constraints. |
| 160 | +- Restricting token transfers and approvals. |
| 161 | +- Limiting execution frequency. |
| 162 | + |
| 163 | +For more complex scenarios, you can also [create custom caveat enforcers](../how-to/create-delegation/create-custom-caveat-enforcer.md) by implementing the `ICaveatEnforcer` interface. |
| 164 | + |
| 165 | +## Attenuating authority with redelegations |
| 166 | + |
| 167 | +When [creating chains of delegations](../how-to/create-delegation/index.md#create-a-redelegation), it's important to understand how authority flows and can be restricted. |
| 168 | + |
| 169 | +Caveats applied to a chain of delegations are *accumulative*—they stack on top of each other: |
| 170 | + |
| 171 | +- Each delegation in the chain inherits all restrictions from its parent delegation. |
| 172 | +- New caveats can add further restrictions, but can't remove existing ones. |
| 173 | + |
| 174 | +This means that a delegate can only redelegate with equal or lesser authority than they received. |
| 175 | + |
| 176 | +### Example: Narrowing permissions |
| 177 | + |
| 178 | +Imagine a simple financial delegation scenario: |
| 179 | + |
| 180 | +1. **Alice delegates to Bob**, allowing him to withdraw up to 100 USDC on her behalf. |
| 181 | +2. **Bob re-delegates to Carol**, but limits the permission to: |
| 182 | + - Only 50 USDC (reducing the amount). |
| 183 | + - Only before the end of the week (adding a time constraint). |
| 184 | + |
| 185 | +Carol now has a more restricted version of Alice's original delegation. Bob couldn't give Carol more authority than he had (such as allowing her to withdraw 200 USDC), but he could narrow the permission. |
0 commit comments