@proto-kit/protocol 0.1.1-develop.153

package/dist/utils/merkletree/RollupMerkleTree.js

@@ -0,0 +1,244 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+/* 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";
+// 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),
+}) {
+    height() {
+        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.
+     */
+    calculateRoot(hash) {
+        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.
+     */
+    calculateIndex() {
+        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;
+    }
+}
+RollupMerkleWitness.height = 256;
+/**
+ * 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 {
+    static get leafCount() {
+        return 2n ** BigInt(RollupMerkleTree.height - 1);
+    }
+    constructor(store) {
+        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.
+     */
+    getNode(level, index) {
+        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.
+     */
+    getRoot() {
+        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?
+    setNode(level, index, value) {
+        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.
+     */
+    setLeaf(index, leaf) {
+        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.
+     */
+    getWitness(index) {
+        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.
+     */
+    fill(leaves) {
+        leaves.forEach((value, index) => {
+            this.setLeaf(BigInt(index), value);
+        });
+    }
+    /**
+     * Returns the amount of leaf nodes.
+     * @returns Amount of leaf nodes.
+     */
+    get leafCount() {
+        return RollupMerkleTree.leafCount;
+    }
+}
+RollupMerkleTree.height = 256;
+__decorate([
+    notInCircuit(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Number, BigInt]),
+    __metadata("design:returntype", Field)
+], RollupMerkleTree.prototype, "getNode", null);
+__decorate([
+    notInCircuit(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Field)
+], RollupMerkleTree.prototype, "getRoot", null);
+__decorate([
+    notInCircuit(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [BigInt, Field]),
+    __metadata("design:returntype", void 0)
+], RollupMerkleTree.prototype, "setLeaf", null);
+__decorate([
+    notInCircuit(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [BigInt]),
+    __metadata("design:returntype", RollupMerkleWitness)
+], RollupMerkleTree.prototype, "getWitness", null);
+__decorate([
+    notInCircuit(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Array]),
+    __metadata("design:returntype", void 0)
+], RollupMerkleTree.prototype, "fill", null);
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export var MerkleTreeUtils;
+(function (MerkleTreeUtils) {
+    function normalizeKey(key) {
+        // 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;
+        // }
+    }
+    MerkleTreeUtils.normalizeKey = normalizeKey;
+    function checkMembership(witness, root, key, value) {
+        const root2 = witness.calculateRoot(value);
+        const key2 = witness.calculateIndex();
+        key.assertEquals(key2, "Keys of MerkleWitness does not match");
+        return root.equals(root2);
+    }
+    MerkleTreeUtils.checkMembership = checkMembership;
+    function computeRoot(witness, value) {
+        return witness.calculateRoot(value);
+    }
+    MerkleTreeUtils.computeRoot = computeRoot;
+})(MerkleTreeUtils || (MerkleTreeUtils = {}));
+/**
+ * More efficient version of `maybeSwapBad` which
+ * reuses an intermediate variable
+ */
+function maybeSwap(b, x, y) {
+    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/jest.config.cjs

@@ -0,0 +1 @@
+module.exports = require("../../jest.config.cjs");

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@proto-kit/protocol",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "version": "0.1.1-develop.153+10a7974",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "lint": "eslint ./src ./test",
+    "test:file": "node --experimental-vm-modules --experimental-wasm-modules --experimental-wasm-threads ../../node_modules/jest/bin/jest.js",
+    "test": "npm run test:file -- ./src/** ./test/**",
+    "test:watch": "npm run test:file -- ./src/** ./test/** --watch"
+  },
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@proto-kit/common": "0.1.1-develop.153+10a7974",
+    "lodash": "^4.17.21",
+    "loglevel": "^1.8.1",
+    "reflect-metadata": "^0.1.13",
+    "tsyringe": "^4.7.0"
+  },
+  "peerDependencies": {
+    "snarkyjs": "0.11.0",
+    "tsyringe": "^4.7.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/lodash": "^4.14.194"
+  },
+  "gitHead": "10a7974582f79be6f4f099eec83c4b0359cce2a6"
+}

