Skip to content

index.md

Latest commit

 

History

History
482 lines (365 loc) · 14.5 KB

index.md

File metadata and controls

482 lines (365 loc) · 14.5 KB
Raw
description Delegation-related API methods reference.
toc_max_heading_level 2

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

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 DeleGatorEnvironment Yes Environment to resolve the smart contracts for the current chain.
config CaveatBuilderConfig No Configuration for CaveatBuilder.

Example

import { createCaveatBuilder } from "@metamask/delegation-toolkit";
import { delegatorSmartAccount } from "./config.ts";

const caveats = createCaveatBuilder(delegatorSmartAccount.environment)
import {
  Implementation,
  toMetaMaskSmartAccount,
} from "@metamask/delegation-toolkit";
import { createWalletClient, createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia as chain } from "viem/chains";
 
const publicClient = createPublicClient({
  chain,
  transport: http(),
});

const delegatorAccount = privateKeyToAccount("0x...");

export const delegatorSmartAccount = await toMetaMaskSmartAccount({
  client: publicClient,
  implementation: Implementation.Hybrid,
  deployParams: [delegatorAccount.address, [], [], []],
  deploySalt: "0x",
  signer: { account: delegatorAccount },
});

Allow empty caveats

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

import { createCaveatBuilder } from "@metamask/delegation-toolkit";
// The config.ts is the same as in the previous example.
import { delegatorSmartAccount } from "./config.ts";

const caveats = createCaveatBuilder(delegatorSmartAccount.environment, {
  // add-next-line 
  allowEmptyCaveats: 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.
environment DeleGatorEnvironment Yes The environment used by the toolkit to define contract addresses for interacting with the Delegation Framework contracts.
caveats Caveats No Caveats that further refine the authority granted by the scope.
parentDelegation Delegation | Hex No The parent delegation or its corresponding hex to create a delegation chain.
salt Hex No The salt for generating the delegation hash. This helps prevent hash collisions when creating identical delegations.

Example

import { createDelegation, getDelegatorEnvironment } from "@metamask/delegation-toolkit";
import { sepolia } from "viem/chains";

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: getDelegatorEnvironment(sepolia.id);
  scope: {
    type: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});

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 Yes The scope of the delegation that defines the initial authority.
environment DeleGatorEnvironment Yes The environment used by the toolkit to define contract addresses for interacting with the Delegation Framework contracts.
caveats Caveats No Caveats that further refine the authority granted by the scope.
parentDelegation Delegation | Hex No The parent delegation or its corresponding hex to create a delegation chain.
salt Hex No The salt for generating the delegation hash. This helps prevent hash collisions when creating identical delegations.

Example

import { createOpenDelegation, getDelegatorEnvironment } from "@metamask/delegation-toolkit";
import { sepolia } from "viem/chains";

const delegation = createOpenDelegation({
  // Address that is granting the delegation
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  // Alternatively you can use environment property of MetaMask smart account.
  environment: getDelegatorEnvironment(sepolia.id);
  scope: {
    type: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});

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/delegation-toolkit";

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

deployDeleGatorEnvironment

Deploys the Delegation Framework 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 { deployDeleGatorEnvironment } from "@metamask/delegation-toolkit/utils";
import { walletClient, publicClient } from "./config.ts";
import { sepolia as chain } from "viem/chains";

const environment = await deployDeleGatorEnvironment(
  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 { DeleGatorEnvironment } from "@metamask/delegation-toolkit";
import { 
  overrideDeployedEnvironment,
  deployDeleGatorEnvironment,
} from "@metamask/delegation-toolkit/utils";

const environment: DeleGatorEnvironment = await deployDeleGatorEnvironment(
  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/delegation-toolkit/contracts";
import { delegation } from "./delegation.ts";

const disableDelegationData = DelegationManager.encode.disableDelegation({
  delegation,
});
import { createDelegation } from "@metamask/delegation-toolkit";
import { sepolia } from "viem/chains";

export const delegation = createDelegation({
  from: "0x7E48cA6b7fe6F3d57fdd0448B03b839958416fC1",
  to: "0x2B2dBd1D5fbeB77C4613B66e9F35dBfE12cB0488",
  environment: getDelegatorEnvironment(sepolia.id);
  scope: {
    type: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});

getDeleGatorEnvironment

Resolves the DeleGatorEnvironment for a chain.

Parameters

Name Type Required Description
chainId number Yes The chain ID of the network for which the DeleGatorEnvironment should be resolved.
version SupportedVersion No Specifies the version of the Delegation Framework contracts to use. If omitted, the latest supported version will be used by default.

Example

import { getDeleGatorEnvironment } from "@metamask/delegation-toolkit";
import { sepolia } from "viem/chains";

const environment = getDeleGatorEnvironment(sepolia.id)

overrideDeployedEnvironment

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

Parameters

Name Type Required Description
chainId number Yes The chain ID of the network for which the DeleGatorEnvironment should be overridden.
version SupportedVersion Yes The version of the Delegation Framework contracts to override for the specified chain.
environment DeleGatorEnvironment Yes The environment containing contract addresses to override for the given chain and version.

Example

import { environment } from "./environment.ts";
import { overrideDeployedEnvironment } from "@metamask/delegation-toolkit/utils";
import { sepolia } from "viem/chains";

overrideDeployedEnvironment(
  sepolia.id,
  "1.3.0",
  environment
);
import { DeleGatorEnvironment } from "@metamask/delegation-toolkit";

export const environment: DeleGatorEnvironment = {
  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. Supported execution modes are SingleDefault, SingleTry, BatchDefault, and BatchTry.
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/delegation-toolkit";
import { DelegationManager } from "@metamask/delegation-toolkit/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
signer WalletClient Yes Viem Wallet Client to sign 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.

Example

import { signDelegation } from "@metamask/delegation-toolkit";
import { walletClient, delegation, delegationManager } from "./config.ts";
import { sepolia } from "viem/chains";

const signature = signDelegation({
  signer: walletClient,
  delegation,
  chainId: sepolia.id,
  delegationManager,
})
import { 
  getDeleGatorEnvironment,
  createDelegation,
} from "@metamask/delegation-toolkit";
import { createWalletClient } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { sepolia } from "viem/chains";

const environment = getDelegatorEnvironment(sepolia.id);
export const delegationManager = environment.DelegationManager;

const account = privateKeyToAccount(delegateWallet as `0x${string}`);

export const walletClient = createWalletClient({
  account,
  transport: http(),
  chain: sepolia,
});

// 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: "nativeTokenTransferAmount",
    // 0.001 ETH in wei format.
    maxAmount: 1000000000000000n,
  },
});