Skip to main content

Create a delegation

The MetaMask Delegation Toolkit enables you to create delegations from a delegator account to a delegate account.

note

Delegations are compatible with ERC-7710 and ERC-7715, to support a standardized minimal interface. Requesting ERC-7715 permissions and redeeming ERC-7710 delegations are experimental features.

warning

The examples on this page demonstrate delegations without any restrictions. Unrestricted delegations grant complete control over the account to the delegate, which can pose significant security risks. It is crucial to add caveats to limit the delegated authority. Learn how to restrict a delegation using caveat enforcers.

Prerequisites​

Create a root delegation​

A root delegation is a delegation that doesn't derive its authority from another delegation. It is when a delegator delegates its own authority away, as opposed to a redelegation. Create a root delegation as follows:

import { createDelegation } from "@metamask/delegation-toolkit";
import { delegatorSmartAccount } from "./config.ts";

// The address to which the delegation is granted. It can be an EOA address, or 
// smart account address.
const delegate = "0x2FcB88EC2359fA635566E66415D31dD381CF5585";

const delegation = createDelegation({
  to: delegate,
  from: delegatorSmartAccount.address,
  caveats: [] // Empty caveats array - we recommend adding appropriate restrictions.
});

Create an open root delegation​

An open root delegation is a root delegation that doesn't specify a delegate. This means that any account can redeem the delegation. You must create open root delegations carefully, to ensure that they are not misused. Create an open root delegation by setting the delegate property to the special address 0x0000000000000000000000000000000000000a11 (available via the constant ANY_BENEFICIARY).

import { createOpenDelegation } from "@metamask/delegation-toolkit";
import { delegatorSmartAccount } from "./config.ts";

const openRootDelegation = createOpenDelegation({
  from: delegatorSmartAccount.address,
  caveats: [] // Empty caveats array - we recommend adding appropriate restrictions.
});

Create a redelegation​

A recipient of a delegation (the delegate), can redelegate that authority to a third party, potentially applying additional restrictions. Create a redelegation as follows:

import { 
  createDelegation,
  getDelegationHashOffchain
 } from "@metamask/delegation-toolkit";
import { delegatorSmartAccount } from "./config.ts";

// The address is used as the root delegator. While creating the leaf delegation,
// the root delegate address will be the delegator address. 
const delegate = "0x2FcB88EC2359fA635566E66415D31dD381CF5585";

const delegation = createDelegation({
  to: delegate,
  from: delegatorSmartAccount.address,
  caveats: [] // Empty caveats array - we recommend adding appropriate restrictions.
});

// The authority is the (typed data) hash of the delegation from which the authority is derived.
const parentDelegationHash = getDelegationHashOffchain(delegation);

// The address is used as the delegate address while creating the redelegation.
const leafDelegate = "0xb4821Ab7d5942Bd2533387592068a12608B4a52C"

const leafDelegation = createDelegation({
  to: leafDelegate,
  from: delegate,
  // You can also choose to pass the parent delegation object, and let function
  // handle the rest.
  parentDelegation: parentDelegationHash,
  caveats: [] // Empty caveats array - we recommend adding appropriate restrictions.
});

Create an open redelegation​

An open redelegation is a redelegation that doesn't specify a delegate. This means that any account can redeem the redelegation. As with open root delegations, you must create open redelegations carefully, to ensure that they are not misused. Create an open redelegation as follows:

import { 
  createDelegation,
  createOpenDelegation,
  getDelegationHashOffchain
 } from "@metamask/delegation-toolkit";
import { delegatorSmartAccount } from "./config.ts";

// The address is used as the root delegator. While creating the leaf delegation,
// the root delegate address will be the delegator address. 
const delegate = "0x2FcB88EC2359fA635566E66415D31dD381CF5585";

const delegation = createDelegation({
  to: delegate,
  from: delegatorSmartAccount.address,
  caveats: [] // Empty caveats array - we recommend adding appropriate restrictions.
});

// The authority is the (typed data) hash of the delegation from which the authority is derived.
const parentDelegationHash = getDelegationHashOffchain(delegation);

const leafDelegation = createOpenDelegation({
  from: delegate,
  // You can also choose to pass the parent delegation object, and let the function
  // handle the rest.
  parentDelegation: parentDelegationHash,
  caveats: [] // Empty caveats array - we recommend adding appropriate restrictions.
});

Sign a delegation​

A delegation must be signed by the delegator to be valid for redemption. The MetaMaskSmartAccount supports signing the delegation using EIP-712 Typed Data via the signDelegation method. Sign a delegation as follows:

import { createDelegation } from "@metamask/delegation-toolkit";
import { delegatorSmartAccount } from "./config.ts";

// The address to which the delegation is granted. It can be an EOA address, or 
// smart account address.
const delegate = "0x2FcB88EC2359fA635566E66415D31dD381CF5585";

const delegation = createDelegation({
  to: delegate,
  from: delegatorSmartAccount.address,
  caveats: [] // Empty caveats array - we recommend adding appropriate restrictions.
});

const signature = await delegatorSmartAccount.signDelegation({ delegation });

const signedDelegation = {
  ...delegation,
  signature
};
Last updated on by Alexandra Carrillo