@proto-kit/module 0.1.1-develop.153

package/src/state/State.ts

@@ -0,0 +1,154 @@
+/* eslint-disable new-cap */
+
+import { Mixin } from "ts-mixer";
+import { Bool, Field, Provable, type FlexibleProvablePure } from "snarkyjs";
+import { container } from "tsyringe";
+import { Option, StateTransition, type Path } from "@proto-kit/protocol";
+
+import { PartialRuntime } from "../runtime/RuntimeModule.js";
+import { RuntimeMethodExecutionContext } from "../method/RuntimeMethodExecutionContext.js";
+
+export class WithPath {
+  public path?: Field;
+
+  public hasPathOrFail(): asserts this is { path: Path } {
+    if (!this.path) {
+      throw new Error(
+        "Could not find 'path', did you forget to add '@state' to your state property?"
+      );
+    }
+  }
+}
+
+export class WithRuntime {
+  public runtime?: PartialRuntime;
+
+  public hasRuntimeOrFail(): asserts this is {
+    runtime: PartialRuntime;
+  } {
+    if (!this.runtime) {
+      throw new Error(
+        "Could not find 'runtime', did you forget to add '@state' to your state property?"
+      );
+    }
+  }
+}
+
+/**
+ * Utilities for runtime module state, such as get/set
+ */
+export class State<Value> extends Mixin(WithPath, WithRuntime) {
+  /**
+   * Creates a new state wrapper for the provided value type.
+   *
+   * @param valueType - Type of value to be stored (e.g. UInt64, Struct, ...)
+   * @returns New state for the given value type.
+   */
+  public static from<Value>(valueType: FlexibleProvablePure<Value>) {
+    return new State<Value>(valueType);
+  }
+
+  /**
+   * Computes a dummy value for the given value type.
+   *
+   * @param valueType - Value type to generate the dummy value for
+   * @returns Dummy value for the given value type
+   */
+  public static dummyValue<Value>(
+    valueType: FlexibleProvablePure<Value>
+  ): Value {
+    const length = valueType.sizeInFields();
+    const fields = Array.from({ length }, () => Field(0));
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return valueType.fromFields(fields) as Value;
+  }
+
+  public constructor(public valueType: FlexibleProvablePure<Value>) {
+    super();
+  }
+
+  /**
+   * Provides an in-circuit witness for the current state representation,
+   * and constructs an Option out of it.
+   *
+   * @returns Optional value of the current state
+   */
+  private witnessState() {
+    // get the value from storage, or return a dummy value instead
+    const value = Provable.witness(this.valueType, () => {
+      this.hasRuntimeOrFail();
+      this.hasPathOrFail();
+
+      const fields = this.runtime.stateService.get(this.path);
+      if (fields) {
+        // eslint-disable-next-line max-len
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        return this.valueType.fromFields(fields) as Value;
+      }
+
+      return State.dummyValue(this.valueType);
+    });
+
+    // check if the value exists in the storage or not
+    const isSome = Provable.witness(Bool, () => {
+      this.hasRuntimeOrFail();
+      this.hasPathOrFail();
+
+      const fields = this.runtime.stateService.get(this.path);
+
+      return Bool(fields !== undefined);
+    });
+
+    return Option.from(isSome, value, this.valueType);
+  }
+
+  /**
+   * Retrieves the current state and creates a state transition
+   * anchoring the use of the current state value in the circuit.
+   *
+   * @returns Option representation of the current state.
+   */
+  public get(): Option<Value> {
+    const option = this.witnessState();
+
+    this.hasPathOrFail();
+
+    const stateTransition = StateTransition.from(this.path, option);
+
+    container
+      .resolve(RuntimeMethodExecutionContext)
+      .addStateTransition(stateTransition);
+
+    return option;
+  }
+
+  /**
+   * Sets a new state value by creating a state transition from
+   * the current value to the newly set value.
+   *
+   * The newly set value isn't available via state.get(), since the
+   * state transitions are not applied within the same circuit.
+   * You can however store and access your new value in
+   * a separate circuit variable.
+   *
+   * @param value - Value to be set as the current state
+   */
+  public set(value: Value) {
+    // link the transition to the current state
+    const fromOption = this.witnessState();
+    const toOption = Option.from(Bool(true), value, this.valueType);
+
+    this.hasPathOrFail();
+
+    const stateTransition = StateTransition.fromTo(
+      this.path,
+      fromOption,
+      toOption
+    );
+
+    container
+      .resolve(RuntimeMethodExecutionContext)
+      .addStateTransition(stateTransition);
+  }
+}

