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

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,
+    };
+  }
+}

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,98 @@
+import { createReference, Reference } from "@proto-kit/common";
+
+import { WithPath, WithStateServiceProvider } from "../State";
+import { Path } from "../../model/Path";
+import { StateServiceProvider } from "../StateServiceProvider";
+import { PROTOKIT_PREFIXES } from "../../hashing/protokit-prefixes";
+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'?`
+    ),
+
+  missingParent: (className: string, type: string, moduleType: string) =>
+    new Error(
+      `Unable to provide parent '${type}' for state, ${className} is missing a name. 
+      Did you forget to extend your module with 'extends ${moduleType}'?`
+    ),
+};
+
+export interface StatefulModule {
+  name?: string;
+  parent?: {
+    stateServiceProvider: StateServiceProvider;
+  };
+}
+
+/**
+ * Decorates a runtime module property as state, passing down some
+ * underlying values to improve developer experience.
+ */
+export function state() {
+  return <TargetTransitioningModule extends StatefulModule>(
+    target: TargetTransitioningModule,
+    propertyKey: string
+  ) => {
+    Object.defineProperty(target, propertyKey, {
+      enumerable: true,
+
+      get: function get(this: TargetTransitioningModule) {
+        // The reason for why we store the state value in this weird way is that
+        // in the decorator on the prototype of the class. This means that if there
+        // are multiple instances of this class, any closure that this getter shares
+        // will be the same for all instances.
+        // Therefore, we need to somehow save the set instance on the instance itself
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const reference:
+          | Reference<WithPath & WithStateServiceProvider>
+          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+          | undefined = (this as any)[`protokit_state_cache_${propertyKey}`];
+
+        // Short-circuit this to return the state in case its already initialized
+        if (reference !== undefined && reference.value.path !== undefined) {
+          return reference.value;
+        }
+
+        if (this.name === undefined) {
+          throw errors.missingName(this.constructor.name);
+        }
+
+        const isProtocol = target instanceof TransitioningProtocolModule;
+
+        if (!this.parent) {
+          const debugInfo = isProtocol
+            ? { parentName: "protocol", baseModuleNames: "...Hook" }
+            : { parentName: "runtime", baseModuleNames: "RuntimeModule" };
+
+          throw errors.missingParent(
+            this.constructor.name,
+            debugInfo.parentName,
+            debugInfo.baseModuleNames
+          );
+        }
+
+        const statePrefix = isProtocol
+          ? PROTOKIT_PREFIXES.STATE_PROTOCOL
+          : PROTOKIT_PREFIXES.STATE_RUNTIME;
+        const path = Path.fromProperty(this.name, propertyKey, statePrefix);
+        if (reference) {
+          const { value } = reference;
+          value.path = path;
+          value.stateServiceProvider = this.parent.stateServiceProvider;
+        }
+        return reference?.value;
+      },
+
+      set: function set(
+        this: TargetTransitioningModule & any,
+        newValue: WithPath & WithStateServiceProvider
+      ) {
+        this[`protokit_state_cache_${propertyKey}`] = createReference(newValue);
+      },
+    });
+  };
+}

package/src/utils/FieldOptions.ts

@@ -0,0 +1,13 @@
+import { Bool, Field, Provable, Struct } from "o1js";
+
+export class FieldOption extends Struct({
+  isSome: Bool,
+  value: Field,
+}) {
+  public static from(isSome: Bool, potentialValue: Field) {
+    return {
+      isSome,
+      value: Provable.if(isSome, potentialValue, Field(0)),
+    };
+  }
+}

package/src/utils/MinaPrefixedProvableHashList.ts

