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

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,66 @@
+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 = Field(0)
+  ) {
+    super(valueType, internalCommitment);
+  }
+
+  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 = Field(0)) {
+    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)
   ) {

package/src/utils/ProvableHashList.ts

@@ -1,16 +1,73 @@
-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 constructor(
-    private readonly valueType: FlexibleProvablePure<Value>,
-    public commitment: Field = Field(0)
+    protected readonly valueType: ProvablePure<Value>,
+    public commitment: Field = Field(0),
+    private unconstrainedList: Unconstrained<
+      ProvableHashListData<Value>[]
+    > = Unconstrained.from([])
   ) {}
 
   protected abstract hash(elements: Field[]): Field;
 
+  private pushUnconstrained(preimage: Field, value: Value) {
+    const valueConstant = this.valueType.fromFields(
+      this.valueType.toFields(value).map((field) => field.toConstant())
+    );
+    this.unconstrainedList.get().push({
+      preimage: preimage.toConstant(),
+      value: valueConstant,
+    });
+  }
+
+  /**
+   * 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 witnessTip(preimage: Field, value: Value): Bool {
+    return this.hash([
+      this.commitment,
+      ...this.valueType.toFields(value),
+    ]).equals(this.commitment);
+  }
+
   /**
    * Converts the provided value to Field[] and appends it to
    * the current hashlist.
@@ -19,19 +76,31 @@ export abstract class ProvableHashList<Value> {
    * @returns Current hash list.
    */
   public push(value: Value) {
+    Provable.asProver(() => {
+      this.pushUnconstrained(this.commitment, value);
+    });
+
     this.commitment = this.hash([
       this.commitment,
       ...this.valueType.toFields(value),
     ]);
+
     return this;
   }
 
   public pushIf(value: Value, condition: Bool) {
+    Provable.asProver(() => {
+      if (condition.toBoolean()) {
+        this.pushUnconstrained(this.commitment, value);
+      }
+    });
+
     const newCommitment = this.hash([
       this.commitment,
       ...this.valueType.toFields(value),
     ]);
     this.commitment = Provable.if(condition, newCommitment, this.commitment);
+
     return this;
   }
 
@@ -41,6 +110,12 @@ export abstract class ProvableHashList<Value> {
   public toField() {
     return this.commitment;
   }
+
+  public getUnconstrainedValues(): Unconstrained<
+    ProvableHashListData<Value>[]
+  > {
+    return this.unconstrainedList;
+  }
 }
 
 export class DefaultProvableHashList<Value> extends ProvableHashList<Value> {

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

package/src/utils/utils.ts

@@ -1,7 +1,5 @@
-// eslint-disable-next-line max-len
-/* eslint-disable @typescript-eslint/no-explicit-any,@typescript-eslint/ban-types, @typescript-eslint/no-unsafe-return,@typescript-eslint/no-empty-function */
-
-import { Circuit, Field, Poseidon, Proof } from "snarkyjs";
+import { Bool, Field, Poseidon, Provable } from "o1js";
+import floor from "lodash/floor";
 
 export type ReturnType<FunctionType extends Function> = FunctionType extends (
   ...args: any[]
@@ -9,10 +7,6 @@ export type ReturnType<FunctionType extends Function> = FunctionType extends (
   ? Return
   : any;
 
-export type UnTypedClass = new (...args: any[]) => any;
-
-export type TypedClass<Class> = new (...args: any[]) => Class;
-
 export type Subclass<Class extends new (...args: any) => any> = (new (
   ...args: any
 ) => InstanceType<Class>) & {
@@ -28,76 +22,71 @@ export function notInCircuit(): MethodDecorator {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     const childFunction = descriptor.value;
     descriptor.value = function value(this: any, ...args: any[]) {
-      if (Circuit.inCheckedComputation() || Circuit.inProver()) {
+      if (Provable.inCheckedComputation() || Provable.inProver()) {
         throw new Error(
           `Method ${propertyKey.toString()} is supposed to be only called outside of the circuit`
         );
       }
-      // eslint-disable-next-line max-len
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-call,@typescript-eslint/no-unsafe-member-access
       return childFunction.apply(this, args);
     };
     return descriptor;
   };
 }
 
-export function stringToField(value: string, throwOnOverflow = false) {
-  const fieldSize = Field.sizeInBytes();
+export function stringToField(value: string) {
+  const fieldSize = Field.sizeInBytes - 1;
 
-  // eslint-disable-next-line putout/putout
+  // Encode string as byte[]
   const encoder = new TextEncoder();
-
   const stringBytes = Array.from(encoder.encode(value));
 
+  // Add padding in case the string is not a multiple of Field.sizeInBytes
   const padding = Array.from<number>({
-    length: fieldSize - stringBytes.length,
+    length: fieldSize - (stringBytes.length % fieldSize),
   }).fill(0);
-  const data = stringBytes.concat(padding);
+  const data = stringBytes.concat(padding).reverse();
 
-  if (data.length > fieldSize) {
-    if (throwOnOverflow) {
-      throw new Error(
-        "Trying to encode a stringt that is larger than 256 bits"
-      );
-    }
-
-    // Hash the result Field[] to reduce it to
-    const chunks = data.reduce<number[][]>((a, b, index) => {
-      const arrayIndex = index / fieldSize;
-      if (a.length <= arrayIndex) {
-        a.push([]);
-      }
+  // Hash the result Field[] to reduce it to
+  const chunks = data.reduce<number[][]>(
+    (a, b, index) => {
+      const arrayIndex = floor(index / fieldSize);
       a[arrayIndex].push(b);
       return a;
-    }, []);
-    return Poseidon.hash(chunks.map((x) => Field.fromBytes(x)));
-  }
-
-  return Field.fromBytes(data);
+    },
+
+    Array.from<number[]>({ length: floor(data.length / fieldSize) }).map(
+      () => []
+    )
+  );
+  const fields = chunks.map((x) =>
+    // We have to add a zero at the highest byte here, because a Field is
+    // a bit smaller than 2^256
+    Field.fromBytes(x.concat([0]))
+  );
+  return Poseidon.hash(fields);
 }
 
-/**
- * Note: This only works for strings that have been encoded using the `throwOnOverflow` set to true
- */
-export function fieldToString(value: Field | bigint): string {
+export function singleFieldToString(value: Field | bigint): string {
+  let fieldValue = value;
   if (typeof value === "bigint") {
-    value = Field(value);
+    fieldValue = Field(value);
   }
-  let bytes = Field.toBytes(value);
-  // Find start of padded zeroes in order to remove them.
-  const zeroesStart =
-    bytes.length -
-    bytes
-      .slice()
-      .reverse()
-      .findIndex((element) => element !== 0);
-
-  bytes = bytes.slice(0, zeroesStart);
+  return fieldValue.toString();
+}
 
-  // eslint-disable-next-line putout/putout
-  const decoder = new TextDecoder();
+type NonMethodKeys<T> = {
+  [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+export type NonMethods<T> = Pick<T, NonMethodKeys<T>>;
 
-  return decoder.decode(new Uint8Array(bytes));
+/**
+ * Asserts the equality of a and b, but only if doAssertion is true, otherwise it will assert 0 = 0
+ */
+export function assertEqualsIf(
+  a: Field,
+  b: Field,
+  doAssertion: Bool,
+  msg: string
+) {
+  a.mul(doAssertion.toField()).assertEquals(b.mul(doAssertion.toField()), msg);
 }
-
-export function noop(): void {}