@proto-kit/common 0.1.1-develop.0

package/src/dependencyFactory/injectOptional.ts

@@ -0,0 +1,41 @@
+import {
+  container,
+  injectable,
+  injectWithTransform,
+  Lifecycle,
+  scoped,
+} from "tsyringe";
+
+@injectable()
+@scoped(Lifecycle.ResolutionScoped)
+class UndefinedDisguise {}
+
+class UndefinedTransform<Dependency> {
+  public transform(
+    incoming: Dependency | UndefinedDisguise
+  ): Dependency | undefined {
+    if (incoming instanceof UndefinedDisguise) {
+      return undefined;
+    }
+    return incoming;
+  }
+}
+
+/**
+ * This function injects a dependency only if it has been registered, otherwise
+ * injects undefined. This can be useful for having optional dependencies, where
+ * tsyringe would normally error out and not be able to resolve. With this
+ * decorator, we can now do this.
+ *
+ * The strategy we employ here is that we inject a dummy into the global
+ * container that is of type UndefinedDisguise. We can't inject undefined
+ * directly, therefore we use this object to disguise itself as undefined.
+ * Then a child container registers something under the same token, it by
+ * default resolves that new dependency. If that doesn't happen, the
+ * resolution hits our disguise, which we then convert into undefined
+ * using the Transform
+ */
+export function injectOptional<T>(token: string) {
+  container.register(token, { useClass: UndefinedDisguise });
+  return injectWithTransform(token, UndefinedTransform<T>);
+}

package/src/dummyVerificationKey.ts

@@ -0,0 +1,10 @@
+import { Field, VerificationKey } from "o1js";
+
+export function dummyVerificationKey() {
+  return new VerificationKey({
+    hash: Field(
+      "3392518251768960475377392625298437850623664973002200885669375116181514017494"
+    ),
+    data: "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",
+  });
+}

package/src/events/EventEmitter.ts

@@ -0,0 +1,61 @@
+import { EventsRecord } from "./EventEmittingComponent";
+
+type ListenersHolder<Events extends EventsRecord> = {
+  [key in keyof Events]?: ((...args: Events[key]) => void)[];
+};
+
+export class EventEmitter<Events extends EventsRecord> {
+  protected readonly listeners: ListenersHolder<Events> = {};
+
+  protected readonly wildcardListeners: ((
+    event: keyof Events,
+    args: Events[keyof Events]
+  ) => void)[] = [];
+
+  public emit<Key extends keyof Events>(
+    event: Key,
+    ...parameters: Events[Key]
+  ) {
+    const listeners = this.listeners[event];
+    if (listeners !== undefined) {
+      listeners.forEach((listener) => {
+        listener(...parameters);
+      });
+    }
+    this.wildcardListeners.forEach((wildcardListener) => {
+      wildcardListener(event, parameters);
+    });
+  }
+
+  public onAll(listener: (event: keyof Events, args: unknown[]) => void): void {
+    this.wildcardListeners.push(listener);
+  }
+
+  public on<Key extends keyof Events>(
+    event: Key,
+    listener: (...args: Events[Key]) => void
+  ) {
+    (this.listeners[event] ??= []).push(listener);
+  }
+
+  /**
+   * Primitive .off() with identity comparison for now.
+   * Could be replaced by returning an id in .on() and using that.
+   */
+  public off<Key extends keyof Events>(
+    event: Key,
+    listener: (...args: Events[Key]) => void
+  ) {
+    const events = this.listeners[event];
+    if (events !== undefined) {
+      this.listeners[event] = events.filter(
+        (candidate) => candidate !== listener
+      );
+    }
+  }
+}
+
+export type EventListenable<Events extends EventsRecord> = Pick<
+  EventEmitter<Events>,
+  "on" | "onAll" | "off"
+>;

package/src/events/EventEmitterProxy.ts

