Skip to main content

Using the JSON-RPC API

This section describes how to call Masca RPC methods, without the usage of the Masca Connector SDK. You can find all of the types mentioned below in the @blockchain-lab-um/masca-types library.

VC Methods​

saveCredential​

Description​

saveCredential stores a VC in Masca. The VC can be saved in one or more supported stores.

Parameters​

  1. verifiableCredential - type W3CVerifiableCredential from @veramo/core
  2. options? - SaveCredentialRequestParams.
    1. store? - string or string[]. Defines where to store the VC.
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'saveCredential',
      params: {
        verifiableCredential,
      },
    },
  },
});

Returns​

SaveCredentialRequestResult[]

queryCredentials​

Description​

queryCredentials gets a list of VCs stored by the currently selected MetaMask account. Optional parameter params is an object with optional properties filter, and options.

filter defines what queryCredentials returns, and options defines where to search for data and what format to return it in.

QueryCredentialsRequestParams :

Currently, three different filter types are supported; none, id, and JSONPath. Type none will work as if no filter property was provided, id will search for matching ID of VC and JSONPath will use jsonpath to find matching VCs.

In the case of id, filter.filter is an id string.

In the case of JSONPath, filter.filter is a string containing JSONPath string.

NOTE

Query needs to start with @.data while filtering VC alone.

Example:

const jsonPath =
  '$[?(@.data.credentialSubject.achievement == "Certified Solidity Developer 2")]';

options define where to search for VCs. One or more supported stores can be provided. If returnStore is enabled, metadata of returned VCs will contain a string where they're stored

Parameters​

  1. filter? - QueryCredentialsRequestParams object.
  2. options? - QueryCredentialsOptions object.
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'queryCredentials',
      params: {
        filter: {
          type: 'id',
          filter: '0x123456789',
        },
        options: {
          store: 'snap',
          returnStore: true,
        },
      },
    },
  },
});

Returns​

QueryCredentialsRequestResult[]

deleteCredential​

Description​

deleteCredential deletes a VC from one or more stores, based on an ID obtained with queryCredentials method.

Parameters​

  1. id - id of a VC.
  2. options? - DeleteCredentialsOptions object.
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'deleteCredential',
      params: {
        id: '123',
        options: {
          store: 'snap',
        },
      },
    },
  },
});

Returns​

boolean[] - true, if VC deleted from store X, false if there was an error, or a VC was not found.

createCredential​

Description​

createCredential creates a VC from the payload. proofFormat can be selected, and the created VC can be optionally stored in the snap.

Methods did:pkh and did:ethr will return an unsigned credential! that needs to be signed manually on the dapp, as making signatures with Ethereum addresses is not possible in Masca. Here is an example of how we handle this in Connector.

Parameters​

  1. minimalUnsignedCredential - payload used to create a VC. Needs to contain at least type, credentialSubject, credentialSchema and @context.
  2. proofFormat - Can be jwt, json-ld or EthereumEIP712Signature.
  3. options? - CreateCredentialOptions object.

const payload: MinimalUnsignedCredential = {
  type: ['VerifiableCredential', 'TestCertificate'],
  credentialSubject: {
    accomplishmentType: 'Test Certificate',
    id: 'did:ethr:sepolia:0x123...321',
  },
  credentialSchema: {
    id: 'https://beta.api.schemas.serto.id/v1/public/program-completion-certificate/1.0/json-schema.json',
    type: 'JsonSchemaValidator2018',
  },
  '@context': [
    'https://www.w3.org/2018/credentials/v1',
    'https://beta.api.schemas.serto.id/v1/public/program-completion-certificate/1.0/ld-context.json',
  ],
};

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'createCredential'
      params: {
        minimalUnsignedCredential: payload,
        proofFormat: 'jwt',
        options: {
          save: 'true',
          store: ['snap'],
        },
    },
  },
  }
});

Returns​

VerifiableCredential

createPresentation​

Description​

createPresentation gets a VP for one or more passed VCs. params object is of type:

