@rarimo/rarime-connector

RariMe Connector

RariMe connector is used to install snap and exposes methods for calling snap on dApps and other applications.

Usage

Connector has an exposed function for installing the snap.

async function enableSnap(
  snapOrigin?: string,
  version?: string,
): Promise<MetamaskSnap>;

After snap installation, this function returns MetamaskSnap object that can be used to retrieve snap connector. An example of initializing snap and invoking snap connector is shown below.

// install snap and get connector
const snap = await enableSnap();
const connector = await snap.getConnector();

// invoke connector
const identity = await connector.createIdentity();

console.log(`Snap installed, identity created: ${identity}`);

For ease of use, the connector package also exposes this functions:

isMetamaskInstalled(): Promise<boolean>
isSnapInstalled(snapOrigin?: string, version?: string): Promise<boolean>

Connector Methods

Create an identity

To create an identity you need to call this method:

createIdentity(): Promise<string>

Returns DID.

Get identity

Returns DID in string and BigInt string formats. Throws error if the DID wasn't initialised yet.

const { identityIdString, identityIdBigIntString } =
  await connector.getIdentity();

or

const privateKeyHex = '0x...';

const { identityIdString, identityIdBigIntString } =
  await connector.getIdentity({
    privateKeyHex,
  });

Returns DID.

Export identity

To export your identity you need to call this method:

ExportIdentity(): Promise<string>

Show Your identity private key in metamask dialog.

Save Verifiable Credentials

To save Verifiable Credentials you need to call this method with params:

saveCredentials(params: SaveCredentialsRequestParams): Promise<W3CCredential[]>

type SaveCredentialsRequestParams = {
  body: {
    credentials: [
      {
        description: string;
        id: string;
      },
    ];
    url: string;
  };
  from: string;
  id: string;
  thid?: string;
  to: string;
  typ?: string;
  type: string;
};

Returns saved Verifiable Credentials

type W3CCredential = {
  id: string;
  '@context': string[];
  type: string[];
  expirationDate?: string;
  issuanceDate?: string;
  credentialSubject: { [key: string]: object | string | number };
  credentialStatus: CredentialStatus;
  issuer: string;
  credentialSchema: CredentialSchema;
  proof?: { [key: string]: any } | any[];
};

type CredentialStatus = {
  id: string;
  type: string;
  revocationNonce?: number;
  statusIssuer?: CredentialStatus;
};

type CredentialSchema = {
  id: string;
  type: string;
};

Create a proof

Make sure you are on the correct network before creating a proof! To create a proof you need to call this method with params:

createProof(params: CreateProofRequestParams): Promise<ZKPProofResponse>

type CreateProofRequestParams = {
  id?: number;
  accountAddress?: string; // Metamask user address for on-chain proofs
  circuitId:
    | 'credentialAtomicQueryMTPV2'
    | 'credentialAtomicQueryMTPV2OnChain'
    | 'credentialAtomicQuerySigV2'
    | 'credentialAtomicQuerySigV2OnChain';
  challenge?: string; // bigint string
  query: ProofQuery;
};

type ProofQuery = {
  allowedIssuers?: string[];
  credentialSubject?: { [key: string]: any };
  schema?: string;
  claimId?: string;
  credentialSubjectId?: string;
  context?: string;
  type?: string;
};

Returns ZKPProofResponse - zkpProof for off-chain and updateStateTx, statesMerkleData, ZKProof for on-chain

type ZKPProofResponse = {
  updateStateTx?: TransactionRequest; // ethers TransactionRequest
  zkpProof: ZKProof;
  statesMerkleData?: {
    issuerId: string;
    state: StateInfo;
    merkleProof: string[];
  };
};

type ZKProof = {
  proof: ProofData;
  pub_signals: string[];
};
type ProofData = {
  pi_a: string[];
  pi_b: string[][];
  pi_c: string[];
  protocol: string;
};
type StateInfo = {
  index: string;
  hash: string;
  createdAtTimestamp: string;
  lastUpdateOperationIndex: string;
};

Check state contract sync

checkStateContractSync(): Promise<boolean>

Returns true if the lightweight state contract on current chain doesn't need to be synced with the state contract on Rarimo chain.

Get Verifiable Credentials

• Only supported domains

getCredentials(): Promise<W3CCredential[]>

Returns all Verifiable Credentials saved inside the snap storage

type W3CCredential = {
  id: string;
  '@context': string[];
  type: string[];
  expirationDate?: string;
  issuanceDate?: string;
  credentialSubject: { [key: string]: object | string | number };
  credentialStatus: CredentialStatus;
  issuer: string;
  credentialSchema: CredentialSchema;
  proof?: { [key: string]: any } | any[];
};

