Developing Smart Contracts for Delegation Systems

This guide focuses on creating smart contracts that work seamlessly with the MetaMask Delegation Toolkit. The key principle is to keep your contracts simple, focused on core functionality, and completely unaware of the delegation system itself.

Core Principles

Simplicity: Contracts should focus solely on their core business logic.
Owner-centric: Use onlyOwner modifiers for privileged functions.
Delegation-agnostic: Contracts should not reference Delegation, DelegationManager, or mode encoding.
Extensibility: Design core functions to be easily extended through the delegation framework.

Contract Structure

Here's an example of a basic contract structure:

// SPDX-License-Identifier: MITpragma solidity ^0.8.0;import "@openzeppelin/contracts/token/ERC721/ERC721.sol";import "@openzeppelin/contracts/access/Ownable.sol";contract MyContract is ERC721, Ownable {    constructor(string memory name, string memory symbol) ERC721(name, symbol) Ownable(msg.sender) {}    function mint(address to, uint256 tokenId) public onlyOwner {        _mint(to, tokenId);    }}

Core Functions

Minting

The mint function is a simple example of a core function that can be easily extended through the delegation framework.

Using Caveat Enforcers

Caveat enforcers allow you to add specific conditions or restrictions to delegations. The MetaMask Delegation Toolkit provides several out-of-the-box caveat enforcers:

AllowedCalldataEnforcer.sol
AllowedMethodsEnforcer.sol
AllowedTargetsEnforcer.sol
BlockNumberEnforcer.sol
DeployedEnforcer.sol
ERC20TransferAmountEnforcer.sol
ERC20BalanceGteEnforcer.sol
NonceEnforcer.sol
LimitedCallsEnforcer.sol
IdEnforcer.sol
TimestampEnforcer.sol
ValueLteEnforcer.sol

So any policy that is composed of those can be assumed provided already.

In the case that you need to create a custom enforcer, you can use the CaveatEnforcer.sol base class and write your own like this:

