@proto-kit/protocol 0.1.1-develop.165 → 0.1.1-develop.1665

package/src/settlement/modularity/OutgoingMessageProcessor.ts

@@ -0,0 +1,65 @@
+import {
+  AccountUpdate,
+  Bool,
+  Field,
+  FlexibleProvablePure,
+  PublicKey,
+} from "o1js";
+import { implement, NoConfig } from "@proto-kit/common";
+
+import { ProtocolModule } from "../../protocol/ProtocolModule";
+
+export function outgoingMessageProcessor() {
+  return implement("OutgoingMessageProcessor");
+}
+
+export type MessageProcessorArgs = {
+  bridgeContract: {
+    publicKey: PublicKey;
+    tokenId: Field;
+  };
+};
+
+export abstract class OutgoingMessageProcessor<
+  T,
+  Config = NoConfig,
+> extends ProtocolModule<Config> {
+  private status: Bool = Bool(false);
+
+  private statusMessage?: string = undefined;
+
+  public assertTrue(b: Bool, msg?: string) {
+    this.status = this.status.and(b);
+    if (this.statusMessage === undefined) {
+      this.statusMessage = msg;
+    }
+  }
+
+  processMessage(
+    message: T,
+    args: MessageProcessorArgs
+  ): {
+    accountUpdates: AccountUpdate[];
+    status: Bool;
+    statusMessage?: string;
+  } {
+    this.status = Bool(true);
+    this.statusMessage = undefined;
+
+    const accountUpdates = this.process(message, args);
+
+    return {
+      accountUpdates,
+      status: this.status,
+      statusMessage: this.statusMessage,
+    };
+  }
+
+  abstract type: FlexibleProvablePure<T>;
+
+  abstract messageType: string;
+
+  abstract dummy(): T;
+
+  abstract process(message: T, args: MessageProcessorArgs): AccountUpdate[];
+}

package/src/settlement/modularity/ProvableSettlementHook.ts

@@ -0,0 +1,36 @@
+import { Field, PublicKey, UInt32 } from "o1js";
+import { InferProofBase } from "@proto-kit/common";
+
+import { ProtocolModule } from "../../protocol/ProtocolModule";
+import { NetworkState } from "../../model/network/NetworkState";
+import type { BlockProof } from "../../prover/block/BlockProver";
+import type { SettlementSmartContractBase } from "../contracts/SettlementSmartContract";
+
+export type InputBlockProof = InferProofBase<BlockProof>;
+
+export type SettlementStateRecord = {
+  sequencerKey: PublicKey;
+  lastSettlementL1BlockHeight: UInt32;
+
+  stateRoot: Field;
+  networkStateHash: Field;
+  blockHashRoot: Field;
+};
+
+export type SettlementHookInputs = {
+  blockProof: InputBlockProof;
+  fromNetworkState: NetworkState;
+  toNetworkState: NetworkState;
+  newPromisedMessagesHash: Field;
+  contractState: SettlementStateRecord;
+  currentL1BlockHeight: UInt32;
+};
+
+export abstract class ProvableSettlementHook<
+  Config,
+> extends ProtocolModule<Config> {
+  public abstract beforeSettlement(
+    smartContract: SettlementSmartContractBase,
+    inputs: SettlementHookInputs
+  ): Promise<void>;
+}

package/src/settlement/modularity/types.ts

@@ -0,0 +1,22 @@
+import { TypedClass } from "@proto-kit/common";
+
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "../ContractModule";
+import type { SettlementModulesRecord } from "../SettlementContractModule";
+
+export type InferContractType<
+  Module extends TypedClass<ContractModule<any, any>>,
+> =
+  Module extends TypedClass<infer ConcreteModule>
+    ? ConcreteModule extends ContractModule<infer Contract, any>
+      ? Contract
+      : never
+    : never;
+
+export type GetContracts<SettlementModules extends SettlementModulesRecord> = {
+  [Key in keyof SettlementModules]: SmartContractClassFromInterface<
+    InferContractType<SettlementModules[Key]>
+  >;
+};

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,177 @@
+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.toConstant().toBigInt() ===
+          path.toConstant().toBigInt() && 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,38 @@
+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()) {
+      const messageString =
+        message !== undefined && typeof message === "function"
+          ? message()
+          : message;
+
+      // If no isSimulated was set, we treat it as not simulated,
+      // therefore printing the log
+      if (!(executionContext.current().isSimulated ?? false)) {
+        log.debug("Assertion failed: ", messageString);
+      }
+      executionContext.setStatusMessage(messageString, new Error().stack);
+    }
+  });
+
+  executionContext.setStatus(status);
+}

package/src/state/context/RuntimeMethodExecutionContext.ts

@@ -0,0 +1,181 @@
+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;
+
+  private isSimulated: boolean = false;
+
+  // The inputs corresponding to the current result
+  private lastInputs:
+    | {
+        input: RuntimeMethodExecutionData | undefined;
+        isSimulated: boolean;
+      }
+    | undefined;
+
+  public override result = new RuntimeProvableMethodExecutionResult();
+
+  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<T>(
+    eventType: FlexibleProvablePure<T>,
+    event: T,
+    eventName: string,
+    condition: Bool = Bool(true)
+  ) {
+    this.assertSetupCalled();
+    this.result.events.push({
+      eventType,
+      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.lastInputs = {
+        input: this.input,
+        isSimulated: this.isSimulated,
+      };
+      // 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.lastInputs?.input,
+      isSimulated: this.lastInputs?.isSimulated,
+    };
+  }
+}