Delegation API reference

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

createCaveatBuilder

Builds an array of caveatsCaveat A restriction attached to a delegation that limits how delegated authority can be used..

Parameters

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

Example

import { createCaveatBuilder } from '@metamask/smart-accounts-kit/utils'
import { getSmartAccountsEnvironment } from '@metamask/smart-accounts-kit'
import { sepolia } from 'viem/chains'

const environment = getSmartAccountsEnvironment(sepolia.id)
const caveatBuilder = createCaveatBuilder(environment)

Allow empty caveats

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

example.ts

import { createCaveatBuilder } from '@metamask/smart-accounts-kit/utils'
import { getSmartAccountsEnvironment } from '@metamask/smart-accounts-kit'
import { sepolia } from 'viem/chains'

const environment = getSmartAccountsEnvironment(sepolia.id)
const caveatBuilder = createCaveatBuilder(environment, {
  allowInsecureUnrestrictedDelegation: true,
})

createDelegation

Creates a delegation with a specific delegateDelegate account The account that receives delegated authority and can redeem a delegation under its constraints..

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. See delegation scopes for the full list of scope types and their parameters.
environment	SmartAccountsEnvironment	Yes	The environment used by the toolkit to define contract addresses for interacting with the Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. contracts.
caveats	Caveats	No	Caveats that further refine the authority granted by the scope. See caveats reference for the full list of caveat types and their parameters.
parentDelegation	Delegation | Hex	No	The parent delegation or its corresponding hex to create a delegation chain. Mutually exclusive with parentPermissionContext.
parentPermissionContext	PermissionContext	No	Parent chain as Hex or as decoded Delegation values (leaf first). Mutually exclusive with parentDelegation.
salt	Hex	No	The salt for generating the delegation hash. This helps prevent hash collisions when creating identical delegations.

Example

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

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: getSmartAccountsEnvironment(sepolia.id),
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther('0.001'),
  },
})

createOpenDelegation

Creates an open delegationOpen delegation A delegation that leaves the delegate unspecified, allowing any account to redeem it. that can be redeemed by any delegate.

Parameters

Name	Type	Required	Description
from	Hex	Yes	The address that is granting the delegation.
scope	ScopeConfig	Conditional	Defines the delegation authority. See delegation scopes for supported types and parameters. Required for a root open delegation. Optional when either parentDelegation or parentPermissionContext is set; if omitted, authority is inherited from the parent chain.
environment	SmartAccountsEnvironment	Yes	The environment used by the toolkit to define contract addresses for interacting with the Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. contracts.
caveats	Caveats	No	Caveats that further refine the authority granted by the scope. See caveats reference for the full list of caveat types and their parameters.
parentDelegation	Delegation | Hex	No	The parent delegation or its corresponding hex to create a delegation chain. Mutually exclusive with parentPermissionContext.
parentPermissionContext	PermissionContext	No	Parent chain as Hex or as decoded Delegation values (leaf first). Mutually exclusive with parentDelegation.
salt	Hex	No	The salt for generating the delegation hash. This helps prevent hash collisions when creating identical delegations.

Example

import {
  createOpenDelegation,
  getSmartAccountsEnvironment,
  ScopeType,
} from '@metamask/smart-accounts-kit'
import { sepolia } from 'viem/chains'
import { parseEther } from 'viem'

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

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/smart-accounts-kit'
import { parseEther } from 'viem'

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

decodeDelegations

Decodes an ABI-encoded hex string to an array of delegations.

Use decodeDelegations when working with a permission context that contains a delegation chain, such as the context property returned by requestExecutionPermissions response.

Parameters

Name	Type	Required	Description
encoded	Hex	Yes	The ABI encoded hex string to decode.

Example

import { decodeDelegations } from '@metamask/smart-accounts-kit/utils'

const delegations = decodeDelegations('0x7f0db33d..c06aeeac')

decodeDelegation

Decodes an ABI-encoded hex string to a single delegation.

Use decodeDelegation when you have a single encoded delegation rather than an encoded delegation chain.

Parameters

Name	Type	Required	Description
encoded	Hex	Yes	The ABI-encoded hex string to decode.

Example

import { decodeDelegation } from '@metamask/smart-accounts-kit/utils'

const delegation = decodeDelegation('0x7f0db33d..c06aeeac')

decodeCaveat

Decodes a caveat's encoded terms.

Throws an error if the caveat enforcer is not a known enforcer in SmartAccountsEnvironment.

Parameters

Name	Type	Required	Description
caveat	Caveat	Yes	The caveatCaveat A restriction attached to a delegation that limits how delegated authority can be used. object containing an enforcer address and ABI-encoded terms.
environment	SmartAccountsEnvironment	Yes	Environment to resolve the caveat enforcerCaveat enforcer A smart contract that enforces delegation rules by validating caveat conditions during redemption hooks. addresses.

