Last update: January 26, 2024

MMI’s JSON-RPC provider¶

Terminology information

This document refers to the injected RPC provider also known as window.ethereum. This is the provider that is injected into the browser by Metamask. It does not refer to the JSON-RPC endpoint served by the custodian, or the JSON-RPC provider endpoint served by Ethereum nodes.

The browser ethereum provider is used by dapps to communicate with the extension, and is the primary way that dapps interact with the user’s wallet. The provider is a JavaScript object that is injected into the browser by the extension. The provider is accessible at window.ethereum in the browser. It is also used by custodians to communicate with the extension while the user is interacting with the custodian’s UI.

MMI provides several methods that are additional to the standard MetaMask provider API, for the purpose of managing the tokens stored in the extension.

In brief¶

Transaction link

Wherever MMI is installed, window.ethereum is present on every web page visited by the user
Use window.ethereum.request({ method , params }) to send JSON-RPC commands to the extension.
metamaskinstitutional_supported allows the custodian to check if MMI is installed (and not MetaMask)
metamaskinstitutional_authenticate is the command used by the custodian to begin importing accounts into MMI
metamaskinstitutional_reauthenticate is the command used by the custodian to replace an existing token
metamaskinstitutional_checkIfTokenIsPresent is a command used by the custodian to check if a token is already present in the extension
Before injecting the token, the API must detect whether MMI is installed, or just MetaMask.
The user must be prompted to install MMI if it is not already installed
If MetaMask is installed, the user must be prompted to disable MetaMask before installing MMI

metamaskinstitutional_supported : Detect whether the user has installed MMI¶

Important

Use a try-catch. An exception is thrown if MMI is not installed, this includes when ordinary MetaMask is present.

let mmiPresent = false;
try {
  let result = await window.ethereum.request({
    method: 'metamaskinstitutional_supported'
  })
  mmiPresent = !!result;
} catch (e) {
  // MMI is not present
}

metamaskinstitutional_authenticate : Inject the token¶

Several values here will depend on the your integration process.

token is the token that the user will be prompted to enter into the extension. This is the token that the user will use to authenticate with the custodian’s API.
apiUrl is the base URL of the custodian’s API. This does not include /v3/json-rpc or end in a trailing slash
environment is the name that we will provide to you which corresponds to your deployment. For example, custodianname-dev or custodianname-prod

 window.ethereum.request({
  'method': 'metamaskinstitutional_authenticate',
  'params': {
    'token': 'eyJoZWxsbyIgOiAid29ybGQifQo=',  // (Example value) The refresh token
    'apiUrl' : 'http://custodian-api', //  (Example value)  Custodian API URL, without trailing slash
    'feature': 'custodian',
    'service': 'ECA3', 
    'environment' : 'custodian-dev' //  (Example value)  This is the name of your environment - we will tell you what value to use here
  },
})

metamaskinstitutional_reauthenticate : Replace an existing token¶

As described in our authentication documentation, this can be used to replace existing tokens.

 window.ethereum.request({
  'method': 'metamaskinstitutional_reauthenticate',
  'params': {
    'token': 'eyJoZWxsbyIgOiAid29ybGQifQo=',  // (Example value) The refresh token
    'apiUrl' : 'http://custodian-api', //  (Example value)  Custodian API URL, without trailing slash
    'feature': 'custodian',
    'service': 'ECA3', 
    'environment' : 'custodian-dev' //  (Example value)  This is the name of your environment - we will tell you what value to use here
  },
})

metamaskinstitutional_checkIfTokenIsPresent : Check if a token is present¶

 window.ethereum.request({
  'method': 'metamaskinstitutional_checkIfTokenIsPresent',
  'params': {
    'token': 'eyJoZWxsbyIgOiAid29ybGQifQo=',  // (Example value) The refresh token
    'apiUrl' : 'http://custodian-api', //  (Example value)  Custodian API URL, without trailing slash
    'feature': 'custodian',
    'service': 'ECA3', 
    'environment' : 'custodian-dev' //  (Example value)  This is the name of your environment - we will tell you what value to use here
  },
})

The response will be a boolean indicating whether the token is present.

FAQ¶

How does the extension determine which token to replace during interactive token replacement?¶

The extension will use the replacement token to fetch a list of accounts from the custodian API (using custodian_listAccounts) and replace the token corresponding to the accounts in that list.