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.
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.
this.someController = new SomeController({
messenger: this.controllerMessenger.getRestricted({
name: 'SomeController',
allowedActions: [
`${this.approvalController.name}:addRequest`,
`${this.approvalController.name}:acceptRequest`,
`${this.approvalController.name}:rejectRequest`,
],
}),
...
});
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 |
await this.messagingSystem.call(
'ApprovalController:addRequest',
{
id,
origin,
type,
requestData,
},
true,
);
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' } |
await this.messagingSystem.call(
'ApprovalController:updateRequestState',
{
id,
requestState: { counter },
},
);
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.
Add your imported file to the APPROVAL_TEMPLATES
constant in:
ui/pages/confirmation/templates/index.js
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 |
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,
};
}
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. |
function getAlerts(_pendingApproval) {
return [
{
id: 'EXAMPLE_ALERT',
severity: SEVERITIES.WARNING,
content: {
element: 'span',
children: {
element: 'MetaMaskTranslation',
props: {
translationKey: 'exampleMessage',
},
},
},
},
];
}
Ensure the getValues
and getAlerts
functions are exported from the template file.
const example = {
getAlerts,
getValues,
};
export default example;
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
.
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.
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.