Example

example.ts

import { decodeCaveat } from '@metamask/smart-accounts-kit/utils'
import { delegation } from './config.ts'

const environment = delegation.environment

// Decode the first caveat from the delegation.
const decodedCaveat = decodeCaveat({
  caveat: delegation.caveats[0],
  environment,
})

// Output:
// {
//   type: 'erc20TransferAmount',
//   tokenAddress: '0x1c7D...7238',
//   maxAmount: 10000000n,
// }

config.ts

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

const environment = getSmartAccountsEnvironment(sepolia.id)

// USDC address on Ethereum Sepolia.
const tokenAddress = '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238'

export const delegation = createDelegation({
  from: '0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1',
  to: '0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488',
  environment,
  scope: {
    type: ScopeType.Erc20TransferAmount,
    tokenAddress,
    // 10 USDC
    maxAmount: parseUnits('10', 6),
  },
})

decodeRevertData

Decodes raw ABI-encoded revert data into a DecodedRevertReason.

Tries standard Solidity errors, and known Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. ABIs, then falls back to decoding printable ASCII bytes.

Returns undefined if the data could not be decoded.

Parameters

Name	Type	Required	Description
rawData	Hex	Yes	The raw ABI-encoded revert data.

Example

import { decodeRevertData } from '@metamask/smart-accounts-kit/utils'

const decoded = decodeRevertData('0x08c379a0...')

decodeRevertReason

Extracts revert data from an error object and decodes it using decodeRevertData. Use this when you catch an error from any Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. interaction and want to decode the revert reason.

Returns undefined if no revert data is found in the error.

Parameters

Name	Type	Required	Description
error	unknown	Yes	The error object to extract and decode revert data from.

Example

This example assumes you have a delegation signed by the delegatorDelegator account The account that creates and signs a delegation to grant limited authority to another account..

import { ExecutionMode } from '@metamask/smart-accounts-kit'
import { DelegationManager } from '@metamask/smart-accounts-kit/contracts'
import { decodeRevertReason } from '@metamask/smart-accounts-kit/utils'

try {
  await DelegationManager.execute.redeemDelegations({
    delegations: [[signedDelegation]],
    modes: [ExecutionMode.SingleDefault],
    executions: [[execution]],
  })
} catch (error) {
  const decoded = decodeRevertReason(error)
  if (decoded) {
    console.log(decoded.message)
  }
}

deploySmartAccountsEnvironment

Deploys the Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. 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

import { deploySmartAccountsEnvironment } from '@metamask/smart-accounts-kit/utils'
import { walletClient, publicClient } from './config.ts'
import { sepolia as chain } from 'viem/chains'

const environment = await deploySmartAccountsEnvironment(walletClient, publicClient, chain)

config.ts

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 { SmartAccountsEnvironment } from '@metamask/smart-accounts-kit'
import {
  overrideDeployedEnvironment,
  deploySmartAccountsEnvironment,
} from '@metamask/smart-accounts-kit/utils'

const environment: SmartAccountsEnvironment = await deploySmartAccountsEnvironment(
  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

import { DelegationManager } from '@metamask/smart-accounts-kit/contracts'
import { delegation } from './delegation.ts'

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

delegation.ts

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

export const delegation = createDelegation({
  from: '0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1',
  to: '0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488',
  environment: getSmartAccountsEnvironment(sepolia.id),
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther('0.001'),
  },
})

enableDelegation

Encodes the calldata to enable a disabled delegation.

Parameters

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

Example

import { DelegationManager } from '@metamask/smart-accounts-kit/contracts'

const enableDelegationData = DelegationManager.encode.enableDelegation({
  delegation, // Already disabled delegation.
})

encodeDelegations

Encodes an array of delegations to an ABI-encoded hex string.

The delegations must be ordered from leaf to root delegation, with each delegation's authority referencing the hash of the next entry in the array.

Parameters

Name	Type	Required	Description
delegations	Delegation[]	Yes	The delegation chain to encode, ordered from leaf to root delegation.

Example

example.ts

import { encodeDelegations } from '@metamask/smart-accounts-kit/utils'
import { delegation } from './delegation.ts'

const encodedDelegations = encodeDelegations([delegation])

delegation.ts

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

export const delegation = createDelegation({
  from: '0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1',
  to: '0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488',
  environment: getSmartAccountsEnvironment(sepolia.id),
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther('0.001'),
  },
})

encodeDelegation

Encodes a single delegation to an ABI-encoded hex string.

Parameters

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

Example

example.ts

import { encodeDelegation } from '@metamask/smart-accounts-kit/utils'
import { delegation } from './delegation.ts'

const encodedDelegation = encodeDelegation(delegation)

delegation.ts

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