type CredentialStatus = {
  id: string;
  type: string;
  revocationNonce?: number;
  statusIssuer?: CredentialStatus;
};

type CredentialSchema = {
  id: string;
  type: string;
};

Snap connector usage examples

Create a proof

const connector = await snap.getConnector();

const proof = connector.createProof({
  circuitId: 'credentialAtomicQueryMTPV2OnChain',
  accountAddress: '0x......',
  challenge: '1251760352881625298994789945427452069454957821390', // BigInt string
  query: {
    allowedIssuers: ['*'],
    credentialSubject: {
      isNatural: {
        $eq: 1,
      },
    },
    type: 'IdentityProviders',
  },
});

where:

• circuitId: type of proof
• accountAddress(optional): Metamask user address for on-chain proofs
• challenge(optional): text that will be signed
• query
  • allowedIssuers: types of issuers allowed
    • *: all types of Issuers are allowed
  • context: URL for getting the vocabulary for the credential
  • type: type of credentials allowed
  • credentialSubject: query request to a query circuit

Save Verifiable Credentials

const connector = await snap.getConnector();

const vc = connector.saveCredentials({
  body: {
    credentials: [
      {
        description: 'Natural Person',
        id: '86531650-023c-4c6c-a437-a82e137ead68',
      },
    ],
    url: 'http://127.0.0.1:8000/integrations/issuer/v1/public/claims/offers/callback',
  },
  from: 'did:iden3:tJnRoZ1KqUPbsfVGrk8io51iqoRc5dGhj5LLMHSrD',
  id: '026035f6-42f6-4a2d-b516-0b11d2674850',
  thid: '348b7198-7cb1-46f4-bc0a-98a358f65539',
  to: 'did:iden3:tTxif8ahrSqRWavS8Qatrp4ZEJvPdu3ELSMgqTEQN',
  typ: 'application/iden3comm-plain-json',
  type: 'https://iden3-communication.io/credentials/1.0/offer',
});

where:

• id: request identifier
• thid: ID of the message thread
• from: identifier of the person from whom the offer was received
• to: identifier of the person who received the offer
• typ: media type of the message. In our case, it is the type of the protocol of the packed message application/iden3comm-plain-json
• type: type of iden3comm protocol message
• body
  • credentials[0]
    • description: description of the schema
    • id: credential id
  • url: URL to which requested information is sent and response is received

Remove Verifiable Credentials

await connector.removeCredentials({
  ids: [
    'https://example.issuer.node.api.com/v1/credentials/86531650-023c-4c6c-a437-a82e137ead68',
  ],
});

where:

• ids: list of credential IDs to remove, e.g. W3CCredential.id

Send proof to custom verifier contract

const connector = await snap.getConnector();

const proofData = connector.createProof({
  circuitId: 'credentialAtomicQueryMTPV2OnChain',
  accountAddress: '0x......',
  query: {
    allowedIssuers: ['*'],
    credentialSubject: {
      isNatural: {
        $eq: 1,
      },
    },
    type: 'IdentityProviders',
  },
});

const provider = new providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

if (proofData.updateStateTx) {
  const updateStateTx = await signer.sendTransaction(proofData.updateStateTx);
  await updateStateTx.wait();
}

const contractInterface = DemoVerifier__factory.createInterface();

// Can be another data depending on your contract
const data = contractInterface.encodeFunctionData('proveIdentity', [
  {
    issuerId: proofData.statesMerkleData.issuerId,
    issuerState: proofData.statesMerkleData.state.hash,
    createdAtTimestamp: proofData.statesMerkleData.state.createdAtTimestamp,
    merkleProof: proofData.statesMerkleData.merkleProof.map(
      (el) => utils.arrayify(el), // utils from ethers
    ),
  },
  proofData.zkpProof.pub_signals.map((el) => BigInt(el)),
  [proofData.zkpProof.proof.pi_a[0], proofData.zkpProof.proof.pi_a[1]],
  [
    [proofData.zkpProof.proof.pi_b[0][1], proofData.zkpProof.proof.pi_b[0][0]],
    [proofData.zkpProof.proof.pi_b[1][1], proofData.zkpProof.proof.pi_b[1][0]],
  ],
  [proofData.zkpProof.proof.pi_c[0], proofData.zkpProof.proof.pi_c[1]],
]);

const verifyTx = await signer.sendTransaction({
  to: 'verifierContractAddress',
  data,
});

await verifyTx.wait();

Changelog

[2.1.1] - 2024-06-18

Fixed

• @rarimo/rarime-connector
• • request params: wallet_invokeSnap method should accept params only if it exists, passing undefined would cause an error at least in Metamask Flask version 11.16.10-flask.0 and Metamask version 11.16.11