package/src/state/StateMap.ts

@@ -0,0 +1,69 @@
+import type { Field, FlexibleProvablePure } from "snarkyjs";
+import { Path, type Option } from "@proto-kit/protocol";
+import { Mixin } from "ts-mixer";
+
+import { State, WithRuntime, WithPath } from "./State.js";
+
+/**
+ * Map-like wrapper for state
+ */
+// eslint-disable-next-line new-cap
+export class StateMap<KeyType, ValueType> extends Mixin(WithPath, WithRuntime) {
+  /**
+   * Create a new state map with the given key and value types
+   *
+   * @param keyType - Type to be used as a key
+   * @param valueType - Type to be stored as a value
+   * @returns State map with provided key and value types.
+   */
+  public static from<KeyType, ValueType>(
+    keyType: FlexibleProvablePure<KeyType>,
+    valueType: FlexibleProvablePure<ValueType>
+  ) {
+    return new StateMap<KeyType, ValueType>(keyType, valueType);
+  }
+
+  public constructor(
+    public keyType: FlexibleProvablePure<KeyType>,
+    public valueType: FlexibleProvablePure<ValueType>
+  ) {
+    super();
+  }
+
+  public getPath(key: KeyType): Field {
+    this.hasPathOrFail();
+    return Path.fromKey(this.path, this.keyType, key);
+  }
+
+  /**
+   * Obtains a value for the provided key in the current state map.
+   *
+   * @param key - Key to obtain the state for
+   * @returns Value for the provided key.
+   */
+  public get(key: KeyType): Option<ValueType> {
+    const state = State.from(this.valueType);
+    this.hasPathOrFail();
+    this.hasRuntimeOrFail();
+
+    state.path = this.getPath(key);
+    state.runtime = this.runtime;
+    return state.get();
+  }
+
+  /**
+   * Sets a value for the given key in the current state map.
+   *
+   * @param key - Key to store the value under
+   * @param value - Value to be stored under the given key
+   */
+  public set(key: KeyType, value: ValueType) {
+    const state = State.from(this.valueType);
+    this.hasPathOrFail();
+    this.hasRuntimeOrFail();
+
+    state.path = Path.fromKey(this.path, this.keyType, key);
+    state.runtime = this.runtime;
+    state.set(value);
+  }
+}

package/src/state/StateServiceProvider.ts

@@ -0,0 +1,24 @@
+import { inject, injectable } from "tsyringe";
+
+import { StateService } from "./InMemoryStateService";
+
+@injectable()
+export class StateServiceProvider {
+  private readonly defaultStateService: StateService = this.currentStateService;
+
+  public constructor(
+    @inject("StateService") private currentStateService: StateService
+  ) {}
+
+  public get stateService(): StateService {
+    return this.currentStateService;
+  }
+
+  public setCurrentStateService(service: StateService) {
+    this.currentStateService = service;
+  }
+
+  public resetToDefault() {
+    this.currentStateService = this.defaultStateService;
+  }
+}

package/src/state/decorator.ts

