@proto-kit/protocol 0.1.1-develop.153

package/src/utils/merkletree/RollupMerkleTree.ts

@@ -0,0 +1,250 @@
+/* eslint-disable id-length */
+/* eslint-disable line-comment-position */
+/* eslint-disable no-inline-comments */
+/* eslint-disable @typescript-eslint/no-magic-numbers */
+import { Bool, Circuit, Field, Poseidon, Struct } from "snarkyjs";
+
+import { notInCircuit } from "../utils";
+import { MerkleTreeStore } from "./MerkleTreeStore";
+
+// external API
+// eslint-disable-next-line @typescript-eslint/no-use-before-define
+export { RollupMerkleTree, RollupMerkleWitness };
+
+// internal API
+// eslint-disable-next-line @typescript-eslint/no-use-before-define
+export { maybeSwap };
+
+/**
+ * The {@link BaseMerkleWitness} class defines a circuit-compatible base class
+ * for [Merkle Witness'](https://computersciencewiki.org/index.php/Merkle_proof).
+ */
+class RollupMerkleWitness extends Struct({
+  path: Circuit.array(Field, 256 - 1),
+  isLeft: Circuit.array(Bool, 256 - 1),
+}) {
+  public static height = 256;
+
+  public height(): number {
+    return RollupMerkleWitness.height;
+  }
+
+  /**
+   * Calculates a root depending on the leaf value.
+   * @param leaf Value of the leaf node that belongs to this Witness.
+   * @returns The calculated root.
+   */
+  public calculateRoot(hash: Field): Field {
+    const n = this.height();
+
+    for (let index = 1; index < n; ++index) {
+      const isLeft = this.isLeft[index - 1];
+      // eslint-disable-next-line @typescript-eslint/no-use-before-define
+      const [left, right] = maybeSwap(isLeft, hash, this.path[index - 1]);
+      hash = Poseidon.hash([left, right]);
+    }
+
+    return hash;
+  }
+
+  /**
+   * Calculates the index of the leaf node that belongs to this Witness.
+   * @returns Index of the leaf.
+   */
+  public calculateIndex(): Field {
+    let powerOfTwo = Field(1);
+    let index = Field(0);
+    const n = this.height();
+
+    // eslint-disable-next-line no-underscore-dangle
+    for (let index_ = 1; index_ < n; ++index_) {
+      index = Circuit.if(this.isLeft[index_ - 1], index, index.add(powerOfTwo));
+      powerOfTwo = powerOfTwo.mul(2);
+    }
+
+    return index;
+  }
+}
+
+/**
+ * A [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) is a binary tree in
+ * which every leaf is the cryptography hash of a piece of data,
+ * and every node is the hash of the concatenation of its two child nodes.
+ *
+ * A Merkle Tree allows developers to easily and securely verify
+ * the integrity of large amounts of data.
+ *
+ * Take a look at our [documentation](https://docs.minaprotocol.com/en/zkapps)
+ * on how to use Merkle Trees in combination with zkApps and
+ * zero knowledge programming!
+ *
+ * Levels are indexed from leaves (level 0) to root (level N - 1).
+ */
+class RollupMerkleTree {
+  public static height = 256;
+
+  public static get leafCount(): bigint {
+    return 2n ** BigInt(RollupMerkleTree.height - 1);
+  }
+
+  private readonly zeroes: bigint[];
+
+  public readonly store: MerkleTreeStore;
+
+  public constructor(store: MerkleTreeStore) {
+    this.store = store;
+    // eslint-disable-next-line @shopify/prefer-class-properties
+    this.zeroes = [0n];
+    for (let index = 1; index < RollupMerkleTree.height; index += 1) {
+      const previousLevel = Field(this.zeroes[index - 1]);
+      this.zeroes.push(
+        Poseidon.hash([previousLevel, previousLevel]).toBigInt()
+      );
+    }
+  }
+
+  /**
+   * Returns a node which lives at a given index and level.
+   * @param level Level of the node.
+   * @param index Index of the node.
+   * @returns The data of the node.
+   */
+  @notInCircuit()
+  public getNode(level: number, index: bigint): Field {
+    return Field(this.store.getNode(index, level) ?? this.zeroes[level]);
+  }
+
+  /**
+   * Returns the root of the [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree).
+   * @returns The root of the Merkle Tree.
+   */
+  @notInCircuit()
+  public getRoot(): Field {
+    return this.getNode(RollupMerkleTree.height - 1, 0n);
+  }
+
+  // eslint-disable-next-line no-warning-comments
+  // TODO: this allows to set a node at an index larger than the size. OK?
+  private setNode(level: number, index: bigint, value: Field) {
+    this.store.setNode(index, level, value.toBigInt());
+  }
+
+  /**
+   * TODO: if this is passed an index bigger than the max, it will set a couple
+   * of out-of-bounds nodes but not affect the real Merkle root. OK?
+   */
+
+  /**
+   * Sets the value of a leaf node at a given index to a given value.
+   * @param index Position of the leaf node.
+   * @param leaf New value.
+   */
+  @notInCircuit()
+  public setLeaf(index: bigint, leaf: Field) {
+    if (index >= this.leafCount) {
+      index %= this.leafCount;
+    }
+    this.setNode(0, index, leaf);
+    let currentIndex = index;
+    for (let level = 1; level < RollupMerkleTree.height; level += 1) {
+      currentIndex /= 2n;
+
+      const left = this.getNode(level - 1, currentIndex * 2n);
+      const right = this.getNode(level - 1, currentIndex * 2n + 1n);
+
+      this.setNode(level, currentIndex, Poseidon.hash([left, right]));
+    }
+  }
+
+  /**
+   * Returns the witness (also known as
+   * [Merkle Proof or Merkle Witness](https://computersciencewiki.org/index.php/Merkle_proof))
+   * for the leaf at the given index.
+   * @param index Position of the leaf node.
+   * @returns The witness that belongs to the leaf.
+   */
+  @notInCircuit()
+  public getWitness(index: bigint): RollupMerkleWitness {
+    if (index >= this.leafCount) {
+      index %= this.leafCount;
+    }
+    const path = [];
+    const isLefts = [];
+    for (let level = 0; level < RollupMerkleTree.height - 1; level += 1) {
+      const isLeft = index % 2n === 0n;
+      const sibling = this.getNode(level, isLeft ? index + 1n : index - 1n);
+      isLefts.push(Bool(isLeft));
+      path.push(sibling);
+      index /= 2n;
+    }
+    return new RollupMerkleWitness({
+      isLeft: isLefts,
+      path,
+    });
+  }
+
+  // eslint-disable-next-line no-warning-comments, max-len
+  // TODO: should this take an optional offset? should it fail if the array is too long?
+  /**
+   * Fills all leaves of the tree.
+   * @param leaves Values to fill the leaves with.
+   */
+  @notInCircuit()
+  public fill(leaves: Field[]) {
+    leaves.forEach((value, index) => {
+      this.setLeaf(BigInt(index), value);
+    });
+  }
+
+  /**
+   * Returns the amount of leaf nodes.
+   * @returns Amount of leaf nodes.
+   */
+  public get leafCount(): bigint {
+    return RollupMerkleTree.leafCount;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export namespace MerkleTreeUtils {
+  export function normalizeKey(key: Field): Field {
+    // if(NJORD_MERKLE_TREE_HEIGHT < 256){
+    //     return fieldMod(key, Field(RollupMerkleTree.leafCount).toConstant())
+    // eslint-disable-next-line max-len
+    //     // return modPower2(key, RollupMerkleTree.height - 1) //TODO Fix modPower2
+    // }else{
+    return key;
+
+    // }
+  }
+
+  export function checkMembership(
+    witness: RollupMerkleWitness,
+    root: Field,
+    key: Field,
+    value: Field
+  ): Bool {
+    const root2 = witness.calculateRoot(value);
+    const key2 = witness.calculateIndex();
+    key.assertEquals(key2, "Keys of MerkleWitness does not match");
+    return root.equals(root2);
+  }
+
+  export function computeRoot(
+    witness: RollupMerkleWitness,
+    value: Field
+  ): Field {
+    return witness.calculateRoot(value);
+  }
+}
+
+/**
+ * More efficient version of `maybeSwapBad` which
+ * reuses an intermediate variable
+ */
+function maybeSwap(b: Bool, x: Field, y: Field): [Field, Field] {
+  const m = b.toField().mul(x.sub(y)); // b*(x - y)
+  const x1 = y.add(m); // y + b*(x - y)
+  const y2 = x.sub(m); // x - b*(x - y) = x + b*(y - x)
+  return [x1, y2];
+}

package/src/utils/merkletree/VirtualMerkleTreeStore.ts

@@ -0,0 +1,21 @@
+import { MerkleTreeStore } from "./MerkleTreeStore";
+import { InMemoryMerkleTreeStorage } from "./InMemoryMerkleTreeStorage";
+
+/**
+ * A MemoryMerkleTreeStore that, if falls back to a parent store if it
+ * has no data
+ */
+export class VirtualMerkleTreeStore extends InMemoryMerkleTreeStorage {
+  public constructor(private readonly parent: MerkleTreeStore) {
+    super()
+  }
+
+  public getNode(key: bigint, level: number): bigint | undefined {
+    return super.getNode(key, level) ?? this.parent.getNode(key, level);
+  }
+
+  public setNode(key: bigint, level: number, value: bigint): void {
+    super.setNode(key, level, value);
+  }
+
+}

package/src/utils/utils.ts

@@ -0,0 +1,103 @@
+// 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 { TextEncoder, TextDecoder } from "node:util";
+
+import { Circuit, Field, Poseidon, Proof } from "snarkyjs";
+
+export type ReturnType<FunctionType extends Function> = FunctionType extends (
+  ...args: any[]
+) => infer Return
+  ? 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>) & {
+  [Key in keyof Class]: Class[Key];
+} & { prototype: InstanceType<Class> };
+
+export function notInCircuit(): MethodDecorator {
+  return function ReplacedFunction(
+    target: any,
+    propertyKey: string | symbol,
+    descriptor: PropertyDescriptor
+  ) {
+    // 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()) {
+        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();
+
+  const encoder = new TextEncoder();
+
+  const stringBytes = Array.from(encoder.encode(value));
+
+  const padding = Array.from<number>({
+    length: fieldSize - stringBytes.length,
+  }).fill(0);
+  const data = stringBytes.concat(padding);
+
+  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([]);
+      }
+      a[arrayIndex].push(b);
+      return a;
+    }, []);
+    return Poseidon.hash(chunks.map((x) => Field.fromBytes(x)));
+  }
+
+  return Field.fromBytes(data);
+}
+
+/**
+ * Note: This only works for strings that have been encoded using the `throwOnOverflow` set to true
+ */
+export function fieldToString(value: Field | bigint): string {
+  if (typeof value === "bigint") {
+    value = 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);
+
+  const decoder = new TextDecoder();
+
+  return decoder.decode(new Uint8Array(bytes));
+}
+
+export function noop(): void {}