// SPDX-License-Identifier: MIT AND Apache-2.0pragma solidity 0.8.23;import "forge-std/Test.sol";import { Ownable } from "@openzeppelin/contracts/access/Ownable.sol";import { ModeLib } from "@erc7579/lib/ModeLib.sol";import { ExecutionLib } from "@erc7579/lib/ExecutionLib.sol";import { Execution, Caveat, Delegation, ModeCode } from "../../src/utils/Types.sol";import { Counter } from "../utils/Counter.t.sol";import { CaveatEnforcerBaseTest } from "./CaveatEnforcerBaseTest.t.sol";import { AllowedMethodsEnforcer } from "../../src/enforcers/AllowedMethodsEnforcer.sol";import { ICaveatEnforcer } from "../../src/interfaces/ICaveatEnforcer.sol";contract AllowedMethodsEnforcerTest is CaveatEnforcerBaseTest {    ////////////////////// State //////////////////////    AllowedMethodsEnforcer public allowedMethodsEnforcer;    ModeCode public mode = ModeLib.encodeSimpleSingle();    ////////////////////// Set up //////////////////////    function setUp() public override {        super.setUp();        allowedMethodsEnforcer = new AllowedMethodsEnforcer();        vm.label(address(allowedMethodsEnforcer), "Allowed Methods Enforcer");    }    ////////////////////// Valid cases //////////////////////    // should allow a method to be called when a single method is allowed    function test_singleMethodCanBeCalled() public {        // Create the execution that would be executed        Execution memory execution_ = Execution({            target: address(aliceDeleGatorCounter),            value: 0,            callData: abi.encodeWithSelector(Counter.increment.selector)        });        bytes memory executionCallData_ = ExecutionLib.encodeSingle(execution_.target, execution_.value, execution_.callData);        // beforeHook, mimicking the behavior of Alice's DeleGator        vm.prank(address(delegationManager));        allowedMethodsEnforcer.beforeHook(            abi.encodePacked(Counter.increment.selector), hex"", mode, executionCallData_, keccak256(""), address(0), address(0)        );    }    // should allow a method to be called when a multiple methods are allowed    function test_multiMethodCanBeCalled() public {        // Create the execution that would be executed        Execution memory execution_ = Execution({            target: address(aliceDeleGatorCounter),            value: 0,            callData: abi.encodeWithSelector(Counter.increment.selector)        });        bytes memory executionCallData_ = ExecutionLib.encodeSingle(execution_.target, execution_.value, execution_.callData);        // beforeHook, mimicking the behavior of Alice's DeleGator        vm.prank(address(delegationManager));        allowedMethodsEnforcer.beforeHook(            abi.encodePacked(Counter.setCount.selector, Ownable.renounceOwnership.selector, Counter.increment.selector),            hex"",            mode,            executionCallData_,            keccak256(""),            address(0),            address(0)        );    }    ////////////////////// Invalid cases //////////////////////    // should FAIL to get terms info when passing an invalid terms length    function test_getTermsInfoFailsForInvalidLength() public {        vm.expectRevert("AllowedMethodsEnforcer:invalid-terms-length");        allowedMethodsEnforcer.getTermsInfo(bytes("1"));    }    // should FAIL if execution.callData length < 4    function test_notAllow_invalidExecutionLength() public {        // Create the execution that would be executed        Execution memory execution_ =            Execution({ target: address(aliceDeleGatorCounter), value: 0, callData: abi.encodePacked(true) });        bytes memory executionCallData_ = ExecutionLib.encodeSingle(execution_.target, execution_.value, execution_.callData);        // beforeHook, mimicking the behavior of Alice's DeleGator        vm.prank(address(delegationManager));        vm.expectRevert("AllowedMethodsEnforcer:invalid-execution-data-length");        allowedMethodsEnforcer.beforeHook(            abi.encodePacked(Counter.setCount.selector, Ownable.renounceOwnership.selector, Ownable.owner.selector),            hex"",            mode,            executionCallData_,            keccak256(""),            address(0),            address(0)        );    }    // should NOT allow a method to be called when the method is not allowed    function test_onlyApprovedMethodsCanBeCalled() public {        // Create the execution that would be executed        Execution memory execution_ = Execution({            target: address(aliceDeleGatorCounter),            value: 0,            callData: abi.encodeWithSelector(Counter.increment.selector)        });        bytes memory executionCallData_ = ExecutionLib.encodeSingle(execution_.target, execution_.value, execution_.callData);        // beforeHook, mimicking the behavior of Alice's DeleGator        vm.prank(address(delegationManager));        vm.expectRevert("AllowedMethodsEnforcer:method-not-allowed");        allowedMethodsEnforcer.beforeHook(            abi.encodePacked(Counter.setCount.selector, Ownable.renounceOwnership.selector, Ownable.owner.selector),            hex"",            mode,            executionCallData_,            keccak256(""),            address(0),            address(0)        );    }    ////////////////////// Integration //////////////////////    // should allow a method to be called when a single method is allowed Integration    function test_methodCanBeSingleMethodIntegration() public {        uint256 initialValue_ = aliceDeleGatorCounter.count();        // Create the execution that would be executed        Execution memory execution_ = Execution({            target: address(aliceDeleGatorCounter),            value: 0,            callData: abi.encodeWithSelector(Counter.increment.selector)        });        Caveat[] memory caveats_ = new Caveat[](1);        caveats_[0] =            Caveat({ args: hex"", enforcer: address(allowedMethodsEnforcer), terms: abi.encodePacked(Counter.increment.selector) });        Delegation memory delegation_ = Delegation({            delegate: address(users.bob.deleGator),            delegator: address(users.alice.deleGator),            authority: ROOT_AUTHORITY,            caveats: caveats_,            salt: 0,            signature: hex""        });        delegation_ = signDelegation(users.alice, delegation_);        // Execute Bob's UserOp        Delegation[] memory delegations_ = new Delegation[](1);        delegations_[0] = delegation_;        // Enforcer allows the delegation        invokeDelegation_UserOp(users.bob, delegations_, execution_);        // Get count        uint256 valueAfter_ = aliceDeleGatorCounter.count();        // Validate that the count has increased by 1        assertEq(valueAfter_, initialValue_ + 1);        // Enforcer allows to reuse the delegation        invokeDelegation_UserOp(users.bob, delegations_, execution_);        // Get final count        uint256 finalValue_ = aliceDeleGatorCounter.count();        // Validate that the count has increased again        assertEq(finalValue_, initialValue_ + 2);    }    // should NOT allow a method to be called when the method is not allowed Integration    function test_onlyApprovedMethodsCanBeCalledIntegration() public {        uint256 initialValue_ = aliceDeleGatorCounter.count();        // Create the execution that would be executed        Execution memory execution_ = Execution({            target: address(aliceDeleGatorCounter),            value: 0,            callData: abi.encodeWithSelector(Counter.increment.selector)        });        Caveat[] memory caveats_ = new Caveat[](1);        caveats_[0] = Caveat({            args: hex"",            enforcer: address(allowedMethodsEnforcer),            terms: abi.encodePacked(Counter.setCount.selector, Ownable.renounceOwnership.selector, Ownable.owner.selector)        });        Delegation memory delegation_ = Delegation({            delegate: address(users.bob.deleGator),            delegator: address(users.alice.deleGator),            authority: ROOT_AUTHORITY,            caveats: caveats_,            salt: 0,            signature: hex""        });        delegation_ = signDelegation(users.alice, delegation_);        // Execute Bob's UserOp        Delegation[] memory delegations_ = new Delegation[](1);        delegations_[0] = delegation_;        // Enforcer allows the delegation        invokeDelegation_UserOp(users.bob, delegations_, execution_);        // Get final count        uint256 valueAfter_ = aliceDeleGatorCounter.count();        // Validate that the count has not changed        assertEq(valueAfter_, initialValue_);    }    function _getEnforcer() internal view override returns (ICaveatEnforcer) {        return ICaveatEnforcer(address(allowedMethodsEnforcer));    }}

