Delegation API reference

The following API methods are related to creating and managing delegations.

createCaveatBuilder

Builds an array of caveats.

Parameters

Name	Type	Required	Description
environment	DeleGatorEnvironment	Yes	Environment to resolve the smart contracts for the current chain.
config	CaveatBuilderConfig	No	Configuration for CaveatBuilder.

Example

• example.ts
• config.ts

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

const caveats = createCaveatBuilder(delegatorSmartAccount.environment)

import {
  Implementation,
  toMetaMaskSmartAccount,
} from "@metamask/delegation-toolkit";
import { createWalletClient, createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia as chain } from "viem/chains";
 
const publicClient = createPublicClient({
  chain,
  transport: http(),
});

const delegatorAccount = privateKeyToAccount("0x...");

export const delegatorSmartAccount = await toMetaMaskSmartAccount({
  client: publicClient,
  implementation: Implementation.Hybrid,
  deployParams: [delegatorAccount.address, [], [], []],
  deploySalt: "0x",
  signer: { account: delegatorAccount },
});

Allow empty caveats

To create an empty caveat collection, set the CaveatBuilderConfig.allowEmptyCaveats to true.

example.ts

import { createCaveatBuilder } from "@metamask/delegation-toolkit";
// The config.ts is the same as in the previous example.
import { delegatorSmartAccount } from "./config.ts";

const caveats = createCaveatBuilder(delegatorSmartAccount.environment, {
  allowEmptyCaveats: true,
});

createDelegation

Creates a delegation with a specific delegate.

Parameters

Name	Type	Required	Description
from	Hex	Yes	The address that is granting the delegation.
to	Hex	Yes	The address to which the delegation is being granted.
scope	ScopeConfig	Yes	The scope of the delegation that defines the initial authority.
environment	DeleGatorEnvironment	Yes	The environment used by the toolkit to define contract addresses for interacting with the Delegation Framework contracts.
caveats	Caveats	No	Caveats that further refine the authority granted by the scope.
parentDelegation	Delegation | Hex	No	The parent delegation or its corresponding hex to create a delegation chain.
salt	Hex	No	The salt for generating the delegation hash. This helps prevent hash collisions when creating identical delegations.

Example

import { createDelegation, getDelegatorEnvironment } from "@metamask/delegation-toolkit";
import { sepolia } from "viem/chains";

