Veramo plugin template

This template repository provides a bare-bones structure for writing an agent plugin for Veramo and/or for providing your own implementations for key management and storage, or for DID storage.

Quick start

• Copy this repo
• Rename package in package.json
• yarn
• yarn generate-plugin-schema to re-generate a schema for your plugin
• yarn build or yarn watch
• yarn start or VSCode Debugger (CMD + Shift + D) > Run OpenAPI server

Structure of this template

1. A custom Veramo agent plugin

An agent plugin for Veramo is a class that provides some methods to be called on the agent object, and also emit and listen to agent events triggered by other plugins.

This repository has an example of such a class in ./src/agent-plugin/my-plugin.ts that implements the myPluginFoo() method and listens to validatedMessage events and emits my-event and my-other-event.

The schema and data types associated with this plugin are declared in ./src/types/IMyAgentPlugin.ts

Adding a declaration for this in package.json is necessary to programmatically regenerate the schema for this plugin:

{
  //...
  "veramo": {
    "pluginInterfaces": {
      "IMyAgentPlugin": "./src/types/IMyAgentPlugin.ts"
    }
  }
}

A plugin can declare multiple interfaces, and each interface can have multiple methods and events. The schema for the plugin is (re)generated by running yarn generate-plugin-schema.

2. Custom key management templates

This template contains some skeleton code for some customizations to the ways keys are managed by Veramo. You can change how and where keys are stored and how they are encrypted by the default Veramo plugins, and/or create your own AbstractKeyManagementSystem implementation from scratch.

3. Custom DID management templates

You can change how DIDs are stored by Veramo. You can implement support for other DID methods by overriding MyIdentifierProvider

4. Use your plugin with @veramo/cli

See ./agent.yml for an example Veramo CLI configuration that uses the plugin and customizations from this template alongside other Veramo plugins to create a fully functioning agent.

Testing your plugin

There are a number of ways to test your plugin.

Integration tests

This repository contains 2 sample test setups that run the same tests in different contexts.

• localAgent.test.ts creates an agent using agent.yml and runs the shared tests using that agent.
• restAgent.test.ts creates an agent using agent.yml and runs it as a remote agent. Then, it creates another agent that uses @veramo/remote-client to expose the methods of the remote agent locally, and runs the tests using the local agent.

Call your agent using the Veramo OpenAPI server

You can also run yarn veramo server in your terminal and then go to http://localhost:3335/api-docs to see all the available plugin methods. You can call them after you click Authorize and provide the API key defined in agent.yml. By default, it is test123.

Step by step debugging

This repository includes some Visual Studio Code launch configurations that can be used for step by step debugging.