Delegation

Delegation is the ability for an account owner (the delegator) to grant permission to another smart contract account (SCA) or externally owned account (EOA) to perform specific executions on the delegator's behalf.

Caveats can be used to apply rules and restrictions to delegations. For example: Alice delegates the ability to spend her USDC to Bob, limiting the amount to 100 USDC.

Users can also redelegate permissions that have been delegated to them, creating a chain of delegations across trusted parties.

A delegation conforms to the following structure:

export type DelegationStruct = {
  delegate: Hex; // The account that receives permissions to perform executions 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.
};

Delegation lifecycle

The delegation lifecycle is as follows:

1. Delegation creation - An account owner initializes a delegation with caveats, and signs it.

2. Caveat enforcement - Caveats are applied to the delegation to specify conditions under which the delegation can be redeemed.

3. Delegation storage - The delegation must be stored in order to be available for redemption in the future.

4. Delegation redemption - The delegation is redeemed through an ERC-4337 user operation or an EOA, verifying that the delegator's authority is valid for the execution to be performed.

See how to manage delegations for instructions on completing specific tasks within the delegation lifecycle.

Delegation Framework

The MetaMask Delegation Toolkit includes the Delegation Framework, which is a set of comprehensively audited smart contracts that collectively handle delegator account creation, the delegation lifecycle, and caveat enforcement. It consists of the following components:

• Delegator Core - Delegator Core contains the logic for the ERC-4337 compliant delegator accounts. It defines the interface needed for the Delegation Manager to invoke executions on behalf of the accounts.

• Delegator account implementations - There are multiple delegator account implementations, with the main difference being the signature scheme used to manage the underlying account:

  • Multi-signature delegator - This enables multi-signature (multisig) authentication with a specified threshold or minimum number of EOA signatures required. This threshold can be updated by the account owner. Signers can be added, removed, and replaced.

  • Hybrid delegator - This supports both EOA and passkey (NIST P-256) signatures for authentication. Multiple signers can be added, but only one is needed for a valid signature. Hybrid delegator inherits from ERC-173, enabling transfer of ownership. Both EOA and passkey signers can be added or deleted.

• Delegation Manager - The Delegation Manager validates delegations and triggers executions on behalf of the delegator, ensuring tasks are executed accurately and securely.

  When a delegation is redeemed, the Delegation Manager performs the following steps. It processes a single step for all redemptions before proceeding to the next one:

  1. Validates the input data by ensuring the lengths of permissionContexts, modes, and executionCallDatas match, or throws BatchDataLengthMismatch.
  2. Decodes and validates the delegation, checking that the caller (msg.sender) is the delegate and that there are no empty signatures, or throws InvalidDelegate.
  3. Verifies delegation signatures, ensuring validity using ECDSA (for EOAs) or isValidSignature (for contracts), or throws InvalidSignature.
  4. Validates the delegation chain's authority and ensures delegations are not disabled.
  5. Executes the beforeHook for each caveat in the delegation, passing relevant data (terms, arguments, mode, execution calldata, and delegationHash) to the caveat enforcer.
  6. Calls executeFromExecutor to perform the delegation's execution, either by the delegator or the caller for self-authorized executions.
  7. Executes the afterHook for each caveat, similar to the beforeHook, passing required data to enforce post-execution conditions.
  8. Emits RedeemedDelegation events for each delegation that was successfully redeemed.

• Caveat enforcers - Caveat enforcers manage rules and restrictions for delegations, providing fine-tuned control over delegated executions. Learn more about caveat enforcers.