@proto-kit/protocol 0.1.1-develop.1086

package/src/settlement/modules/NetworkStateSettlementModule.ts

@@ -0,0 +1,42 @@
+import { UInt64 } from "o1js";
+
+import {
+  ProvableSettlementHook,
+  SettlementHookInputs,
+} from "../modularity/ProvableSettlementHook";
+import { SettlementSmartContract } from "../contracts/SettlementSmartContract";
+
+type NetworkStateSettlementModuleConfig = {
+  blocksPerL1Block: UInt64;
+};
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+export class NetworkStateSettlementModule extends ProvableSettlementHook<NetworkStateSettlementModuleConfig> {
+  public async beforeSettlement(
+    smartContract: SettlementSmartContract,
+    {
+      blockProof,
+      fromNetworkState,
+      toNetworkState,
+      contractState,
+      currentL1BlockHeight,
+    }: SettlementHookInputs
+  ) {
+    const { lastSettlementL1BlockHeight } = contractState;
+
+    const blocksPerL1Block = this.config.blocksPerL1Block.toConstant();
+
+    const numL1Blocks = currentL1BlockHeight.sub(lastSettlementL1BlockHeight);
+    const expectedHeightDiff = numL1Blocks.toUInt64().mul(blocksPerL1Block);
+
+    const actualHeightDiff = toNetworkState.block.height.sub(
+      fromNetworkState.block.height
+    );
+
+    const acceptableDerivation = numL1Blocks.mul(1).div(10);
+
+    // TODO Check within bounds efficiently
+  }
+}
+
+/* eslint-enable @typescript-eslint/no-unused-vars */

package/src/state/State.ts

