Skip to main content

Delegation Toolkit documentation

Embed MetaMask Smart Accounts into your dapp, enabling new user experiences.

Caveats

When restricting a delegation, you can specify the following caveat types in the CaveatBuilder.

allowedCalldata​

Limits the calldata that is executed.

You can use this caveat to enforce function parameters. We strongly recommend using this caveat to validate static types and not dynamic types. You can validate dynamic types through a series of allowedCalldata terms, but this is tedious and error-prone.

Caveat enforcer contract: AllowedCalldataEnforcer.sol

Parameters​

  1. Index in the calldata byte array (including the 4-byte method selector) where the expected calldata starts
  2. Expected calldata as a hex string

Example​

caveatBuilder.addCaveat("allowedCalldata",
  4,
  encodeAbiParameters([
    { type: "string" },
    { type: "uint256" }
  ], [
    "Hello Gator",
    12345n
  ])
);
note

This example uses Viem's encodeAbiParameters utility to encode the parameters as ABI-encoded hex strings.

allowedMethods​

Limits what methods the delegate can call.

Caveat enforcer contract: AllowedMethodsEnforcer.sol

Parameters​

  1. An array of methods as 4-byte hex strings, ABI function signatures, or ABIFunction objects

Example​

caveatBuilder.addCaveat("allowedMethods", [
  "0xa9059cbb",
  "transfer(address,uint256)",
  {
    name: 'transfer',
    type: 'function',
    inputs: [
      { name: 'recipient', type: 'address' },
      { name: 'amount', type: 'uint256' }
    ],
    outputs: [],
    stateMutability: 'nonpayable',
  }
]);
note

This example adds the transfer function to the allowed methods in three different ways - as the 4-byte function selector, the ABI function signature, and the ABIFunction object.

allowedTargets​

Limits what addresses the delegate can call.

Caveat enforcer contract: AllowedTargetsEnforcer.sol

Parameters​

  1. An array of addresses as hex strings

Example​

caveatBuilder.addCaveat("allowedTargets", [
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
  "0xB2880E3862f1024cAC05E66095148C0a9251718b"
]);

argsEqualityCheck​

Ensures that the args provided when redeeming the delegation are equal to the terms specified on the caveat.

Caveat enforcer contract: ArgsEqualityCheckEnforcer.sol

Parameters​

  1. The expected args as a hex string

Example​

caveatBuilder.addCaveat("argsEqualityCheck",
  "0xf2bef872456302645b7c0bb59dcd96ffe6d4a844f311ebf95e7cf439c9393de2"
);

blockNumber​

Specifies a range of blocks through which the delegation will be valid.

Caveat enforcer contract: BlockNumberEnforcer.sol

Parameters​

  1. After threshold block number as a bigint
  2. Before threshold block number as a bigint

You can specify 0n to indicate that there is no limitation on a threshold.

Example​

caveatBuilder.addCaveat("blocknumber",
  19426587n,
  0n
);

deployed​

Ensures a contract is deployed, and if not, deploys the contract.

Caveat enforcer contract: DeployedEnforcer.sol

Parameters​

  1. A contract address as a hex string
  2. The salt to use with the contract, as a hex string
  3. The bytecode of the contract as a hex string

Example​

caveatBuilder.addCaveat("deployed",
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
  "0x0e3e8e2381fde0e8515ed47ec9caec8ba2bc12603bc2b36133fa3e3fa4d88587",
  "0x..." // The deploy bytecode for the contract at 0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92
);

erc1155BalanceChange​

Ensures that the recipient's ERC-1155 token balance has changed within the allowed bounds — either increased by a minimum or decreased by a maximum specified amount.

Caveat enforcer contract: ERC1155BalanceBalanceEnforcer.sol

Parameters​

  1. An ERC-1155 contract address as a hex string
  2. The recipient's address as a hex string
  3. The ID of the ERC-1155 token as a bigint
  4. The amount by which the balance must have changed as a bigint
  5. The balance change type for the ERC-1155 token. Specifies whether the balance should have increased or decreased. Valid parameters are BalanceChangeType.Increase and BalanceChangeType.Decrease.

Example​

caveatBuilder.addCaveat("erc1155BalanceChange",
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
  "0x3fF528De37cd95b67845C1c55303e7685c72F319",
  1n,
  1_000_000n,
  BalanceChangeType.Increase,
);

erc20BalanceChange​

Ensures that the recipient's ERC-20 token balance has changed within the allowed bounds — either increased by a minimum or decreased by a maximum specified amount.

Caveat enforcer contract: ERC20BalanceChangeEnforcer.sol

