@proto-kit/common 0.1.1-develop.153

package/src/config/ConfigurableModule.ts

@@ -0,0 +1,44 @@
+const errors = {
+  configNotSet: (moduleName: string) =>
+    new Error(
+      `Trying to retrieve config of ${moduleName}, which was not yet set`
+    ),
+};
+
+// defines how presets can be provided, either a function or a record
+export type Preset<Config> = Config | ((...args: any[]) => Config);
+export type Presets<Config> = Record<string, Preset<Config>>;
+
+// describes the interface of a configurable module
+export interface Configurable<Config> {
+  config: Config;
+}
+
+/**
+ * Used by various module sub-types that may need to be configured
+ */
+export class ConfigurableModule<Config> implements Configurable<Config> {
+  /**
+   * Store the config separately, so that we can apply additional
+   * checks when retrieving it via the getter
+   */
+  protected currentConfig: Config | undefined;
+
+  // retrieve the existing config
+  public get config(): Config {
+    if (this.currentConfig === undefined) {
+      throw errors.configNotSet(this.constructor.name);
+    }
+    return this.currentConfig;
+  }
+
+  // set the config
+  public set config(config: Config) {
+    this.currentConfig = config;
+  }
+}
+
+// Helps ensure that the target class implements static presets
+export interface StaticConfigurableModule<Config> {
+  presets: Presets<Config>;
+}

package/src/config/ModuleContainer.ts

