description

Delegation-related API methods reference.

toc_max_heading_level

keywords

delegation

API

methods

reference

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

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`	`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.

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, {
  // add-next-line
  allowInsecureUnrestrictedDelegation: 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. 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 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 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`	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 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 caveat object containing an `enforcer` address and ABI-encoded `terms`.
`environment`	`SmartAccountsEnvironment`	Yes	Environment to resolve the caveat enforcer addresses.

Example

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,
// }

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),
  },
})

`deploySmartAccountsEnvironment`

Deploys the 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

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)

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.

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
)

// add-start
overrideDeployedEnvironment(chain.id, '1.3.0', environment)
// add-end

`disableDelegation`

Encodes the calldata for disabling a delegation.

Parameters

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

Example

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

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

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.

Parameters

Name	Type	Required	Description
`delegations`	`Delegation[]`	Yes	The delegation array to be encoded.

Example

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

const encodedDelegations = encodeDelegations([delegation])

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

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

const encodedDelegation = encodeDelegation(delegation)

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

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

const delegationHash = hashDelegation(delegation)

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 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)

`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 contracts to override for the specified chain.
`environment`	`SmartAccountsEnvironment`	Yes	The environment containing contract addresses to override for the given chain and version.

Example

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)

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.

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.
`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/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 caveats. The default is `false`.

Example

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,
})

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'),
  },
})

Uh oh!

Uh oh!

FilesExpand file tree

index.md

Latest commit

History

index.md

File metadata and controls

Delegation API reference

createCaveatBuilder

Parameters

Example

Allow empty caveats

createDelegation

Parameters

Example

createOpenDelegation

Parameters

Example

createExecution

Parameters

Example

decodeDelegations

Parameters

Example

decodeDelegation

Parameters

Example

decodeCaveat

Parameters

Example

deploySmartAccountsEnvironment

Parameters

Example

Inject deployed contracts

disableDelegation

Parameters

Example

enableDelegation

Parameters

Example

encodeDelegations

Parameters

Example

encodeDelegation

Parameters

Example

hashDelegation

Parameters

Example

getSmartAccountsEnvironment

Parameters

Example

overrideDeployedEnvironment

Parameters

Example

redeemDelegations

Parameters

Example

signDelegation

Parameters

Example

`createCaveatBuilder`

`createDelegation`

`createOpenDelegation`

`createExecution`

`decodeDelegations`

`decodeDelegation`

`decodeCaveat`

`deploySmartAccountsEnvironment`

`disableDelegation`

`enableDelegation`

`encodeDelegations`

`encodeDelegation`

`hashDelegation`

`getSmartAccountsEnvironment`

`overrideDeployedEnvironment`

`redeemDelegations`

`signDelegation`