package/src/Constants.ts

@@ -0,0 +1,3 @@
+export const constants = {
+  stateTransitionProverBatchSize: 4,
+};

package/src/index.ts

@@ -0,0 +1,23 @@
+export * from "./utils/ProvableHashList";
+export * from "./model/StateTransition";
+export * from "./model/StateTransitionProvableBatch";
+export * from "./model/Option";
+export * from "./model/Path";
+export * from "./model/network/NetworkState";
+export * from "./model/transaction/ProtocolTransaction";
+export * from "./model/transaction/RuntimeTransaction";
+export * from "./utils/PrefixedProvableHashList.js";
+export * from "./utils/utils";
+export * from "./prover/block/BlockProver";
+export * from "./prover/block/BlockProvable";
+export * from "./prover/statetransition/StateTransitionProver";
+export * from "./prover/statetransition/StateTransitionProvable";
+export * from "./prover/statetransition/StateTransitionWitnessProvider";
+export * from "./utils/merkletree/MerkleTreeStore";
+export * from "./utils/merkletree/InMemoryMerkleTreeStorage";
+export * from "./utils/merkletree/RollupMerkleTree";
+export * from "./model/MethodPublicOutput";
+export * from "./prover/statetransition/StateTransitionWitnessProviderReference";
+export * from "./protocol/Protocol";
+export * from "./protocol/ProtocolModule";
+export { constants as ProtocolConstants } from "./Constants";

package/src/model/MethodPublicOutput.ts

@@ -0,0 +1,12 @@
+import { Bool, Field, Struct } from "snarkyjs";
+
+/**
+ * Public input used to link in-circuit execution with
+ * the proof's public input.
+ */
+export class MethodPublicOutput extends Struct({
+  stateTransitionsHash: Field,
+  status: Bool,
+  transactionHash: Field,
+  networkStateHash: Field,
+}) {}

package/src/model/Option.test.ts

@@ -0,0 +1,21 @@
+import { Bool, Field, Poseidon } from "snarkyjs";
+
+import { Option } from "./Option";
+
+describe("option", () => {
+  it.each([
+    [Bool(true), Field(0), Field, true],
+    [Bool(false), Field(0), Field, false],
+  ])(
+    "should serialize to the correct tree value",
+    (isSome, value, valueType, shouldHash) => {
+      expect.assertions(1);
+
+      const option = Option.from(isSome, value, valueType);
+      // eslint-disable-next-line jest/no-conditional-in-test
+      const treeValue = shouldHash ? Poseidon.hash(value.toFields()) : Field(0);
+
+      expect(option.treeValue.toString()).toStrictEqual(treeValue.toString());
+    }
+  );
+});

package/src/model/Option.ts