@@ -0,0 +1,83 @@
+import type {
+  BaseModuleType,
+  ModuleContainer,
+  ModulesRecord,
+} from "../config/ModuleContainer";
+import { StringKeyOf, UnionToIntersection } from "../types";
+
+import { EventEmitter } from "./EventEmitter";
+import {
+  EventEmittingComponent,
+  EventEmittingContainer,
+  EventsRecord,
+} from "./EventEmittingComponent";
+
+export type CastToEventsRecord<Record> = Record extends EventsRecord
+  ? Record
+  : {};
+
+export type ModuleEvents<ModuleType extends BaseModuleType> =
+  InstanceType<ModuleType> extends EventEmittingComponent<infer Events>
+    ? Events
+    : InstanceType<ModuleType> extends ModuleContainer<infer NestedModules>
+      ? CastToEventsRecord<ContainerEvents<NestedModules>>
+      : // &
+        // (InstanceType<ModuleType> extends EventEmittingContainer<
+        //   infer ContainerEvents
+        // >
+        //   ? ContainerEvents
+        //   : {})
+        EventsRecord;
+
+export type ContainerEvents<Modules extends ModulesRecord> = {
+  [Key in StringKeyOf<Modules>]: ModuleEvents<Modules[Key]>;
+};
+
+export type FlattenObject<Target extends Record<string, EventsRecord>> =
+  UnionToIntersection<Target[keyof Target]>;
+
+export type FlattenedContainerEvents<Modules extends ModulesRecord> =
+  FlattenObject<ContainerEvents<Modules>>; // & FlattenObject<any>;
+
+export class EventEmitterProxy<
+  Modules extends ModulesRecord,
+> extends EventEmitter<CastToEventsRecord<FlattenedContainerEvents<Modules>>> {
+  public constructor(private readonly container: ModuleContainer<Modules>) {
+    super();
+    container.moduleNames.forEach((moduleName) => {
+      if (
+        container.isValidModuleName(container.definition.modules, moduleName)
+      ) {
+        const module = container.resolve(moduleName);
+        if (this.isEventEmitter(module)) {
+          module.events.onAll((events: any, args: any[]) => {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            this.emit(events, ...args);
+          });
+        }
+        if (this.isEventEmittingContainer(module)) {
+          module.containerEvents.onAll((events: any, args: any[]) => {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            this.emit(events, ...args);
+          });
+        }
+      }
+    });
+  }
+
+  private isEventEmittingContainer(
+    module: any
+  ): module is EventEmittingContainer<EventsRecord> {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const emitter = module.containerEvents;
+    return emitter !== undefined && emitter instanceof EventEmitter;
+  }
+
+  private isEventEmitter(
+    module: any
+  ): module is EventEmittingComponent<EventsRecord> {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const emitter = module.events;
+    return emitter !== undefined && emitter instanceof EventEmitter;
+  }
+}

package/src/events/EventEmittingComponent.ts

@@ -0,0 +1,11 @@
+import type { EventEmitter } from "./EventEmitter";
+
+export type EventsRecord = Record<string, unknown[]>;
+
+export interface EventEmittingComponent<Events extends EventsRecord> {
+  events: EventEmitter<Events>;
+}
+
+export interface EventEmittingContainer<Events extends EventsRecord> {
+  containerEvents: EventEmitter<Events>;
+}

package/src/events/ReplayingSingleUseEventEmitter.ts

