Skip to content

Commit 8c39f76

Browse files
alexandratranalexandratran
committed
Refactor and update delegation content
1 parent e4819e1 commit 8c39f76

File tree

22 files changed

+450
-879
lines changed

22 files changed

+450
-879
lines changed

‎delegation-toolkit/concepts/delegation.md‎

Lines changed: 0 additions & 140 deletions
This file was deleted.

delegation-toolkit/concepts/caveat-enforcers.md renamed to delegation-toolkit/concepts/delegation/caveat-enforcers.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
description: Learn about caveat enforcers and how they restrict delegations.
3-
sidebar_position: 4
3+
sidebar_position: 2
44
---
55

66
# Caveat enforcers
77

88
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).
9+
They serve as the underlying mechanism that enables conditional execution within the [Delegation Framework](index.md#delegation-framework).
1010

1111
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.
1212

@@ -119,23 +119,23 @@ This "all-or-nothing" approach ensures that delegations only execute exactly as
119119

120120
## Caveat builder
121121

122-
While caveat enforcers operate at the smart contract level, most developers interact with them through the [`CaveatBuilder`](../guides/create-delegation/restrict-delegation.md) interface in the MetaMask Delegation Toolkit.
122+
While caveat enforcers operate at the smart contract level, most developers interact with them through the [`CaveatBuilder`](../../guides/delegation/restrict-delegation.md) interface in the MetaMask Delegation Toolkit.
123123

124124
The `CaveatBuilder` provides a developer-friendly TypeScript API that:
125125

126126
- Abstracts away the complexity of correctly formatting and encoding caveat terms.
127127
- Provides type-checking and validation for caveat parameters.
128128
- Handles the creation of the `caveats` array needed when creating a delegation.
129129

130-
Each [caveat type](../reference/caveats.md) in the `CaveatBuilder`
130+
Each [caveat type](../../reference/caveats.md) in the `CaveatBuilder`
131131
corresponds to a specific caveat enforcer contract. For example, when you use:
132132

133133
```typescript
134134
caveatBuilder.addCaveat("allowedTargets", ["0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92"]);
135135
```
136136

137137
The builder is creating a caveat that references the
138-
[`AllowedTargetsEnforcer`](../reference/caveats.md#allowedtargets) contract address and
138+
[`AllowedTargetsEnforcer`](../../reference/caveats.md#allowedtargets) contract address and
139139
properly encodes the provided addresses as terms for that enforcer.
140140

141141
## Caveat enforcer best practices
@@ -145,26 +145,26 @@ When designing delegations with caveats, consider these best practices:
145145
- **Combine caveat enforcers appropriately** - Use multiple caveat enforcers to create comprehensive restrictions.
146146

147147
- **Consider caveat enforcer order** - When using caveat enforcers that modify external contract states, the order matters.
148-
For example, using [`NativeTokenPaymentEnforcer`](../reference/caveats.md#nativetokenpayment) before
149-
[`NativeBalanceChangeEnforcer`](../reference/caveats.md#nativebalancechange) might cause validation failures.
148+
For example, using [`NativeTokenPaymentEnforcer`](../../reference/caveats.md#nativetokenpayment) before
149+
[`NativeBalanceChangeEnforcer`](../../reference/caveats.md#nativebalancechange) might cause validation failures.
150150

151151
- **Be careful with unbounded delegations** - Always include appropriate caveat enforcers to limit what a delegate can do.
152152

153153
## Available caveat enforcers
154154

155-
The Delegation Toolkit provides [many out-of-the-box caveat enforcers](../reference/caveats.md)
155+
The Delegation Toolkit provides [many out-of-the-box caveat enforcers](../../reference/caveats.md)
156156
for common restriction patterns, including:
157157

158158
- Limiting target addresses and methods.
159159
- Setting time or block number constraints.
160160
- Restricting token transfers and approvals.
161161
- Limiting execution frequency.
162162

163-
For more complex scenarios, you can also [create custom caveat enforcers](../guides/create-delegation/create-custom-caveat-enforcer.md) by implementing the `ICaveatEnforcer` interface.
163+
For more complex scenarios, you can also [create custom caveat enforcers](../../guides/delegation/create-custom-caveat-enforcer.md) by implementing the `ICaveatEnforcer` interface.
164164

165165
## Attenuating authority with redelegations
166166

167-
When [creating chains of delegations](../guides/create-delegation/index.md#create-a-redelegation), it's important to understand how authority flows and can be restricted.
167+
When creating chains of delegations via [redelegations](index.md#delegation-types), it's important to understand how authority flows and can be restricted.
168168

169169
Caveats applied to a chain of delegations are *accumulative*—they stack on top of each other:
170170

‎delegation-toolkit/concepts/delegation/index.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
description: Learn about delegation, the delegation lifecycle, and the Delegation Framework.
3+
sidebar_position: 2
4+
toc_max_heading_level: 2
5+
---
6+
7+
import Tabs from "@theme/Tabs";
8+
import TabItem from "@theme/TabItem";
9+
10+
# Delegation
11+
12+
*Delegation* is the ability for a [MetaMask smart account](../smart-accounts.md) to grant permission to another smart account
13+
or externally owned account (EOA) to perform specific executions on its behalf, under defined rules and restrictions.
14+
The account that grants the permission is called the *delegator account*, while the account that receives the permission
15+
is called the *delegate account*.
16+
17+
The MetaMask Delegation Toolkit follows the [ERC-7710](https://eips.ethereum.org/EIPS/eip-7710) standard for smart contract delegation.
18+
In addition, users can use [caveat enforcers](caveat-enforcers.md) to apply rules and restrictions to delegations.
19+
For example: Alice delegates the ability to spend her USDC to Bob, limiting the amount to 100 USDC.
20+
21+
## Delegation lifecycle
22+
23+
The delegation lifecycle is as follows:
24+
25+
1. **Delegation creation** - A delegation is initialized, and the delegator account signs it.
26+
27+
2. **Caveat enforcement** - The caveats applied to the delegation specify conditions under which
28+
the delegation can be redeemed.
29+
30+
3. **Delegation storage** - The delegation can be stored, enabling retrieval for future redemption.
31+
32+
4. **Delegation redemption** - The delegate (the account being granted the permission) redeems the delegation via the Delegation Manager,
33+
which verifies that the delegated authority is valid in order to perform the execution.
34+
35+
See [how to perform executions on a user's behalf](../../guides/delegation/execute-on-users-behalf.md) to get started with the delegation lifecycle.
36+
37+
## Delegation types
38+
39+
There are multiple types of delegations you can create:
40+
41+
- A **root delegation** is a delegation that doesn't derive its authority from another delegation.
42+
It is when a delegator delegates its own authority away, as opposed to a redelegation.
43+
Use [`createDelegation`](../../reference/api/delegation.md#createdelegation) to create a root delegation.
44+
45+
- An **open root delegation** is a root delegation that doesn't specify a delegate.
46+
This means that any account can redeem the delegation.
47+
You must create open root delegations carefully, to ensure that they are not misused.
48+
Use [`createOpenDelegation`](../../reference/api/delegation.md#createopendelegation) to create a root delegation.
49+
50+
- A delegate can **redelegate** permissions that have been granted to them, creating a chain of delegations across trusted parties.
51+
Use [`createDelegation`](../../reference/api/delegation.md#createdelegation) to create a redelegation.
52+
53+
- An **open redelegation** is a redelegation that doesn't specify a delegate.
54+
This means that any account can redeem the redelegation.
55+
As with open root delegations, you must create open redelegations carefully, to ensure that they are not misused.
56+
Use [`createOpenDelegation`](../../reference/api/delegation.md#createopendelegation) to create an open redelegation.
57+
58+
## Delegation Framework
59+
60+
The MetaMask Delegation Toolkit includes the Delegation Framework, which is a
61+
[set of comprehensively audited smart contracts](https://github.com/MetaMask/delegation-framework) that
62+
collectively handle delegator account creation, the delegation lifecycle,
63+
and caveat enforcement.
64+
It consists of the following components:
65+
66+
- **Delegator Core** - Delegator Core contains the logic for the ERC-4337 compliant delegator accounts.
67+
It defines the interface needed for the Delegation Manager to invoke executions on behalf of the accounts.
68+
69+
- **Delegator account implementations** - Delegator accounts are smart accounts, and there are [multiple smart account implementations](../smart-accounts.md#smart-account-implementation-types),
70+
with differing signature schemes used to manage the underlying account.
71+
72+
- **Delegation Manager** - The Delegation Manager validates delegations and triggers executions
73+
on behalf of the delegator, ensuring tasks are executed accurately and securely.
74+
75+
When you redeem a delegation using [`redeemDelegations`](../../reference/api/delegation.md#redeemdelegations), the Delegation Manager performs the following steps.
76+
It processes a single step for all redemptions before proceeding to the next one:
77+
78+
1. Validates the input data by ensuring the lengths of `delegations`, `modes`, and
79+
`executions` match.
80+
2. Decodes and validates the delegation, checking that the caller is the delegate
81+
and that there are no empty signatures.
82+
3. Verifies delegation signatures, ensuring validity using ECDSA (for EOAs) or
83+
`isValidSignature` (for contracts).
84+
4. Validates the delegation chain's authority and ensures delegations are not disabled.
85+
5. Executes the `beforeHook` for each [caveat](caveat-enforcers.md) in the delegation, passing relevant data (`terms`,
86+
`arguments`, `mode`, `execution` `calldata`, and `delegationHash`) to the caveat enforcer.
87+
6. Calls `executeFromExecutor` to perform the delegation's execution, either by the delegator or
88+
the caller for self-authorized executions.
89+
7. Executes the `afterHook` for each caveat, similar to the `beforeHook`, passing required data
90+
to enforce post-execution conditions.
91+
8. Emits `RedeemedDelegation` events for each delegation that was successfully redeemed.
92+
93+
- **Caveat enforcers** - [Caveat enforcers](caveat-enforcers.md) manage rules and restrictions for delegations,
94+
providing fine-tuned control over delegated executions.
95+
96+
## Delegation flow
97+
98+
This diagram illustrates how a delegation is created and subsequently redeemed on the Delegation Manager.
99+
The Delegation Manager is responsible for validating the signature of the delegation and the caveat enforcers.
100+
If everything is correct, it allows a delegate to execute an action on behalf of the delegator.
101+
102+
Learn more about the caveat enforcer hooks in the [Caveat enforcers](caveat-enforcers.md) section.
103+
104+
```mermaid
105+
%%{
106+
init: {
107+
'sequence': {
108+
'actorMargin': 30,
109+
'width': 250
110+
}
111+
}
112+
}%%
113+
114+
sequenceDiagram
115+
participant Delegator
116+
participant Delegate
117+
participant Manager as Delegation Manager
118+
participant Enforcer as Caveat enforcer
119+
120+
Delegator->>Delegator: Create delegation with caveat enforcers
121+
Delegator->>Delegator: Sign delegation
122+
Delegator->>Delegate: Send signed delegation
123+
Note right of Delegate: Hold delegation until redemption
124+
125+
Delegate->>Manager: redeemDelegations() with delegation & execution details
126+
Manager->>Delegator: isValidSignature()
127+
Delegator-->>Manager: Confirm valid (or not)
128+
129+
Manager->>Enforcer: beforeAllHook()
130+
Note right of Manager: Expect no error
131+
Manager->>Enforcer: beforeHook()
132+
Note right of Manager: Expect no error
133+
134+
Manager->>Delegator: executeFromExecutor() with execution details
135+
Delegator->>Delegator: Perform execution
136+
Note right of Manager: Expect no error
137+
138+
Manager->>Enforcer: afterHook()
139+
Note right of Manager: Expect no error
140+
Manager->>Enforcer: afterAllHook()
141+
Note right of Manager: Expect no error
142+
```
143+
144+
## Execution modes
145+
146+
When redeeming a delegation using [`redeemDelegations`](../../reference/api/delegation.md#redeemdelegations), you must pass an execution mode for each delegation chain you pass to the method.
147+
The Delegation Toolkit supports several execution modes based on [ERC-7579](https://erc7579.com/): `SINGLE_DEFAULT_MODE`, `SINGLE_TRY_MODE`, `BATCH_DEFAULT_MODE`, and `BATCH_TRY_MODE`.
148+
149+
### `SINGLE` execution modes
150+
151+
In `SINGLE` execution modes, only a single delegation chain and a single execution can be provided. This mode processes delegations sequentially:
152+
153+
1. For each delegation in the chain, all caveats' `before` hooks are called.
154+
2. The single redeemed action is executed.
155+
3. For each delegation in the chain, all caveats' `after` hooks are called.
156+
157+
### `BATCH` execution modes
158+
159+
In `BATCH` execution modes, multiple delegation chains and multiple executions can be provided. This mode executes delegations in an interleaved way:
160+
161+
1. For each chain in the batch, and each delegation in the chain, all caveats' `before` hooks are called.
162+
2. Each redeemed action is executed.
163+
3. For each chain in the batch, and each delegation in the chain, all caveats' `after` hooks are called.
164+
165+
`BATCH` mode allows for powerful use cases, but the Delegation Framework currently does not include any `BATCH` compatible caveat enforcers.
166+
167+
### `DEFAULT` modes
168+
169+
In `DEFAULT` modes, if a revert occurs during redemption, the entire user operation reverts at that point.
170+
171+
### `TRY` modes
172+
173+
In `TRY` modes, if a revert occurs during redemption, execution of the user operation continues.

0 commit comments

Comments
 (0)