Skip to content

delegation-scopes.md

Latest commit

 

History

History
361 lines (288 loc) · 25 KB

delegation-scopes.md

File metadata and controls

361 lines (288 loc) · 25 KB
Raw
description Delegation scopes reference.
sidebar_label Delegation scopes
keywords
delegation scopes
configuration
reference

import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import GlossaryTerm from '@theme/GlossaryTerm';

Delegation scopes

When creating a delegation, you can configure the following scopes to define the delegation's initial authority. Learn how to use delegation scopes.

Spending limit scopes

ERC-20 periodic scope

Ensures a per-period limit for ERC-20 token transfers. At the start of each new period, the allowance resets.

Parameters

Name Type Required Description
tokenAddress Address Yes The ERC-20 token contract address as a hex string.
periodAmount bigint Yes The maximum amount of tokens that can be transferred per period.
periodDuration number Yes The duration of each period in seconds.
startDate number Yes The timestamp when the first period begins in seconds.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";
import { parseUnits } from "viem";

// Since current time is in seconds, convert milliseconds to seconds.
const startDate = Math.floor(Date.now() / 1000);

const delegation = createDelegation({
  scope: {
    type: ScopeType.Erc20PeriodTransfer,
    tokenAddress: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
    // 10 ERC-20 token with 6 decimals
    periodAmount: parseUnits("10", 6),
    periodDuration: 86400,
    startDate,
  },
  // Address that is granting the delegation
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

ERC-20 streaming scope

Ensures a linear streaming transfer limit for ERC-20 tokens. Token transfers are blocked until the defined start timestamp. At the start, a specified initial amount is released, after which tokens accrue linearly at the configured rate, up to the maximum allowed amount.

Parameters

Name Type Required Description
tokenAddress Address Yes The ERC-20 token contract address.
initialAmount bigint Yes The initial amount that can be transferred at start time.
maxAmount bigint Yes The maximum total amount that can be unlocked.
amountPerSecond bigint Yes The rate at which tokens accrue per second.
startTime number Yes The start timestamp in seconds.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";
import { parseUnits } from "viem";

// Since current time is in seconds, convert milliseconds to seconds.
const startTime = Math.floor(Date.now() / 1000);

const delegation = createDelegation({
  scope: {
    type: ScopeType.Erc20Streaming,
    tokenAddress: "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
    // 0.1 ERC-20 token with 6 decimals
    amountPerSecond: parseUnits("0.1", 6),
    // 1 ERC-20 token with 6 decimals
    initialAmount: parseUnits("1", 6),
    // 10 ERC-20 token with 6 decimals
    maxAmount: parseUnits("10", 6),
    startTime,
  },
  // Address that is granting the delegation
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

ERC-20 transfer scope

Ensures that ERC-20 token transfers are limited to a predefined maximum amount. This scope is useful for setting simple, fixed transfer limits without any time-based or streaming conditions.

Parameters

Name Type Required Description
tokenAddress Address Yes The ERC-20 token contract address.
maxAmount bigint Yes The maximum amount of tokens that can be transferred by delegate.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";
import { parseUnits } from "viem";

const delegation = createDelegation({
  scope: {
    type: ScopeType.Erc20TransferAmount,
    tokenAddress: "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
    // 1 ERC-20 token with 6 decimals
    maxAmount: parseUnits("1", 6),
  },
  // Address that is granting the delegation
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

ERC-721 scope

Limits the delegation to ERC-721 token (NFT) transfers only.

Parameters

Name Type Required Description
tokenAddress Address Yes The ERC-721 token contract address.
tokenId bigint Yes The ID of the ERC-721 token that can be transferred by delegate.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";

const delegation = createDelegation({
  scope: {
    type: ScopeType.Erc721Transfer,
    tokenAddress: "0x3fF528De37cd95b67845C1c55303e7685c72F319",
    tokenId: 1n,
  },
  // Address that is granting the delegation
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

Native token periodic scope

Ensures a per-period limit for native token transfers. At the start of each new period, the allowance resets.

Parameters

Name Type Required Description
periodAmount bigint Yes The maximum amount of tokens that can be transferred per period.
periodDuration number Yes The duration of each period in seconds.
startDate number Yes The timestamp when the first period begins in seconds.
allowedCalldata AllowedCalldataBuilderConfig[] No The list of calldata the delegate is allowed to call. It doesn't support multiple selectors. Each entry in the list represents a portion of calldata corresponding to the same function signature. You can include or exclude specific parameters to define what parts of the calldata are valid. Cannot be used together with exactCalldata.
exactCalldata ExactCalldataBuilderConfig No The calldata the delegate is allowed to call. The default is 0x to disallow ERC-20 and ERC-721 token transfers. Cannot be used together with allowedCalldata.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";
import { parseEther } from "viem";

// Since current time is in seconds, convert milliseconds to seconds.
const startDate = Math.floor(Date.now() / 1000);

const delegation = createDelegation({
  scope: {
    type: ScopeType.NativeTokenPeriodTransfer,
    periodAmount: parseEther("0.01"),
    periodDuration: 86400,
    startDate,
  },
  // Address that is granting the delegation.
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted.
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

Native token streaming scope

Ensures a linear streaming transfer limit for native tokens. Token transfers are blocked until the defined start timestamp. At the start, a specified initial amount is released, after which tokens accrue linearly at the configured rate, up to the maximum allowed amount.

Parameters

Name Type Required Description
initialAmount bigint Yes The initial amount that can be transferred at start time.
maxAmount bigint Yes The maximum total amount that can be unlocked.
amountPerSecond bigint Yes The rate at which tokens accrue per second.
startTime number Yes The start timestamp in seconds.
allowedCalldata AllowedCalldataBuilderConfig[] No The list of calldata the delegate is allowed to call. It doesn't support multiple selectors. Each entry in the list represents a portion of calldata corresponding to the same function signature. You can include or exclude specific parameters to define what parts of the calldata are valid. Cannot be used together with exactCalldata.
exactCalldata ExactCalldataBuilderConfig No The calldata the delegate is allowed to call. The default is 0x to disallow ERC-20 and ERC-721 token transfers. Cannot be used together with allowedCalldata.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";
import { parseEther } from "viem";

// Since current time is in seconds, convert milliseconds to seconds.
const startTime = Math.floor(Date.now() / 1000);

const delegation = createDelegation({
  scope: {
    type: ScopeType.NativeTokenStreaming,
    amountPerSecond: parseEther("0.0001"),
    initialAmount: parseEther("0.01"),
    maxAmount: parseEther("0.1"),
    startTime,
  },
  // Address that is granting the delegation.
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted.
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

Native token transfer scope

Ensures that native token transfers are limited to a predefined maximum amount. This scope is useful for setting simple, fixed transfer limits without any time based or streaming conditions.

Parameters

Name Type Required Description
maxAmount bigint Yes The maximum amount of tokens that can be transferred by delegate.
allowedCalldata AllowedCalldataBuilderConfig[] No The list of calldata the delegate is allowed to call. It doesn't support multiple selectors. Each entry in the list represents a portion of calldata corresponding to the same function signature. You can include or exclude specific parameters to define what parts of the calldata are valid. Cannot be used together with exactCalldata.
exactCalldata ExactCalldataBuilderConfig No The calldata the delegate is allowed to call. The default is 0x to disallow ERC-20 and ERC-721 token transfers. Cannot be used together with allowedCalldata.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";
import { parseEther } from "viem";

const delegation = createDelegation({
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther("0.001"),
  },
  // Address that is granting the delegation.
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted.
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

Function call scope

Defines the specific methods, contract addresses, and calldata that are allowed for the delegation.

Parameters

Name Type Required Description
targets Address[] Yes The list of addresses that the delegate is allowed to call.
selectors MethodSelector[] Yes The list of method selectors that the delegate is allowed to call. The selector value can be 4-byte hex string, ABI function signature, or ABI function object.
allowedCalldata AllowedCalldataBuilderConfig[] No The list of calldata the delegate is allowed to call. It doesn't support multiple selectors. Each entry in the list represents a portion of calldata corresponding to the same function signature. You can include or exclude specific parameters to define what parts of the calldata are valid. Cannot be used together with exactCalldata.
exactCalldata ExactCalldataBuilderConfig No The calldata the delegate is allowed to call. Cannot be used together with allowedCalldata.
valueLte ValueLteBuilderConfig No The maximum native token amount the delegate can transfer. By default, the amount is set to 0.

Example

This example sets the delegation scope to allow the delegate to call the approve function on the USDC token contract:

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";

const delegation = createDelegation({
  scope: {
    type: ScopeType.FunctionCall,
    targets: ["0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"], // USDC address on Sepolia.
    selectors: ["approve(address, uint256)"]
  },
  // Address that is granting the delegation.
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted.
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});

Ownership transfer scope

Restricts a delegation to ownership transfer calls only.

Parameters

Name Type Required Description
contractAddress Address Yes The target contract address for which ownership transfers are allowed.

Example

import { createDelegation, getSmartAccountsEnvironment, ScopeType } from "@metamask/smart-accounts-kit";
import { sepolia } from "viem/chains";

const contractAddress = "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238"

const delegation = createDelegation({
  scope: {
    type: ScopeType.OwnershipTransfer,
    contractAddress,
  },
  // Address that is granting the delegation.
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Address to which the delegation is being granted.
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getSmartAccountsEnvironment(sepolia.id);
});