export type CreatePresentationRequestParams = {
  vcs: W3CVerifiableCredential[];
  proofFormat?: 'jwt' | 'lds' | 'EthereumEip712Signature2021';
  proofOptions?: {
    type?: string;
    domain?: string;
    challenge?: string;
  };
};

export type VCRequest = {
  id: string;
  metadata?: {
    store?: AvailableCredentialStores;
  };
};

vcs is of type W3CVerifiableCredential[].

proofFormat can be jwt, jsonld or EthereumEip712Signature2021.

options? defines domain, type, and challenge if needed.

holder of the VP will be a DID generated based on the currently selected MetaMask account AND the currently set DID Method.

Methods did:pkh and did:ethr will return an unsigned presentation! that needs to be signed manually on the dapp, as making signatures with Ethereum addresses is not possible in Masca. Here is an example of how we handle this in Connector.

Parameters​

  1. vcs - VCRequest[].
  2. proofFormat? - string, jwt by default
  3. proofOptions? - ProofOptions object
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'createPresentation',
      params: {
        vcs: [verifiableCredentialObject],
        proofFormat: 'jwt',
        options: {
          challenge: '123456789',
        },
      },
    },
  },
});

Returns​

VerifiablePresentation

verifyData​

Description​

verifyData verify a VC or a VP validity.

Parameters​

  1. presentation - W3CVerifiablePresentation object OR
  2. credential - W3CVerifiableCredential object
  3. verbose? - boolean that changes the return value of this method
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'verifyData',
      params: {
        credential: VC,
        verbose: true,
      },
    },
  },
});

Returns​

boolean - true if VC/VP is valid, false otherwise.

If verbose is set to true, it returns IVerifyResult instead, which also contains an Error message.

DID Methods​

getDID​

Description​

getDID generates and returns a DID based on the currently set MetaMask Account AND DID method.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'getDID',
    },
  },
});

getDIDMethod​

Description​

getDIDMethod returns the currently selected DID method.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'getDIDMethod',
    },
  },
});

switchDIDMethod​

Description​

switchDIDMethod switches the DID method.

Parameters​

  1. didMethod - name of the did method to switch to (did:ethr, did:key, or did:pkh etc.). Must be one of the methods returned by getAvailableMethods.
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'switchDIDMethod',
      params: {
        didMethod: 'did:ethr',
      },
    },
  },
});

Returns​

string - DID for the newly selected method.

getAvailableMethods​

Description​

getAvailableMethods returns a string[] list of supported DID methods.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'getAvailableMethods',
    },
  },
});

resolveDID​

Description​

resolveDID resolves a DID.

Parameters​

  1. did - DID string.
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'resolveDID',
      params: {
        did: 'did:ethr:0x01:0x123...321',
      },
    },
  },
});

Returns​

DIDResolutionResult, containing DID Document if successful.

VC Store Methods​

getCredentialStore​

Description​

getCredentialStore gets the selected VC Store plugin.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'getCredentialStore',
    },
  },
});

Returns​

A Record of CredentialStores[] and whether or not they're enabled. By default both snap & ceramic are enabled.

setCredentialStore​

Description​

setCredentialStore changes the selected VC Store plugin.

Parameters​

  1. store - name of the VC Store plugin ("snap" or "ceramic"). Must be one of methods returned by getAvailableCredentialStores.
  2. value - boolean. Enable/disable specific store plugins.
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'setCredentialStore',
      params: {
        store: 'ceramic',
        value: false,
      },
    },
  },
});

Returns​

boolean

getAvailableCredentialStores​

Description​

getAvailableCredentialStores gets a string[] list of supported VC Store plugins.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'getAvailableCredentialStores',
    },
  },
});

Returns​

strings[]

Snap Methods​

setCurrentAccount​

Description​

setCurrentAccount sets the account in Masca. This is required for Masca to work properly. Without appropriately calling this method, switching accounts in MetaMask will NOT result in switching accounts in Masca!

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'setCurrentAccount',
      params: {
        currentAccount: '0x123...321',
      },
    },
  },
});

Parameters​

  1. currentAccount - string of address of the account to set as current.

Returns​

boolean

NOTE