@@ -0,0 +1,65 @@
+import { Path } from "@proto-kit/protocol";
+
+import type { RuntimeModule } from "../runtime/RuntimeModule.js";
+
+import type { State } from "./State.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
+  ) => {
+    // eslint-disable-next-line @typescript-eslint/init-declarations
+    let value: State<unknown> | undefined;
+
+    Object.defineProperty(target, propertyKey, {
+      enumerable: true,
+
+      get: function get() {
+        // eslint-disable-next-line max-len
+        // 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;
+          // eslint-disable-next-line no-warning-comments
+          // TODO: why is this complaining about `any`?
+
+          value.runtime = self.runtime;
+        }
+        return value;
+      },
+
+      set: (newValue: State<unknown>) => {
+        value = newValue;
+      },
+    });
+  };
+}

package/test/Runtime.test.ts

@@ -0,0 +1,37 @@
+import { InMemoryStateService, Runtime } from "../src";
+import { Balances } from "./modules/Balances";
+import { Bool } from "snarkyjs";
+
+describe("runtime", () => {
+
+  it("should encode methodnames correctly", () => {
+    const runtime = Runtime.from({
+      state: new InMemoryStateService(),
+      modules: {
+        Balances: Balances
+      },
+      config: {
+        Balances: {
+          test: Bool(true)
+        }
+      }
+    })
+
+    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.getMethodId(moduleName, methodName);
+    const method = runtime.getMethodById(methodId)
+
+    // eslint-disable-next-line jest/no-restricted-matchers
+    expect(method).toBeDefined();
+
+  })
+
+})

package/test/modules/Admin.ts

@@ -0,0 +1,19 @@
+import { PublicKey } from "snarkyjs";
+
+import { runtimeModule } from "../../src/module/decorator.js";
+import { RuntimeModule } from "../../src/runtime/RuntimeModule.js";
+import { runtimeMethod } from "../../src/method/runtimeMethod.js";
+import { assert } from "../../src/method/assert.js";
+
+interface AdminConfig {
+  publicKey: string;
+}
+
+@runtimeModule()
+export class Admin extends RuntimeModule<AdminConfig> {
+  @runtimeMethod()
+  public isAdmin(publicKey: PublicKey) {
+    const admin = PublicKey.empty().toConstant();
+    assert(admin.equals(publicKey));
+  }
+}

package/test/modules/Balances.test.ts

