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.
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' } |
const approvalData = await Engine.context.ApprovalController.add({
origin: hostname,
type: ApprovalTypes.EXAMPLE,
requestData: { value: 'Example Value' }
});
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' } |
await Engine.context.ApprovalController.updateRequestState({
id,
requestState: { counter },
});
Update the ApprovalTypes
enum in app/core/RPCMethods/RPCMethodMiddleware.ts to include a new entry to identify the new confirmations.
export enum ApprovalTypes {
...
EXAMPLE = 'EXAMPLE'
}
This must match the opts.type
provided in the add
request.
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.
case ApprovalTypes.EXAMPLE:
setExampleRequest({ data: requestData, id: request.id });
showPendingApprovalModal({
type: ApprovalTypes.EXAMPLE,
origin: request.origin,
});
break;
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.
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.
const onExampleConfirm = () => {
acceptPendingApproval(exampleRequest.id, exampleRequest.requestData);
setShowPendingApproval(false);
setExampleRequest(undefined);
};
const onExampleReject = () => {
rejectPendingApproval(exampleRequest.id, exampleRequest.requestData);
setShowPendingApproval(false);
setExampleRequest(undefined);
};
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.
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>
);
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
.