9.2 KiB
Adding New Confirmations
Overview
Given the security focused nature of self-custody, confirmations and approvals form a pivotal aspect of the MetaMask extension.
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.
As we try to maintain a clean boundary between the UI and background page, the effort to implement a new confirmation can also be split accordingly.
Background
1. Create Messenger
Ensure the controller or logic requiring a confirmation has access to a controller messenger.
Provide a messenger argument in the constructor if using a controller.
Ensure the allowed actions include at least the ApprovalController:addRequest action.
If the controller extends BaseControllerV2, the property messagingSystem is available to access the messenger passed to the base controller. Otherwise, ensure the provided messenger is assigned to a private property.
Example
this.someController = new SomeController({
messenger: this.controllerMessenger.getRestricted({
name: 'SomeController',
allowedActions: [
`${this.approvalController.name}:addRequest`,
`${this.approvalController.name}:acceptRequest`,
`${this.approvalController.name}:rejectRequest`,
],
}),
...
});
2. Create Approval Request
Send an addRequest message to the ApprovalController to create an approval request.
This message 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 message 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 | An arbitrary string identifying the type of request. | "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 ApprovalController.updateRequestState action. |
{ status: 'pending' } |
| shouldShowRequest | A boolean indicating whether the popup should be displayed. | true |
Example
await this.messagingSystem.call(
'ApprovalController:addRequest',
{
id,
origin,
type,
requestData,
},
true,
);
3. Update Approval Request
If you wish to provide additional state to the confirmation while it is visible, send an updateRequestState message to the ApprovalController.
This requires you to have provided the id when creating the approval request, so it can be passed to the update message.
The available message 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 this.messagingSystem.call(
'ApprovalController:updateRequestState',
{
id,
requestState: { counter },
},
);
Frontend
1. Create Template File
The ConfirmationPage component is already configured to display any approval requests generated by the ApprovalController and the associated pendingApprovals state.
In order to configure how the resulting confirmation is rendered, an Approval Template is required.
Create a new JavaScript file in ui/pages/confirmation/templates with the name matching the type used in the background approval request.
2. Update Approval Templates
Add your imported file to the APPROVAL_TEMPLATES constant in:
ui/pages/confirmation/templates/index.js
3. Define Values
Inside the template file, define a getValues function that returns an object with the following properties:
| Name | Description | Example Value |
|---|---|---|
| content | An array of objects defining the components to be rendered in the confirmation. Processed by the MetaMaskTemplateRenderer. |
See example below. |
| onSubmit | A callback to execute when the user approves the confirmation. | actions.resolvePendingApproval(...) |
| onCancel | A callback to execute when the user rejects the confirmation. | actions.rejectPendingApproval(...) |
| submitText | Text shown for the accept button. | t('approveButtonText') |
| cancelText | Text shown on the reject button. | t('cancel') |
| loadingText | Text shown while waiting for the onSubmit callback to complete. | t('addingCustomNetwork') |
| networkDisplay | A boolean indicating whether to show the current network at the top of the confirmation. | true |
Example
function getValues(pendingApproval, t, actions, _history) {
return {
content: [
{
element: 'Typography',
key: 'title',
children: 'Example',
props: {
variant: TypographyVariant.H3,
align: 'center',
fontWeight: 'bold',
boxProps: {
margin: [0, 0, 4],
},
},
},
...
],
cancelText: t('cancel'),
submitText: t('approveButtonText'),
loadingText: t('addingCustomNetwork'),
onSubmit: () =>
actions.resolvePendingApproval(
pendingApproval.id,
pendingApproval.requestData,
),
onCancel: () =>
actions.rejectPendingApproval(
pendingApproval.id,
ethErrors.provider.userRejectedRequest().serialize(),
),
networkDisplay: true,
};
}
4. Define Alerts
If any alerts are required in the confirmation, define the getAlerts function in the template file.
This needs to return an array of any required alerts, based on the current pending approval.
Each alert is an object with the following properties:
| Name | Description | Example Value |
|---|---|---|
| id | A unique string to identify the alert. | "MISMATCHED_NETWORK_RPC" |
| severity | The severity of the alert. Use the constants from the design system. |
SEVERITIES.DANGER |
| content | The component to be rendered inside the alert. Uses the same format as the content returned from getValues.The component can have nested components via the children property. |
See example below. |
Example
function getAlerts(_pendingApproval) {
return [
{
id: 'EXAMPLE_ALERT',
severity: SEVERITIES.WARNING,
content: {
element: 'span',
children: {
element: 'MetaMaskTranslation',
props: {
translationKey: 'exampleMessage',
},
},
},
},
];
}
5. Export Functions
Ensure the getValues and getAlerts functions are exported from the template file.
Example
const example = {
getAlerts,
getValues,
};
export default example;
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 Request Permissions.
Glossary
ApprovalController
The ApprovalController is a controller defined in the core repository which is responsible for creating and tracking approvals and confirmations in both the MetaMask extension and MetaMask mobile.
The pendingApprovals state used by the ApprovalController is not currently persisted, meaning any confirmations created by it will not persist after restarting the browser for example.
ConfirmationPage
The ConfirmationPage is a React component that aims to provide a generic confirmation window which can be configured using templates, each implementing a consistent interface.
This avoids the need for additional React components when creating confirmations, as additional templates with less logic, and less duplication, can be created instead.
Screenshots
Confirmation Window
