@metamask/snaps-rpc-methods/dist/restricted/manageState.d.mts

MetaMask Snaps JSON-RPC method implementations

import type { CryptographicFunctions } from "@metamask/key-tree";
import type { Messenger } from "@metamask/messenger";
import type { PermissionSpecificationBuilder, RestrictedMethodOptions, ValidPermissionSpecification } from "@metamask/permission-controller";
import { PermissionType } from "@metamask/permission-controller";
import type { ManageStateParams, ManageStateResult } from "@metamask/snaps-sdk";
import type { NonEmptyArray } from "@metamask/utils";
import type { SnapControllerClearSnapStateAction, SnapControllerGetSnapAction, SnapControllerGetSnapStateAction, SnapControllerUpdateSnapStateAction } from "../types.mjs";
import type { MethodHooksObject } from "../utils.mjs";
export declare const STATE_ENCRYPTION_SALT = "snap_manageState encryption";
declare const methodName = "snap_manageState";
export type ManageStateMethodHooks = {
    /**
     * Waits for the extension to be unlocked.
     *
     * @returns A promise that resolves once the extension is unlocked.
     */
    getUnlockPromise: (shouldShowUnlockRequest: boolean) => Promise<void>;
};
export type ManageStateMessengerActions = SnapControllerClearSnapStateAction | SnapControllerGetSnapAction | SnapControllerGetSnapStateAction | SnapControllerUpdateSnapStateAction;
type ManageStateSpecificationBuilderOptions = {
    allowedCaveats?: Readonly<NonEmptyArray<string>> | null;
    methodHooks: ManageStateMethodHooks;
    messenger: Messenger<string, ManageStateMessengerActions>;
};
type ManageStateSpecification = ValidPermissionSpecification<{
    permissionType: PermissionType.RestrictedMethod;
    targetName: typeof methodName;
    methodImplementation: ReturnType<typeof getManageStateImplementation>;
    allowedCaveats: Readonly<NonEmptyArray<string>> | null;
}>;
/**
 * The specification builder for the `snap_manageState` permission.
 * `snap_manageState` lets the Snap store and manage some of its state on
 * your device.
 *
 * @param options - The specification builder options.
 * @param options.allowedCaveats - The optional allowed caveats for the permission.
 * @param options.messenger - The messenger.
 * @param options.methodHooks - The RPC method hooks needed by the method implementation.
 * @returns The specification for the `snap_manageState` permission.
 */
export declare const specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, ManageStateSpecificationBuilderOptions, ManageStateSpecification>;
/**
 * Allow the Snap to persist up to 64 MB of data to disk and retrieve it at
 * will. By default, the data is automatically encrypted using a Snap-specific
 * key and automatically decrypted when retrieved. You can set `encrypted` to
 * `false` to use unencrypted storage (available when the client is locked).
 *
 * @example
 * ```json name="Manifest"
 * {
 *   "initialPermissions": {
 *     "snap_manageState": {}
 *   }
 * }
 * ```
 * ```ts name="Usage"
 * // 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 there's no need to store data anymore, clear it out.
 * await snap.request({
 *   method: 'snap_manageState',
 *   params: {
 *     operation: 'clear',
 *   },
 * })
 * ```
 */
export declare const manageStateBuilder: Readonly<{
    readonly targetName: "snap_manageState";
    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.RestrictedMethod, ManageStateSpecificationBuilderOptions, {
        permissionType: PermissionType.RestrictedMethod;
        targetName: typeof methodName;
        methodImplementation: ReturnType<typeof getManageStateImplementation>;
        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
    }>;
    readonly methodHooks: MethodHooksObject<ManageStateMethodHooks>;
    readonly actionNames: readonly ["SnapController:clearSnapState", "SnapController:getSnap", "SnapController:getSnapState", "SnapController:updateSnapState"];
}>;
export declare const STORAGE_SIZE_LIMIT = 64000000;
type GetEncryptionKeyArgs = {
    snapId: string;
    seed: Uint8Array;
    cryptographicFunctions?: CryptographicFunctions | undefined;
};
/**
 * Get a deterministic encryption key to use for encrypting and decrypting the
 * state.
 *
 * This key should only be used for state encryption using `snap_manageState`.
 * To get other encryption keys, a different salt can be used.
 *
 * @param args - The encryption key args.
 * @param args.snapId - The ID of the snap to get the encryption key for.
 * @param args.seed - The mnemonic seed to derive the encryption key
 * from.
 * @param args.cryptographicFunctions - The cryptographic functions to use for
 * the client.
 * @returns The state encryption key.
 */
export declare function getEncryptionEntropy({ seed, snapId, cryptographicFunctions, }: GetEncryptionKeyArgs): Promise<`0x${string}`>;
/**
 * Builds the method implementation for `snap_manageState`.
 *
 * @param options - The options.
 * @param options.messenger - The messenger.
 * @param options.methodHooks - The RPC method hooks.
 * @param options.methodHooks.getUnlockPromise - A function that resolves once the MetaMask
 * extension is unlocked and prompts the user to unlock their MetaMask if it is
 * locked.
 * @returns The method implementation which either returns `null` for a
 * successful state update/deletion or returns the decrypted state.
 * @throws If the params are invalid.
 */
export declare function getManageStateImplementation({ methodHooks: { getUnlockPromise }, messenger, }: ManageStateSpecificationBuilderOptions): (options: RestrictedMethodOptions<ManageStateParams>) => Promise<ManageStateResult>;
/**
 * Validates the manageState method `params` and returns them cast to the correct
 * type. Throws if validation fails.
 *
 * @param params - The unvalidated params object from the method request.
 * @param method - RPC method name used for debugging errors.
 * @returns The validated method parameter object.
 */
export declare function getValidatedParams(params: unknown, method: string): ManageStateParams;
export {};
//# sourceMappingURL=manageState.d.mts.map