Data storage

You can store and manage sensitive information within a Snap using encrypted storage, or non-sensitive information using unencrypted storage. Use the snap_manageState API method to persist up to 100 MB of data to the user's disk and retrieve it at will. We recommend using this method for storing data in a Snap long term.

important

Snaps are installed in each user's MetaMask instance. If a Snap stores data, that data is specific to that user's MetaMask instance. However, this data can be shared across multiple dapps. Do not assume that the data a Snap stores is unique to a single dapp unless it is specifically designed to be that way.

Steps

1. Get permission to store data

Request the snap_manageState permission. Add the following to your Snap's manifest file:

snap.manifest.json

"initialPermissions": {
  "snap_manageState": {}
}

2. Use encrypted storage

By default, snap_manageState automatically encrypts data using a Snap-specific key before storing it on the user's disk, and automatically decrypts it when retrieved. This is useful to store sensitive information, such as passwords.

The following example uses snap_manageState to store some data using the update operation, and retrieves the data at a later time using the get operation. When the data is no longer required, the Snap's state is cleared using the clear operation.

index.js

// Persist some data.
await snap.request({
  method: "snap_manageState",
  params: { 
    operation: "update",
    newState: { hello: "world" },
  },
});

// At a later time, get the stored data.
const persistedData = await snap.request({
  method: "snap_manageState",
  params: { operation: "get" },
});

console.log(persistedData);
// { hello: "world" }

// If data storage is no longer necessary, clear it.
await snap.request({
  method: "snap_manageState",
  params: { 
    operation: "clear",
  },
});

tip

Accessing encrypted state requires MetaMask to be unlocked. If you need to access encrypted state in a background task such as a cron job, use snap_getClientStatus to ensure that MetaMask is unlocked before accessing state, preventing an unexpected password request.

3. Use unencrypted storage

To use unencrypted storage, set encrypted to false when storing, retrieving, or clearing data using snap_manageState. The Snap will use a storage section separate from the encrypted storage, and will not encrypt the data. This is useful to access non-sensitive data from background operations such as cron jobs, without requiring the user to enter their password in the case that MetaMask is locked.

index.js

// Persist some data.
await snap.request({
  method: "snap_manageState",
  params: { 
    operation: "update",
    newState: { hello: "world" },
    encrypted: false,
  },
});

// At a later time, get the stored data.
const persistedData = await snap.request({
  method: "snap_manageState",
  params: { 
    operation: "get",
    encrypted: false,
  },
});

console.log(persistedData);
// { hello: "world" }

// If data storage is no longer necessary, clear it.
await snap.request({
  method: "snap_manageState",
  params: { 
    operation: "clear",
    encrypted: false,
  },
});

Example

See the @metamask/manage-state-example-snap package for a full example of storing data using snap_manageState. This example exposes a custom JSON-RPC API for dapps to store, retrieve, and clear data.