This example demonstrates a custom caveat enforcer that only permits approved methods to be called on. Here are some additional tips for working with the MetaMask Delegation Toolkit:

Simplify contract logic: The delegation framework allows you to move complex permission logic out of your main contracts. For example, instead of implementing complex access control in your main contract, you can use onlyOwner modifiers and handle permissions through delegations.
Leverage existing enforcers: Before creating a custom enforcer, check if any of the existing caveat enforcers (like AllowedCalldataEnforcer, BlockNumberEnforcer, ERC20TransferAmountEnforcer, etc.) can meet your needs.
Intent-based applications: When building intent-based apps:
a. Identify the resource being offered (e.g., NFT minting rights)
b. Determine the terms for offering the resource (e.g., payment, time limits)
c. Use or create appropriate caveat enforcers
Handle payments via delegations: NEVER use ERC20 allowances, payable functions, or permit() signatures. ONLY use delegations for receiving payments.

Assume that payments are usually handled by delegation managers (enforced outside of primary application logic), and that the primary application logic is focused on the intent to share a resource, without needing to consider the payment mechanics. As a result, it should be rare that a payment is required directly in a non-CaveatEnforcer contract. If payment is required by a contract (usually a CaveatEnforcer contract), never use ERC20 allowances, or token permit() signatures. The delegation framework is meant to be a general purpose alternative to these more constrained mechanisms. If a payment is required in exchange for something, have the payment be paid as a Delegation + a delegationManager address, which can then be redeemed using the ERC-7710 redeemDelegations() function on that delegationManager:

function redeemDelegations(        bytes[] calldata _permissionContexts,        ModeCode[] calldata _modes,        bytes[] calldata _executionCallDatas    )

Where _modes is an array of ModeCode values, which are used to determine the behavior of the redeemDelegations() function (and mode 1 is a normal internal message call).

Calling a function using a permission context and delegation manager to performa simple send looks like this:

import { ModeLib } from "@erc7579/lib/ModeLib.sol";using ModeLib for ModeCode;// Redeem ERC-7710 delegationbytes[] memory permissionContexts_ = new bytes[](1);permissionContexts_[0] = abi.encode(delegations_);bytes[] memory executionCallDatas_ = new bytes[](1);executionCallDatas_[0] = ExecutionLib.encodeSingle(recipient_, amount_, hex"");ModeCode[] memory encodedModes_ = new ModeCode[](1);encodedModes_[0] = ModeLib.encodeSimpleSingle();// Attempt to redeem the delegation and make the paymentdelegationManager.redeemDelegations(permissionContexts_, encodedModes_, executionCallDatas_);

