Skip to main content

Store and retrieve delegations

You can use methods provided by the DelegationStorageClient to store and retrieve delegations.

Experimental

This experimental feature requires MetaMask Delegation Toolkit version 0.7.0 or later and may change in future releases.

Prerequisites​

Configure a DelegationStorageClient​

Import the DelegationStorageClient and configure it using your API key and API key ID:

import { DelegationStorageClient, DelegationStorageEnvironment } from "@metamask-private/delegator-core-viem/experimental";

const delegationStorageClient = new DelegationStorageClient({
  apiKey: "<YOUR-API-KEY>",
  apiKeyId: "<YOUR-API-KEY-ID>",
  environment: DelegationStorageEnvironment.prod
});

Store a delegation​

To store a delegation, use the storeDelegation method of the DelegationStorageClient. This method takes one parameter:

  1. delegation - A DelegationStruct object representing the delegation to be stored.

Example​

const delegation: DelegationStruct = {
  delegate: "0xD5142498A04b8b1198a788F3B443edC0a0CB865b",
  delegator: "0x8DF9cb41c9A70FF8b97F69Cd87d11996629B50A4",
  authority: "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
  caveats: [],
  salt: 0n,
  signature: "0x082fd634e47b06a5fd7d3dce5eb288af9c1e1961fa2c1f49f9f7f1be1e9905f56694a3c85cfa3c652a953f8968e48d723de0d56a680906d67378306547d8a078b7",
};

const delegationHash = await delegationStorageClient.storeDelegation(delegation);

Retrieve a delegation chain​

To retrieve a delegation chain, use the getDelegationChain method of the DelegationStorageClient. This method takes one parameter:

  1. leafDelegationOrDelegationHash - Either a DelegationStruct object or the delegation hash as a hex string.
note

A delegation can be a "root" delegation, where its authority is 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff. It can also be a child of another delegation, where its authority is the hash of its parent delegation. This method returns the delegation referenced by leafDelegationOrDelegationHash and any ancestors.

Example​

const delegationHash: Hex = "0xdf2750b9309221aa5b78bede5edb6610c7fcf50366b6261112ba7588549e76d9";

const delegationChain: DelegationStruct[] = await delegationStorageClient.getDelegationChain(delegationHash);

Retrieve delegations for a specific account​

To retrieve delegations stored for a specific account, use the fetchDelegations method of the DelegationStorageClient. This method allows you to fetch delegations where the specified account is either the delegator or the delegate. It takes two parameters:

  1. account - The address of the account for which you want to retrieve delegations.
  2. filter - The nature of the delegations. Possible values are:
    • DelegationStoreFilter.Given - For delegations where the specified account is the delegator.
    • DelegationStoreFilter.Received - For delegations where the specified account is the delegate.

Example​

// Fetch the delegations given by deleGatorAddress.
const grantedDelegations = await delegationStore.fetchDelegations(
  deleGatorAddress,
  DelegationStoreFilter.Given,
);

// Fetch the delegations received by deleGatorAddress.
const received = await delegationStore.fetchDelegations(
  deleGatorAddress,
  DelegationStoreFilter.Received,
);