Parameters​

  1. An ERC-20 contract address as a hex string
  2. The recipient's address as a hex string
  3. The amount by which the balance must have changed as a bigint
  4. The balance change type for the ERC-20 token. Specifies whether the balance should have increased or decreased. Valid parameters are BalanceChangeType.Increase and BalanceChangeType.Decrease.

Example​

caveatBuilder.addCaveat("erc20BalanceChange",
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
  "0x3fF528De37cd95b67845C1c55303e7685c72F319",
  1_000_000n,
  BalanceChangeType.Increase,
);

erc20PeriodTransfer​

Ensures that ERC-20 token transfers remain within a predefined limit during a specified time window. At the start of each new period, the allowed transfer amount resets. Any unused transfer allowance from the previous period does not carry over and is forfeited.

Caveat enforcer contract: ERC20PeriodTransferEnforcer.sol

Parameters​

  1. The address of the ERC-20 token contract.
  2. The maximum amount of tokens that can be transferred per period, in wei.
  3. The duration of each period in seconds.
  4. The timestamp when the first period begins.

Example​

caveatBuilder.addCaveat("erc20PeriodTransfer",
  "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da", // Address of the ERC-20 token
  1000000000000000000n, // 1 ERC-20 token - 18 decimals, in wei
  86400, // 1 day in seconds
  1743763600, // April 4th, 2025, at 00:00:00 UTC
);

erc20Streaming​

Enforces a linear streaming transfer limit for ERC-20 tokens. Block token access until the specified start timestamp. At the start timestamp, immediately release the specified initial amount. Afterward, accrue tokens linearly at the specified rate, up to the specified maximum.

Caveat enforcer contract: ERC20StreamingEnforcer.sol

Parameters​

  1. An ERC-20 contract address as a hex string
  2. Initial amount available at start time as a bigint
  3. Maximum total amount that can be unlocked as a bigint
  4. Rate at which tokens accrue per second as a bigint
  5. Start timestamp as a number

Example​

caveatBuilder.addCaveat("erc20Streaming",
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
  1_000_000n,
  10_000_000n,
  100n,
  1703980800
);

erc20TransferAmount​

Limits the transfer of ERC-20 tokens.

Caveat enforcer contract: ERC20TransferAmountEnforcer.sol

Parameters​

  1. An ERC-20 contract address as a hex string
  2. Amount as a bigint

Example​

caveatBuilder.addCaveat("erc20TransferAmount",
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
  1_000_000n
);

erc721BalanceChange​

Ensures that the recipient's ERC-721 token balance has changed within the allowed bounds — either increased by a minimum or decreased by a maximum specified amount.

Caveat enforcer contract: ERC721BalanceChangeEnforcer.sol

Parameters​

  1. An ERC-721 contract address as a hex string
  2. The recipient's address as a hex string
  3. The amount by which the balance must have changed as a bigint
  4. The balance change type for the ERC-721 token. Specifies whether the balance should have increased or decreased. Valid parameters are BalanceChangeType.Increase and BalanceChangeType.Decrease.

Example​

caveatBuilder.addCaveat("erc721BalanceChange",
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92",
  "0x3fF528De37cd95b67845C1c55303e7685c72F319",
  1_000_000n,
  BalanceChangeType.Increase,
);

erc721Transfer​

Restricts the execution to only allow ERC-721 token transfers, specifically the transferFrom(from, to, tokenId) function, for a specified token ID and contract.

Caveat enforcer contract: ERC721TransferEnforcer.sol

Parameters​

  1. The permitted ERC-721 contract address as a hex string
  2. The permitted ID of the ERC-721 token as a bigint

Example​

caveatBuilder.addCaveat("erc721Transfer",
  "0x3fF528De37cd95b67845C1c55303e7685c72F319",
  1n
);

exactCalldata​

Verifies that the transaction calldata matches the expected calldata. For batch transactions, see exactCalldataBatch.

Caveat enforcer contract: ExactCalldataEnforcer.sol

Parameters​

  1. A hex value for calldata.

Example​

caveatBuilder.addCaveat("exactCalldata", 
  "0x1234567890abcdef" // Calldata to be matched
);

exactCalldataBatch​

Verifies that the provided batch execution calldata matches the expected calldata for each individual execution in the batch.

Caveat enforcer contract: ExactCalldataBatchEnforcer.sol

Parameters​

  1. Array of expected ExecutionStruct, each containing target address, value, and calldata.

Example​

const executions = [
  {
    target: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
    value: 1000000000000000000n, // 1 ETH
    callData: "0x",
  },
  {
    target: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
    value: 0n,
    callData: "0x",
  },
];

caveatBuilder.addCaveat("exactCalldataBatch",
  executions
);

