Plugin System

What is a plugin?

initLearnCard() gives you an object with methods like issueCredential, send, and read.get. None of those live in the core. Each comes from a plugin, and the core's only job is to load plugins in order and merge what they expose.

That matters to you in three ways:

• You only carry what you use. A server that just verifies credentials needs three plugins; a full network client needs a dozen. initLearnCard picks the right stack from the options you pass (seed, network, didWeb…), so you rarely assemble it by hand.

• Plugins can be swapped. Anything that implements the same interface can stand in — a different storage backend, a different DID method, a test double. Plugins that implement a control plane stack: three storage plugins all answer store.upload, and you pick which by name.

• You can add your own. A plugin is a plain object with a name and some methods; it can depend on the methods of plugins loaded before it. See Build a Plugin (GitHub) for a 10-minute walkthrough.

The rest of this page is how that works underneath.

Plugin Interface

A LearnCard plugin follows a standard interface structure which includes:

• name: A unique identifier string

• displayName: A human-readable name for UI display

• description: A description of the plugin's functionality

• methods: An object containing the functions provided by the plugin

The type system uses generics to track which plugins are added to a LearnCard instance, ensuring type safety when accessing plugin methods.

Adding Plugins

In order to create a fully functioning LearnCard, you will need to add some plugins. Specifically, you will (probably) want to add at least one plugin that implements each Control Plane.

To learn more about Control Planes, as well as find recommended Plugins for each Control Plane, click here!

In code, constructing a LearnCard completely from scratch looks like this:

Install @learncard/init, @learncard/didkit-plugin, and @learncard/didkey-plugin. Use a 32-byte (64-hex) seed; this example generates one if SECURE_SEED is unset.

import { randomBytes } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import { createRequire } from 'node:module';
import { initLearnCard } from '@learncard/init';
import { getDidKitPlugin } from '@learncard/didkit-plugin';
import { getDidKeyPlugin } from '@learncard/didkey-plugin';

const seed = process.env.SECURE_SEED ?? randomBytes(32).toString('hex');
const require = createRequire(import.meta.url);
const didkit = readFile(
    require.resolve('@learncard/didkit-plugin/dist/didkit/didkit_wasm_bg.wasm')
);
const baseLearnCard = await initLearnCard({ custom: true });
const didkitLearnCard = await baseLearnCard.addPlugin(await getDidKitPlugin(didkit));
const learnCard = await didkitLearnCard.addPlugin(
    await getDidKeyPlugin(didkitLearnCard, seed, 'key')
);
console.log(learnCard.id.did());

However, you don't have to start from scratch! Each instantiation function is completely able to add bespoke plugins to it:

import { initLearnCard } from '@learncard/init';

const HelloPlugin = {
    name: 'Hello',
    methods: {
        hello: () => 'world',
    },
};
const baseLearnCard = await initLearnCard({ custom: true });
const learnCard = await baseLearnCard.addPlugin(HelloPlugin);
console.log(learnCard.invoke.hello());

https://github.com/learningeconomy/LearnCard/blob/942bb5f7/packages/learn-card-core/src/types/LearnCard.ts#L1-L7

import { LearnCard, Plugin } from 'types/wallet';

export type GetPlugins<LC extends LearnCard<any, any, any>> = LC['plugins'];

export type AddPlugin<LC extends LearnCard<any, any, any>, P extends Plugin> = LearnCard<
    [...GetPlugins<LC>, P]
>;

Example: Expiration Plugin

Let's examine how the Expiration Plugin is implemented to understand a typical plugin structure:

The Expiration Plugin extends the credential verification process to check expiration dates:

1. It depends on the VC Plugin's verifyCredential method

2. It calls the original method to perform base verification

3. It adds additional checks for credential expiration

4. It returns an enhanced verification result

This demonstrates how plugins can build upon each other's functionality in a composable manner.

https://github.com/learningeconomy/LearnCard/blob/942bb5f7/packages/plugins/expiration/src/index.ts#L10-L33

export const expirationPlugin = (
    learnCard: LearnCard<any, any, VerifyExtension>
): ExpirationPlugin => ({
    name: 'Expiration',
    displayName: 'Expiration Extension',
    description: "Adds a check to make sure credentials aren't expired when verifying them",
    methods: {
        verifyCredential: async (_learnCard, credential, options) => {
            const verificationCheck = await learnCard.invoke.verifyCredential(credential, options);

            if (credential.expirationDate && new Date() > new Date(credential.expirationDate)) {
                verificationCheck.errors.push('expiration error: Credential is expired');
            } else if (credential.validFrom && new Date() < new Date(credential.validFrom)) {
                verificationCheck.errors.push('expiration error: Credential is not valid yet');
            } else if (credential.validUntil && new Date() > new Date(credential.validUntil)) {
                verificationCheck.errors.push('expiration error: Credential is no longer valid');
            } else {
                verificationCheck.checks.push('expiration');
            }

            return verificationCheck;
        },
    },
});

Interacting with Plugins

After initialization, applications interact with plugins through the LearnCard instance's invoke property. The method calls follow this pattern:

This unified interface allows applications to access all plugin functionality through a single entry point, abstracting away the details of which plugin provides which method.

Plugin Data Types

Plugins often work with specific data types, particularly for credential operations. The core types used across plugins include:

Type	Description
UnsignedVC	Unsigned Verifiable Credential data structure
VC	Signed Verifiable Credential with proof
UnsignedVP	Unsigned Verifiable Presentation
VP	Signed Verifiable Presentation with proof
Proof	Cryptographic proof structure
Profile	Entity profile information

These types are defined in the @learncard/types package and used consistently across all plugins to ensure interoperability.

https://github.com/learningeconomy/LearnCard/blob/942bb5f7/packages/learn-card-types/src/vc.ts#L129-L158

export const UnsignedVCValidator = z
    .object({
        '@context': ContextValidator,
        id: z.string().optional(),
        type: z.string().array().nonempty(),
        issuer: ProfileValidator,
        credentialSubject: CredentialSubjectValidator.or(CredentialSubjectValidator.array()),
        refreshService: RefreshServiceValidator.or(RefreshServiceValidator.array()).optional(),
        credentialSchema: CredentialSchemaValidator.or(
            CredentialSchemaValidator.array()
        ).optional(),

        // V1
        issuanceDate: z.string().optional(),
        expirationDate: z.string().optional(),
        credentialStatus: CredentialStatusValidator.or(
            CredentialStatusValidator.array()
        ).optional(),

        // V2
        name: z.string().optional(),
        description: z.string().optional(),
        validFrom: z.string().optional(),
        validUntil: z.string().optional(),
        status: CredentialStatusValidator.or(CredentialStatusValidator.array()).optional(),
        termsOfUse: TermsOfUseValidator.or(TermsOfUseValidator.array()).optional(),
        evidence: VC2EvidenceValidator.or(VC2EvidenceValidator.array()).optional(),
    })
    .catchall(z.any());
export type UnsignedVC = z.infer<typeof UnsignedVCValidator>;

https://github.com/learningeconomy/LearnCard/blob/942bb5f7/packages/learn-card-types/src/vc.ts#L174-L177

export const VCValidator = UnsignedVCValidator.extend({
    proof: ProofValidator.or(ProofValidator.array()),
});
export type VC = z.infer<typeof VCValidator>;

Graph of Plugins