High-level navigation enhancements

.github/CODEOWNERS

@@ -17,6 +17,9 @@
 # Snaps documentation
 /snaps/ @MetaMask/tech-writers @MetaMask/snaps
 
+# Delegation Toolkit documentation
+/delegation-toolkit/ @MetaMask/tech-writers @MetaMask/delegation @MetaMask/delegation-devrel
+
 # SDK documentation
 /sdk/ @MetaMask/tech-writers @MetaMask/sdk-devs @MetaMask/sdk-devrel
 

delegation-toolkit/concepts/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Concepts",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "slug": "/concepts",
+    "title": "Delegation Toolkit concepts"
+  }
+}

delegation-toolkit/concepts/caveat-enforcers.md

@@ -0,0 +1,185 @@
+---
+description: Learn about caveat enforcers and how they restrict delegations.
+sidebar_position: 4
+---
+
+# Caveat enforcers
+
+The MetaMask Delegation Toolkit provides *caveat enforcers*, which are smart contracts that implement rules and restrictions (*caveats*) on delegations.
+They serve as the underlying mechanism that enables conditional execution within the [Delegation Framework](delegation.md#delegation-framework).
+
+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.
+
+:::warning Important
+- Without caveat enforcers, a delegation has infinite and unbounded authority to make any execution the original account can make.
+  We strongly recommend using caveat enforcers.
+- Caveat enforcers safeguard the execution process but do not guarantee a final state post-redemption.
+  Always consider the full impact of combined caveat enforcers.
+:::
+
+## Smart contract interface
+
+Caveat enforcers are Solidity contracts that implement the [`ICaveatEnforcer`](https://github.com/MetaMask/delegation-framework/blob/main/src/interfaces/ICaveatEnforcer.sol) interface:
+
+```solidity
+// SPDX-License-Identifier: MIT AND Apache-2.0
+pragma solidity 0.8.23;
+
+import { ModeCode } from "../utils/Types.sol";
+
+/**
+ * This is an abstract contract that exposes pre and post Execution hooks during delegation redemption.
+ */
+interface ICaveatEnforcer {
+  /**
+   * Enforces conditions before any actions in a batch redemption process begin.
+   */
+  function beforeAllHook(
+    bytes calldata _terms, // The terms to enforce set by the delegator.
+    bytes calldata _args, // An optional input parameter set by the redeemer at time of invocation.
+    ModeCode _mode, // The mode of execution for the executionCalldata.
+    bytes calldata _executionCalldata, // The data representing the execution.
+    bytes32 _delegationHash, // The hash of the delegation.
+    address _delegator, // The address of the delegator.
+    address _redeemer // The address that is redeeming the delegation.
+)
+    external;
+
+  /**
+   * Enforces conditions before the execution tied to a specific delegation in the redemption process.
+   */
+  function beforeHook(
+    bytes calldata _terms,
+    bytes calldata _args,
+    ModeCode _mode,
+    bytes calldata _executionCalldata,
+    bytes32 _delegationHash,
+    address _delegator,
+    address _redeemer
+  )
+    external;
+
+  /**
+   * Enforces conditions after the execution tied to a specific delegation in the redemption process.
+   */
+  function afterHook(
+    bytes calldata _terms,
+    bytes calldata _args,
+    ModeCode _mode,
+    bytes calldata _executionCalldata,
+    bytes32 _delegationHash,
+    address _delegator,
+    address _redeemer
+  )
+    external;
+
+  /**
+   * Enforces conditions after all actions in a batch redemption process have been executed.
+   */
+  function afterAllHook(
+    bytes calldata _terms,
+    bytes calldata _args,
+    ModeCode _mode,
+    bytes calldata _executionCalldata,
+    bytes32 _delegationHash,
+    address _delegator,
+    address _redeemer
+  )
+    external;
+}
+```
+
+The interface consists of four key hook functions that are called at different stages of the delegation redemption process:
+
+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.
+
+2. **`beforeHook`**: Called before the execution tied to a specific delegation. This allows for pre-execution validation of conditions specific to that delegation.
+
+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.
+
+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.
+
+Each of these hooks receives comprehensive information about the execution context, including:
+- The caveat terms specified by the delegator.
+- Optional arguments provided by the redeemer.
+- The execution mode and calldata.
+- The delegation hash.
+- The delegator and redeemer addresses.
+
+### Caveat enforcer rejection
+
+The most important safety feature of these hooks is their ability to block executions:
+
+- If any hook determines its conditions aren't met, it will **revert** (throw an exception).
+- When a reversion occurs, the entire delegation redemption process is canceled.
+- This prevents partial or invalid executions from occurring.
+- No state changes from the attempted execution will be committed to the blockchain.
+
+This "all-or-nothing" approach ensures that delegations only execute exactly as intended by their caveats.
+
+## Caveat builder
+
+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.
+
+The `CaveatBuilder` provides a developer-friendly TypeScript API that:
+
+- Abstracts away the complexity of correctly formatting and encoding caveat terms.
+- Provides type-checking and validation for caveat parameters.
+- Handles the creation of the `caveats` array needed when creating a delegation.
+
+Each [caveat type](../reference/caveats.md) in the `CaveatBuilder`
+corresponds to a specific caveat enforcer contract. For example, when you use:
+
+```typescript
+caveatBuilder.addCaveat("allowedTargets", ["0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92"]);
+```
+
+The builder is creating a caveat that references the
+[`AllowedTargetsEnforcer`](../reference/caveats.md#allowedtargets) contract address and
+properly encodes the provided addresses as terms for that enforcer.
+
+## Caveat enforcer best practices
+
+When designing delegations with caveats, consider these best practices:
+
+- **Combine caveat enforcers appropriately** - Use multiple caveat enforcers to create comprehensive restrictions.
+
+- **Consider caveat enforcer order** - When using caveat enforcers that modify external contract states, the order matters.
+  For example, using [`NativeTokenPaymentEnforcer`](../reference/caveats.md#nativetokenpayment) before
+  [`NativeBalanceChangeEnforcer`](../reference/caveats.md#nativebalancechange) might cause validation failures.
+
+- **Be careful with unbounded delegations** - Always include appropriate caveat enforcers to limit what a delegate can do.
+
+## Available caveat enforcers
+
+The Delegation Toolkit provides [many out-of-the-box caveat enforcers](../reference/caveats.md)
+for common restriction patterns, including:
+
+- Limiting target addresses and methods.
+- Setting time or block number constraints.
+- Restricting token transfers and approvals.
+- Limiting execution frequency.
+
+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.
+
+## Attenuating authority with redelegations
+
+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.
+
+Caveats applied to a chain of delegations are *accumulative*—they stack on top of each other:
+
+- Each delegation in the chain inherits all restrictions from its parent delegation.
+- New caveats can add further restrictions, but can't remove existing ones.
+
+This means that a delegate can only redelegate with equal or lesser authority than they received.
+
+### Example: Narrowing permissions
+
+Imagine a simple financial delegation scenario:
+
+1. **Alice delegates to Bob**, allowing him to withdraw up to 100 USDC on her behalf.
+2. **Bob re-delegates to Carol**, but limits the permission to:
+   - Only 50 USDC (reducing the amount).
+   - Only before the end of the week (adding a time constraint).
+
+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.

delegation-toolkit/concepts/delegation.md

@@ -0,0 +1,140 @@
+---
+description: Learn about delegation, the delegation lifecycle, and the Delegation Framework.
+sidebar_position: 2
+---
+
+# Delegation
+
+*Delegation* is the ability for a [smart account](smart-accounts.md) to grant permission to another smart account
+or externally owned account (EOA) to perform specific executions on their behalf, under defined rules and restrictions.
+The account that grants the permission is called the *delegator account*, while the account that receives the permission
+is called the *delegate account*.
+
+The MetaMask Delegation Toolkit includes the following delegation features:
+
+- **Caveats** - Users can use [caveat enforcers](caveat-enforcers.md) to apply rules and restrictions to delegations.
+  For example: Alice delegates the ability to spend her USDC to Bob, limiting the amount to 100 USDC.
+
+- **Chain of delegations** - Users can redelegate permissions that have been delegated to them, creating a chain of delegations across trusted parties.
+
+Delegations are created using the `Delegation` type, which is specified as follows:
+
+```typescript
+export type Delegation = {
+  delegate: Hex;     // The address to which the delegation is being granted.
+  delegator: Hex;    // The address that is granting the delegation.
+  authority: Hex;    // Hash of the parent delegation, or the constant ROOT_AUTHORITY.
+  caveats: Caveat[]; // Caveats that restrict the authority being granted.
+  salt: Hex;         // Used to avoid hash collisions between identical delegations.
+  signature: Hex;    // Signature from the delegator account.
+};
+```
+
+## Delegation lifecycle
+
+The delegation lifecycle is as follows:
+
+1. **Delegation creation** - A delegation is initialized, and the delegator account signs it.
+
+2. **Caveat enforcement** - The caveats applied to the delegation specify conditions under which
+   the delegation can be redeemed.
+
+3. **Delegation storage** - The delegation can be stored, enabling retrieval for future redemption.
+
+    :::note
+    [Storing and retrieving delegations](../experimental/store-retrieve-delegations.md) using the toolkit's
+    `DelegationStorageClient` is an experimental feature.
+    :::
+
+4. **Delegation redemption** - The delegate (the account being granted the permission) redeems the
+   delegation through an [ERC-4337 user operation](smart-accounts.md#account-abstraction-erc-4337),
+   which verifies that the delegated authority is valid in order to perform the execution.
+
+See [how to create a delegation](../how-to/create-delegation/index.md) to get started with the
+delegation lifecycle.
+
+## Delegation Framework
+
+The MetaMask Delegation Toolkit includes the Delegation Framework, which is a
+[set of comprehensively audited smart contracts](https://github.com/MetaMask/delegation-framework) that
+collectively handle delegator account creation, the delegation lifecycle,
+and caveat enforcement.
+It consists of the following components:
+
+- **Delegator Core** - Delegator Core contains the logic for the ERC-4337 compliant delegator accounts.
+  It defines the interface needed for the Delegation Manager to invoke executions on behalf of the accounts.
+
+- **Delegator account implementations** - There are [multiple delegator account implementations](smart-accounts.md#smart-account-implementation-types),
+  with the main difference being the signature scheme used to manage the underlying account.
+
+- **Delegation Manager** - The Delegation Manager validates delegations and triggers executions
+  on behalf of the delegator, ensuring tasks are executed accurately and securely.
+
+  When a delegation is redeemed, the Delegation Manager performs the following steps.
+  It processes a single step for all redemptions before proceeding to the next one:
+
+  1. Validates the input data by ensuring the lengths of `permissionContexts`, `modes`, and
+     `executionCallDatas` match, or throws `BatchDataLengthMismatch`.
+	2. Decodes and validates the delegation, checking that the caller (`msg.sender`) is the delegate
+     and that there are no empty signatures, or throws `InvalidDelegate`.
+	3. Verifies delegation signatures, ensuring validity using `ECDSA` (for EOAs) or
+     `isValidSignature` (for contracts), or throws `InvalidSignature`.
+	4. Validates the delegation chain's authority and ensures delegations are not disabled.
+	5. Executes the `beforeHook` for each `caveat` in the delegation, passing relevant data (`terms`,
+     `arguments`, `mode`, `execution` `calldata`, and `delegationHash`) to the caveat enforcer.
+	6. Calls `executeFromExecutor` to perform the delegation's execution, either by the delegator or
+     the caller for self-authorized executions.
+	7. Executes the `afterHook` for each `caveat`, similar to the `beforeHook`, passing required data
+     to enforce post-execution conditions.
+	8. Emits `RedeemedDelegation` events for each delegation that was successfully redeemed.
+
+- **Caveat enforcers** - [Caveat enforcers](caveat-enforcers.md) manage rules and restrictions for delegations,
+  providing fine-tuned control over delegated executions.
+
+## Delegation redemption flow
+
+This diagram illustrates how a delegation is created and subsequently redeemed on the Delegation Manager.
+The Delegation Manager is responsible for validating the signature of the delegation and the caveat enforcers.
+If everything is correct, it allows a delegate to execute an action on behalf of the delegator.
+
+Learn more about the caveat enforcer hooks in the [Caveat enforcers](caveat-enforcers.md) section.
+
+```mermaid
+%%{
+  init: {
+    'sequence': {
+      'actorMargin': 25,
+      'width': 200
+    }
+  }
+}%%
+
+sequenceDiagram
+    participant Delegator
+    participant Delegate
+    participant Manager as Delegation Manager
+    participant Enforcer as Caveat enforcer
+
+    Delegator->>Delegator: Create delegation with caveat enforcers
+    Delegator->>Delegator: Sign delegation
+    Delegator->>Delegate: Send signed delegation
+    Note right of Delegate: Hold delegation until redemption
+
+    Delegate->>Manager: redeemDelegations() with delegation & execution details
+    Manager->>Delegator: isValidSignature()
+    Delegator-->>Manager: Confirm valid (or not)
+
+    Manager->>Enforcer: beforeAllHook()
+    Note right of Manager: Expect no error
+    Manager->>Enforcer: beforeHook()
+    Note right of Manager: Expect no error
+
+    Manager->>Delegator: executeFromExecutor() with execution details
+    Delegator->>Delegator: Perform execution
+    Note right of Manager: Expect no error
+
+    Manager->>Enforcer: afterHook()
+    Note right of Manager: Expect no error
+    Manager->>Enforcer: afterAllHook()
+    Note right of Manager: Expect no error
+```