@proto-kit/protocol 0.1.1-develop.191 → 0.1.1-develop.2024

package/src/settlement/messages/OutgoingMessageArgument.ts

@@ -0,0 +1,53 @@
+import { Bool, Field, FlexibleProvablePure, Provable, Struct } from "o1js";
+import {
+  LinkedMerkleTree,
+  LinkedMerkleTreeReadWitness,
+} from "@proto-kit/common";
+
+import { OutgoingMessage } from "./OutgoingMessage";
+
+// TODO Make that dynamic based on processors configured
+export const OUTGOING_MESSAGE_BATCH_SIZE = 1;
+
+export function createMessageStruct<T>(type: FlexibleProvablePure<T>) {
+  return class MessageStruct extends Struct({
+    value: type,
+    messageType: Field,
+  }) {} satisfies FlexibleProvablePure<OutgoingMessage<T>>;
+}
+
+export class OutgoingMessageArgument extends Struct({
+  witness: LinkedMerkleTreeReadWitness,
+  messageType: Field,
+}) {
+  public static dummy(): OutgoingMessageArgument {
+    return new OutgoingMessageArgument({
+      witness: LinkedMerkleTree.dummyReadWitness(),
+      messageType: Field(0),
+    });
+  }
+}
+
+export class OutgoingMessageArgumentBatch extends Struct({
+  arguments: Provable.Array(
+    OutgoingMessageArgument,
+    OUTGOING_MESSAGE_BATCH_SIZE
+  ),
+
+  isDummys: Provable.Array(Bool, OUTGOING_MESSAGE_BATCH_SIZE),
+}) {
+  public static fromMessages(providedArguments: OutgoingMessageArgument[]) {
+    const batch = providedArguments.slice();
+    const isDummys = batch.map(() => Bool(false));
+
+    while (batch.length < OUTGOING_MESSAGE_BATCH_SIZE) {
+      batch.push(OutgoingMessageArgument.dummy());
+      isDummys.push(Bool(true));
+    }
+
+    return new OutgoingMessageArgumentBatch({
+      arguments: batch,
+      isDummys,
+    });
+  }
+}

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/BlockProvable";
+import type { SettlementContractType } from "../contracts/settlement/SettlementBase";
+
+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: SettlementContractType,
+    inputs: SettlementHookInputs
+  ): Promise<void>;
+}

package/src/settlement/modularity/types.ts

@@ -0,0 +1,23 @@
+import { TypedClass } from "@proto-kit/common";
+import { SmartContract } from "o1js";
+
+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 & SmartContract
+      : 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 { SettlementContractType } from "../contracts/settlement/SettlementBase";
+
+type NetworkStateSettlementModuleConfig = {
+  blocksPerL1Block: UInt64;
+};
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+export class NetworkStateSettlementModule extends ProvableSettlementHook<NetworkStateSettlementModuleConfig> {
+  public async beforeSettlement(
+    smartContract: SettlementContractType,
+    {
+      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,190 @@
+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";
+import { WitnessBlockContext } from "./WitnessBlockContext";
+
+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 { isInWitnessBlock } = container.resolve(WitnessBlockContext);
+
+    // If we're inside a witness block, we only want to retrieve the state
+    // to use as a witness but not emit an ST
+    if (!isInWitnessBlock) {
+      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
+    );
+
+    const { isInWitnessBlock } = container.resolve(WitnessBlockContext);
+
+    if (isInWitnessBlock) {
+      throw new Error("Cannot set state inside of provable block.");
+    }
+
+    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/WitnessBlockContext.ts

@@ -0,0 +1,50 @@
+import { container, singleton } from "tsyringe";
+import { Provable } from "o1js";
+
+@singleton()
+export class WitnessBlockContext {
+  public witnessBlockDepth: number = 0;
+
+  public get isInWitnessBlock() {
+    return this.witnessBlockDepth > 0;
+  }
+}
+
+const asyncProxyWitnessFunction = <
+  Ret,
+  F extends (...args: any[]) => Promise<Ret>,
+>(
+  originalFuncDef: F
+) => {
+  return async (...args: Parameters<F>) => {
+    const context = container.resolve(WitnessBlockContext);
+    context.witnessBlockDepth += 1;
+    const ret = await originalFuncDef(...args);
+    context.witnessBlockDepth -= 1;
+    return ret;
+  };
+};
+
+const proxySyncWitnessFunction = <
+  Params extends any[],
+  Ret,
+  F extends (...args: Params) => Ret,
+>(
+  originalFuncDef: F
+) => {
+  return (...args: Params): Ret => {
+    const context = container.resolve(WitnessBlockContext);
+    context.witnessBlockDepth += 1;
+    const ret = originalFuncDef(...args);
+    context.witnessBlockDepth -= 1;
+    return ret;
+  };
+};
+
+Provable.witnessAsync = asyncProxyWitnessFunction(Provable.witnessAsync);
+
+Provable.witness = proxySyncWitnessFunction(Provable.witness);
+
+Provable.witnessFields = proxySyncWitnessFunction(Provable.witnessFields);
+
+Provable.asProver = proxySyncWitnessFunction(Provable.asProver);

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() && previousStatus.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);
+}