@@ -0,0 +1,70 @@
+import { Field, Poseidon, ProvablePure } from "o1js";
+import { hashWithPrefix, prefixToField } from "@proto-kit/common";
+
+import { MINA_PREFIXES, MINA_SALTS } from "../hashing/mina-prefixes";
+
+import { ProvableHashList } from "./ProvableHashList";
+
+function salt(prefix: string) {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return Poseidon.update(
+    [Field(0), Field(0), Field(0)],
+    [prefixToField(prefix)]
+  ) as [Field, Field, Field];
+}
+
+export function emptyActions(): Field {
+  return salt(MINA_SALTS.empty_actions)[0];
+}
+
+export function emptyEvents(): Field {
+  return salt(MINA_SALTS.empty_events)[0];
+}
+
+export class MinaActions {
+  static actionHash(
+    action: Field[],
+    previousHash: Field = emptyActions()
+  ): Field {
+    const actionDataHash = hashWithPrefix(MINA_PREFIXES.event, action);
+    return hashWithPrefix(MINA_PREFIXES.sequenceEvents, [
+      previousHash,
+      actionDataHash,
+    ]);
+  }
+}
+
+export class MinaEvents {
+  static eventHash(event: Field[], previousHash: Field = emptyEvents()): Field {
+    const actionDataHash = hashWithPrefix(MINA_PREFIXES.event, event);
+    return hashWithPrefix(MINA_PREFIXES.events, [previousHash, actionDataHash]);
+  }
+}
+
+export class MinaPrefixedProvableHashList<
+  Value,
+> extends ProvableHashList<Value> {
+  public constructor(
+    valueType: ProvablePure<Value>,
+    public readonly prefix: string,
+    internalCommitment?: Field
+  ) {
+    super(valueType, internalCommitment);
+  }
+
+  public empty(): Field {
+    return Field(0);
+  }
+
+  protected hash(elements: Field[]): Field {
+    const init = salt(this.prefix);
+    const digest = Poseidon.update(init, elements);
+    return digest[0];
+  }
+}
+
+export class MinaActionsHashList extends MinaPrefixedProvableHashList<Field> {
+  public constructor(internalCommitment?: Field) {
+    super(Field, MINA_PREFIXES.sequenceEvents, internalCommitment);
+  }
+}

package/src/utils/PrefixedProvableHashList.ts

@@ -1,4 +1,4 @@
-import { Field, FlexibleProvablePure, Poseidon } from "snarkyjs";
+import { Field, ProvablePure, Poseidon } from "o1js";
 
 import { ProvableHashList } from "./ProvableHashList.js";
 import { stringToField } from "./utils";
