Skip to content

Commit f83b2c2

Browse files
author
“AyushBherwani1998”
committed
add delegation scopes guide
1 parent e68e3c6 commit f83b2c2

File tree

5 files changed

+316
-0
lines changed

5 files changed

+316
-0
lines changed

‎delegation-toolkit/guides/delegation/use-delegation-scope/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Use delegation scopes",
3+
"position": 2
4+
}

‎delegation-toolkit/guides/delegation/use-delegation-scope/function-call-scope.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
description: Learn how to use the function call scope for a delegation
3+
sidebar_position: 2
4+
sidebar_label: Function call scope
5+
---
6+
7+
# Function call scope
8+
9+
Function call scope define the specific methods, contract addresses, and optional calldata that are allowed
10+
for the delegation. For example, Alice can delegate to Bob the ability to call the approve function
11+
on the USDC contract, with the approval amount set to `0`.
12+
13+
The scope internally uses the combination of [`allowedTargets`](../../../reference/caveats#allowedtargets) and [`allowedMethods`](../../../reference/caveats#allowedmethods) caveat enforcers, and
14+
can optionally include [`allowedCalldata`](../../../reference/caveats#allowedcalldata) or [`exactCalldata`](../../../reference/caveats#exactcalldata) caveat enforcers when those parameters are specified.
15+
16+
## Prerequisites
17+
18+
- [Install and set up the Delegation Toolkit.](../../get-started/install)
19+
- [Configure the Delegation Toolkit](../../configure).
20+
- [Create a MetaMask smart account](../execute-on-smart-accounts-behalf#3-create-a-delegator-account) to create delegations.
21+
- [Create a delegate account](../execute-on-smart-accounts-behalf#4-create-a-delegate-account)
22+
23+
## Use function call scope
24+
25+
The scope requires `targets` and `selectors` as mandatory parameters for the configuration. You can specify
26+
the allowed methods in `selectors` and the permitted contract addresses in `targets`.
27+
28+
In the example, we are setting the delegation scope to allow the delegate to call the `approve` function
29+
on the USDC token contract.
30+
31+
```typescript
32+
import { createDelegation } from "@metamask/delegatino-toolkit";
33+
34+
// USDC address on Sepolia.
35+
const USDC_ADDRESS = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
36+
37+
const delegation = createDelegation({
38+
scope: {
39+
type: "functionCall",
40+
targets: [USDC_ADDRESS],
41+
selectors: ["approve(address, uint256)"]
42+
},
43+
to: delegateaAccount,
44+
from: delegatorAccount,
45+
});
46+
```
47+
48+
## Next steps
49+
50+
- See [Restrict a delegation](../restrict-delegation) to learn how to further limit the authority of a delegation.

‎delegation-toolkit/guides/delegation/use-delegation-scope/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
description: Learn how to use the delegation scopes
3+
sidebar_position: 1
4+
---
5+
6+
# Use delegation scopes
7+
8+
You can set a scope configuration when creating a delegation to define its permissions. Scopes help define the initial
9+
authority for the delegation and prevent misuse. This initial authority can then be further refined by adding caveats.
10+
When creating a delegation, you can use one of the supported scopes.
11+
12+
The Delegation Toolkit currently supports three categories of scopes:
13+
14+
| Scope Type | Description |
15+
|------------|-------------|
16+
| [Spending limit scopes](./spending-limit-scope) | Restricts the spending of native tokens, ERC-20, and ERC-721 assets based on defined conditions. |
17+
| [Function call scope](./function-call-scope) | Restricts the delegation to specific contract methods, contract addresses, or even precise calldata. |
18+
| [Ownership transfer scope](./owernship-transfer-scope) | Restricts the delegation to only allow ownership transfers, specifically the `transferOwnership` function for a specified contract. |

‎delegation-toolkit/guides/delegation/use-delegation-scope/owernship-transfer-scope.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
description: Learn how to use the ownership transfer scope for a delegation
3+
sidebar_position: 3
4+
sidebar_label: Ownership transfer scope
5+
---
6+
7+
# Ownership transfer scope
8+
9+
Ownership Transfer Scope restricts a delegation to ownership transfer calls only. For example, if Alice has deployed a
10+
smart contract, she can delegate to Bob the ability to transfer ownership of that contract.
11+
12+
The scope internally uses the [`ownershipTransfer`](../../../reference/caveats#ownershiptransfer) caveat enfrocer.
13+
14+
## Prerequisites
15+
16+
- [Install and set up the Delegation Toolkit.](../../get-started/install)
17+
- [Configure the Delegation Toolkit](../../configure).
18+
- [Create a MetaMask smart account](../execute-on-smart-accounts-behalf#3-create-a-delegator-account) to create delegations.
19+
- [Create a delegate account](../execute-on-smart-accounts-behalf#4-create-a-delegate-account)
20+
21+
## Use ownership transfer scope
22+
23+
The scope requires a `contractAddress`, which represents address of the deployed contract.
24+
25+
```typescript
26+
import { createDelegation } from "@metamask/delegatino-toolkit";
27+
28+
const contractAddress = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"
29+
30+
const delegation = createDelegation({
31+
scope: {
32+
type: "ownershipTransfer",
33+
contractAddress,
34+
},
35+
to: delegateaAccount,
36+
from: delegatorAccount,
37+
});
38+
```
39+
40+
## Next steps
41+
42+
- See [Restrict a delegation](../restrict-delegation) to learn how to further limit the authority of a delegation.

‎delegation-toolkit/guides/delegation/use-delegation-scope/spending-limit-scope.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
description: Learn how to use the spending limit scopes for a delegation
3+
sidebar_position: 1
4+
sidebar_label: Spending limit scopes
5+
---
6+
7+
# Spending limit scopes
8+
9+
Spending limit scopes let you define how much a delegate can spend in native, ERC-20, or ERC-721 tokens.
10+
The toolkit provides multiple types of spending limit scopes tailored for different use cases.
11+
12+
## Prerequisites
13+
14+
- [Install and set up the Delegation Toolkit.](../../get-started/install)
15+
- [Configure the Delegation Toolkit](../../configure).
16+
- [Create a MetaMask smart account](../execute-on-smart-accounts-behalf#3-create-a-delegator-account) to create delegations.
17+
- [Create a delegate account](../execute-on-smart-accounts-behalf#4-create-a-delegate-account)
18+
19+
## ERC-20 periodic scope
20+
21+
This scope ensures that ERC-20 token transfers remain within a predefined limit during a specified time
22+
window. At the start of each new period, the transfer allowance resets. For example, Alice can create a delegation
23+
that allows Bob to spend 10 USDC on her behalf each day, week, or month.
24+
25+
When this scope is applied, the toolkit automatically sets the native token transfer limit
26+
to `0`, meaning native token transfers are disabled.
27+
28+
Internally, the scope uses combination of [`erc20PeriodTransfer`](../../../reference/caveats#erc20periodtransfer), and [`valueLte`](../../../reference/caveats#valuelte) caveat enforcers.
29+
30+
```typescript
31+
import { createDelegation } from "@metamask/delegatino-toolkit";
32+
33+
const delegation = createDelegation({
34+
scope: {
35+
type: "erc20PeriodTransfer",
36+
tokenAddress: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
37+
periodAmount: 1000000000000000000n,
38+
periodDuration: 86400,
39+
startDate: 1743763600,
40+
},
41+
to: delegateaAccount,
42+
from: delegatorAccount,
43+
});
44+
```
45+
46+
## ERC-20 streaming scope
47+
48+
This scopes ensures a linear streaming transfer limit for ERC-20 tokens. Token transfers are blocked until the defined
49+
start timestamp. At the start, a specified initial amount is released, after which tokens accrue linearly at the
50+
configured rate, up to the maximum allowed amount. For example, Alice can create delegation that allows Bob to spend
51+
0.1 USDC per second, starting with an initial amount of 10 USDC, up to a maximum of 100 USDC.
52+
53+
When this scope is applied, the toolkit automatically sets the native token transfer limit
54+
to `0`, meaning native token transfers are disabled.
55+
56+
Internally, the scope uses combination of [`erc20Streaming`](../../../reference/caveats#erc20streaming), and [`valueLte`](../../../reference/caveats#valuelte) caveat enforcers.
57+
58+
```typescript
59+
60+
import { createDelegation } from "@metamask/delegatino-toolkit";
61+
62+
const delegation = createDelegation({
63+
scope: {
64+
type: "erc20Streaming",
65+
tokenAddress: "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
66+
amountPerSecond: 100n,
67+
initialAmount: 1000000n,
68+
maxAmount: 10000000n,
69+
startTime: 1703980800,
70+
},
71+
to: delegateaAccount,
72+
from: delegatorAccount,
73+
});
74+
```
75+
76+
## ERC-20 transfer scope
77+
78+
This scope ensures that ERC-20 token transfers are limited to a predefined maximum amount. This scope is useful for
79+
setting simple, fixed transfer limits without any time based or streaming conditions. For example, Alice can create
80+
a delegation that allows Bob to spend up to 10 USDC without any conditions. Bob may use the 10 USDC in a single
81+
transaction or make multiple transactions, as long as the total does not exceed 10 USDC.
82+
83+
When this scope is applied, the toolkit automatically sets the native token transfer limit
84+
to `0`, meaning native token transfers are disabled.
85+
86+
Internally, the scope uses combination of [`erc20TransferAmount`](../../../reference/caveats#erc20transferamount), and [`valueLte`](../../../reference/caveats#valuelte) caveat enforcers.
87+
88+
```typescript
89+
import { createDelegation } from "@metamask/delegatino-toolkit";
90+
91+
const delegation = createDelegation({
92+
scope: {
93+
type: "erc20TransferAmount",
94+
tokenAddress: "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
95+
maxAmount: 10000n,
96+
},
97+
to: delegateaAccount,
98+
from: delegatorAccount,
99+
});
100+
```
101+
102+
## ERC-721 scope
103+
104+
This scope limits the delegation to ERC-721 token transfers only. Internally, the scope uses [`erc721Transfer`](../../../reference/caveats#erc721transfer) caveat enforcer.
105+
For example, Alice can create a delegation that allows Bob to transfer an NFT she owns on her behalf.
106+
107+
```typescript
108+
import { createDelegation } from "@metamask/delegatino-toolkit";
109+
110+
const delegation = createDelegation({
111+
scope: {
112+
type: "erc721Transfer",
113+
tokenAddress: "0x3fF528De37cd95b67845C1c55303e7685c72F319",
114+
tokenId: 1n,
115+
},
116+
to: delegateaAccount,
117+
from: delegatorAccount,
118+
});
119+
```
120+
121+
## Native token periodic scope
122+
123+
This scope ensures that native token transfers remain within a predefined limit during a specified time
124+
window. At the start of each new period, the transfer allowance resets. For example, Alice can create a delegation
125+
that allows Bob to spend 0.01 ETH on her behalf each day, week, or month.
126+
127+
When this scope is applied, the toolkit automatically sets the allowed calldata to `0x`, disabling
128+
the ERC-20 and ERC-721 token transfers.
129+
130+
Internally, the scope uses combination of [`exactCalldata`](../../../reference/caveats#exactcalldata), and [`nativeTokenPeriodTransfer`](../../../reference/caveats#nativetokenperiodtransfer) caveat enforcers.
131+
132+
```typescript
133+
import { createDelegation } from "@metamask/delegatino-toolkit";
134+
135+
const delegation = createDelegation({
136+
scope: {
137+
type: "nativeTokenPeriodTransfer",
138+
periodAmount: 1000000000000000000n,
139+
periodDuration: 86400,
140+
startDate: 1743763600,
141+
},
142+
to: delegateaAccount,
143+
from: delegatorAccount,
144+
});
145+
```
146+
147+
## Native token streaming scope
148+
149+
This scopes ensures a linear streaming transfer limit for native tokens. Token transfers are blocked until the defined
150+
start timestamp. At the start, a specified initial amount is released, after which tokens accrue linearly at the
151+
configured rate, up to the maximum allowed amount. For example, Alice can create delegation that allows Bob to spend
152+
0.001 ETH per second, starting with an initial amount of 0.01 ETH, up to a maximum of 0.1 ETH.
153+
154+
When this scope is applied, the toolkit automatically sets the allowed calldata to `0x`, disabling
155+
the ERC-20 and ERC-721 token transfers.
156+
157+
Internally, the scope uses combination of [`exactCalldata`](../../../reference/caveats#exactcalldata), and [`nativeTokenStreaming`](../../../reference/caveats#nativetokenstreaming) caveat enforcers.
158+
159+
```typescript
160+
import { createDelegation } from "@metamask/delegatino-toolkit";
161+
162+
const delegation = createDelegation({
163+
scope: {
164+
type: "nativeTokenStreaming",
165+
amountPerSecond: 100n,
166+
initialAmount: 1000000n,
167+
maxAmount: 10000000n,
168+
startTime: 1703980800,
169+
},
170+
to: delegateaAccount,
171+
from: delegatorAccount,
172+
});
173+
```
174+
175+
## Native token transfer scope
176+
177+
This scope ensures that native token transfers are limited to a predefined maximum amount. This scope is useful for setting
178+
simple, fixed transfer limits without any time based or streaming conditions. For example, Alice can create
179+
a delegation that allows Bob to spend up to 0.1 ETH without any conditions. Bob may use the 0.1 ETH in a single
180+
transaction or make multiple transactions, as long as the total does not exceed 0.1 ETH.
181+
182+
When this scope is applied, the toolkit automatically sets the allowed calldata to `0x`, disabling
183+
the ERC-20 and ERC-721 token transfers.
184+
185+
Internally, the scope uses combination of [`exactCalldata`](../../../reference/caveats#exactcalldata), and [`nativeTokenTransferAmount`](../../../reference/caveats#nativetokentransferamount) caveat enforcers.
186+
187+
```typescript
188+
import { createDelegation } from "@metamask/delegatino-toolkit";
189+
190+
const delegation = createDelegation({
191+
scope: {
192+
type: "nativeTokenTransferAmount",
193+
maxAmount: 1000000n,
194+
},
195+
to: delegateaAccount,
196+
from: delegatorAccount,
197+
});
198+
```
199+
200+
## Next steps
201+
202+
- See [Restrict a delegation](../restrict-delegation) to learn how to further limit the authority of a delegation.

0 commit comments

Comments
 (0)