export const delegation = createDelegation({
  from: '0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1',
  to: '0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488',
  environment: getSmartAccountsEnvironment(sepolia.id),
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther('0.001'),
  },
})

hashDelegation

Returns the delegation hash.

Parameters

Name	Type	Required	Description
input	Delegation	Yes	The delegation object to hash.

Example

example.ts

import { hashDelegation } from '@metamask/smart-accounts-kit/utils'
import { delegation } from './config.ts'

const delegationHash = hashDelegation(delegation)

config.ts

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

const environment = getSmartAccountsEnvironment(sepolia.id)

// 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,
  // Address that is granting the delegation.
  from: '0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1',
  environment,
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther('0.001'),
  },
})

getSmartAccountsEnvironment

Resolves the SmartAccountsEnvironment for a chain.

Parameters

Name	Type	Required	Description
chainId	number	Yes	The chain ID of the network for which the SmartAccountsEnvironment should be resolved.
version	SupportedVersion	No	Specifies the version of the Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. contracts to use. If omitted, the latest supported version will be used by default.

Example

import { getSmartAccountsEnvironment } from '@metamask/smart-accounts-kit'
import { sepolia } from 'viem/chains'

const environment = getSmartAccountsEnvironment(sepolia.id)

generateSalt

Generates a random 32-byte hex salt for creating delegations. This helps prevent hash collisions when creating identical delegations.

Example

import { generateSalt } from '@metamask/smart-accounts-kit/utils'

const salt = generateSalt()

overrideDeployedEnvironment

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

Parameters

Name	Type	Required	Description
chainId	number	Yes	The chain ID of the network for which the SmartAccountsEnvironment should be overridden.
version	SupportedVersion	Yes	The version of the Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. contracts to override for the specified chain.
environment	SmartAccountsEnvironment	Yes	The environment containing contract addresses to override for the given chain and version.

Example

example.ts

import { environment } from './environment.ts'
import { overrideDeployedEnvironment } from '@metamask/smart-accounts-kit/utils'
import { sepolia } from 'viem/chains'

overrideDeployedEnvironment(sepolia.id, '1.3.0', environment)

environment.ts

import { SmartAccountsEnvironment } from '@metamask/smart-accounts-kit'

export const environment: SmartAccountsEnvironment = {
  SimpleFactory: '0x124..',
  // ...
  implementations: {
    // ...
  },
}

redeemDelegations

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

Each inner delegation array must be ordered from leaf to root delegation, with each delegation's authority referencing the hash of the next entry in the array.

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, ordered from leaf to root delegation.
modes	ExecutionMode[]	Yes	A collection specifying the execution mode for each corresponding delegation chain.
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 delegatorDelegator account The account that creates and signs a delegation to grant limited authority to another account..

import { createExecution, ExecutionMode } from '@metamask/smart-accounts-kit'
import { DelegationManager } from '@metamask/smart-accounts-kit/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
privateKey	Hex	Yes	The private key to use for signing 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.
allowInsecureUnrestrictedDelegation	boolean	No	Whether to allow insecure unrestricted delegation with no caveatsCaveat A restriction attached to a delegation that limits how delegated authority can be used.. The default is false.

Example

example.ts

import { signDelegation } from '@metamask/smart-accounts-kit'
import { privateKey, delegation, delegationManager } from './config.ts'
import { sepolia } from 'viem/chains'

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

config.ts

import {
  getSmartAccountsEnvironment,
  createDelegation,
  ScopeType,
} from '@metamask/smart-accounts-kit'
import { createWalletClient, parseEther } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { sepolia } from 'viem/chains'

const environment = getSmartAccountsEnvironment(sepolia.id)
export const delegationManager = environment.DelegationManager

export const privateKey = `0x12141..`
const account = privateKeyToAccount(privateKey)

// 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: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther('0.001'),
  },
})

toDelegationStruct

Converts a Delegation object to a DelegationStruct object.

Use when you need to pass a delegation directly to a Delegation FrameworkDelegation Framework A set of audited smart contracts that handle smart account creation, the delegation lifecycle, and caveat enforcement. contract call or other onchain interaction that expects the struct form.

Parameters

Name	Type	Required	Description
delegation	Delegation	Yes	The delegation to convert.

Example

example.ts

import { toDelegationStruct } from '@metamask/smart-accounts-kit/utils'
import { delegation } from './delegation.ts'

const delegationStruct = toDelegationStruct(delegation)

delegation.ts

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

export const delegation = createDelegation({
  from: '0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1',
  to: '0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488',
  environment: getSmartAccountsEnvironment(sepolia.id),
  scope: {
    type: ScopeType.NativeTokenTransferAmount,
    // 0.001 ETH in wei format.
    maxAmount: parseEther('0.001'),
  },
})