@@ -0,0 +1,340 @@
+/* eslint-disable max-lines */
+import "reflect-metadata";
+import {
+  Bool,
+  Field,
+  Poseidon,
+  PrivateKey,
+  Proof,
+  PublicKey,
+  UInt64,
+} from "snarkyjs";
+import { container } from "tsyringe";
+import { type ProvableStateTransition, Path } from "@proto-kit/protocol";
+
+import {
+  InMemoryStateService,
+  StateService,
+} from "../../src/state/InMemoryStateService.js";
+import {
+  MethodPublicOutput,
+  Runtime,
+  RuntimeMethodExecutionContext,
+} from "../../src";
+
+import { Balances } from "./Balances.js";
+import { Admin } from "./Admin.js";
+
+describe("balances", () => {
+  let balances: Balances;
+
+  let state: StateService;
+
+  let runtime: Runtime<{
+    Admin: typeof Admin;
+    Balances: typeof Balances;
+  }>;
+
+  function getStateValue(path: Field | undefined) {
+    if (!path) {
+      throw new Error("Path not found");
+    }
+
+    const stateValue = state.get(path);
+
+    if (!stateValue) {
+      throw new Error("stateValue is undefined");
+    }
+
+    return stateValue;
+  }
+
+  function createChain() {
+    state = new InMemoryStateService();
+
+    runtime = Runtime.from({
+      state,
+
+      modules: {
+        Admin,
+        Balances,
+      },
+    });
+
+    runtime.appChain = {
+      areProofsEnabled: false,
+
+      setProofsEnabled(areProofsEnabled) {
+        this.areProofsEnabled = areProofsEnabled;
+      },
+    };
+
+    runtime.configure({
+      Admin: {
+        publicKey: PublicKey.empty().toBase58(),
+      },
+
+      Balances: {
+        test: Bool(true),
+      },
+    });
+
+    balances = runtime.resolve("Balances");
+
+    state.set(
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      balances.totalSupply.path!,
+      UInt64.from(10).toFields()
+    );
+  }
+
+  describe("compile and prove", () => {
+    beforeAll(createChain);
+
+    // Disabled until we implement a mechanism to enable/disable compiling tests
+    it("should compile and prove a method execution", async () => {
+      expect.assertions(3);
+
+      runtime.zkProgrammable.appChain?.setProofsEnabled(true);
+
+      const executionContext = container.resolve(RuntimeMethodExecutionContext);
+      const expectedStateTransitionsHash =
+        "1439144406936083177718146178121957896974210157062549589517697792374542035761";
+      const expectedStatus = true;
+
+      await runtime.zkProgrammable.zkProgram.compile();
+
+      balances.getTotalSupply();
+
+      const { result } = executionContext.current();
+
+      const proof = await result.prove<Proof<undefined, MethodPublicOutput>>();
+
+      const verified = await runtime.zkProgrammable.zkProgram.verify(proof);
+
+      runtime.zkProgrammable.appChain?.setProofsEnabled(false);
+
+      expect(verified).toBe(true);
+
+      expect(proof.publicOutput.stateTransitionsHash.toString()).toStrictEqual(
+        expectedStateTransitionsHash
+      );
+      expect(proof.publicOutput.status.toBoolean()).toBe(expectedStatus);
+    }, 180_000);
+  });
+
+  describe("getTotalSupply", () => {
+    beforeAll(createChain);
+
+    describe("state transitions", () => {
+      let stateTransitions: ProvableStateTransition[];
+
+      beforeEach(() => {
+        const executionContext = container.resolve(
+          RuntimeMethodExecutionContext
+        );
+        balances.getTotalSupply();
+
+        stateTransitions = executionContext
+          .current()
+          .result.stateTransitions.map((stateTransition) =>
+            stateTransition.toProvable()
+          );
+      });
+
+      it("should return a single state transition", () => {
+        expect.assertions(1);
+        expect(stateTransitions).toHaveLength(1);
+      });
+
+      it("should have a state transition for the correct path", () => {
+        expect.assertions(1);
+
+        const path = Path.fromProperty("Balances", "totalSupply");
+
+        expect(stateTransitions[0].path.toString()).toStrictEqual(
+          path.toString()
+        );
+      });
+
+      it("should produce a from-only state transition", () => {
+        expect.assertions(3);
+
+        const [stateTransition] = stateTransitions;
+
+        const value = UInt64.fromFields(
+          getStateValue(balances.totalSupply.path)
+        );
+        const treeValue = Poseidon.hash(value.toFields());
+
+        expect(stateTransition.from.isSome.toBoolean()).toBe(true);
+        expect(stateTransition.from.value.toString()).toBe(
+          treeValue.toString()
+        );
+        expect(stateTransition.to.isSome.toBoolean()).toBe(false);
+      });
+    });
+
+    describe("state transitions from empty state", () => {
+      let stateTransitions: ProvableStateTransition[];
+
+      beforeAll(() => {
+        createChain();
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        state.set(balances.totalSupply.path!, undefined);
+      });
+
+      beforeEach(() => {
+        const executionContext = container.resolve(
+          RuntimeMethodExecutionContext
+        );
+        balances.getTotalSupply();
+
+        stateTransitions = executionContext
+          .current()
+          .result.stateTransitions.map((stateTransition) =>
+            stateTransition.toProvable()
+          );
+      });
+
+      it("should return a single state transition", () => {
+        expect.assertions(1);
+        expect(stateTransitions).toHaveLength(1);
+      });
+
+      it("should have a state transition for the correct path", () => {
+        expect.assertions(1);
+
+        const path = Path.fromProperty("Balances", "totalSupply");
+
+        expect(stateTransitions[0].path.toString()).toStrictEqual(
+          path.toString()
+        );
+      });
+
+      it("should produce a from-only state transition", () => {
+        expect.assertions(3);
+
+        const [stateTransition] = stateTransitions;
+
+        const treeValue = Field(0);
+
+        expect(stateTransition.from.isSome.toBoolean()).toBe(true);
+        expect(stateTransition.from.value.toString()).toBe(
+          treeValue.toString()
+        );
+        expect(stateTransition.to.isSome.toBoolean()).toBe(false);
+      });
+    });
+  });
+
+  describe("setTotalSupply", () => {
+    beforeAll(createChain);
+
+    describe("state transitions", () => {
+      let stateTransitions: ProvableStateTransition[];
+
+      beforeEach(() => {
+        const executionContext = container.resolve(
+          RuntimeMethodExecutionContext
+        );
+        balances.setTotalSupply();
+
+        stateTransitions = executionContext
+          .current()
+          .result.stateTransitions.map((stateTransition) =>
+            stateTransition.toProvable()
+          );
+      });
+
+      it("should return a single state transition", () => {
+        expect.assertions(1);
+        expect(stateTransitions).toHaveLength(1);
+      });
+
+      it("should have a state transition for the correct path", () => {
+        expect.assertions(1);
+
+        const path = Path.fromProperty("Balances", "totalSupply");
+
+        expect(stateTransitions[0].path.toString()).toStrictEqual(
+          path.toString()
+        );
+      });
+
+      it("should produce a from-to state transition", () => {
+        expect.assertions(4);
+
+        const [stateTransition] = stateTransitions;
+        const fromValue = UInt64.fromFields(
+          getStateValue(balances.totalSupply.path)
+        );
+        const fromTreeValue = Poseidon.hash(fromValue.toFields());
+
+        const toValue = UInt64.from(20);
+        const toTreeValue = Poseidon.hash(toValue.toFields());
+
+        expect(stateTransition.from.isSome.toBoolean()).toBe(true);
+        expect(stateTransition.from.value.toString()).toBe(
+          fromTreeValue.toString()
+        );
+
+        expect(stateTransition.to.isSome.toBoolean()).toBe(true);
+        expect(stateTransition.to.value.toString()).toBe(
+          toTreeValue.toString()
+        );
+      });
+    });
+  });
+
+  describe("getBalance", () => {
+    beforeAll(createChain);
+
+    describe("state transitions", () => {
+      let stateTransitions: ProvableStateTransition[];
+      const address = PrivateKey.random().toPublicKey();
+
+      beforeEach(() => {
+        const executionContext = container.resolve(
+          RuntimeMethodExecutionContext
+        );
+        balances.getBalance(address);
+
+        stateTransitions = executionContext
+          .current()
+          .result.stateTransitions.map((stateTransition) =>
+            stateTransition.toProvable()
+          );
+      });
+
+      it("should return a single state transition", () => {
+        expect.assertions(1);
+        expect(stateTransitions).toHaveLength(1);
+      });
+
+      it("should have a state transition for the correct path", () => {
+        expect.assertions(1);
+
+        const path = Path.fromKey<PublicKey>(
+          Path.fromProperty("Balances", "balances"),
+          PublicKey,
+          address
+        );
+
+        expect(stateTransitions[0].path.toString()).toStrictEqual(
+          path.toString()
+        );
+      });
+
+      it("should produce a from-only state transition, for non-existing state", () => {
+        expect.assertions(3);
+
+        const [stateTransition] = stateTransitions;
+
+        expect(stateTransition.from.isSome.toBoolean()).toBe(true);
+        expect(stateTransition.from.value.toString()).toBe(Field(0).toString());
+        expect(stateTransition.to.isSome.toBoolean()).toBe(false);
+      });
+    });
+  });
+});