@@ -0,0 +1,42 @@
+import { EventsRecord } from "./EventEmittingComponent";
+import { EventEmitter } from "./EventEmitter";
+
+/**
+ * Event Emitter variant that emits a certain event only once to a registered listener.
+ * Additionally, if a listener registers to a event that has already been emitted, it
+ * re-emits it to said listener.
+ * This pattern is especially useful for listening for inclusions of transactions.
+ * Those events will only occur once, and listeners could come too late to the party,
+ * so we need to make sure they get notified as well in those cases.
+ */
+export class ReplayingSingleUseEventEmitter<
+  Events extends EventsRecord,
+> extends EventEmitter<Events> {
+  public emitted: Partial<Events> = {};
+
+  public emit<Key extends keyof Events>(
+    event: Key,
+    ...parameters: Events[Key]
+  ) {
+    super.emit(event, ...parameters);
+    this.emitted[event] = parameters;
+    this.listeners[event] = [];
+  }
+
+  public onAll(listener: (event: keyof Events, args: unknown[]) => void) {
+    Object.entries(this.emitted).forEach(([key, params]) => {
+      if (params !== undefined) listener(key, params);
+    });
+    super.onAll(listener);
+  }
+
+  public on<Key extends keyof Events>(
+    event: Key,
+    listener: (...args: Events[Key]) => void
+  ) {
+    if (this.emitted[event] !== undefined) {
+      listener(...this.emitted[event]!);
+    }
+    super.on(event, listener);
+  }
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from "./config/ModuleContainer";
+export * from "./config/ConfigurableModule";
+export * from "./config/ChildContainerProvider";
+export * from "./config/ChildContainerCreatable";
+export * from "./types";
+export * from "./zkProgrammable/ZkProgrammable";
+export * from "./zkProgrammable/ProvableMethodExecutionContext";
+export * from "./zkProgrammable/provableMethod";
+export * from "./utils";
+export * from "./dependencyFactory/DependencyFactory";
+export * from "./dependencyFactory/injectOptional";
+export * from "./log";
+export * from "./events/EventEmittingComponent";
+export * from "./events/EventEmitter";
+export * from "./trees/MerkleTreeStore";
+export * from "./trees/InMemoryMerkleTreeStorage";
+export * from "./trees/RollupMerkleTree";
+export * from "./events/EventEmitterProxy";
+export * from "./events/ReplayingSingleUseEventEmitter";
+export * from "./trees/MockAsyncMerkleStore";
+export * from "./compiling/AtomicCompileHelper";
+export * from "./compiling/CompileRegistry";
+export * from "./compiling/CompilableModule";
+export * from "./compiling/services/ChildVerificationKeyService";
+export * from "./config/injectAlias";

package/src/log.ts

@@ -0,0 +1,143 @@
+import loglevel, { LogLevelDesc, LogLevelNames } from "loglevel";
+import { Provable } from "o1js";
+
+/* eslint-disable @typescript-eslint/no-unsafe-argument */
+function logProvable(
+  logFunction: (...args: unknown[]) => void,
+  ...args: any[]
+) {
+  Provable.asProver(() => {
+    const prettyArguments: string[] = [];
+
+    args.forEach((argument) => {
+      if (argument?.toPretty !== undefined) {
+        prettyArguments.push(argument.toPretty());
+      } else {
+        try {
+          prettyArguments.push(JSON.parse(JSON.stringify(argument)));
+        } catch {
+          prettyArguments.push(argument);
+        }
+      }
+    });
+    logFunction(...prettyArguments);
+  });
+}
+/* eslint-enable */
+
+// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+if (process.env?.IN_CI ?? false) {
+  loglevel.setLevel("ERROR");
+}
+
+const timeMap: Record<string, number> = {};
+
+function time(label = "time") {
+  timeMap[label] = Date.now();
+}
+
+function timeLog(label = "time"): string {
+  const prev = timeMap[label];
+  if (prev === undefined) {
+    return "Label not found";
+  }
+  return `${label} took ${Date.now() - prev}ms`;
+}
+
+function timeEnd(label = "time"): string {
+  const str = timeLog(label);
+  delete timeMap[label];
+  return str;
+}
+
+export const log = {
+  provable: {
+    info: (...args: unknown[]) => {
+      logProvable(loglevel.info, ...args);
+    },
+
+    debug: (...args: unknown[]) => {
+      logProvable(loglevel.debug, ...args);
+    },
+
+    error: (...args: unknown[]) => {
+      logProvable(loglevel.error, ...args);
+    },
+
+    trace: (...args: unknown[]) => {
+      logProvable(log.trace, ...args);
+    },
+
+    warn: (...args: unknown[]) => {
+      logProvable(loglevel.warn, ...args);
+    },
+  },
+
+  time,
+
+  timeLog: {
+    info: (label?: string) => loglevel.info(timeLog(label)),
+    debug: (label?: string) => loglevel.debug(timeLog(label)),
+    error: (label?: string) => loglevel.error(timeLog(label)),
+    trace: (label?: string) => loglevel.trace(timeLog(label)),
+    warn: (label?: string) => loglevel.warn(timeLog(label)),
+  },
+
+  timeEnd: {
+    info: (label?: string) => loglevel.info(timeEnd(label)),
+    debug: (label?: string) => loglevel.debug(timeEnd(label)),
+    error: (label?: string) => loglevel.error(timeEnd(label)),
+    trace: (label?: string) => loglevel.trace(timeEnd(label)),
+    warn: (label?: string) => loglevel.warn(timeEnd(label)),
+  },
+
+  info: (...args: unknown[]) => {
+    loglevel.info(...args);
+  },
+
+  debug: (...args: unknown[]) => {
+    loglevel.debug(...args);
+  },
+
+  error: (...args: unknown[]) => {
+    loglevel.error(...args);
+  },
+
+  trace: (...args: unknown[]) => {
+    // Loglevel prints the stack trace by default. To still be able to use trace
+    // inside out application, we use the level, but call debug() under the hood
+    if (loglevel.getLevel() <= loglevel.levels.TRACE) {
+      loglevel.debug(...args);
+    }
+  },
+
+  warn: (...args: unknown[]) => {
+    loglevel.warn(...args);
+  },
+
+  setLevel: (level: LogLevelDesc) => {
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    if (!(process.env?.IN_CI ?? false)) {
+      loglevel.setLevel(level);
+    }
+  },
+
+  get levels() {
+    return loglevel.levels;
+  },
+
+  getLevel: () => loglevel.getLevel(),
+};
+
+const validLogLevels = ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "SILENT"];
+
+export function assertValidTextLogLevel(
+  level: string | number
+): asserts level is LogLevelNames {
+  if (
+    typeof level === "number" ||
+    !validLogLevels.includes(level.toUpperCase())
+  ) {
+    throw new Error(`${level} is not a valid loglevel`);
+  }
+}

