@proto-kit/module 0.1.1-develop.0

package/src/runtime/Runtime.ts

@@ -0,0 +1,395 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment,@typescript-eslint/no-unsafe-argument */
+import { ZkProgram } from "o1js";
+import { container, DependencyContainer, injectable } from "tsyringe";
+import {
+  StringKeyOf,
+  ModuleContainer,
+  ModulesConfig,
+  ModulesRecord,
+  TypedClass,
+  ZkProgrammable,
+  PlainZkProgram,
+  AreProofsEnabled,
+  ChildContainerProvider,
+  CompilableModule,
+  CompileRegistry,
+} from "@proto-kit/common";
+import {
+  MethodPublicOutput,
+  StateServiceProvider,
+  SimpleAsyncStateService,
+  RuntimeMethodExecutionContext,
+  RuntimeTransaction,
+  NetworkState,
+} from "@proto-kit/protocol";
+
+import {
+  combineMethodName,
+  isRuntimeMethod,
+  runtimeMethodTypeMetadataKey,
+  toWrappedMethod,
+  AsyncWrappedMethod,
+} from "../method/runtimeMethod";
+import { MethodIdFactory } from "../factories/MethodIdFactory";
+
+import { RuntimeModule } from "./RuntimeModule";
+import { MethodIdResolver } from "./MethodIdResolver";
+import { RuntimeEnvironment } from "./RuntimeEnvironment";
+
+export function getAllPropertyNames(obj: any) {
+  let currentPrototype: any | undefined = obj;
+  let keys: (string | symbol)[] = [];
+  // if primitive (primitives still have keys) skip the first iteration
+  if (!(obj instanceof Object)) {
+    currentPrototype = Object.getPrototypeOf(obj);
+  }
+  // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+  while (currentPrototype) {
+    keys = keys.concat(Reflect.ownKeys(currentPrototype));
+    currentPrototype = Object.getPrototypeOf(currentPrototype);
+  }
+  return keys;
+}
+
+/**
+ * Record of modules accepted by the Runtime module container.
+ *
+ * We have to use TypedClass since RuntimeModule
+ * is an abstract class
+ */
+export type RuntimeModulesRecord = ModulesRecord<
+  TypedClass<RuntimeModule<unknown>>
+>;
+
+const errors = {
+  methodNotFound: (methodKey: string) =>
+    new Error(`Unable to find method with id ${methodKey}`),
+};
+
+/**
+ * Definition / required arguments for the Runtime class
+ */
+export interface RuntimeDefinition<Modules extends RuntimeModulesRecord> {
+  modules: Modules;
+  config?: ModulesConfig<Modules>;
+}
+
+export class RuntimeZkProgrammable<
+  Modules extends RuntimeModulesRecord,
+> extends ZkProgrammable<undefined, MethodPublicOutput> {
+  public constructor(public runtime: Runtime<Modules>) {
+    super();
+  }
+
+  public get areProofsEnabled() {
+    return this.runtime.areProofsEnabled;
+  }
+
+  public zkProgramFactory(): PlainZkProgram<undefined, MethodPublicOutput>[] {
+    type Methods = Record<
+      string,
+      {
+        privateInputs: any;
+        method: AsyncWrappedMethod;
+      }
+    >;
+    // We need to use explicit type annotations here,
+    // therefore we can't use destructuring
+
+    // eslint-disable-next-line prefer-destructuring
+    const runtime: Runtime<Modules> = this.runtime;
+
+    const MAXIMUM_METHODS_PER_ZK_PROGRAM = 8;
+
+    const runtimeMethods = runtime.runtimeModuleNames.reduce<Methods>(
+      (allMethods, runtimeModuleName) => {
+        runtime.isValidModuleName(
+          runtime.definition.modules,
+          runtimeModuleName
+        );
+
+        /**
+         * Couldnt find a better way to circumvent the type assertion
+         * regarding resolving only known modules. We assert in the line above
+         * but we cast it to any anyways to satisfy the proof system.
+         */
+
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const runtimeModule = runtime.resolve(runtimeModuleName as any);
+
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const modulePrototype = Object.getPrototypeOf(runtimeModule) as Record<
+          string,
+          // Technically not all methods have to be async, but for this context it's ok
+          (...args: unknown[]) => Promise<unknown>
+        >;
+
+        const modulePrototypeMethods = getAllPropertyNames(runtimeModule).map(
+          (method) => method.toString()
+        );
+
+        const moduleMethods = modulePrototypeMethods.reduce<Methods>(
+          (allModuleMethods, methodName) => {
+            if (isRuntimeMethod(runtimeModule, methodName)) {
+              const combinedMethodName = combineMethodName(
+                runtimeModuleName,
+                methodName
+              );
+              const method = modulePrototype[methodName];
+              const invocationType = Reflect.getMetadata(
+                runtimeMethodTypeMetadataKey,
+                runtimeModule,
+                methodName
+              );
+
+              const wrappedMethod: AsyncWrappedMethod = Reflect.apply(
+                toWrappedMethod,
+                runtimeModule,
+                [methodName, method, { invocationType }]
+              );
+
+              const privateInputs = Reflect.getMetadata(
+                "design:paramtypes",
+                runtimeModule,
+                methodName
+              );
+
+              return {
+                ...allModuleMethods,
+
+                [combinedMethodName]: {
+                  privateInputs,
+                  method: wrappedMethod,
+                },
+              };
+            }
+
+            return allModuleMethods;
+          },
+          {}
+        );
+
+        return {
+          ...allMethods,
+          ...moduleMethods,
+        };
+      },
+      {}
+    );
+
+    const sortedRuntimeMethods = Object.fromEntries(
+      Object.entries(runtimeMethods).sort()
+    );
+
+    const splitRuntimeMethods = () => {
+      const buckets: Array<
+        Record<
+          string,
+          {
+            privateInputs: any;
+            method: AsyncWrappedMethod;
+          }
+        >
+      > = [];
+      Object.entries(sortedRuntimeMethods).forEach(
+        async ([methodName, method]) => {
+          let methodAdded = false;
+          for (const bucket of buckets) {
+            if (buckets.length === 0) {
+              const record: Record<
+                string,
+                {
+                  privateInputs: any;
+                  method: AsyncWrappedMethod;
+                }
+              > = {};
+              record[methodName] = method;
+              buckets.push(record);
+              methodAdded = true;
+              break;
+            } else if (
+              Object.keys(bucket).length <=
+              MAXIMUM_METHODS_PER_ZK_PROGRAM - 1
+            ) {
+              bucket[methodName] = method;
+              methodAdded = true;
+              break;
+            }
+          }
+          if (!methodAdded) {
+            const record: Record<
+              string,
+              {
+                privateInputs: any;
+                method: AsyncWrappedMethod;
+              }
+            > = {};
+            record[methodName] = method;
+            buckets.push(record);
+          }
+        }
+      );
+      return buckets;
+    };
+
+    return splitRuntimeMethods().map((bucket, index) => {
+      const name = `RuntimeProgram-${index}`;
+      const program = ZkProgram({
+        name,
+        publicOutput: MethodPublicOutput,
+        methods: bucket,
+      });
+
+      const SelfProof = ZkProgram.Proof(program);
+
+      const methods = Object.keys(bucket).reduce<Record<string, any>>(
+        (boundMethods, methodName) => {
+          boundMethods[methodName] = program[methodName].bind(program);
+          return boundMethods;
+        },
+        {}
+      );
+
+      return {
+        name,
+        compile: program.compile.bind(program),
+        verify: program.verify.bind(program),
+        analyzeMethods: program.analyzeMethods.bind(program),
+        Proof: SelfProof,
+        methods,
+      };
+    });
+  }
+}
+
+/**
+ * Wrapper for an application specific runtime, which helps orchestrate
+ * runtime modules into an interoperable runtime.
+ */
+@injectable()
+export class Runtime<Modules extends RuntimeModulesRecord>
+  extends ModuleContainer<Modules>
+  implements RuntimeEnvironment, CompilableModule
+{
+  public static from<Modules extends RuntimeModulesRecord>(
+    definition: RuntimeDefinition<Modules>
+  ): TypedClass<Runtime<Modules>> {
+    return class RuntimeScoped extends Runtime<Modules> {
+      public constructor() {
+        super(definition);
+      }
+    };
+  }
+
+  // runtime modules composed into a ZkProgram
+  public program?: ReturnType<typeof ZkProgram>;
+
+  public definition: RuntimeDefinition<Modules>;
+
+  public zkProgrammable: ZkProgrammable<undefined, MethodPublicOutput>;
+
+  /**
+   * Creates a new Runtime from the provided config
+   *
+   * @param modules - Configuration object for the constructed Runtime
+   */
+  public constructor(definition: RuntimeDefinition<Modules>) {
+    super(definition);
+    this.definition = definition;
+    this.zkProgrammable = new RuntimeZkProgrammable<Modules>(this);
+  }
+
+  // TODO Remove after changing DFs to type-based approach
+  public create(childContainerProvider: ChildContainerProvider) {
+    super.create(childContainerProvider);
+
+    this.useDependencyFactory(this.container.resolve(MethodIdFactory));
+  }
+
+  public get areProofsEnabled(): AreProofsEnabled | undefined {
+    return this.container.resolve<AreProofsEnabled>("AreProofsEnabled");
+  }
+
+  public get stateServiceProvider(): StateServiceProvider {
+    return this.dependencyContainer.resolve<StateServiceProvider>(
+      "StateServiceProvider"
+    );
+  }
+
+  public get stateService(): SimpleAsyncStateService {
+    return this.stateServiceProvider.stateService;
+  }
+
+  public get methodIdResolver(): MethodIdResolver {
+    return this.container.resolve<MethodIdResolver>("MethodIdResolver");
+  }
+
+  /**
+   * @returns The dependency injection container of this runtime
+   */
+  public get dependencyContainer(): DependencyContainer {
+    return this.container;
+  }
+
+  /**
+   * @param methodId The encoded name of the method to call.
+   * Encoding: "stringToField(module.name) << 128 + stringToField(method-name)"
+   */
+  public getMethodById(
+    methodId: bigint
+  ): ((...args: unknown[]) => Promise<unknown>) | undefined {
+    const methodDescriptor =
+      this.methodIdResolver.getMethodNameFromId(methodId);
+
+    if (methodDescriptor === undefined) {
+      return undefined;
+    }
+    const [moduleName, methodName] = methodDescriptor;
+
+    this.assertIsValidModuleName(moduleName);
+    const module = this.resolve(moduleName);
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const method = (module as any)[methodName];
+    if (method === undefined) {
+      throw errors.methodNotFound(`${moduleName}.${methodName}`);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return (method as (...args: unknown[]) => Promise<unknown>).bind(module);
+  }
+
+  /**
+   * Add a name and other respective properties required by RuntimeModules,
+   * that come from the current Runtime
+   *
+   * @param moduleName - Name of the runtime module to decorate
+   * @param containedModule
+   */
+  public decorateModule(
+    moduleName: StringKeyOf<Modules>,
+    containedModule: InstanceType<Modules[StringKeyOf<Modules>]>
+  ) {
+    containedModule.name = moduleName;
+    containedModule.runtime = this;
+
+    super.decorateModule(moduleName, containedModule);
+  }
+
+  /**
+   * @returns A list of names of all the registered module names
+   */
+  public get runtimeModuleNames() {
+    return Object.keys(this.definition.modules);
+  }
+
+  public async compile(registry: CompileRegistry) {
+    const context = container.resolve(RuntimeMethodExecutionContext);
+    context.setup({
+      transaction: RuntimeTransaction.dummyTransaction(),
+      networkState: NetworkState.empty(),
+    });
+    return await this.zkProgrammable.compile(registry);
+  }
+}
+/* eslint-enable @typescript-eslint/no-unsafe-assignment,@typescript-eslint/no-unsafe-argument */

package/src/runtime/RuntimeEnvironment.ts

@@ -0,0 +1,16 @@
+import { AreProofsEnabled, WithZkProgrammable } from "@proto-kit/common";
+import {
+  MethodPublicOutput,
+  SimpleAsyncStateService,
+  StateServiceProvider,
+} from "@proto-kit/protocol";
+
+import { MethodIdResolver } from "./MethodIdResolver";
+
+export interface RuntimeEnvironment
+  extends WithZkProgrammable<undefined, MethodPublicOutput> {
+  get areProofsEnabled(): AreProofsEnabled | undefined;
+  get stateService(): SimpleAsyncStateService;
+  get stateServiceProvider(): StateServiceProvider;
+  get methodIdResolver(): MethodIdResolver;
+}

package/src/runtime/RuntimeModule.ts

@@ -0,0 +1,112 @@
+import { ConfigurableModule, NoConfig, Presets } from "@proto-kit/common";
+import { container, injectable } from "tsyringe";
+import {
+  NetworkState,
+  RuntimeTransaction,
+  RuntimeMethodExecutionContext,
+  RuntimeMethodExecutionData,
+  RuntimeMethodExecutionDataStruct,
+} from "@proto-kit/protocol";
+import { FlexibleProvablePure, Provable, Bool } from "o1js";
+
+import { runtimeMethodNamesMetadataKey } from "../method/runtimeMethod";
+
+import { RuntimeEnvironment } from "./RuntimeEnvironment";
+
+const errors = {
+  inputDataNotSet: () => new Error("Input data for runtime execution not set"),
+};
+
+type EventRecord = Record<string, FlexibleProvablePure<any>>;
+
+type InferProvable<T extends FlexibleProvablePure<any>> =
+  T extends Provable<infer U> ? U : never;
+
+export class RuntimeEvents<Events extends EventRecord> {
+  public constructor(private readonly events: Events) {}
+
+  public emitIf<Key extends keyof Events>(
+    condition: Bool,
+    eventName: Key,
+    event: InferProvable<Events[Key]>
+  ) {
+    if (this.events === undefined) {
+      throw new Error(
+        "'events' property not defined, make sure to define the event types on your runtimemodule"
+      );
+    }
+    const eventType: FlexibleProvablePure<any> = this.events[eventName];
+    if (typeof eventName !== "string") {
+      throw new Error("Only string");
+    }
+    return container
+      .resolve(RuntimeMethodExecutionContext)
+      .addEvent(eventType, event, eventName, condition);
+  }
+
+  public emit<Key extends keyof Events>(
+    eventName: Key,
+    event: InferProvable<Events[Key]>
+  ) {
+    this.emitIf(Bool(true), eventName, event);
+  }
+}
+
+/**
+ * Base class for runtime modules providing the necessary utilities.
+ */
+@injectable()
+export class RuntimeModule<
+  Config = NoConfig,
+> extends ConfigurableModule<Config> {
+  public static presets: Presets<unknown> = {};
+
+  /**
+   * Holds all method names that are callable throw transactions
+   */
+  public readonly runtimeMethodNames: string[] = [];
+
+  /**
+   * This property exists only to typecheck that the RuntimeModule
+   * was extended correctly in e.g. a decorator. We need at least
+   * one non-optional property in this class to make the typechecking work.
+   */
+  public isRuntimeModule = true;
+
+  public name?: string;
+
+  public runtime?: RuntimeEnvironment;
+
+  public events?: RuntimeEvents<any> = undefined;
+
+  public constructor() {
+    super();
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const methodNames: string[] | undefined = Reflect.getMetadata(
+      runtimeMethodNamesMetadataKey,
+      this
+    );
+    this.runtimeMethodNames = methodNames ?? [];
+  }
+
+  public getInputs(): RuntimeMethodExecutionData {
+    return Provable.witness(RuntimeMethodExecutionDataStruct, () => {
+      const { input } = container.resolve<RuntimeMethodExecutionContext>(
+        RuntimeMethodExecutionContext
+      );
+      if (input === undefined) {
+        throw errors.inputDataNotSet();
+      }
+
+      return input;
+    });
+  }
+
+  public get transaction(): RuntimeTransaction {
+    return this.getInputs().transaction;
+  }
+
+  public get network(): NetworkState {
+    return this.getInputs().networkState;
+  }
+}

package/src/state/InMemoryStateService.ts

@@ -0,0 +1,25 @@
+import { Field } from "o1js";
+import { SimpleAsyncStateService } from "@proto-kit/protocol";
+
+/**
+ * Naive implementation of an in-memory variant of the StateService interface
+ */
+export class InMemoryStateService implements SimpleAsyncStateService {
+  /**
+   * This mapping container null values if the specific entry has been deleted.
+   * This is used by the CachedState service to keep track of deletions
+   */
+  public values: Record<string, Field[] | null> = {};
+
+  public async get(key: Field): Promise<Field[] | undefined> {
+    return this.values[key.toString()] ?? undefined;
+  }
+
+  public async set(key: Field, value: Field[] | undefined) {
+    if (value === undefined) {
+      this.values[key.toString()] = null;
+    } else {
+      this.values[key.toString()] = value;
+    }
+  }
+}

package/src/state/decorator.ts

@@ -0,0 +1,61 @@
+import { Path, State } from "@proto-kit/protocol";
+
+import type { RuntimeModule } from "../runtime/RuntimeModule.js";
+
+const errors = {
+  missingName: (className: string) =>
+    new Error(
+      `Unable to provide a unique identifier for state, ${className} is missing a name. 
+      Did you forget to extend your runtime module with 'extends RuntimeModule'?`
+    ),
+
+  missingRuntime: (className: string) =>
+    new Error(
+      `Unable to provide 'runtime' for state, ${className} is missing a name. 
+      Did you forget to extend your runtime module with 'extends RuntimeModule'?`
+    ),
+};
+
+/**
+ * Decorates a runtime module property as state, passing down some
+ * underlying values to improve developer experience.
+ */
+export function state() {
+  return <TargetRuntimeModule extends RuntimeModule<unknown>>(
+    target: TargetRuntimeModule,
+    propertyKey: string
+  ) => {
+    let value: State<unknown> | undefined;
+
+    Object.defineProperty(target, propertyKey, {
+      enumerable: true,
+
+      get: function get() {
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const self = this as TargetRuntimeModule;
+
+        if (self.name === undefined) {
+          throw errors.missingName(self.constructor.name);
+        }
+
+        if (!self.runtime) {
+          throw errors.missingRuntime(self.constructor.name);
+        }
+
+        const path = Path.fromProperty(self.name, propertyKey);
+        if (value) {
+          value.path = path;
+
+          // TODO: why is this complaining about `any`?
+
+          value.stateServiceProvider = self.runtime.stateServiceProvider;
+        }
+        return value;
+      },
+
+      set: (newValue: State<unknown>) => {
+        value = newValue;
+      },
+    });
+  };
+}

package/test/Runtime.test.ts

@@ -0,0 +1,70 @@
+describe("noop", () => {
+  it("noop", () => {
+    expect(1).toBe(1);
+  });
+});
+
+// TODO disabled because of the reflect-metadata error in the CI
+// import "reflect-metadata";
+// import { container } from "tsyringe";
+// import {
+//   RuntimeMethodExecutionContext,
+//   RuntimeTransaction,
+//   NetworkState,
+// } from "@proto-kit/protocol";
+//
+// import { MethodIdResolver } from "../src";
+//
+// import { Balances } from "./modules/Balances";
+// import { createTestingRuntime } from "./TestingRuntime";
+//
+// describe.skip("runtime", () => {
+//   it("should encode methodnames correctly", () => {
+//     expect.assertions(2);
+//
+//     const { runtime } = createTestingRuntime(
+//       {
+//         Balances,
+//       },
+//       {
+//         Balances: {},
+//       }
+//     );
+//
+//     const balances = runtime.resolve("Balances");
+//
+//     expect(balances).toBeDefined();
+//
+//     console.log(Object.keys(balances));
+//     console.log(balances.getTotalSupply);
+//
+//     const moduleName = "Balances";
+//     const methodName = "getTotalSupply";
+//
+//     const methodId = runtime.dependencyContainer
+//       .resolve<MethodIdResolver>("MethodIdResolver")
+//       .getMethodId(moduleName, methodName);
+//     const method = runtime.getMethodById(methodId);
+//
+//     expect(method).toBeDefined();
+//   });
+//
+//   it("regression - check that analyzeMethods works on runtime", async () => {
+//     const { runtime } = createTestingRuntime(
+//       {
+//         Balances,
+//       },
+//       {
+//         Balances: {},
+//       }
+//     );
+//
+//     const context = container.resolve(RuntimeMethodExecutionContext);
+//     context.setup({
+//       transaction: RuntimeTransaction.dummyTransaction(),
+//       networkState: NetworkState.empty(),
+//     });
+//
+//     await runtime.zkProgrammable.zkProgram.analyzeMethods();
+//   });
+// });