Veramo React

Veramo React makes it easy to interact with multiple agents in React Applications.

Motivation

When using veramo in your front end React apps, you may need to manage the state of multiple remote and local agents. Veramo React makes it easy to manage agents without needing to write or maintain boilerplate code. It also enables making new features available to front-end stacks without developers needing to implement them manually.

When you add an agent configuration, it is persisted to local storage. A randomly generated ID is assigned to each agent.

Install and set up

yarn add @veramo-community/veramo-react

NOTE: Veramo React depends on the @next versions of @veramo

Installation includes @veramo/core@next and @veramo/remote-client@next. You will NOT need to add additional @veramo dependencies to your app if you are just working with remote agents.

The following sippet is a simplified extract from Veramo Agent Explorer that uses React Query ontop of Veramo React to manage the data layer including caching and global data syncing.

import React from 'react'
import { BrowserRouter, Route } from 'react-router-dom'
import { VeramoProvider } from '@veramo-community/veramo-react'
import { QueryClientProvider, QueryClient } from 'react-query'
import App from '../App'

const queryClient = new QueryClient()

export default () => (
  <QueryClientProvider client={queryClient}>
    <VeramoProvider>
      <BrowserRouter>
        <Route component={App} />
      </BrowserRouter>
    </VeramoProvider>
  </QueryClientProvider>
)

Create the local agent

Create an agent in your app and export it. You will need to install additional dependencies

yarn add @veramo/did-resolver@next ethr-did-resolver web-did-resolver

import { createAgent, IResolver } from '@veramo/core'

import { DIDResolverPlugin } from '@veramo/did-resolver'
import { getResolver as ethrDidResolver } from 'ethr-did-resolver'
import { getResolver as webDidResolver } from 'web-did-resolver'

// You will need to get a project ID from infura https://www.infura.io
const INFURA_PROJECT_ID = '<your PROJECT_ID here>'

export const agent = createAgent<IResolver>({
  plugins: [
    new DIDResolverPlugin({
      ...ethrDidResolver({ infuraProjectId: INFURA_PROJECT_ID }),
      ...webDidResolver(),
    }),
  ],
})

In the provider setup above, add the following to bootstrap the local agent. You can also call addAgent to add while your application is running.

import { agent } from '../veramo'
;<VeramoProvider agent={[agent]}>...</VeramoProvider>

useVeramo hook

The primary hook that provides the following API to your app. The below syntax uses React Query to fetch the data and uses the cache key of resolutionResult + agentID to identify the data to your app.

import { useVeramo } from '@veramo-community/veramo-react'
import { useQuery } from 'react-query'

export default () => {
  const { agent } = useVeramo<IResolver>()
  const { data } = useQuery(['resolutionResult', { agentId: agent?.context.id }], () =>
    agent?.resolveDid({ didUrl: 'did:web:community.veramo.io' })(),
  )

  return (
    <div>
      {data?.didDocument?.verificationMethod.map((key) => (
        <div>{JSON.stringify(key)}</div>
      ))}
    </div>
  )
}

If you are not using React Query you can just call agent?.resolveDid() and manage the data like any async data source.

API

agent

The current active agent object. Call agent methods as normal:

agent[METHOD]

agents

A list of all configured agents.

activeAgentId

The ID of the currently active agent.

setActiveAgentId

Set the current active agent by ID

addAgent

Add a local agent. Create a local agent as per example in Create local agent section.

import { agent } from '../veramo'
import { useVeramo } from '@veramo-community/veramo-react'

// Inside a function component

const { addAgent } = useVeramo()

const addLocalAgent = () => {
  addAgent(agent)
}

removeAgent

Remove an agent by ID.

addAgentConfig

Add a remote agent configuration.

import { useVeramo } from '@veramo-community/veramo-react'

// Inside a function component
const { addAgentConfig } = useVeramo()

const newAgentConfig = () => {
  addAgentConfig({
    context: { name: 'Agent Name', schema: schemaUrl },
    remoteAgents: [
      {
        url: agentUrl,
        enabledMethods: Object.keys(schema['x-methods']),
        token: apiKey,
      },
    ],
  })
}

updateAgentConfig

Update the configuration of an agent.

getAgentConfig

Get the current configuration for an agent.

getAgent

Get an agent by ID.