[Smart Accounts KIt] Update docs for v1.6 release

gator-sidebar.js

@@ -107,6 +107,7 @@ const sidebar = {
               items: [
                 'guides/advanced-permissions/use-permissions/erc20-token',
                 'guides/advanced-permissions/use-permissions/native-token',
+                'guides/advanced-permissions/use-permissions/approval-revocation',
               ],
             },
             'guides/advanced-permissions/get-granted-permissions',

smart-accounts-kit/get-started/supported-advanced-permissions.md

@@ -12,9 +12,12 @@ the Smart Accounts Kit, [MetaMask Flask](/snaps/get-started/install-flask), and
 If you don't see the Advanced Permissions type you're looking for, you can request it by
 emailing [`hellogators@consensys.net`](mailto:hellogators@consensys.net).
 
-| Permission type                                                                                                          | Smart Accounts Kit | MetaMask Flask | MetaMask    |
-| ------------------------------------------------------------------------------------------------------------------------ | ------------------ | -------------- | ----------- |
-| [ERC-20 periodic](../guides/advanced-permissions/use-permissions/erc20-token.md#erc-20-periodic-permission)              | >= v0.1.0          | >= v13.5.0     | >= v13.23.0 |
-| [ERC-20 stream](../guides/advanced-permissions/use-permissions/erc20-token.md#erc-20-stream-permission)                  | >= v0.1.0          | >= v13.5.0     | >= v13.23.0 |
-| [Native token periodic](../guides/advanced-permissions/use-permissions/native-token.md#native-token-periodic-permission) | >= v0.1.0          | >= v13.5.0     | >= v13.23.0 |
-| [Native token stream](../guides/advanced-permissions/use-permissions/native-token.md#native-token-stream-permission)     | >= v0.1.0          | >= v13.5.0     | >= v13.23.0 |
+| Permission type                                                                                                                         | Smart Accounts Kit | MetaMask Flask      | MetaMask    |
+| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------- | ----------- |
+| [ERC-20 allowance](../guides/advanced-permissions/use-permissions/erc20-token.md#erc-20-allowance-permission)                           | >= v1.4.0          | >= v13.32.1-flask.0 | >= v13.32.1 |
+| [ERC-20 periodic](../guides/advanced-permissions/use-permissions/erc20-token.md#erc-20-periodic-permission)                             | >= v0.1.0          | >= v13.5.0          | >= v13.23.0 |
+| [ERC-20 stream](../guides/advanced-permissions/use-permissions/erc20-token.md#erc-20-stream-permission)                                 | >= v0.1.0          | >= v13.5.0          | >= v13.23.0 |
+| [Native token allowance](../guides/advanced-permissions/use-permissions/native-token.md#native-token-allowance-permission)              | >= v1.4.0          | >= v13.32.1-flask.0 | >= v13.32.1 |
+| [Native token periodic](../guides/advanced-permissions/use-permissions/native-token.md#native-token-periodic-permission)                | >= v0.1.0          | >= v13.5.0          | >= v13.23.0 |
+| [Native token stream](../guides/advanced-permissions/use-permissions/native-token.md#native-token-stream-permission)                    | >= v0.1.0          | >= v13.5.0          | >= v13.23.0 |
+| [Token approval revocation](../guides/advanced-permissions/use-permissions/approval-revocation.md#token-approval-revocation-permission) | >= v1.6.0          | -                   | -           |

smart-accounts-kit/guides/advanced-permissions/use-permissions/approval-revocation.md

@@ -0,0 +1,80 @@
+---
+description: Learn how to use the token approval revocation permission with Advanced Permissions (ERC-7715).
+keywords: [permissions, revocation, approval, 7715, erc-7715, erc20, erc721, permit2]
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Use approval revocation permission
+
+[Advanced Permissions (ERC-7715)](../../../concepts/advanced-permissions.md) supports the token approval
+revocation permission type that allows you to request permission to revoke existing token approvals
+on behalf of the user.
+
+## Prerequisites
+
+- [Install and set up the Smart Accounts Kit.](../../../get-started/install.md)
+- [Configure the Smart Accounts Kit.](../../configure-toolkit.md)
+- [Create a session account.](../execute-on-metamask-users-behalf.md#3-set-up-a-session-account)
+
+## Token approval revocation permission
+
+This permission type enables revoking existing token approvals on behalf of the user.
+
+For example, a user signs an ERC-7715 permission that lets a dapp revoke any ERC-20 token
+allowances periodically, or during an ongoing exploit.
+
+See the [token approval revocation permission API reference](../../../reference/advanced-permissions/permissions.md#token-approval-revocation-permission) for more information.
+
+<Tabs>
+<TabItem value="example.ts">
+
+```typescript
+import { sepolia as chain } from 'viem/chains'
+import { walletClient } from './client.ts'
+
+// Since current time is in seconds, convert milliseconds to seconds.
+const currentTime = Math.floor(Date.now() / 1000)
+
+// 30 days from now.
+const expiry = currentTime + 60 * 60 * 24 * 30
+
+const grantedPermissions = await walletClient.requestExecutionPermissions([
+  {
+    chainId: chain.id,
+    expiry,
+    // The requested permissions will be granted to the
+    // session account.
+    to: sessionAccount.address,
+    permission: {
+      type: 'token-approval-revocation',
+      data: {
+        erc20Approve: true,
+        erc721Approve: false,
+        erc721SetApprovalForAll: false,
+        permit2Approve: true,
+        permit2Lockdown: false,
+        permit2InvalidateNonces: false,
+        justification: 'Permission to revoke ERC-20 token approvals',
+      },
+      isAdjustmentAllowed: false,
+    },
+  },
+])
+```
+
+</TabItem>
+<TabItem value="client.ts">
+
+```typescript
+import { createWalletClient, custom } from 'viem'
+import { erc7715ProviderActions } from '@metamask/smart-accounts-kit/actions'
+
+export const walletClient = createWalletClient({
+  transport: custom(window.ethereum),
+}).extend(erc7715ProviderActions())
+```
+
+</TabItem>
+</Tabs>

smart-accounts-kit/reference/advanced-permissions/permissions.md

@@ -1,12 +1,21 @@
 ---
 description: Advanced Permissions (ERC-7715) reference.
 sidebar_label: Permissions
-keywords: [ERC-7715, permissions, ERC-20 token, native token, reference, advanced permissions]
+keywords:
+  [
+    ERC-7715,
+    permissions,
+    ERC-20 token,
+    native token,
+    approval revocation,
+    reference,
+    advanced permissions,
+  ]
 ---
 
 # Advanced Permissions reference
 
-When [executing on a MetaMask user's behalf](../../guides/advanced-permissions/execute-on-metamask-users-behalf.md), you can request the following permission types for ERC-20 token and native token transfers.
+When [executing on a MetaMask user's behalf](../../guides/advanced-permissions/execute-on-metamask-users-behalf.md), you can request the following permission types.
 Learn [how to use Advanced Permissions types](../../guides/advanced-permissions/use-permissions/erc20-token.md).
 
 ## ERC-20 token permissions
@@ -223,3 +232,37 @@ const permission = {
   isAdjustmentAllowed: true,
 }
 ```
+
+## Token approval revocation permission
+
+Enables revoking an existing token approvals on behalf of the user.
+
+#### Parameters
+
+| Name                      | Type      | Required | Description                                                            |
+| ------------------------- | --------- | -------- | ---------------------------------------------------------------------- |
+| `erc20Approve`            | `boolean` | Yes      | Whether to allow revoking ERC-20 allowances.                           |
+| `erc721Approve`           | `boolean` | Yes      | Whether to allow revoking ERC-721 per-token approvals.                 |
+| `erc721SetApprovalForAll` | `boolean` | Yes      | Whether to allow revoking ERC-721 and ERC-1155 operator approvals.     |
+| `permit2Approve`          | `boolean` | Yes      | Whether to allow revoking Permit2 approvals.                           |
+| `permit2Lockdown`         | `boolean` | Yes      | Whether to allow locking down Permit2.                                 |
+| `permit2InvalidateNonces` | `boolean` | Yes      | Whether to allow invalidating Permit2.                                 |
+| `justification`           | `string`  | No       | A human-readable explanation of why the permission is being requested. |
+
+#### Example
+
+```typescript
+const permission = {
+  type: 'token-approval-revocation',
+  data: {
+    erc20Approve: true,
+    erc721Approve: true,
+    erc721SetApprovalForAll: true,
+    permit2Approve: false,
+    permit2Lockdown: false,
+    permit2InvalidateNonces: false,
+    justification: 'Permission to revoke ERC-20, ERC-721, and ERC-115 token approvals',
+  },
+  isAdjustmentAllowed: false,
+}
+```

smart-accounts-kit/reference/delegation/caveats.md

@@ -13,6 +13,42 @@ When [constraining a delegation scope](../../guides/delegation/use-delegation-sc
 
 You can use either a string literal or the [`CaveatType`](../types.md#caveattype) enum to define the caveat type.
 
+## `approvalRevocation`
+
+Restricts the <GlossaryTerm term="Delegate account">delegate</GlossaryTerm> to revoking token approvals.
+Set each flag to `true` to enable the corresponding revocation type.
+
+<GlossaryTerm term="Caveat enforcer" /> contract: [`ApprovalRevocationEnforcer.sol`](https://github.com/MetaMask/delegation-framework/blob/main/src/enforcers/ApprovalRevocationEnforcer.sol)
+
+### Parameters
+
+| Name                      | Type      | Required | Description                                                        |
+| ------------------------- | --------- | -------- | ------------------------------------------------------------------ |
+| `erc20Approve`            | `boolean` | Yes      | Whether to allow revoking ERC-20 allowances.                       |
+| `erc721Approve`           | `boolean` | Yes      | Whether to allow revoking ERC-721 per-token approvals.             |
+| `erc721SetApprovalForAll` | `boolean` | Yes      | Whether to allow revoking ERC-721 and ERC-1155 operator approvals. |
+| `permit2Approve`          | `boolean` | Yes      | Whether to allow revoking Permit2 approvals.                       |
+| `permit2Lockdown`         | `boolean` | Yes      | Whether to allow locking down Permit2.                             |
+| `permit2InvalidateNonces` | `boolean` | Yes      | Whether to allow invalidating Permit2.                             |
+
+### Example
+
+```typescript
+import { CaveatType } from '@metamask/smart-accounts-kit'
+
+const caveats = [
+  {
+    type: CaveatType.ApprovalRevocation,
+    erc20Approve: true,
+    erc721Approve: false,
+    erc721SetApprovalForAll: false,
+    permit2Approve: false,
+    permit2Lockdown: false,
+    permit2InvalidateNonces: false,
+  },
+]
+```
+
 ## `allowedCalldata`
 
 Limits the calldata that is executed.

smart-accounts-kit/reference/delegation/index.md

@@ -273,6 +273,66 @@ export const delegation = createDelegation({
 </TabItem>
 </Tabs>
 
+## `decodeRevertData`
+
+Decodes raw ABI-encoded revert data into a [`DecodedRevertReason`](../types.md#decodedrevertreason).
+
+Tries standard Solidity errors, and known
+<GlossaryTerm term="Delegation Framework" /> ABIs, then falls back to decoding printable ASCII bytes.
+
+Returns `undefined` if the data could not be decoded.
+
+### Parameters
+
+| Name      | Type  | Required | Description                      |
+| --------- | ----- | -------- | -------------------------------- |
+| `rawData` | `Hex` | Yes      | The raw ABI-encoded revert data. |
+
+### Example
+
+```ts
+import { decodeRevertData } from '@metamask/smart-accounts-kit/utils'
+
+const decoded = decodeRevertData('0x08c379a0...')
+```
+
+## `decodeRevertReason`
+
+Extracts revert data from an error object and decodes it using [`decodeRevertData`](#decoderevertdata).
+Use this when you catch an error from any <GlossaryTerm term="Delegation Framework" /> interaction
+and want to decode the revert reason.
+
+Returns `undefined` if no revert data is found in the error.
+
+### Parameters
+
+| Name    | Type      | Required | Description                                              |
+| ------- | --------- | -------- | -------------------------------------------------------- |
+| `error` | `unknown` | Yes      | The error object to extract and decode revert data from. |
+
+### Example
+
+This example assumes you have a delegation signed by the <GlossaryTerm term="Delegator account">delegator</GlossaryTerm>.
+
+```ts
+import { ExecutionMode } from '@metamask/smart-accounts-kit'
+import { DelegationManager } from '@metamask/smart-accounts-kit/contracts'
+import { decodeRevertReason } from '@metamask/smart-accounts-kit/utils'
+
+try {
+  await DelegationManager.execute.redeemDelegations({
+    delegations: [[signedDelegation]],
+    modes: [ExecutionMode.SingleDefault],
+    executions: [[execution]],
+  })
+} catch (error) {
+  const decoded = decodeRevertReason(error)
+  if (decoded) {
+    console.log(decoded.message)
+  }
+}
+```
+
 ## `deploySmartAccountsEnvironment`
 
 Deploys the <GlossaryTerm term="Delegation Framework" /> contracts to an EVM chain.

smart-accounts-kit/reference/types.md

@@ -18,6 +18,7 @@ Enum representing the [caveat](delegation/caveats.md) type.
 
 | Value                                         | String                               |
 | --------------------------------------------- | ------------------------------------ |
+| `CaveatType.ApprovalRevocation`               | `"approvalRevocation"`               |
 | `CaveatType.AllowedCalldata`                  | `"allowedCalldata"`                  |
 | `CaveatType.AllowedMethods`                   | `"allowedMethods"`                   |
 | `CaveatType.AllowedTargets`                   | `"allowedTargets"`                   |
@@ -143,6 +144,16 @@ Represents a delegation that grants permissions from a <GlossaryTerm term="Deleg
 | `salt`      | `Hex`                   | Yes      | The salt for generating the delegation hash. This helps prevent hash collisions when creating identical delegations.               |
 | `signature` | `Hex`                   | Yes      | The signature to validate the delegation.                                                                                          |
 
+### `DecodedRevertReason`
+
+Represents a decoded revert reason from a <GlossaryTerm term="Delegation Framework" /> error. Returned by [`decodeRevertData`](delegation/index.md#decoderevertdata) and [`decodeRevertReason`](delegation/index.md#decoderevertreason).
+
+| Name        | Type     | Required | Description                        |
+| ----------- | -------- | -------- | ---------------------------------- |
+| `errorName` | `string` | Yes      | The name of the decoded error.     |
+| `message`   | `string` | Yes      | The decoded revert reason message. |
+| `rawData`   | `Hex`    | Yes      | The raw ABI-encoded revert data.   |
+
 ### `ExactCalldataBuilderConfig`
 
 Defines the exact calldata the <GlossaryTerm term="Delegate account">delegate</GlossaryTerm> is allowed to call.