exactExecution​

Verifies that the provided execution matches the expected execution. For batch transactions, see exactExecutionBatch.

Caveat enforcer contract: ExactExecutionEnforcer.sol

Parameters​

  1. ExecutionStruct to be expected.

Example​

caveatBuilder.addCaveat("exactExecution", {
  target: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
  value: 1000000000000000000n, // 1 ETH
  callData: "0x",
})

exactExecutionBatch​

Verifies that each execution in the batch matches the expected execution parameters - including target, value, and calldata.

Caveat enforcer contract: ExactExecutionBatchEnforcer.sol

Parameters​

  1. Array of expected ExecutionStruct, each containing target address, value, and calldata.

Example​

const executions = [
  {
    target: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
    value: 1000000000000000000n, // 1 ETH
    callData: "0x",
  },
  {
    target: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
    value: 0n,
    callData: "0x",
  },
];

caveatBuilder.addCaveat("exactExecutionBatch",
  executions
);

id​

Specifies an ID for multiple delegations. Once one of them is redeemed, the other delegations with the same ID are revoked.

Caveat enforcer contract: IdEnforcer.sol

Parameters​

  1. An ID as a number

Example​

caveatBuilder.addCaveat("id",
  123456
);

limitedCalls​

Limits the number of times the delegate can perform executions on the delegator's behalf.

Caveat enforcer contract: LimitedCallsEnforcer.sol

Parameters​

  1. A count as a number

Example​

caveatBuilder.addCaveat("limitedCalls",
  1
);

multiTokenPeriod​

Ensures that token transfers for multiple tokens stay within the specified limits for the defined periods. At the start of each new period, the allowed transfer amount for each token resets. Any unused transfer allowance from the previous period expires and does not carry over.

When redeeming the delegation, the index of the relevant token configuration must be specified as the args of this caveat (encoded as uint256 hex value).

Caveat enforcer contract: MultiTokenPeriodEnforcer.sol

Parameters​

An array of token period configuration objects, where each object contains:

  • token: The address of the token contract as a hex string.
  • periodAmount: The maximum amount of tokens that can be transferred per period, in wei.
  • periodDuration: The duration of each period in seconds.
  • startDate: A Unix epoch timestamp (in seconds) representing when the first period begins.

Example​

caveatBuilder.addCaveat("multiTokenPeriod", [
  {
    token: "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da", // First token contract
    periodAmount: 1000000000000000000n, // 1 token with 18 decimals
    periodDuration: 86400, // 1 day in seconds
    startDate: 1743763600, // April 4th, 2025, at 00:00:00 UTC
  },
  {
    token: "0x6be97c23596ECed7170fdFb28e8dA1Ca5cdc54C5", // Second token contract
    periodAmount: 500000000n, // 0.5 tokens with 9 decimals
    periodDuration: 3600, // 1 hour in seconds
    startDate: 1743763600, // April 4th, 2025, at 00:00:00 UTC
  }
]);

nativeBalanceChange​

Ensures that the recipient's native token balance has changed within the allowed bounds — either increased by a minimum or decreased by a maximum specified amount.

Caveat enforcer contract: NativeBalanceChangeEnforcer.sol

Parameters​

  1. The recipient's address as a hex string
  2. The amount by which the balance must have changed as a bigint
  3. The balance change type for the native token. Specifies whether the balance should have increased or decreased. Valid parameters are BalanceChangeType.Increase and BalanceChangeType.Decrease.

Example​

caveatBuilder.addCaveat("nativeBalanceChange",
  "0x3fF528De37cd95b67845C1c55303e7685c72F319",
  1_000_000n,
  BalanceChangeType.Increase,
);

nativeTokenPayment​

Enforces payment in native token (for example, ETH) for the right to use the delegation. A permissions context allowing payment must be provided as the args when redeeming the delegation.

Caveat enforcer contract: NativeTokenPaymentEnforcer.sol

Parameters​

  1. The recipient's address as a hex string
  2. The amount that must be paid as a bigint

Example​

caveatBuilder.addCaveat("nativeTokenPayment",
  "0x3fF528De37cd95b67845C1c55303e7685c72F319",
    1_000_000n
);

nativeTokenPeriodTransfer​

Ensures that native token transfers remain within a predefined limit during a specified time window. At the start of each new period, the allowed transfer amount resets. Any unused transfer allowance from the previous period does not carry over and is forfeited.

Caveat enforcer contract: NativeTokenPeriodTransferEnforcer.sol

Parameters​

  1. The maximum amount of tokens that can be transferred per period, in wei.
  2. The duration of each period in seconds.
  3. The timestamp when the first period begins.

Example​

