Skip to main content

Use delegation scopes

When creating a delegation, you can configure a scope to define the delegation's initial authority and help prevent delegation misuse. You can further refine this initial authority by adding caveats to a delegation.

Prerequisites​

Use a delegation scope​

The Delegation Toolkit currently supports three categories of scopes:

  • Spending limit scopes - Restricts the spending of native, ERC-20, and ERC-721 tokens based on defined conditions.
  • Function call scope - Restricts the delegation to specific contract methods, contract addresses, or calldata.
  • Ownership transfer scope - Restricts the delegation to only allow ownership transfers, specifically the transferOwnership function for a specified contract.

When creating a delegation using the toolkit's createDelegation function, specify the delegation scope and its parameters using the scope property.

The following example specifies the ERC-20 periodic scope, which ensures that ERC-20 token transfers remain within a predefined limit during a specified time window. At the start of each new period, the transfer allowance resets.

The delegator (Alice) creates a delegation that allows the delegate (Bob) to spend 1 ERC-20 token on her behalf each day:

import { createDelegation } from "@metamask/delegation-toolkit";

const delegation = createDelegation({
  scope: {
    type: "erc20PeriodTransfer",
    tokenAddress: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da", // Address of the ERC-20 token
    periodAmount: 1000000000000000000n, // 1 ERC-20 token - 18 decimals, in wei
    periodDuration: 86400, // 1 day in seconds
    startDate: 1743763600, // April 4, 2025 at 00:00:00 UTC
  },
  to: delegateAccount,
  from: delegatorAccount,
});

See the delegation scopes reference for a full list of supported scopes and example parameters.

Next steps​

See how to further refine the authority of a delegation using caveat enforcers.

On this page