const delegation = createDelegation({
  // 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: getDelegatorEnvironment(sepolia.id);
  scope: {
    type: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});

createOpenDelegation

Creates an open delegation that can be redeemed by any delegate.

Parameters

Name	Type	Required	Description
from	Hex	Yes	The address that is granting the delegation.
scope	ScopeConfig	Yes	The scope of the delegation that defines the initial authority.
environment	DeleGatorEnvironment	Yes	The environment used by the toolkit to define contract addresses for interacting with the Delegation Framework contracts.
caveats	Caveats	No	Caveats that further refine the authority granted by the scope.
parentDelegation	Delegation | Hex	No	The parent delegation or its corresponding hex to create a delegation chain.
salt	Hex	No	The salt for generating the delegation hash. This helps prevent hash collisions when creating identical delegations.

Example

import { createOpenDelegation, getDelegatorEnvironment } from "@metamask/delegation-toolkit";
import { sepolia } from "viem/chains";

const delegation = createOpenDelegation({
  // Address that is granting the delegation
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getDelegatorEnvironment(sepolia.id);
  scope: {
    type: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});

createExecution

Creates an ExecutionStruct instance.

Parameters

Name	Type	Required	Description
target	Address	No	Address of the contract or recipient that the call is directed to.
value	bigint	No	Value of native tokens to send along with the call in wei.
callData	Hex	No	Encoded function data or payload to be executed on the target address.

Example

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

// Creates an ExecutionStruct to transfer 0.01 ETH to
// 0xe3C818389583fDD5cAC32f548140fE26BcEaE907 address.
const execution = createExecution({
  target: "0xe3C818389583fDD5cAC32f548140fE26BcEaE907",
  // 0.01 ETH in wei
  value: 10000000000000000n,
  callData: "0x",
});

deployDeleGatorEnvironment

Deploys the Delegation Framework contracts to an EVM chain.

Parameters

Name	Type	Required	Description
walletClient	WalletClient	Yes	Viem Wallet Client to deploy the contracts.
publicClient	PublicClient	Yes	Viem Public Client to interact with the given chain.
chain	Chain	Yes	Viem Chain where you wish to deploy the Delegation Framework contracts.
deployedContracts	{ [contract: string]: Hex }	No	Allows overriding specific contract addresses when calling the function. For example, if certain contracts have already been deployed on the target chain, their addresses can be provided directly to the function.

Example

• example.ts
• config.ts

import { deployDeleGatorEnvironment } from "@metamask/delegation-toolkit/utils";
import { walletClient, publicClient } from "./config.ts";
import { sepolia as chain } from "viem/chains";

const environment = await deployDeleGatorEnvironment(
  walletClient, 
  publicClient, 
  chain
);

import { privateKeyToAccount } from "viem/accounts";
import { sepolia as chain } from "viem/chains";
import { http, createWalletClient, createPublicClient } from "viem";

// Your deployer wallet private key.
const privateKey = "0x123.."; 
const account = privateKeyToAccount(privateKey);

export const walletClient = createWalletClient({
  account,
  chain,
  transport: http()
});
 
export const publicClient = createPublicClient({ 
  transport: http(), 
  chain, 
});

Inject deployed contracts

Once the contracts are deployed, you can use them to override the delegator environment using overrideDeployedEnvironment.

example.ts

import { walletClient, publicClient } from "./config.ts";
import { sepolia as chain } from "viem/chains";
import { DeleGatorEnvironment } from "@metamask/delegation-toolkit";
import { 
  overrideDeployedEnvironment,
  deployDeleGatorEnvironment,
} from "@metamask/delegation-toolkit/utils";

const environment: DeleGatorEnvironment = await deployDeleGatorEnvironment(
  walletClient, 
  publicClient, 
  chain
);

overrideDeployedEnvironment(
  chain.id,
  "1.3.0",
  environment,
);

disableDelegation

Encodes the calldata for disabling a delegation.

Parameters

Name	Type	Required	Description
delegation	Delegation	Yes	The delegation to be disabled.

Example

• example.ts
• delegation.ts

import { DelegationManager } from "@metamask/delegation-toolkit/contracts";
import { delegation } from "./delegation.ts";

const disableDelegationData = DelegationManager.encode.disableDelegation({
  delegation,
});

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

export const delegation = createDelegation({
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  environment: getDelegatorEnvironment(sepolia.id);
  scope: {
    type: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});

getDeleGatorEnvironment

Resolves the DeleGatorEnvironment for a chain.

Parameters

Name	Type	Required	Description
chainId	number	Yes	The chain ID of the network for which the DeleGatorEnvironment should be resolved.
version	SupportedVersion	No	Specifies the version of the Delegation Framework contracts to use. If omitted, the latest supported version will be used by default.

Example

import { getDeleGatorEnvironment } from "@metamask/delegation-toolkit";
import { sepolia } from "viem/chains";

const environment = getDeleGatorEnvironment(sepolia.id)

overrideDeployedEnvironment

Overrides or adds the DeleGatorEnvironment for a chain and supported version.

Parameters

Name	Type	Required	Description
chainId	number	Yes	The chain ID of the network for which the DeleGatorEnvironment should be overridden.
version	SupportedVersion	Yes	The version of the Delegation Framework contracts to override for the specified chain.
environment	DeleGatorEnvironment	Yes	The environment containing contract addresses to override for the given chain and version.

Example

• example.ts
• environment.ts

import { environment } from "./environment.ts";
import { overrideDeployedEnvironment } from "@metamask/delegation-toolkit/utils";
import { sepolia } from "viem/chains";

overrideDeployedEnvironment(
  sepolia.id,
  "1.3.0",
  environment
);

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

export const environment: DeleGatorEnvironment = {
  SimpleFactory: "0x124..",
  // ...
  implementations: {
    // ...
  },
};

redeemDelegations

Encodes calldata for redeeming delegations. This method supports batch redemption, allowing multiple delegations to be processed within a single transaction.

Parameters

Name	Type	Required	Description
delegations	Delegation[][]	Yes	A nested collection representing chains of delegations. Each inner collection contains a chain of delegations to be redeemed.
modes	ExecutionMode[]	Yes	A collection specifying the execution mode for each corresponding delegation chain. Supported execution modes are SingleDefault, SingleTry, BatchDefault, and BatchTry.
executions	ExecutionStruct[][]	Yes	A nested collection where each inner collection contains a list of ExecutionStruct objects associated with a specific delegation chain.

Example

This example assumes you have a delegation signed by the delegator.

import { createExecution, ExecutionMode } from "@metamask/delegation-toolkit";
import { DelegationManager } from "@metamask/delegation-toolkit/contracts";
import { zeroAddress } from "viem";

const data = DelegationManager.encode.redeemDelegations({
  delegations: [[ signedDelegation ]],
  modes: [ ExecutionMode.SingleDefault ],
  executions: [[ execution ]],
});

signDelegation

Signs the delegation and returns the delegation signature.

Parameters

Name	Type	Required	Description
signer	WalletClient	Yes	Viem Wallet Client to sign the delegation.
delegation	Omit<Delegation, "signature">	Yes	The unsigned delegation object to sign.
chainId	number	Yes	The chain ID on which the delegation manager is deployed.
delegationManager	0x${string}	Yes	The address of the Delegation Manager.
name	string	No	The name of the domain of the Delegation Manager. The default is DelegationManager.
version	string	No	The version of the domain of the Delegation Manager. The default is 1.

Example

• example.ts
• config.ts

import { signDelegation } from "@metamask/delegation-toolkit";
import { walletClient, delegation, delegationManager } from "./config.ts";
import { sepolia } from "viem/chains";

const signature = signDelegation({
  signer: walletClient,
  delegation,
  chainId: sepolia.id,
  delegationManager,
})

import { 
  getDeleGatorEnvironment,
  createDelegation,
} from "@metamask/delegation-toolkit";
import { createWalletClient } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const environment = getDelegatorEnvironment(sepolia.id);
export const delegationManager = environment.DelegationManager;

const account = privateKeyToAccount(delegateWallet as `0x${string}`);

export const walletClient = createWalletClient({
  account,
  transport: http(),
  chain: sepolia,
});

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

export const delegation = createDelegation({
  to: delegate,
  from: account.address,
  environment,
  scope: {
    type: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});