caveatBuilder.addCaveat("nativeTokenPeriodTransfer",
  1000000000000000000n, // 1 ETH in wei
  86400, // 1 day in seconds
  1743763600, // April 4th, 2025, at 00:00:00 UTC
)

nativeTokenStreaming​

Enforces a linear streaming limit for native tokens (for example, ETH). Nothing is available before the specified start timestamp. At the start timestamp, the specified initial amount becomes immediately available. After that, tokens accrue linearly at the specified rate, capped by the specified maximum.

Caveat enforcer contract: NativeTokenStreamingEnforcer.sol

Parameters​

  1. Initial amount available at start time as a bigint
  2. Maximum total amount that can be unlocked as a bigint
  3. Rate at which tokens accrue per second as a bigint
  4. Start timestamp as a number

Example​

caveatBuilder.addCaveat("nativeTokenStreaming",
  1_000_000n,
  10_000_000n,
  100n,
  1703980800
);

nativeTokenTransferAmount​

Enforces an allowance of native currency (for example, ETH).

Caveat enforcer contract: NativeTokenTransferAmountEnforcer.sol

Parameters​

  1. The allowance as a bigint

Example​

caveatBuilder.addCaveat("nativeTokenTransferAmount",
  1_000_000n
);

nonce​

Adds a nonce to a delegation, and revokes previous delegations by incrementing the current nonce by calling incrementNonce(address _delegationManager).

Caveat enforcer contract: NonceEnforcer.sol

Parameters​

  1. A nonce as a hex string

Example​

caveatBuilder.addCaveat("nonce",
  "0x1"
);

ownershipTransfer​

Restricts the execution to only allow ownership transfers, specifically the transferOwnership(address _newOwner) function, for a specified contract.

Caveat enforcer contract: OwnershipTransferEnforcer.sol

Parameters​

  1. The target contract address as a hex string

Example​

caveatBuilder.addCaveat("ownershipTransfer",
  "0xc11F3a8E5C7D16b75c9E2F60d26f5321C6Af5E92"
);

redeemer​

Limits the addresses that can redeem the delegation. This caveat is designed to restrict smart contracts or EOAs lacking delegation support, and can be placed anywhere in the delegation chain to restrict the redeemer.

note

Delegator accounts with delegation functionalities can bypass these restrictions by delegating to other addresses. For example, Alice makes Bob the redeemer. This condition is enforced, but if Bob is a delegator he can create a separate delegation to Carol that allows her to redeem Alice's delegation through Bob.

Caveat enforcer contract: RedeemerEnforcer.sol

Parameters​

  1. An array of addresses as hex strings

Example​

caveatBuilder.addCaveat("redeemer",
  [
    "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da",
    "0x6be97c23596ECed7170fdFb28e8dA1Ca5cdc54C5"
  ]
);

specificActionERC20TransferBatch​

Ensures validation of a batch consisting of exactly two transactions:

  1. The first transaction must call a specific target contract with predefined calldata.
  2. The second transaction must be an ERC-20 token transfer that matches specified parameters—including the ERC-20 token contract address, amount, and recipient.

Caveat enforcer contract: SpecificActionERC20TransferBatchEnforcer.sol

Parameters​

  1. The address of the ERC-20 token contract.
  2. The address that will receive the tokens.
  3. The amount of tokens to transfer, in wei.
  4. The target address for the first transaction.
  5. The calldata for the first transaction.

Example​

caveatBuilder.addCaveat("specificActionERC20TransferBatch",
  "0xb4aE654Aca577781Ca1c5DE8FbE60c2F423f37da" // Address of ERC-20 token contract
  "0x027aeAFF3E5C33c4018FDD302c20a1B83aDCD96C", // Address that will receive the tokens
  1000000000000000000n, // 1 ERC-20 token - 18 decimals, in wei
  "0xb49830091403f1Aa990859832767B39c25a8006B", // Target address for first transaction
  "0x1234567890abcdef" // Calldata to be matched for first transaction
)

timestamp​

Specifies a range of timestamps through which the delegation will be valid.

Caveat enforcer contract: TimestampEnforcer.sol

Parameters​

  1. After threshold timestamp as a number
  2. Before threshold timestamp as a number

You can specify 0 to indicate that there is no limitation on a threshold.

Example​

caveatBuilder.addCaveat("timestamp",
   499165200,
  1445412480
);

valueLte​

Limits the value of native tokens that the delegate can spend.

Caveat enforcer contract: ValueLteEnforcer.sol

Parameters​

  1. A value as a bigint

Example​

caveatBuilder.addCaveat("valueLte",
  1_000_000_000_000_000_000n // 1 ETH in wei
);
On this page