@@ -0,0 +1,133 @@
+import {
+  Bool,
+  Field,
+  type FlexibleProvablePure,
+  Poseidon,
+  Provable,
+  Struct,
+} from "snarkyjs";
+
+export class ProvableOption extends Struct({
+  isSome: Bool,
+  value: Field,
+}) {
+  public toSome() {
+    this.isSome = Bool(true);
+    return this;
+  }
+}
+
+/**
+ * Option facilitating in-circuit values that may or may not exist.
+ */
+export class Option<Value> {
+  /**
+   * Creates a new Option from the provided parameters
+   *
+   * @param isSome
+   * @param value
+   * @param valueType
+   * @returns New option from the provided parameters.
+   */
+  public static from<Value>(
+    isSome: Bool,
+    value: Value,
+    valueType: FlexibleProvablePure<Value>
+  ) {
+    return new Option(isSome, value, valueType);
+  }
+
+  /**
+   * Creates a new Option from the provided parameters
+   *
+   * @param value
+   * @param valueType
+   * @returns New option from the provided parameters.
+   */
+  public static fromValue<Value>(
+    value: Value,
+    valueType: FlexibleProvablePure<Value>
+  ) {
+    return this.from(Bool(true), value, valueType);
+  }
+
+  /**
+   * @returns Empty / none option
+   */
+  public static none() {
+    return new Option(Bool(false), Field(0), Field);
+  }
+
+  public static dummyValueFields<Value>(
+    valueType: FlexibleProvablePure<Value>
+  ): Field[] {
+    const length = valueType.sizeInFields();
+    return Array.from({ length }, () => Field(0));
+  }
+
+  /**
+   * Computes a dummy value for the given value type.
+   *
+   * @param valueType - Value type to generate the dummy value for
+   * @returns Dummy value for the given value type
+   */
+  public static dummyValue<Value>(
+    valueType: FlexibleProvablePure<Value>
+  ): Value {
+    const fields = Option.dummyValueFields(valueType);
+
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return valueType.fromFields(fields) as Value;
+  }
+
+  public isForcedSome = Bool(false);
+
+  public constructor(
+    public isSome: Bool,
+    public value: Value,
+    public valueType: FlexibleProvablePure<Value>
+  ) {}
+
+  public clone() {
+    return new Option(this.isSome, this.value, this.valueType);
+  }
+
+  public forceSome() {
+    this.isForcedSome = Provable.if(this.isSome, Bool(false), Bool(true));
+    this.isSome = Bool(true);
+  }
+
+  /**
+   * @returns Tree representation of the current value
+   */
+  public get treeValue() {
+    const treeValue = Poseidon.hash(this.valueType.toFields(this.value));
+
+    return Provable.if(
+      this.isSome.and(this.isForcedSome.not()),
+      treeValue,
+      Field(0)
+    );
+  }
+
+  /**
+   * Returns the `to`-value as decoded as a list of fields
+   * Not in circuit
+   */
+  public toFields(): Field[] {
+    if (this.isSome.toBoolean()) {
+      return this.valueType.toFields(this.value);
+    }
+    return [Field(0)];
+  }
+
+  /**
+   * @returns Provable representation of the current option.
+   */
+  public toProvable() {
+    return new ProvableOption({
+      isSome: this.isSome,
+      value: this.treeValue,
+    });
+  }
+}

package/src/model/Path.ts

@@ -0,0 +1,52 @@
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+/* eslint-disable @shopify/no-fully-static-classes */
+import { Field, type FlexibleProvablePure, Poseidon } from "snarkyjs";
+
+import { stringToField } from "../utils/utils";
+
+/**
+ * Helps manage path (key) identifiers for key-values in trees.
+ */
+export class Path {
+  /**
+   * Encodes a JS string as a Field
+   *
+   * @param value
+   * @returns Field representation of the provided value
+   */
+  public static toField(value: string) {
+    return stringToField(value);
+  }
+
+  /**
+   * Encodes a class name and its property name into a Field
+   *
+   * @param className
+   * @param propertyKey
+   * @returns Field representation of class name + property name
+   */
+  public static fromProperty(className: string, propertyKey: string): Field {
+    return Poseidon.hash([
+      Path.toField(className),
+      Path.toField(propertyKey),
+      Field(0),
+    ]);
+  }
+
+  /**
+   * Encodes an existing path with the provided key into a single Field.
+   *
+   * @param path
+   * @param keyType
+   * @param key
+   * @returns Field representation of the leading path + the provided key.
+   */
+  public static fromKey<KeyType>(
+    path: Field,
+    keyType: FlexibleProvablePure<KeyType>,
+    key: KeyType
+  ): Field {
+    const keyHash = Poseidon.hash(keyType.toFields(key));
+    return Poseidon.hash([path, keyHash]);
+  }
+}

package/src/model/StateTransition.ts