@@ -7,7 +7,7 @@ export class PrefixedProvableHashList<Value> extends ProvableHashList<Value> {
   private readonly prefix: Field;
 
   public constructor(
-    valueType: FlexibleProvablePure<Value>,
+    valueType: ProvablePure<Value>,
     prefix: string,
     internalCommitment: Field = Field(0)
   ) {
@@ -15,6 +15,10 @@ export class PrefixedProvableHashList<Value> extends ProvableHashList<Value> {
     this.prefix = stringToField(prefix);
   }
 
+  public empty(): Field {
+    return Field(0);
+  }
+
   protected hash(elements: Field[]): Field {
     return Poseidon.hash([this.prefix, ...elements]);
   }

package/src/utils/ProvableHashList.ts

@@ -1,16 +1,101 @@
-import { Field, Poseidon, FlexibleProvablePure, Bool, Provable } from "snarkyjs";
+import {
+  Field,
+  Poseidon,
+  Bool,
+  Provable,
+  ProvablePure,
+  Unconstrained,
+} from "o1js";
+
+import { NonMethods } from "./utils";
+
+export type ProvableHashListData<Value> = {
+  preimage: Field;
+  value: NonMethods<Value>;
+};
+
+export type VerifiedTransition<T> = {
+  from: T;
+  to: T;
+};
 
 /**
  * Utilities for creating a hash list from a given value type.
  */
 export abstract class ProvableHashList<Value> {
+  public commitment: Field;
+
   public constructor(
-    private readonly valueType: FlexibleProvablePure<Value>,
-    public commitment: Field = Field(0)
-  ) {}
+    protected readonly valueType: ProvablePure<Value>,
+    commitment?: Field | undefined,
+    private unconstrainedList: Unconstrained<
+      ProvableHashListData<Value>[]
+    > = Unconstrained.from([])
+  ) {
+    this.commitment = commitment ?? this.empty();
+  }
+
+  protected abstract empty(): Field;
 
   protected abstract hash(elements: Field[]): Field;
 
+  private pushUnconstrained(preimage: Field, value: Value, condition?: Bool) {
+    this.unconstrainedList.updateAsProver((array) => {
+      if (condition !== undefined && !condition.toBoolean()) {
+        return array;
+      }
+      return [
+        ...array,
+        {
+          preimage: preimage.toConstant(),
+          value: Provable.toConstant(this.valueType, value),
+        },
+      ];
+    });
+  }
+
+  /**
+   * Fast-forwards the state of the hashlist to a specified new tip.
+   * This assumes the transition (from -> to) to be already verified somewhere
+   * else that is outside this scope.
+   */
+  public fastForward(
+    transition: VerifiedTransition<Field>,
+    message: string = "some hashlist"
+  ) {
+    const { from, to } = transition;
+    from.assertEquals(
+      this.commitment,
+      `From-commitment for ${message} not matching`
+    );
+
+    this.commitment = to;
+  }
+
+  public fastForwardIf(
+    transition: VerifiedTransition<Field>,
+    condition: Bool,
+    message: string = "some hashlist"
+  ) {
+    const { from, to } = transition;
+
+    // Equal to condition -> (from == this.commitment)
+    from
+      .mul(condition.toField())
+      .assertEquals(
+        this.commitment.mul(condition.toField()),
+        `From-commitment for ${message} not matching`
+      );
+
+    this.commitment = Provable.if(condition, to, this.commitment);
+  }
+
+  public witnessTip(preimage: Field, value: Value): Bool {
+    return this.hash([preimage, ...this.valueType.toFields(value)]).equals(
+      this.commitment
+    );
+  }
+
   /**
    * Converts the provided value to Field[] and appends it to
    * the current hashlist.
@@ -19,19 +104,25 @@ export abstract class ProvableHashList<Value> {
    * @returns Current hash list.
    */
   public push(value: Value) {
+    this.pushUnconstrained(this.commitment, value);
+
     this.commitment = this.hash([
       this.commitment,
       ...this.valueType.toFields(value),
     ]);
+
     return this;
   }
 
   public pushIf(value: Value, condition: Bool) {
+    this.pushUnconstrained(this.commitment, value, condition);
+
     const newCommitment = this.hash([
       this.commitment,
       ...this.valueType.toFields(value),
     ]);
     this.commitment = Provable.if(condition, newCommitment, this.commitment);
+
     return this;
   }
 
@@ -41,10 +132,24 @@ export abstract class ProvableHashList<Value> {
   public toField() {
     return this.commitment;
   }
+
+  public isEmpty(): Bool {
+    return this.commitment.equals(this.empty());
+  }
+
+  public getUnconstrainedValues(): Unconstrained<
+    ProvableHashListData<Value>[]
+  > {
+    return this.unconstrainedList;
+  }
 }
 
 export class DefaultProvableHashList<Value> extends ProvableHashList<Value> {
   public hash(elements: Field[]): Field {
     return Poseidon.hash(elements);
   }
+
+  public empty(): Field {
+    return Field(0);
+  }
 }

package/src/utils/ProvableReductionHashList.ts

@@ -0,0 +1,77 @@
+import { Bool, Field, Poseidon, Provable, ProvablePure } from "o1js";
+
+import { NonMethods } from "./utils";
+
+export class ProvableReductionHashList<Value> {
+  public constructor(
+    protected readonly valueType: ProvablePure<Value>,
+    public commitment: Field = Field(0)
+  ) {}
+
+  public unconstrainedList: Value[] = [];
+
+  private constrainedLastValue: Value | undefined = undefined;
+
+  private preimage: Field = this.commitment;
+
+  public pushAndReduce(
+    value: Value,
+    reduce: (previous: Value) => [Value, Bool]
+  ): { popLast: Bool; value: Value } {
+    let valueToPush = value;
+    let popLast = Bool(false);
+
+    // Theoretically, we can feed the preimage + last value as a witness
+    // for non-zero commitment starts (like used in the BlockProver), because
+    // currently it won't reduce across chunks. But this is okay for now I think
+    if (this.constrainedLastValue !== undefined) {
+      [valueToPush, popLast] = reduce(this.constrainedLastValue);
+    }
+
+    Provable.asProver(() => {
+      if (popLast.toBoolean()) {
+        this.unconstrainedList.pop();
+      }
+
+      const valueAsConstant = this.valueType.fromFields(
+        this.valueType.toFields(valueToPush).map((field) => field.toConstant())
+      );
+      this.unconstrainedList.push(valueAsConstant);
+    });
+
+    const currentCommitment = this.commitment;
+    const noPopCommitment = this.hash([
+      currentCommitment,
+      ...this.valueType.toFields(valueToPush),
+    ]);
+
+    const popCommitment = this.hash([
+      this.preimage,
+      ...this.valueType.toFields(valueToPush),
+    ]);
+
+    this.commitment = Provable.if(popLast, popCommitment, noPopCommitment);
+
+    this.constrainedLastValue = valueToPush;
+    this.preimage = Provable.if(popLast, this.preimage, currentCommitment);
+
+    return {
+      popLast,
+      value: valueToPush,
+    };
+  }
+
+  public pushIf(value: Value, condition: Bool) {
+    throw new Error("pushIf is not implemented for ReducedHashList");
+
+    return this;
+  }
+
+  public hash(elements: Field[]): Field {
+    return Poseidon.hash(elements);
+  }
+
+  public getUnconstrainedValues(): NonMethods<Value>[] {
+    return this.unconstrainedList;
+  }
+}