confirmations.md

Adding New Confirmations

Overview

Given the security focused nature of self-custody, confirmations and approvals form a pivotal aspect of MetaMask Mobile.

Confirmations can be triggered by dApps and the UI itself, and are used to approve a variety of operations such as:

• Connecting to dApps
• Giving permissions to dApps
• Sending Eth
• Transfering tokens
• Signing data
• Interacting with Snaps
• Adding Ethereum networks

It is vital any new confirmations are implemented using best practices and consistent patterns, to avoid adding complexity to the code, and to minimise the maintenance cost of many alternate confirmations.

Steps

1. Create Approval Request

Call the add method on the ApprovalController to create an approval request.

This returns a Promise which will resolve if the confirmation is approved, and reject if the confirmation is denied or cancelled.

Use an async function to send the message so the logic can await the confirmation and code execution can continue once approved. This enables the logic ran after approval to be kept in the same flow and therefore the logic to remain readable and encapsulated.

Ensure suitable error handling is in place to handle the confirmation being cancelled or denied and therefore the Promise being rejected.

The available arguments are:

Name	Description	Example Value
opts.id	The ID of the approval request. Assigned to a random value if not provided.	"f81f5c8a-33bb-4f31-a4e2-52f8b94c393b"
opts.origin	The origin of the request. Either the dApp host or "metamask" if internal.	"metamask.github.io"
opts.type	A string identifying the type of confirmation.	"eth_signTypedData"
opts.requestData	Additional fixed data for the request. Must be a JSON compatible object.	{ transactionId: '123' }
opts.requestState	Additional mutable data for the request. Must be a JSON compatible object. Can be updated using the updateRequestState method.	{ status: 'pending' }

Example

const approvalData = await Engine.context.ApprovalController.add({
    origin: hostname,
    type: ApprovalTypes.EXAMPLE,
    requestData: { value: 'Example Value' }
});

2. Update Approval Request (Optional)

If you wish to provide additional state to the confirmation while it is visible, call the updateRequestState method on the ApprovalController.

This requires you to have provided the id when creating the approval request, so it can be provided in the arguments.

The available arguments are:

Name	Description	Example Value
opts.id	The ID of the approval request to update.	"f81f5c8a-33bb-4f31-a4e2-52f8b94c393b"
opts.requestState	The updated mutable data for the request. Must be a JSON compatible object.	{ status: 'pending' }

Example

await Engine.context.ApprovalController.updateRequestState({
    id,
    requestState: { counter },
});

3. Define Approval Type

Update the ApprovalTypes enum in app/core/RPCMethods/RPCMethodMiddleware.ts to include a new entry to identify the new confirmations.

Example

export enum ApprovalTypes {
  ...
  EXAMPLE = 'EXAMPLE'
}

This must match the opts.type provided in the add request.

4. Handle Approval Type

Update the handlePendingApprovals method in app/components/Nav/Main/RootRPCMethodsUI.js with a new case for the new approval type.

This case needs to update the local React state using any relevant data from the approval request and set the pending approval state using the showPendingApprovalModal method.

Example

case ApprovalTypes.EXAMPLE:
    setExampleRequest({ data: requestData, id: request.id });
    showPendingApprovalModal({
        type: ApprovalTypes.EXAMPLE,
        origin: request.origin,
    });
    break;

5. Create Approval Component

Create a component in app/components/UI to define the content of the modal.

Use Approval as a suffix so similar components can be identified, such as ExampleApproval.

Include onCancel and onConfirm properties to decouple the component from the side effects of rejecting or approving the confirmation.

For an example, see the ExampleApproval in the example branch.

6. Create Handler Functions

Create handler functions for approval and rejection of the confirmation in the RootRPCMethodsUI component.

Use the acceptPendingApproval and rejectPendingApproval local methods to trigger the accept and reject methods of the ApprovalController to resolve the confirmation promise.

Ensure setShowPendingApproval is called to clear the local pending approval state.

Ensure any related local state is cleared.

Example

const onExampleConfirm = () => {
    acceptPendingApproval(exampleRequest.id, exampleRequest.requestData);
    setShowPendingApproval(false);
    setExampleRequest(undefined);
};

const onExampleReject = () => {
    rejectPendingApproval(exampleRequest.id, exampleRequest.requestData);
    setShowPendingApproval(false);
    setExampleRequest(undefined);
};

7. Render Modal

Update the RootRPCMethodsUI component to render a modal for the new approval type.

Use a new method to encapsulate the code for the approval type.

Include the new approval component as a child of the Modal component.

Reference the new handlers in the Modal properties onSwipeComplete and onBackdropPress, and in the appropriate properties of the new approval component.

Example

const renderExampleModal = () => (
    <Modal
      isVisible={showPendingApproval?.type === ApprovalTypes.EXAMPLE}
      animationIn="slideInUp"
      animationOut="slideOutDown"
      style={styles.bottomModal}
      backdropColor={colors.overlay.default}
      backdropOpacity={1}
      animationInTiming={300}
      animationOutTiming={300}
      onSwipeComplete={onExampleReject}
      onBackdropPress={onExampleReject}
      swipeDirection={'down'}
    >
      <ExampleApproval
        onCancel={onExampleReject}
        onConfirm={onExampleConfirm}
        value={exampleRequest?.requestData.value}
        counter={exampleRequest?.requestState?.counter}
      />
    </Modal>
  );

Example Branch

See this branch as an example of the full code needed to add a confirmation.

The confirmation can be tested using the E2E Test dApp and selecting Connect.

Screenshots

Confirmation Modal