@@ -0,0 +1,72 @@
+import { Field, Struct } from "snarkyjs";
+
+import { Option, ProvableOption } from "./Option.js";
+
+/**
+ * Provable representation of a State Transition, used to
+ * normalize state transitions of various value types for
+ * the state transition circuit.
+ */
+export class ProvableStateTransition extends Struct({
+  path: Field,
+
+  // must be applied even if `None`
+  from: ProvableOption,
+
+  // must be ignored if `None`
+  to: ProvableOption,
+}) {
+  public static dummy(): ProvableStateTransition {
+    return new ProvableStateTransition({
+      path: Field(0),
+      from: Option.none().toProvable(),
+      to: Option.none().toProvable(),
+    });
+  }
+}
+
+/**
+ * Generic state transition that constraints the current method circuit
+ * to external state, by providing a state anchor.
+ */
+export class StateTransition<Value> {
+  public static from<Value>(path: Field, fromValue: Option<Value>) {
+    return new StateTransition(path, fromValue, Option.none());
+  }
+
+  public static fromTo<Value>(
+    path: Field,
+    fromValue: Option<Value>,
+    toValue: Option<Value>
+  ) {
+    return new StateTransition(path, fromValue, toValue);
+  }
+
+  public constructor(
+    public path: Field,
+    public fromValue: Option<Field> | Option<Value>,
+    public toValue: Option<Field> | Option<Value>
+  ) {}
+
+  public get from() {
+    const from = this.fromValue.clone();
+    from.forceSome();
+    return from;
+  }
+
+  public get to() {
+    return this.toValue.clone();
+  }
+
+  /**
+   * Converts a StateTransition to a ProvableStateTransition,
+   * while enforcing the 'from' property to be 'Some' in all cases.
+   */
+  public toProvable(): ProvableStateTransition {
+    return new ProvableStateTransition({
+      path: this.path,
+      from: this.from.toProvable(),
+      to: this.to.toProvable(),
+    });
+  }
+}

package/src/model/StateTransitionProvableBatch.ts

@@ -0,0 +1,31 @@
+import { Circuit, Struct } from "snarkyjs";
+
+import { ProvableStateTransition } from "./StateTransition.js";
+import { constants } from "../Constants";
+
+/**
+ * A Batch of StateTransitions to be consumed by the StateTransitionProver
+ * to prove multiple STs at once
+ */
+export class StateTransitionProvableBatch extends Struct({
+  batch: Circuit.array(
+    ProvableStateTransition,
+    constants.stateTransitionProverBatchSize
+  ),
+}) {
+  private constructor(object: { batch: ProvableStateTransition[] }) {
+    super(object);
+  }
+
+  public static fromTransitions(
+    transitions: ProvableStateTransition[]
+  ): StateTransitionProvableBatch {
+    const array = transitions.slice();
+
+    while (array.length < constants.stateTransitionProverBatchSize) {
+      array.push(ProvableStateTransition.dummy());
+    }
+
+    return new StateTransitionProvableBatch({ batch: array });
+  }
+}

package/src/model/Transaction.ts

@@ -0,0 +1,29 @@
+import {
+  Field,
+  FlexibleProvable,
+  Poseidon,
+  PublicKey,
+  Signature,
+  Struct,
+  UInt64,
+} from "snarkyjs";
+
+function argsToHash(...args: FlexibleProvable<any>[]): Field {
+  const fields = args.flatMap((argument) => argument.toFields(argument));
+  return Poseidon.hash(fields);
+}
+
+class Transaction extends Struct({
+  // must be checked inside @runtimeMethod
+  methodId: Field,
+  // constructed by hashing args + appending all used proof input/output hashes at the end
+  argsHash: Field,
+  // must (due to nonce) be checked during applyTransaction
+  nonce: UInt64,
+  sender: PublicKey,
+  signature: Signature,
+}) {
+  public toHash(): Field {
+    return Poseidon.hash(Transaction.toFields(this));
+  }
+}

package/src/model/network/NetworkState.ts

@@ -0,0 +1,15 @@
+import { Field, Poseidon, Struct, UInt64 } from "snarkyjs";
+
+export class CurrentBlock extends Struct({
+  height: UInt64,
+}) {}
+
+export class NetworkState extends Struct({
+  block: CurrentBlock,
+}) {
+  public hash(): Field {
+    return Poseidon.hash([
+      ...CurrentBlock.toFields(this.block)
+    ])
+  }
+}