Skip to content
Docs

Start typing to search the documentation.

ConfigStore

The config storage layer defines how verification configurations are persisted and retrieved on the backend. These configurations represent the same disclosure/verification rules that the frontend and smart contracts enforce. Keeping them consistent is critical.

This @selfxyz/core library exposes an interface (IConfigStorage) and two default implementations (DefaultConfigStore, InMemoryConfigStore).

IConfigStorage

export interface IConfigStorage {
    getConfig(id: string): Promise<VerificationConfig>
    setConfig(id: string, config: VerificationConfig): Promise<boolean>
    getActionId(userIdentifier: string, data: string): Promise<string>
}

Methods

  • getConfig(id)
    • Returns the VerificationConfig associated with a given id.
    • This id is typically the configId referenced by your contract/backend/frontend.
  • setConfig(id, config)
    • Stores a new verification config under the given id.
    • Returns true if an existing config was replaced, false if it was newly set.
  • getActionId(userIdentifier, data)
    • Computes or retrieves an action id based on user context data from the frontend.
    • This action id links user activity with a registered config and is later used by getConfig(id)

DefaultConfigStore

A simple implementation that always returns the same config regardless of id.

export class DefaultConfigStore implements IConfigStorage {
    constructor(private config: VerificationConfig) {}

    //other methods
}

Example

const defaultConfigStore = new DefaultConfigStore({
  minimumAge: 18,
  excludedCountries: ['US', 'CA'],
  ofac: true,
});

InMemoryConfigStore

A more flexible implementation that can hold multiple configs in memory.

export class InMemoryConfigStore implements IConfigStorage {
  private configs: Map<string, VerificationConfig> = new Map();
  private getActionIdFunc: IConfigStorage['getActionId'];

  constructor(getActionIdFunc: IConfigStorage['getActionId']) {
    this.getActionIdFunc = getActionIdFunc;
  }

  //other methods
}

Example

const inMemoryHandler = async (userIdentifier: string, userDefinedData: string) => {
  return userDefinedData === 'high_value' ? 'strict' : 'standard';
};

const inMemory = new InMemoryConfigStore(inMemoryHandler);
inMemory.setConfig('strict', {
  minimumAge: 18,
  excludedCountries: ['USA', 'CAN'],
  ofac: true,
});
inMemory.setConfig('standard', {
  minimumAge: 18,
  excludedCountries: ['USA', 'CAN'],
  ofac: true,
});

Use cases:

  • Backends that need to manage multiple verification configurations at once.
  • Scenarios where action ids must be computed dynamically per user.
  • Good for prototyping before connecting to a persistent store (DB, KV, etc.).

Custom Implementations

Here’s an example of a KVConfigStore that is used in the playground.

import {
  IConfigStorage,
  VerificationConfig,
} from "@selfxyz/core";
import { Redis } from "@upstash/redis";

export class KVConfigStore implements IConfigStorage {
  private redis: Redis;

  constructor(url: string, token: string) {
    this.redis = new Redis({
      url: url,
      token: token,
    });
  }

  async getActionId(userIdentifier: string, data: string): Promise<string> {
    return userIdentifier;
  }

  async setConfig(id: string, config: VerificationConfig): Promise<boolean> {
    await this.redis.set(id, JSON.stringify(config));
    return true;
  }

  async getConfig(id: string): Promise<VerificationConfig> {
    const config = (await this.redis.get(id)) as VerificationConfig;
    return config;
  }
}

Integration with Frontend

The userDefinedData parameter in the frontend’s SelfAppBuilder is passed to your getActionId method:

// Frontend
const selfApp = new SelfAppBuilder({
  // ... other config
  version: 2,
  userDefinedData: Buffer.from(JSON.stringify({
    action: "high_value_transaction",
    amount: 50000,
    merchant: "merchant_123"
  })).toString('hex'),
  // ...
}).build();

// Backend - getActionId receives this data
async getActionId(userIdentifier: string, userDefinedData: string): Promise<string> {
  const data = JSON.parse(Buffer.from(userDefinedData, 'hex').toString());

  if (data.action === 'high_value_transaction' && data.amount > 10000) {
    return 'strict_verification';
  }

  return 'standard_verification';
}

Summary

  • IConfigStorage defines a contract for working with verification configs.
  • The library ships with DefaultConfigStore (static) and InMemoryConfigStore (multi‑config, dynamic).
  • Backend verifiers (like SelfBackendVerifier) depend on IConfigStorage to fetch configs and action ids.
  • You can plug in your own storage backend by implementing the same interface.