package/test/BlockProver.test.ts

@@ -0,0 +1,127 @@
+import "reflect-metadata";
+import { Bool, Field, Poseidon, Proof } from "snarkyjs";
+import {
+  container as globalContainer,
+  type DependencyContainer,
+} from "tsyringe";
+
+import { MethodPublicOutput } from "@proto-kit/protocol";
+
+import {
+  BlockProver,
+  type BlockProverState,
+} from "../src/prover/block/BlockProver.js";
+import { NoOpStateTransitionWitnessProvider } from "../src/prover/statetransition/StateTransitionWitnessProvider.js";
+import {
+  StateTransitionProverPublicInput,
+  StateTransitionProverPublicOutput,
+} from "../src/prover/statetransition/StateTransitionProvable";
+import { BlockProverPublicInput } from "../src/prover/block/BlockProvable";
+
+type BlockProverProofPair = [
+  Proof<void, MethodPublicOutput>,
+  Proof<StateTransitionProverPublicInput, StateTransitionProverPublicOutput>
+];
+
+describe("blockProver", () => {
+  let container: DependencyContainer;
+
+  beforeEach(() => {
+    const childContainer = globalContainer.createChildContainer();
+    childContainer.register(
+      "StateTransitionWitnessProvider",
+      NoOpStateTransitionWitnessProvider
+    );
+    container = childContainer;
+  });
+
+  function generateTestProofs(
+    fromStateRoot: Field,
+    toStateRoot: Field
+  ): BlockProverProofPair {
+    const transactionHash = Poseidon.hash([Field(12_345)]);
+    const sthash = Field(123);
+
+    const appProof = new Proof<undefined, MethodPublicOutput>({
+      publicInput: undefined,
+      publicOutput: new MethodPublicOutput({
+        transactionHash,
+        stateTransitionsHash: sthash,
+        status: Bool(true),
+      }),
+
+      proof: "",
+      maxProofsVerified: 2,
+    });
+
+    const stProof = new Proof<
+      StateTransitionProverPublicInput,
+      StateTransitionProverPublicOutput
+    >({
+      publicInput: new StateTransitionProverPublicInput({
+        stateTransitionsHash: Field(0),
+        stateRoot: fromStateRoot,
+      }),
+      publicOutput: new StateTransitionProverPublicOutput({
+        stateTransitionsHash: sthash,
+        stateRoot: toStateRoot,
+      }),
+
+      proof: "",
+      maxProofsVerified: 2,
+    });
+
+    return [appProof, stProof];
+  }
+
+  it("should pass with valid inputs", () => {
+    expect.assertions(0);
+
+    const blockProver = container.resolve(BlockProver);
+
+    const fromState = Field(1);
+    const toState = Field(2);
+
+    const [appProof, stProof] = generateTestProofs(fromState, toState);
+
+    const state: BlockProverState = {
+      stateRoot: fromState,
+      transactionsHash: Field(0),
+    };
+    blockProver.applyTransaction(state, stProof, appProof);
+  });
+
+  it("previously applied transaction should also pass with derived publicInputs", () => {
+    expect.assertions(2);
+
+    const blockProver = container.resolve(BlockProver);
+
+    const fromState = Field(1);
+    const toState = Field(2);
+
+    const [appProof, stProof] = generateTestProofs(fromState, toState);
+
+    const fromProverState: BlockProverState = {
+      stateRoot: fromState,
+      transactionsHash: Field(0),
+    };
+    const toProverState = { ...fromProverState };
+    blockProver.applyTransaction(toProverState, stProof, appProof);
+
+    const publicInput = new BlockProverPublicInput({
+      stateRoot: fromProverState.stateRoot,
+      transactionsHash: fromProverState.transactionsHash,
+    });
+
+    const publicOutput = blockProver.proveTransaction(
+      publicInput,
+      stProof,
+      appProof
+    );
+
+    expect(publicOutput.stateRoot).toStrictEqual(toProverState.stateRoot);
+    expect(publicOutput.transactionsHash).toStrictEqual(
+      toProverState.transactionsHash
+    );
+  });
+});