We recommend calling this method in window.ethereum.on('accountsChanged', handler: (accounts: Array<string>);. See Account Switching.

togglePopups​

Description​

togglePopups toggles popups that show up whenever the user tries to save a VC, generate a VP, etc. Popups are enabled by default to keep user in total control of their actions. With popups disabled, a dapp can query user's credentials, etc. without them knowing. We recommend using addTrustedDapp instead to only trust specific dapps.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'togglePopups',
    },
  },
});

changePermission​

Description​

changePermission is used to change enable/disable popups for a specific RPC method (only queryCredentials is supported for now). Dapps (other than masca.io) can only change permissions for themselves. Note that origin needs to be a hostname (masca.io) and not a full URL (https://masca.io)

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'changePermission',
      params: {
        origin: 'masca.io',
        method: 'queryCredentials',
        value: true, // This disables popups
      },
    },
  },
});

addTrustedDapp​

Description​

addTrustedDapp adds a dapp to the list of trusted dapps. Trusted dapps do not show popups. Dapps (other than masca.io) can only add themselves to the list of trusted dapps. Note that origin needs to be a hostname (masca.io) and not a full URL (https://masca.io)

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'addTrustedDapp',
      params: {
        origin: 'masca.io',
      },
    },
  },
});

removeTrustedDapp​

Description​

removeTrustedDapp removes a dapp from trusted dapps. Dapps (other than masca.io) can only remove themselves from the list of trusted dapps. Note that origin needs to be a hostname (masca.io) and not a full URL (https://masca.io)

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'removeTrustedDapp',
      params: {
        origin: 'masca.io',
      },
    },
  },
});

getAccountSettings​

Description​

getAccountSettings obtains the settings of the currently selected account.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'getAccountSettings',
    },
  },
});

Returns​

SSIAccountConfig

export type SSIAccountConfig = {
  ssi: {
    didMethod: AvailableMethods;
    vcStore: Record<AvailableCredentialStores, boolean>;
  };
};

getSnapSettings​

Description​

getSnapSettings obtains the settings of the snap.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'getSnapSettings',
    },
  },
});

Returns​

MascaConfig

export type MascaConfig = {
  snap: {
    infuraToken: string;
    acceptedTerms: boolean;
  };
  dApp: {
    disablePopups: boolean;
    trustedDapps: string[];
  };
};

setCeramicSession​

Description​

setCeramicSession sets the Ceramic session. As an Ethereum account handles storing and retrieving items from Ceramic, generating a session has to be done manually by a dapp. This is already handled in our Masca Connector. You can follow our implementation in the connector to implement this yourself.

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'setCeramicSession',
      params: {
        serializedSession: '...',
      },
    },
  },
});

Returns​

boolean

validateStoredCeramicSession​

Description​

validateStoredCeramicSession checks if there is an existing ceramic session set in Masca and if it's still valid. If this method returns false, the session must be set to use Ceramic!

const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'validateStoredCeramicSession',
    },
  },
});

Returns​

boolean

handleCredentialOffer​

Description​

handleCredentialOffer handles credential offers recieved from Polygon ID or OIDC issuers.

Parameters​

  1. credentialOffer - string (JSON string recieved from the issuer)
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'handleCredentialOffer',
      params: {
        credentialOffer: '...',
      },
    },
  },
});

Returns​

VerifiableCredential[]>

handleAuthorizationRequest​

Description​

handleAuthorizationRequest handles authorization requests recieved from Polygon ID or OIDC verifiers.

Parameters​

  1. authorizationRequest - string (JSON string recieved from the verifier)
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'handleAuthorizationRequest',
      params: {
        authorizationRequest: '...',
      },
    },
  },
});

signData​

Description​

signData is used to sign JWTs and JWZs

Parameters​

  1. type - JWT | JWZ
  2. data - JSON object based on selected type
const response = await ethereum.request({
  method: 'wallet_invokeSnap',
  params: {
    snapId: snapId,
    request: {
      method: 'handleAuthorizationRequest',
      params: {
        type: 'JWT',
        data: {...}
      },
    },
  },
});