package/src/trees/InMemoryMerkleTreeStorage.ts

@@ -0,0 +1,17 @@
+import { MerkleTreeStore } from "./MerkleTreeStore";
+
+export class InMemoryMerkleTreeStorage implements MerkleTreeStore {
+  protected nodes: {
+    [key: number]: {
+      [key: string]: bigint;
+    };
+  } = {};
+
+  public getNode(key: bigint, level: number): bigint | undefined {
+    return this.nodes[level]?.[key.toString()];
+  }
+
+  public setNode(key: bigint, level: number, value: bigint): void {
+    (this.nodes[level] ??= {})[key.toString()] = value;
+  }
+}

package/src/trees/MerkleTreeStore.ts

@@ -0,0 +1,5 @@
+export interface MerkleTreeStore {
+  setNode: (key: bigint, level: number, value: bigint) => void;
+
+  getNode: (key: bigint, level: number) => bigint | undefined;
+}

package/src/trees/MockAsyncMerkleStore.ts

@@ -0,0 +1,30 @@
+import { noop } from "../utils";
+
+import { InMemoryMerkleTreeStorage } from "./InMemoryMerkleTreeStorage";
+
+export class MockAsyncMerkleTreeStore {
+  public readonly store = new InMemoryMerkleTreeStorage();
+
+  public commit(): void {
+    noop();
+  }
+
+  public openTransaction(): void {
+    noop();
+  }
+
+  public async getNodeAsync(
+    key: bigint,
+    level: number
+  ): Promise<bigint | undefined> {
+    return this.store.getNode(key, level);
+  }
+
+  public async setNodeAsync(
+    key: bigint,
+    level: number,
+    value: bigint
+  ): Promise<void> {
+    this.store.setNode(key, level, value);
+  }
+}