@@ -0,0 +1,175 @@
+import { Mixin } from "ts-mixer";
+import { Bool, Field, Provable, type FlexibleProvablePure, Struct } from "o1js";
+import { container } from "tsyringe";
+import { dummyValue } from "@proto-kit/common";
+
+import { Path } from "../model/Path";
+import { Option } from "../model/Option";
+import { StateTransition } from "../model/StateTransition";
+
+import { StateServiceProvider } from "./StateServiceProvider";
+import { RuntimeMethodExecutionContext } from "./context/RuntimeMethodExecutionContext";
+
+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 WithStateServiceProvider {
+  public stateServiceProvider?: StateServiceProvider;
+
+  public hasStateServiceOrFail(): asserts this is {
+    stateServiceProvider: StateServiceProvider;
+  } {
+    if (!this.stateServiceProvider) {
+      throw new Error(
+        "Could not find 'stateServiceProvider', 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, WithStateServiceProvider) {
+  /**
+   * 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);
+  }
+
+  public constructor(public valueType: FlexibleProvablePure<Value>) {
+    super();
+  }
+
+  private stateType = class StateType extends Struct({
+    value: this.valueType,
+    isSome: Bool,
+  }) {};
+
+  /**
+   * Returns the state that is currently the current state tree
+   * value: The value-fields, or if not state was found, dummy values
+   * isSome: Whether the values where found in the state or not
+   * (Basically, whether the value-fields are dummy values or actual values
+   * @private
+   */
+  private async getState(): Promise<{ value: Value; isSome: Bool }> {
+    this.hasStateServiceOrFail();
+    this.hasPathOrFail();
+
+    const { path, stateServiceProvider, valueType } = this;
+
+    const { stateTransitions } = container
+      .resolve(RuntimeMethodExecutionContext)
+      .current().result;
+
+    // TODO Use Stateservice for this
+    // First try to find a match inside already created stateTransitions
+    let previousMutatingTransitions: StateTransition<any>[] = [];
+    previousMutatingTransitions = stateTransitions.filter((transition) =>
+      transition.path.equals(path).and(transition.to.isSome).toBoolean()
+    );
+    const pmtLength = previousMutatingTransitions.length;
+
+    let value =
+      pmtLength > 0
+        ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          (previousMutatingTransitions[pmtLength - 1].to.value as Value)
+        : undefined;
+
+    if (value !== undefined) {
+      return { value, isSome: Bool(true) };
+    }
+
+    // If the value is still undefined, look it up in the stateService
+    const fields = await stateServiceProvider.stateService.get(path);
+    if (fields) {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      value = valueType.fromFields(fields) as Value;
+    }
+
+    if (value !== undefined) {
+      return { value, isSome: Bool(true) };
+    }
+    return { value: dummyValue(valueType), isSome: Bool(false) };
+  }
+
+  /**
+   * 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 async witnessFromState() {
+    // get the value from storage, or return a dummy value instead
+    // also check if the value exists in the storage or not
+    const { value, isSome } = await Provable.witnessAsync(
+      this.stateType,
+      async () => await this.getState()
+    );
+
+    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 async get(): Promise<Option<Value>> {
+    const option = await this.witnessFromState();
+
+    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 async set(value: Value) {
+    // link the transition to the current state
+    const fromOption = await this.witnessFromState();
+    const toOption = Option.fromValue(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,73 @@
+import type { Field, FlexibleProvablePure } from "o1js";
+import { Mixin } from "ts-mixer";
+
+import { Path } from "../model/Path";
+import { Option } from "../model/Option";
+
+import { State, WithStateServiceProvider, WithPath } from "./State";
+
+/**
+ * Map-like wrapper for state
+ */
+export class StateMap<KeyType, ValueType> extends Mixin(
+  WithPath,
+  WithStateServiceProvider
+) {
+  /**
+   * 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>
+  ): StateMap<KeyType, 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 async get(key: KeyType): Promise<Option<ValueType>> {
+    const state = State.from(this.valueType);
+    this.hasPathOrFail();
+    this.hasStateServiceOrFail();
+
+    state.path = this.getPath(key);
+    state.stateServiceProvider = this.stateServiceProvider;
+    return await 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 async set(key: KeyType, value: ValueType): Promise<void> {
+    const state = State.from(this.valueType);
+    this.hasPathOrFail();
+    this.hasStateServiceOrFail();
+
+    state.path = Path.fromKey(this.path, this.keyType, key);
+    state.stateServiceProvider = this.stateServiceProvider;
+    return await state.set(value);
+  }
+}

package/src/state/StateService.ts

@@ -0,0 +1,6 @@
+import { Field } from "o1js";
+
+export interface SimpleAsyncStateService {
+  get: (key: Field) => Promise<Field[] | undefined>;
+  set: (key: Field, value: Field[] | undefined) => Promise<void>;
+}

package/src/state/StateServiceProvider.ts

@@ -0,0 +1,37 @@
+import { injectable } from "tsyringe";
+import { log } from "@proto-kit/common";
+
+import { SimpleAsyncStateService } from "./StateService";
+
+const errors = {
+  stateServiceNotSet: () =>
+    new Error(
+      "StateService has not been set yet. Be sure to either call your runtime or protocol function by creating them with an AppChain or by setting the stateService manually."
+    ),
+};
+
+@injectable()
+export class StateServiceProvider {
+  private readonly stateServiceStack: SimpleAsyncStateService[] = [];
+
+  public get stateService(): SimpleAsyncStateService {
+    if (this.stateServiceStack.length === 0) {
+      throw errors.stateServiceNotSet();
+    }
+
+    // Assertion here is ok, because we check that the array is not empty above
+    return this.stateServiceStack.at(-1)!;
+  }
+
+  public setCurrentStateService(service: SimpleAsyncStateService) {
+    this.stateServiceStack.push(service);
+  }
+
+  public popCurrentStateService() {
+    if (this.stateServiceStack.length === 0) {
+      log.trace("Trying to pop from empty state-service stack");
+      return;
+    }
+    this.stateServiceStack.pop();
+  }
+}

package/src/state/assert/assert.ts

@@ -0,0 +1,35 @@
+import { Bool, Provable } from "o1js";
+import { container } from "tsyringe";
+import { log } from "@proto-kit/common";
+
+import { RuntimeMethodExecutionContext } from "../context/RuntimeMethodExecutionContext";
+
+/**
+ * Maintains an execution status of the current runtime module method,
+ * while prioritizing one-time failures. The assertion won't change the
+ * execution status if it has previously failed at least once within the
+ * same method execution context.
+ *
+ * @param condition - Result of the assertion made about the execution status
+ * @param message - Optional message describing the prior status
+ */
+export function assert(condition: Bool, message?: string | (() => string)) {
+  const executionContext = container.resolve(RuntimeMethodExecutionContext);
+  const previousStatus = executionContext.current().result.status;
+  const status = condition.and(previousStatus);
+
+  Provable.asProver(() => {
+    if (!condition.toBoolean()) {
+      if (!executionContext.current().isSimulated) {
+        log.debug("Assertion failed: ", message);
+      }
+      const messageString =
+        message !== undefined && typeof message === "function"
+          ? message()
+          : message;
+      executionContext.setStatusMessage(messageString, new Error().stack);
+    }
+  });
+
+  executionContext.setStatus(status);
+}

package/src/state/context/RuntimeMethodExecutionContext.ts

@@ -0,0 +1,174 @@
+import { Bool, FlexibleProvablePure, Provable, Struct } from "o1js";
+import { singleton } from "tsyringe";
+import {
+  ProvableMethodExecutionContext,
+  ProvableMethodExecutionResult,
+} from "@proto-kit/common";
+
+import { StateTransition } from "../../model/StateTransition";
+import { RuntimeTransaction } from "../../model/transaction/RuntimeTransaction";
+import { NetworkState } from "../../model/network/NetworkState";
+
+const errors = {
+  setupNotCalled: () =>
+    new Error(
+      "Setup has not been called prior to executing a runtime method. Be sure to do that so that the Runtime is setup property for execution"
+    ),
+};
+
+export class RuntimeProvableMethodExecutionResult extends ProvableMethodExecutionResult {
+  public stateTransitions: StateTransition<any>[] = [];
+
+  public status: Bool = Bool(true);
+
+  public statusMessage?: string;
+
+  public stackTrace?: string;
+
+  public events: {
+    eventType: FlexibleProvablePure<any>;
+    event: any;
+    eventName: string;
+    condition: Bool;
+  }[] = [];
+}
+
+export interface RuntimeMethodExecutionData {
+  transaction: RuntimeTransaction;
+  networkState: NetworkState;
+}
+
+export class RuntimeMethodExecutionDataStruct
+  extends Struct({
+    transaction: RuntimeTransaction,
+    networkState: NetworkState,
+  })
+  implements RuntimeMethodExecutionData {}
+
+/**
+ * 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 RuntimeMethodExecutionContext extends ProvableMethodExecutionContext {
+  public methods: string[] = [];
+
+  public input: RuntimeMethodExecutionData | undefined;
+
+  // The input corresponding to the current result
+  private lastInput: RuntimeMethodExecutionData | undefined;
+
+  public override result = new RuntimeProvableMethodExecutionResult();
+
+  private isSimulated: boolean = false;
+
+  private assertSetupCalled(): asserts this is {
+    input: RuntimeMethodExecutionData;
+  } {
+    if (this.input === undefined) {
+      throw errors.setupNotCalled();
+    }
+  }
+
+  /**
+   * Adds an in-method generated state transition to the current context
+   * @param stateTransition - State transition to add to the context
+   */
+  public addStateTransition<Value>(stateTransition: StateTransition<Value>) {
+    this.assertSetupCalled();
+    this.result.stateTransitions.push(stateTransition);
+  }
+
+  public addEvent(
+    eventType: FlexibleProvablePure<any>,
+    event: any,
+    eventName: string,
+    condition: Bool = Bool(true)
+  ) {
+    this.assertSetupCalled();
+    this.result.events.push({
+      eventType,
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      event,
+      eventName,
+      condition,
+    });
+  }
+
+  /**
+   * @param message - Status message to acompany the current status
+   */
+  public setStatusMessage(message?: string, stackTrace?: string) {
+    this.assertSetupCalled();
+    if (this.isSimulated) {
+      return;
+    }
+    this.result.statusMessage ??= message;
+    this.result.stackTrace ??= stackTrace;
+  }
+
+  /**
+   * @param status - Execution status of the current method
+   */
+  public setStatus(status: Bool) {
+    this.assertSetupCalled();
+    if (this.isSimulated) {
+      return;
+    }
+    this.result.status = status;
+  }
+
+  /**
+   * @param input Input witness data required for a runtime execution
+   */
+  public setup(input: RuntimeMethodExecutionData) {
+    this.input = input;
+  }
+
+  public witnessInput(): RuntimeMethodExecutionDataStruct {
+    this.assertSetupCalled();
+    return Provable.witness(RuntimeMethodExecutionDataStruct, () => {
+      // TODO Is that right? Or this.current().input
+      const { transaction, networkState } = this.input!;
+      return new RuntimeMethodExecutionDataStruct({
+        networkState,
+        transaction,
+      });
+    });
+  }
+
+  public setSimulated(simulated: boolean) {
+    this.isSimulated = simulated;
+  }
+
+  /**
+   * Manually clears/resets the execution context
+   */
+  public clear() {
+    this.result = new RuntimeProvableMethodExecutionResult();
+  }
+
+  public afterMethod() {
+    super.afterMethod();
+    if (this.isFinished) {
+      this.lastInput = this.input;
+      // TODO: find out why input isnt set in TransactionFeeHook during assert
+      // this.input = undefined;
+      this.isSimulated = false;
+    }
+  }
+
+  /**
+   * Had to override current() otherwise it would not infer
+   * the type of result correctly (parent type would be reused)
+   */
+  public current() {
+    return {
+      isFinished: this.isFinished,
+      result: this.result,
+      input: this.lastInput,
+      isSimulated: this.isSimulated,
+    };
+  }
+}

package/src/state/context/TransitionMethodExecutionContext.ts

@@ -0,0 +1,26 @@
+import { StateTransition } from "../../model/StateTransition";
+
+export class TransitionMethodExecutionResult {
+  public stateTransitions: StateTransition<any>[] = [];
+}
+
+export interface TransitionMethodExecutionContext {
+  /**
+   * Adds an in-method generated state transition to the current context
+   * @param stateTransition - State transition to add to the context
+   */
+  addStateTransition: <Value>(stateTransition: StateTransition<Value>) => void;
+
+  /**
+   * Manually clears/resets the execution context
+   */
+  clear: () => void;
+
+  /**
+   * Had to override current() otherwise it would not infer
+   * the type of result correctly (parent type would be reused)
+   */
+  current: () => {
+    result: TransitionMethodExecutionResult;
+  };
+}

package/src/state/protocol/ProtocolState.ts

@@ -0,0 +1,61 @@
+import { State } from "../State";
+import { Path } from "../../model/Path";
+import { TransitioningProtocolModule } from "../../protocol/TransitioningProtocolModule";
+
+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 block module with 'extends ...Hook'?`
+    ),
+
+  missingProtocol: (className: string) =>
+    new Error(
+      `Unable to provide 'procotol' for state, ${className} is missing a name. 
+      Did you forget to extend your block module with 'extends ...Hook'?`
+    ),
+};
+
+/**
+ * Decorates a runtime module property as state, passing down some
+ * underlying values to improve developer experience.
+ */
+export function protocolState() {
+  return <
+    TargetTransitioningModule extends TransitioningProtocolModule<unknown>,
+  >(
+    target: TargetTransitioningModule,
+    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 TargetTransitioningModule;
+
+        if (self.name === undefined) {
+          throw errors.missingName(self.constructor.name);
+        }
+
+        if (!self.protocol) {
+          throw errors.missingProtocol(self.constructor.name);
+        }
+
+        // TODO Add Prefix?
+        const path = Path.fromProperty(self.name, propertyKey);
+        if (value) {
+          value.path = path;
+          value.stateServiceProvider = self.protocol.stateServiceProvider;
+        }
+        return value;
+      },
+
+      set: (newValue: State<unknown>) => {
+        value = newValue;
+      },
+    });
+  };
+}