package/test/Protocol.test.ts

@@ -0,0 +1,27 @@
+import "reflect-metadata";
+import { VanillaProtocol } from "../src/protocol/Protocol";
+import { beforeEach } from "@jest/globals";
+import { BlockProver } from "../src/prover/block/BlockProver";
+import { StateTransitionProver } from "../src/prover/statetransition/StateTransitionProver";
+import { NoOpStateTransitionWitnessProvider } from "../src";
+
+describe("protocol", () => {
+  let protocol: ReturnType<typeof VanillaProtocol.create>;
+
+  beforeEach(() => {
+    protocol = VanillaProtocol.create();
+  });
+
+  it("should resolve all provers correctly", async () => {
+    expect.assertions(2);
+
+    protocol.dependencyContainer.register("StateTransitionWitnessProvider", {
+      useValue: new NoOpStateTransitionWitnessProvider()
+    })
+
+    expect(protocol.blockProver instanceof BlockProver).toBe(true);
+    expect(
+      protocol.stateTransitionProver instanceof StateTransitionProver
+    ).toBe(true);
+  });
+});

package/test/StateTransition.test.ts

@@ -0,0 +1,182 @@
+import "reflect-metadata";
+import { Bool, Field } from "snarkyjs";
+import { container } from "tsyringe";
+
+import {
+  Option,
+  ProvableStateTransition,
+  DefaultProvableHashList,
+  StateTransitionProvableBatch, CachedMerkleTreeStore
+} from "../src/index";
+import {
+  RollupMerkleTree,
+  type RollupMerkleWitness,
+} from "../src/utils/merkletree/RollupMerkleTree.js";
+import { StateTransitionProver } from "../src/prover/statetransition/StateTransitionProver.js";
+import type { StateTransitionWitnessProvider } from "../src/prover/statetransition/StateTransitionWitnessProvider.js";
+
+describe("stateTransition", () => {
+  async function checkTransitions(
+    tree: RollupMerkleTree,
+    transitions: ProvableStateTransition[]
+  ) {
+    const batch = StateTransitionProvableBatch.fromTransitions(transitions);
+
+    const temporaryTree = new RollupMerkleTree(
+      new CachedMerkleTreeStore(tree.store)
+    );
+    const startRoot = temporaryTree.getRoot();
+
+    const hashList = new DefaultProvableHashList(ProvableStateTransition);
+
+    batch.batch.forEach((item) => {
+      if (item.to.isSome.toBoolean()) {
+        temporaryTree.setLeaf(item.path.toBigInt(), item.to.value);
+      }
+      hashList.push(item);
+    });
+
+    const endRoot = temporaryTree.getRoot();
+
+    class DummySTWP implements StateTransitionWitnessProvider {
+      private i = 0;
+
+      public constructor(private readonly witnessTree: RollupMerkleTree) {}
+
+      public getWitness(key: Field): RollupMerkleWitness {
+        const witness = this.witnessTree.getWitness(key.toBigInt());
+        const set = batch.batch[this.i];
+        if (set.to.isSome.toBoolean()) {
+          this.witnessTree.setLeaf(key.toBigInt(), set.to.value);
+        }
+        this.i += 1;
+        return witness;
+      }
+    }
+
+    const childContainer = container.createChildContainer();
+    childContainer.registerInstance(
+      "StateTransitionWitnessProvider",
+      new DummySTWP(tree)
+    );
+    const prover = childContainer.resolve(StateTransitionProver);
+
+    const state = prover.applyTransitions(startRoot, Field(0), batch);
+
+    expect(state.stateRoot).toStrictEqual(endRoot);
+    expect(state.stateTransitionList.commitment).toStrictEqual(
+      hashList.commitment
+    );
+
+    await childContainer.dispose();
+  }
+
+  it.each([
+    [
+      [
+        new ProvableStateTransition({
+          from: Option.fromValue(Field(1), Field).toProvable(),
+          to: Option.fromValue(Field(14), Field).toProvable(),
+          path: Field(1),
+        }),
+        new ProvableStateTransition({
+          from: Option.fromValue(Field(14), Field).toProvable(),
+          to: Option.fromValue(Field(4), Field).toProvable(),
+          path: Field(1),
+        }),
+      ],
+    ],
+    [
+      [
+        new ProvableStateTransition({
+          from: Option.none().toProvable(),
+          to: Option.from(Bool(true), Field(4), Field).toProvable(),
+          path: Field(1),
+        }),
+        new ProvableStateTransition({
+          from: Option.from(Bool(true), Field(5), Field).toProvable(),
+          to: Option.from(Bool(true), Field(2), Field).toProvable(),
+          path: Field(2),
+        }),
+        new ProvableStateTransition({
+          from: Option.from(Bool(true), Field(2), Field).toProvable(),
+          to: Option.none().toProvable(),
+          path: Field(2),
+        }),
+      ],
+    ],
+  ])("should pass without throwing", async (transitions) => {
+    expect.assertions(2);
+
+    const tree = new RollupMerkleTree(new MemoryMerkleTreeStorage());
+
+    // Is ignored because overwritten by first transition
+    tree.setLeaf(1n, Option.fromValue(Field(1), Field).treeValue);
+    tree.setLeaf(2n, Option.fromValue(Field(5), Field).treeValue);
+
+    await checkTransitions(tree, transitions);
+  });
+
+  it.each([
+    [
+      [
+        new ProvableStateTransition({
+          // fail
+          from: Option.from(Bool(true), Field(2), Field).toProvable(),
+          to: Option.none().toProvable(),
+          path: Field(1),
+        }),
+      ],
+      0,
+    ],
+    [
+      [
+        new ProvableStateTransition({
+          // success
+          from: Option.from(Bool(true), Field(1), Field).toProvable(),
+          to: Option.from(Bool(true), Field(14), Field).toProvable(),
+          path: Field(1),
+        }),
+        new ProvableStateTransition({
+          // fail
+          from: Option.from(Bool(true), Field(6), Field).toProvable(),
+          to: Option.none().toProvable(),
+          path: Field(2),
+        }),
+      ],
+      1,
+    ],
+    [
+      [
+        new ProvableStateTransition({
+          // success
+          from: Option.from(Bool(true), Field(1), Field).toProvable(),
+          to: Option.from(Bool(true), Field(14), Field).toProvable(),
+          path: Field(1),
+        }),
+        new ProvableStateTransition({
+          // fail
+          from: Option.from(Bool(true), Field(15), Field).toProvable(),
+          to: Option.none().toProvable(),
+          path: Field(1),
+        }),
+      ],
+      1,
+    ],
+  ])(
+    "should throw because of failing precondition",
+    async (transitions, index) => {
+      expect.assertions(1);
+
+      const tree = new RollupMerkleTree(new MemoryMerkleTreeStorage());
+
+      // Is ignored because overwritten by first transition
+      tree.setLeaf(1n, Option.fromValue(Field(1), Field).treeValue);
+      tree.setLeaf(2n, Option.fromValue(Field(5), Field).treeValue);
+
+      await expect(checkTransitions(tree, transitions)).rejects.toThrow(
+        `MerkleWitness not valid for StateTransition (${index})`
+      );
+    }
+  );
+});