Always use the delegation framework for invitations. Assume the owner can always let others use their account on their behalf with arbitrary terms.
Always ensure you use the onlyOwner modifier on any sensitive functions that should only be available to the owner. It's ok to leave this modifier off the transfer functions of a token or NFT contract. It's also ok to leave it off any function that is meant to be exposed as a public service.
After auto-generating a super simple contract, provide comments above each onlyOwner function that describes some expected/recommended delegation types for that function.

stack:

MetaMask Solidity Delegation .cursorrules prompt file

MetaMask

NEW

MetaMask Toolkit Guide .cursorrules prompt file

This is a repository for getting started with the MetaMask Delegation Toolkit.

The following is pasted directly from the docs/docs/get-started/llm-intro.md file, and should be

replaced as that file is updated.

MetaMask Delegation Toolkit LLM introduction

The following text is a condensed introduction to the MetaMask Delegation Toolkit, for use in an
LLM's limited context.

Copy the following text by selecting the copy icon in the upper right corner of the text block:

This is a software toolkit for developing applications for the Ethereum Virtual Machine (EVM) in anovel way, where users of the application have embedded "delegator" accounts, which are smartcontract accounts adhering to ERC-4337. Users can sign "delegations" to other addresses, eithergranting them unconditional permissions, or creating "offers," by writing enforcement terms aroundthe permission's usage.By putting the responsibility of permissions management onto the individual users' accounts, you canreduce the complexity of the business logic in your smart contracts, and you can express any customauthorization-related code as `CaveatEnforcer` contracts. Core business logic may still deal withownership and transfer rights, but you can use the toolkit to express the logic around delegations,offers, and caveats.Additionally, any holder of a delegation message from one of these accounts can re-delegate thatpermission or offer, even with additional terms, creating an invitation link experience that can beused to invite new users to the system to enjoy some permissions without the need for them to have apre-existing crypto account.A delegator account can be initialized "counterfactually" (without any gas, because its address isdeterministic from the signatory's address and the salt), and can even grant delegations to otheraccounts before it's been put on-chain. The account redeeming a delegation is the one that ends upneeding to put the delegating account on-chain (and any intermediate delegating accounts, as thesedelegations can be chained).Let's look at how you can initialize a delegator account using the MetaMask Delegation Toolkit.First, install Viem and the toolkit's modules into your project:```bashyarn add viem delegator-core-viem delegator-shared && yarn add viem @codefi/delegator-core-viem```Then, import the modules and initialize a burner account (you can back it up later):```typescriptimport { http } from "viem";import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";import {  Implementation,  createDeleGatorClient,  PimlicoVerifyingPaymasterSponsor,  createBundlerClient,  createRootDelegation,  createAction,  type DeleGatorClient,  type DelegationStruct,  type UserOperationV07,  getExplorerAddressLink,  getExplorerTransactionLink,} from "delegator-core-viem";const transport = http();const deploySalt = 0x1n; // Can be any BigInt value.const privateKey: Hex = generatePrivateKey();const signatory = privateKeyToAccount(privateKey);const viemClient = createDeleGatorClient({  transport,  chain,  account: {    implementation: Implementation.Hybrid,    deployParams: [signatory.address, [], [], []],    deploySalt,    isDeployed: false,    signatory,  },});```## Send a user operationThe following example demonstrates how to send a user operation using the toolkit:```typescriptconst userOp = await client.createUserOp(  data,  {    verificationGasLimit: 100000000n,    preVerificationGas: 100000000n,    callGasLimit: 100000000n,  });const bundlerUrl = "`<bundler-url>`";const bundler = createBundlerClient(bundlerUrl);const hash = await bundler.sendUserOp(  userOp,  client.account.environment.EntryPoint,)const { result: receipt } = await bundler.pollForReceipt(hash);console.log(receipt.receipt.transactionHash);```:::warningIn this example, `verificationGasLimit`, `preVerificationGas`, and `callGasLimit` are set toarbitrarily high values. This might result in overpayment for the user operation, and might evencause the bundler to reject the user operation, so we recommend replacing these values with acorrect estimate before submitting to the bundler.:::## Create a delegationA delegation is an instance of `DelegationStruct`, where `delegator` is the account grantingpermission to the `delegate` account. Here's a simple example of creating a delegation without anycaveats:```typescriptimport {  createRootDelegation,} from "delegator-core-viem";const delegatorAddress = "0x1234..."; // The address of the delegator accountconst delegateAddress = "0x5678..."; // The address of the delegate accountconst delegation = createRootDelegation(  delegateAddress,  delegatorAddress);```This creates a basic delegation where the `delegateAddress` is granted full permissions to act onbehalf of the `delegatorAddress`. However, it's important to note that this delegation has norestrictions or caveats applied to it.## Apply caveats to a delegationWhile the previous example demonstrates a simple delegation, granting unrestricted access isgenerally not recommended. It's crucial to apply caveats to limit the scope of the delegatedpermissions.Caveat enforcers are solidity contracts that extend the `ICaveatEnforcer.sol` interface, and arepassed to the delegation struct to enable fine-grained control over delegated permissions.Here's an example of how to apply a caveat to a delegation:```typescriptimport {  createRootDelegation,} from "delegator-core-viem";const delegatorAddress = "0x1234...";const delegateAddress = "0x5678...";const limitedCallsEnforcerAddress = "0x4CE4..."; // Address of the LimitedCallsEnforcer contractconst caveat = {  enforcer: limitedCallsEnforcerAddress,  terms: encodeAbiParameters([{ type: "uint256" }], [2]), // Limit to 2 calls  args: "0x"};const delegation = createRootDelegation(  delegateAddress,  delegatorAddress,  undefined, // No specific authority  [caveat] // Array of caveats);```This example applies the `LimitedCallsEnforcer` caveat, which restricts the delegate to only twocalls using this delegation. This demonstrates how caveats can be used to add specific restrictionsto a delegation.You can apply multiple caveats to a single delegation by adding more caveat objects to the array,allowing for highly customizable access control.## Create a custom caveat enforcerWhile the MetaMask Delegation Toolkit provides several out-of-the-box caveat enforcers, you cancreate custom ones for more specific needs:1. Create a contract that extends the `ICaveatEnforcer.sol` interface.2. Implement the required functions, such as `beforeHook` and `afterHook`.Here's a basic example of a custom caveat enforcer:```solidity// This enforcer provides functionality to enforce a limit on the number of times a delegate may// perform transactions on behalf of the delegator.contract LimitedCallsEnforcer is CaveatEnforcer {  mapping(address delegationManager => mapping(bytes32 delegationHash => uint256 count)) public callCounts;  event IncreasedCount(address indexed sender, bytes32 indexed delegationHash, uint256 limit, uint256 callCount);   function beforeHook(    bytes calldata _terms, // Maximum number of times the delegate can redeem the delegation.    bytes calldata,    Action calldata,    bytes32 _delegationHash, // Hash of the delegation being operated on.    address,    address  )    public    override  {    uint256 limit_ = getTermsInfo(_terms);    uint256 callCounts_ = ++callCounts[msg.sender][_delegationHash];    require(callCounts_ `<= limit_, "LimitedCallsEnforcer:limit-exceeded");    emit IncreasedCount(msg.sender, _delegationHash, limit_, callCounts_);  }```This example shows a `LimitedCallsEnforcer` that restricts the number of times a delegate canperform transactions on behalf of the delegator.## Concepts### DelegationDelegation allows an account owner (the delegator) to grant permission to another account to performspecific actions on their behalf. Delegations can include caveats to apply rules and restrictions.A delegation conforms to the following structure:```typescriptexport type DelegationStruct = {  delegate: Hex; // The account that receives permissions to perform actions on behalf of another account.  delegator: Hex; // The account that assigns the permission to another account.  authority: Hex; // The authority under which the delegation is made. The default is ROOT_AUTHORITY.  caveats: CaveatStruct[]; // An array of caveat enforcers.  salt: bigint; // A unique value to ensure the uniqueness of the delegation.  signature: Hex; // The cryptographic signature that verifies the delegation.};```### Caveat EnforcersCaveat enforcers apply specific conditions or restrictions to a delegation. The MetaMask DelegationToolkit provides several out-of-the-box caveat enforcers, including:- `AllowedCalldataEnforcer.sol`- `AllowedMethodsEnforcer.sol`- `AllowedTargetsEnforcer.sol`- `BlockNumberEnforcer.sol`- `DeployedEnforcer.sol`- `ERC20TransferAmountEnforcer.sol`- `ERC20BalanceGteEnforcer.sol`- `NonceEnforcer.sol`- `LimitedCallsEnforcer.sol`- `IdEnforcer.sol`- `TimestampEnforcer.sol`- `ValueLteEnforcer.sol`Each of these enforcers provides specific functionality to limit and control delegated actions.## Paid delegationsSometimes you may want to require a user to pay for a delegation. You can do this by using the`NativePaidEnforcer` to accept that EVM chain's native token as payment for the delegation.```typescript// Start by initializing two clients, one for the delegator and one for the delegate.const createCounterfactualDelegatorClient = () =>` {  const privateKey = generatePrivateKey();  const owner = privateKeyToAccount(privateKey);  const viemClient = createDeleGatorClient({    transport: http(),    chain,    account: {      implementation: Implementation.Hybrid,      deployParams: [owner.address, [], [], []],      isAccountDeployed: false,      signatory: owner,      deploySalt: SALT,    },  });  return viemClient;};const delegatorClient = createCounterfactualDelegatorClient();const delegateClient = createCounterfactualDelegatorClient();// Set up payment termsconst paymentAmount = 0.1 ether;const paymentTerms = PaymentTerms({ amount: paymentAmount, recipient: address(users.alice.deleGator) });// Create caveat with payment termsconst paymentCaveat = Caveat({     enforcer: address(paidEnforcer),     terms: abi.encode(paymentTerms),     args: hex"" });// Create delegation with payment caveatconst delegation = createRootDelegation(  delegateClient.account.address,  delegatorClient.account.address,  {    caveats: [paymentCaveat]  });// Sign delegationconst signedDelegation = await delegatorClient.signDelegation(delegation);// Create actionconst action = createAction(    to: address(someContract),    value: 0,    data: abi.encodeWithSelector(SomeContract.someMethod.selector));// Redeem delegationdelegateClient.redeemDelegation([signedDelegation], action);```This example demonstrates creating a delegation with a `NativePaidEnforcer` caveat, signing it, andusing it to execute an action. The caveat ensures that Bob pays Alice 0.1 ether when using thedelegation.You can create your own conditional caveat enforcer using the `afterHook` function when defining acustom `CaveatEnforcer` contract. For example, to make sure that the delegator owns a specific NFTbefore allowing the delegation to be used (enabling any action that results in owning that NFT), youcould do something like this:```solidityimport { CaveatEnforcer } from "@delegator/src/enforcers/CaveatEnforcer.sol";import { Action } from "@delegator/src/utils/Types.sol";import { IERC721 } from "@openzeppelin/contracts/token/ERC721/IERC721.sol";contract NFTOwnershipEnforcer is CaveatEnforcer {  struct OwnershipTerms {    address nftContract;    uint256 tokenId;  }  error NotNFTOwner(address account, address nftContract, uint256 tokenId);  function beforeHook(    bytes calldata _terms,    bytes calldata,    Action calldata,    bytes32,    address,    address _redeemer  ) external view override returns (bool) {    return true;  }  function afterHook(    bytes calldata,    bytes calldata,    Action calldata,    bytes32,    address,    address  ) external pure override returns (bool) {    OwnershipTerms memory terms = abi.decode(_terms, (OwnershipTerms));        IERC721 nft = IERC721(terms.nftContract);    if (nft.ownerOf(terms.tokenId) != _redeemer) {      revert NotNFTOwner(_redeemer, terms.nftContract, terms.tokenId);    }    return true;  }}```This `NFTOwnershipEnforcer` checks if the redeemer owns a specific NFT _after_ allowing thedelegation to be used, but the action will be reverted if the `afterHook` returns `false`. It's asimple state lookup that doesn't modify any state.To use this enforcer, create a caveat like this:```typescriptconst nftContract = "0x1234..."; // Address of the NFT contractconst tokenId = 123; // ID of the required NFTconst caveat = {  enforcer: nftOwnershipEnforcerAddress,  terms: encodeAbiParameters(    [{ type: "address" }, { type: "uint256" }],    [nftContract, tokenId]  ),  args: "0x"};const delegation = createDelegation(  delegateAddress,  delegatorAddress,  undefined,  [caveat]);```This example demonstrates a minimal state lookup without modifying any state, which is simpler thanthe previous payment example.

stack:

Ethereum Virtual Machine

ERC-4337

solidity

MetaMask Delegation Toolkit

yarn