@@ -0,0 +1,265 @@
+import "reflect-metadata";
+
+import { container, Frequency, InjectionToken, Lifecycle } from "tsyringe";
+import log from "loglevel";
+
+import { StringKeyOf, TypedClass } from "../types";
+
+import { Configurable, ConfigurableModule } from "./ConfigurableModule";
+
+const errors = {
+  configNotSetInContainer: (moduleName: string) =>
+    new Error(
+      `Trying to get config of ${moduleName}, but it was not yet set in the module container`
+    ),
+
+  onlyValidModuleNames: (moduleName: NonNullable<unknown>) =>
+    new Error(
+      // eslint-disable-next-line max-len
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string,@typescript-eslint/restrict-template-expressions
+      `Only known module names are allowed, using unknown module name: ${moduleName}`
+    ),
+
+  unableToDecorateModule: (moduleName: InjectionToken<unknown>) =>
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    new Error(`Unable to decorate module ${moduleName.toString()}`),
+
+  nonModuleDependency: (runtimeModuleName: string) =>
+    new Error(`
+  Unable to register module: ${runtimeModuleName}, attempting to inject a non-module dependency`),
+
+  unknownDependency: (runtimeModuleName: string, name: string) =>
+    new Error(
+      `Unable to register module: ${runtimeModuleName}, 
+      attempting to inject a dependency that is not registered 
+      as a runtime module for this chain: ${name}`
+    ),
+};
+
+export const ModuleContainerErrors = errors;
+
+// determines that a module should be configurable by default
+export type BaseModuleType = TypedClass<Configurable<unknown>>;
+
+// allows to specify what kind of modules can be passed into a container
+export interface ModulesRecord<
+  // use the default configurable module type
+  ModuleType extends BaseModuleType = BaseModuleType
+> {
+  [name: string]: ModuleType;
+}
+
+// config record derived from the provided modules and their config types
+export type ModulesConfig<Modules extends ModulesRecord> = {
+  // this will translate into = key: module name, value: module.config
+  [ConfigKey in StringKeyOf<Modules>]: InstanceType<
+    Modules[ConfigKey]
+  > extends Configurable<infer Config>
+    ? Config
+    : never;
+};
+
+/**
+ * Parameters required when creating a module container instance
+ */
+export interface ModuleContainerDefinition<Modules extends ModulesRecord> {
+  modules: Modules;
+  // config is optional, as it may be provided by the parent/wrapper class
+  config?: ModulesConfig<Modules>;
+}
+
+/**
+ * Reusable module container facilitating registration, resolution
+ * configuration, decoration and validation of modules
+ */
+export class ModuleContainer<
+  Modules extends ModulesRecord
+> extends ConfigurableModule<unknown> {
+  /**
+   * Determines how often are modules decorated upon resolution
+   * from the tsyringe DI container
+   */
+  private static readonly moduleDecorationFrequency: Frequency = "Once";
+
+  // DI container holding all the registered modules
+  protected readonly container = container.createChildContainer();
+
+  public constructor(public definition: ModuleContainerDefinition<Modules>) {
+    super();
+    // register all provided modules when the container is created
+    this.registerModules(definition.modules);
+  }
+
+  /**
+   * @returns list of module names
+   */
+  public get moduleNames() {
+    return Object.keys(this.definition.modules);
+  }
+
+  /**
+   * Check if the provided module satisfies the container requirements,
+   * such as only injecting other known modules.
+   *
+   * @param moduleName
+   * @param containedModule
+   */
+  protected validateModule(
+    moduleName: StringKeyOf<Modules>,
+    containedModule: ConfigurableModule<unknown>
+  ): void {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const dependencies: { name?: string }[] | string[] | undefined =
+      Reflect.getMetadata("design:paramtypes", containedModule);
+
+    dependencies?.forEach((dependency: string | { name?: string }) => {
+      const name =
+        typeof dependency === "string" ? dependency : dependency.name;
+
+      if (name === undefined) {
+        throw errors.nonModuleDependency(moduleName);
+      }
+
+      if (!this.moduleNames.includes(name)) {
+        throw errors.unknownDependency(moduleName, name);
+      }
+    });
+  }
+
+  /**
+   * Assert that the iterated `moduleName` is of ModuleName type,
+   * otherwise it may be just string e.g. when modules are iterated over
+   * using e.g. a for loop.
+   */
+  public assertIsValidModuleName(
+    modules: Modules,
+    moduleName: string
+  ): asserts moduleName is StringKeyOf<Modules> {
+    this.isValidModuleName(modules, moduleName);
+  }
+
+  public isValidModuleName(
+    modules: Modules,
+    moduleName: number | string | symbol
+  ): asserts moduleName is StringKeyOf<Modules> {
+    if (!Object.prototype.hasOwnProperty.call(modules, moduleName)) {
+      throw errors.onlyValidModuleNames(moduleName);
+    }
+  }
+
+  /**
+   * Register modules into the current container, and registers
+   * a respective resolution hook in order to decorate the module
+   * upon/after resolution.
+   *
+   * @param modules
+   */
+  protected registerModules(modules: Modules) {
+    for (const moduleName in modules) {
+      if (Object.prototype.hasOwnProperty.call(modules, moduleName)) {
+        this.assertIsValidModuleName(modules, moduleName);
+
+        log.debug(`Registering module: ${moduleName}`);
+
+        this.container.register(
+          moduleName,
+          { useClass: modules[moduleName] },
+          { lifecycle: Lifecycle.ContainerScoped }
+        );
+        this.onAfterModuleResolution(moduleName);
+      }
+    }
+  }
+
+  /**
+   * Register a non-module value into the current container
+   * @param modules
+   */
+  // eslint-disable-next-line no-warning-comments
+  // TODO Rename to plural since object is param
+  public registerValue<Value>(modules: Record<string, Value>) {
+    Object.entries(modules).forEach(([moduleName, useValue]) => {
+      this.container.register(moduleName, { useValue });
+    });
+  }
+
+  /**
+   * Provide additional configuration after the ModuleContainer was created.
+   *
+   * Keep in mind that modules are only decorated once after they are resolved,
+   * therefore applying any configuration must happen
+   * before the first resolution.
+   * @param config
+   */
+  public configure(config: ModulesConfig<Modules>) {
+    this.definition.config = config;
+  }
+
+  /**
+   * Resolves a module from the current module container
+   *
+   * We have to narrow down the `ModuleName` type here to
+   * `ResolvableModuleName`, otherwise the resolved value might
+   * be any module instance, not the one specifically requested as argument.
+   *
+   * @param moduleName
+   * @returns
+   */
+  public resolve<ResolvableModuleName extends StringKeyOf<Modules>>(
+    moduleName: ResolvableModuleName
+  ): InstanceType<Modules[ResolvableModuleName]> {
+    return this.container.resolve<InstanceType<Modules[ResolvableModuleName]>>(
+      moduleName
+    );
+  }
+
+  public resolveOrFail<ModuleType>(
+    moduleName: string,
+    moduleType: TypedClass<ModuleType>
+  ) {
+    const instance = this.container.resolve<ModuleType>(moduleName);
+    const isValidModuleInstance = instance instanceof moduleType;
+
+    if (!isValidModuleInstance) {
+      throw new Error("Incompatible module instance");
+    }
+
+    return instance;
+  }
+
+  /**
+   * Override this in the child class to provide custom
+   * features or module checks
+   */
+  protected decorateModule(
+    moduleName: StringKeyOf<Modules>,
+    containedModule: InstanceType<Modules[StringKeyOf<Modules>]>
+  ) {
+    const config = this.definition.config?.[moduleName];
+
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    if (!config) {
+      throw errors.configNotSetInContainer(moduleName.toString());
+    }
+
+    containedModule.config = config;
+  }
+
+  /**
+   * Handle module resolution, e.g. by decorating resolved modules
+   * @param moduleName
+   */
+  protected onAfterModuleResolution(moduleName: StringKeyOf<Modules>) {
+    this.container.afterResolution<InstanceType<Modules[StringKeyOf<Modules>]>>(
+      moduleName,
+      (containedModuleName, containedModule) => {
+        // special case where tsyringe may return multiple known instances (?)
+        if (Array.isArray(containedModule)) {
+          throw errors.unableToDecorateModule(containedModuleName);
+        }
+        this.decorateModule(moduleName, containedModule);
+      },
+      { frequency: ModuleContainer.moduleDecorationFrequency }
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export * from "./config/ModuleContainer";
+export * from "./config/ConfigurableModule";
+export * from "./types";
+export * from "./zkProgrammable/ZkProgrammable";
+export * from "./zkProgrammable/ProvableMethodExecutionContext";
+export * from "./zkProgrammable/provableMethod";
+export * from "./utils";
+// eslint-disable-next-line import/no-unused-modules
+export { default as log } from "loglevel";

package/src/types.ts

@@ -0,0 +1,17 @@
+// allows to reference interfaces as 'classes' rather than instances
+export type TypedClass<Class> = new (...args: any[]) => Class;
+
+/**
+ * Using simple `keyof Target` would result into the key
+ * being `string | number | symbol`, but we want just a `string`
+ */
+export type StringKeyOf<Target extends object> = Extract<keyof Target, string> &
+  string;
+// export type StringKeyOf<Target extends object> = keyof Target
+
+/**
+ * Utility type to infer element type from an array type
+ */
+export type ArrayElement<ArrayType extends readonly unknown[]> =
+  // eslint-disable-next-line putout/putout
+  ArrayType extends readonly (infer ElementType)[] ? ElementType : never;

package/src/utils.ts

@@ -0,0 +1,10 @@
+export function requireTrue(
+  condition: boolean,
+  errorOrFunction: Error | (() => Error)
+): void {
+  if (!condition) {
+    throw typeof errorOrFunction === "function"
+      ? errorOrFunction()
+      : errorOrFunction;
+  }
+}

package/src/zkProgrammable/ProvableMethodExecutionContext.ts

@@ -0,0 +1,122 @@
+import type { FlexibleProvable, Proof } from "snarkyjs";
+import { singleton } from "tsyringe";
+import uniqueId from "lodash/uniqueId";
+
+const errors = {
+  moduleOrMethodNameNotSet: () => new Error("Module or method name not set"),
+
+  proverNotSet: (moduleName: string, methodName: string) =>
+    new Error(
+      `Prover not set for '${moduleName}.${methodName}', did you forget to decorate your method?`
+    ),
+};
+
+export class ProvableMethodExecutionResult {
+  public moduleName?: string;
+
+  public methodName?: string;
+
+  public args?: FlexibleProvable<unknown>[];
+
+  public prover?: () => Promise<Proof<unknown, unknown>>;
+
+  public async prove<
+    // eslint-disable-next-line etc/no-misused-generics
+    ProofType extends Proof<unknown, unknown>
+  >(): Promise<ProofType> {
+    if (!this.prover) {
+      // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+      if (!this.moduleName || !this.methodName) {
+        throw errors.moduleOrMethodNameNotSet();
+      }
+      throw errors.proverNotSet(this.moduleName, this.methodName);
+    }
+
+    // turn the prover result into the desired proof type
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return (await this.prover()) as ProofType;
+  }
+}
+
+/**
+ * Execution context used to wrap runtime module methods,
+ * allowing them to post relevant information (such as execution status)
+ * into the context without any unnecessary 'prop drilling'.
+ */
+@singleton()
+export class ProvableMethodExecutionContext {
+  public id = uniqueId();
+
+  public methods: string[] = [];
+
+  public result: ProvableMethodExecutionResult =
+    new ProvableMethodExecutionResult();
+
+  // eslint-disable-next-line no-warning-comments,max-len
+  // TODO See if we should make this class generic, bc I think we can persist the type
+  /**
+   * Adds a method prover to the current execution context,
+   * which can be collected and ran asynchronously at a later point in time.
+   *
+   * @param prove - Prover function to be ran later,
+   * when the method execution needs to be proven
+   */
+  public setProver(prover: () => Promise<Proof<unknown, unknown>>) {
+    this.result.prover = prover;
+  }
+
+  /**
+   * Adds a method to the method execution stack, reseting the execution context
+   * in a case a new top-level (non nested) method call is made.
+   *
+   * @param methodName - Name of the method being captured in the context
+   */
+  public beforeMethod(
+    moduleName: string,
+    methodName: string,
+    args: FlexibleProvable<unknown>[]
+  ) {
+    if (this.isFinished) {
+      this.clear();
+      this.result.moduleName = moduleName;
+      this.result.methodName = methodName;
+      this.result.args = args;
+    }
+
+    this.methods.push(methodName);
+  }
+
+  /**
+   * Removes the latest method from the execution context stack,
+   * keeping track of the amount of 'unfinished' methods. Allowing
+   * for the context to distinguish between top-level and nested method calls.
+   */
+  public afterMethod() {
+    this.methods.pop();
+  }
+
+  public get isTopLevel() {
+    return this.methods.length === 1;
+  }
+
+  public get isFinished() {
+    return this.methods.length === 0;
+  }
+
+  /**
+   * @returns - Current execution context state
+   */
+  public current() {
+    return {
+      isFinished: this.isFinished,
+      result: this.result,
+    };
+  }
+
+  /**
+   * Manually clears/resets the execution context
+   */
+  public clear() {
+    this.result = new ProvableMethodExecutionResult();
+  }
+}

package/src/zkProgrammable/ZkProgrammable.ts

@@ -0,0 +1,119 @@
+import { Experimental, FlexibleProvablePure, Proof } from "snarkyjs";
+import { Memoize } from "typescript-memoize";
+
+import { mockProof } from "./provableMethod";
+
+const errors = {
+  appChainNotSet: (name: string) =>
+    new Error(`Appchain was not injected for: ${name}`),
+};
+
+export interface CompileArtifact {
+  verificationKey: string;
+}
+
+export interface AreProofsEnabled {
+  areProofsEnabled: boolean;
+  setProofsEnabled: (areProofsEnabled: boolean) => void;
+}
+
+export interface Verify<PublicInput, PublicOutput> {
+  (proof: Proof<PublicInput, PublicOutput>): Promise<boolean>;
+}
+
+export interface Compile {
+  (): Promise<CompileArtifact>;
+}
+
+export interface PlainZkProgram<PublicInput = undefined, PublicOutput = void> {
+  compile: Compile;
+  verify: Verify<PublicInput, PublicOutput>;
+  Proof: ReturnType<
+    typeof Experimental.ZkProgram.Proof<
+      FlexibleProvablePure<PublicInput>,
+      FlexibleProvablePure<PublicOutput>
+    >
+  >;
+  methods: Record<
+    string,
+    | ((
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...args: any
+      ) => Promise<Proof<PublicInput, PublicOutput>>)
+    | ((
+        publicInput: PublicInput,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ...args: any
+      ) => Promise<Proof<PublicInput, PublicOutput>>)
+  >;
+}
+
+export function verifyToMockable<PublicInput, PublicOutput>(
+  verify: Verify<PublicInput, PublicOutput>,
+  { areProofsEnabled }: AreProofsEnabled
+) {
+  return async (proof: Proof<PublicInput, PublicOutput>) => {
+    if (areProofsEnabled) {
+      let verified = false;
+
+      try {
+        verified = await verify(proof);
+      } catch (error: unknown) {
+        // silently fail verification
+        console.error(error);
+        verified = false;
+      }
+
+      return verified;
+    }
+
+    return proof.proof === mockProof;
+  };
+}
+
+export const mockVerificationKey = "mock-verification-key";
+export function compileToMockable(
+  compile: Compile,
+  { areProofsEnabled }: AreProofsEnabled
+): () => Promise<CompileArtifact> {
+  return async () => {
+    if (areProofsEnabled) {
+      return await compile();
+    }
+
+    return {
+      verificationKey: mockVerificationKey,
+    };
+  };
+}
+
+export abstract class ZkProgrammable<
+  PublicInput = undefined,
+  PublicOutput = void
+> {
+  public abstract get appChain(): AreProofsEnabled | undefined;
+
+  public abstract zkProgramFactory(): PlainZkProgram<PublicInput, PublicOutput>;
+
+  @Memoize()
+  public get zkProgram(): PlainZkProgram<PublicInput, PublicOutput> {
+    const zkProgram = this.zkProgramFactory();
+
+    if (!this.appChain) {
+      throw errors.appChainNotSet(this.constructor.name);
+    }
+
+    return {
+      ...zkProgram,
+      verify: verifyToMockable(zkProgram.verify, this.appChain),
+      compile: compileToMockable(zkProgram.compile, this.appChain),
+    };
+  }
+}
+
+export interface WithZkProgrammable<
+  PublicInput = undefined,
+  PublicOutput = void
+> {
+  zkProgrammable: ZkProgrammable<PublicInput, PublicOutput>;
+}

package/src/zkProgrammable/provableMethod.ts

@@ -0,0 +1,109 @@
+import { FlexibleProvable } from "snarkyjs";
+import { container } from "tsyringe";
+
+import { ProvableMethodExecutionContext } from "./ProvableMethodExecutionContext";
+import type { ZkProgrammable } from "./ZkProgrammable";
+
+// eslint-disable-next-line etc/prefer-interface
+export type DecoratedMethod = (...args: unknown[]) => unknown;
+
+export const mockProof = "mock-proof";
+
+export function toProver(
+  methodName: string,
+  simulatedMethod: DecoratedMethod,
+  isFirstParameterPublicInput: boolean,
+  ...args: unknown[]
+) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return async function prover(this: ZkProgrammable<any, any>) {
+    const areProofsEnabled = this.appChain?.areProofsEnabled;
+    if (areProofsEnabled ?? false) {
+      const programProvableMethod = this.zkProgram.methods[methodName];
+      return await Reflect.apply(programProvableMethod, this, args);
+    }
+
+    // create a mock proof by simulating method execution in JS
+    const publicOutput = Reflect.apply(simulatedMethod, this, args);
+
+    return new this.zkProgram.Proof({
+      proof: mockProof,
+
+      // eslint-disable-next-line no-warning-comments
+      // TODO: provide undefined if public input is not used
+      publicInput: isFirstParameterPublicInput ? args[0] : undefined,
+      publicOutput,
+
+      /**
+       * We set this to the max possible number, to avoid having
+       * to manually count in-circuit proof verifications
+       */
+      maxProofsVerified: 2,
+    });
+  };
+}
+
+/**
+ * Decorates a provable method on a 'prover class', depending on
+ * if proofs are enabled or not, either runs the respective zkProgram prover,
+ * or simulates the method execution and issues a mock proof.
+ *
+ * @param isFirstParameterPublicInput
+ * @param executionContext
+ * @returns
+ */
+export function provableMethod(
+  isFirstParameterPublicInput = true,
+  executionContext: ProvableMethodExecutionContext = container.resolve<ProvableMethodExecutionContext>(
+    ProvableMethodExecutionContext
+  )
+) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return <Target extends ZkProgrammable<any, any>>(
+    target: Target,
+    methodName: string,
+    descriptor: PropertyDescriptor
+  ) => {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const simulatedMethod = descriptor.value as DecoratedMethod;
+
+    descriptor.value = function value(
+      this: ZkProgrammable<unknown, unknown>,
+      ...args: FlexibleProvable<unknown>[]
+    ) {
+      const prover = toProver(
+        methodName,
+        simulatedMethod,
+        isFirstParameterPublicInput,
+        ...args
+      );
+
+      executionContext.beforeMethod(this.constructor.name, methodName, args);
+
+      /**
+       * Check if the method is called at the top level,
+       * if yes then create a prover.
+       */
+      if (executionContext.isTopLevel) {
+        executionContext.setProver(prover.bind(this));
+      }
+
+      /**
+       * Regardless of if the method is called from the top level
+       * or not, execute its simulated (Javascript) version and
+       * return the result.
+       */
+      // eslint-disable-next-line @typescript-eslint/init-declarations
+      let result: unknown;
+      try {
+        result = Reflect.apply(simulatedMethod, this, args);
+      } finally {
+        executionContext.afterMethod();
+      }
+
+      return result;
+    };
+
+    return descriptor;
+  };
+}