@proto-kit/protocol 0.1.1-develop.1315 → 0.1.1-develop.1343

package/src/model/StateTransitionProvableBatch.ts

@@ -1,50 +1,74 @@
-import { Bool, Provable, Struct } from "o1js";
-import {
-  InMemoryMerkleTreeStorage,
-  range,
-  RollupMerkleTree,
-  RollupMerkleTreeWitness,
-} from "@proto-kit/common";
+import { Bool, Field, Provable, Struct } from "o1js";
+import { batch, RollupMerkleTreeWitness } from "@proto-kit/common";
 
 import { constants } from "../Constants";
 
 import { ProvableStateTransition } from "./StateTransition.js";
 
 export class StateTransitionType {
-  public static readonly normal = true;
+  public static readonly nothing = 2;
 
-  public static readonly protocol = false;
+  // The reason these are 0 and 1 is to efficiently check
+  // x in [inside, closing] in-circuit via the boolean trick
+  public static readonly closeAndApply = 1;
 
-  public static isNormal(type: boolean) {
-    return type === StateTransitionType.normal;
-  }
-
-  public static isProtocol(type: boolean) {
-    return type === StateTransitionType.protocol;
-  }
+  public static readonly closeAndThrowAway = 0;
 }
 
+/**
+ * STType is encoding both the type and whether it should be accumulated or not in one field
+ */
 export class ProvableStateTransitionType extends Struct({
-  type: Bool,
+  type: Field,
 }) {
-  public static get normal(): ProvableStateTransitionType {
-    return new ProvableStateTransitionType({
-      type: Bool(StateTransitionType.normal),
-    });
+  public static get nothing(): ProvableStateTransitionType {
+    return this.from(StateTransitionType.nothing);
+  }
+
+  public static get closeAndApply(): ProvableStateTransitionType {
+    return this.from(StateTransitionType.closeAndApply);
   }
 
-  public static get protocol(): ProvableStateTransitionType {
+  public static get closeAndThrowAway(): ProvableStateTransitionType {
+    return this.from(StateTransitionType.closeAndThrowAway);
+  }
+
+  private static from(constant: number) {
     return new ProvableStateTransitionType({
-      type: Bool(StateTransitionType.protocol),
+      type: Field(constant),
     });
   }
 
-  public isNormal(): Bool {
-    return this.type;
+  public isClosing() {
+    const { type } = this;
+    // check if base is 0 or 1
+    // 0^2 == 0 && 1^2 == 1
+    return type.mul(type).equals(type);
+  }
+
+  public isNothing() {
+    return this.type.equals(ProvableStateTransitionType.nothing.type);
   }
+}
+
+export class MerkleWitnessBatch extends Struct({
+  witnesses: Provable.Array(
+    RollupMerkleTreeWitness,
+    constants.stateTransitionProverBatchSize
+  ),
+}) {}
 
-  public isProtocol(): Bool {
-    return this.type.not();
+export class ProvableStateTransitionEntry extends Struct({
+  stateTransition: ProvableStateTransition,
+  type: ProvableStateTransitionType,
+  witnessRoot: Bool,
+}) {
+  public static dummy(): ProvableStateTransitionEntry {
+    return {
+      stateTransition: ProvableStateTransition.dummy(),
+      type: ProvableStateTransitionType.nothing,
+      witnessRoot: Bool(false),
+    };
   }
 }
 
@@ -52,94 +76,59 @@ export class ProvableStateTransitionType extends Struct({
  * A Batch of StateTransitions to be consumed by the StateTransitionProver
  * to prove multiple STs at once
  *
- * transitionType:
- * true == normal ST, false == protocol ST
+ * The batch is formed as an array fo ProvableSTEntries, which have a type and
+ * witnessesRoot flag attached to them.
  */
 export class StateTransitionProvableBatch extends Struct({
   batch: Provable.Array(
-    ProvableStateTransition,
-    constants.stateTransitionProverBatchSize
-  ),
-
-  transitionTypes: Provable.Array(
-    ProvableStateTransitionType,
-    constants.stateTransitionProverBatchSize
-  ),
-
-  merkleWitnesses: Provable.Array(
-    RollupMerkleTreeWitness,
+    ProvableStateTransitionEntry,
     constants.stateTransitionProverBatchSize
   ),
 }) {
-  public static fromMappings(
-    transitions: {
-      transition: ProvableStateTransition;
-      type: ProvableStateTransitionType;
-    }[],
-    merkleWitnesses: RollupMerkleTreeWitness[]
-  ): StateTransitionProvableBatch {
-    const batch = transitions.map((entry) => entry.transition);
-    const transitionTypes = transitions.map((entry) => entry.type);
-    const witnesses = merkleWitnesses.slice();
-    // Check that order is correct
-    let normalSTsStarted = false;
-    transitionTypes.forEach((x) => {
-      if (!normalSTsStarted && x.isNormal().toBoolean()) {
-        normalSTsStarted = true;
+  public static fromBatches(
+    batches: {
+      stateTransitions: ProvableStateTransition[];
+      applied: Bool;
+      witnessRoot: Bool;
+    }[]
+  ): StateTransitionProvableBatch[] {
+    const flattened: ProvableStateTransitionEntry[] = [];
+
+    for (const stBatch of batches) {
+      const entries =
+        stBatch.stateTransitions.map<ProvableStateTransitionEntry>(
+          (stateTransition, j, sts) => {
+            return {
+              stateTransition,
+              type:
+                // eslint-disable-next-line no-nested-ternary
+                j === sts.length - 1
+                  ? stBatch.applied.toBoolean()
+                    ? ProvableStateTransitionType.closeAndApply
+                    : ProvableStateTransitionType.closeAndThrowAway
+                  : ProvableStateTransitionType.nothing,
+              witnessRoot: Bool(false),
+            };
+          }
+        );
+
+      flattened.push(...entries);
+
+      if (stBatch.witnessRoot.toBoolean() && flattened.length > 0) {
+        flattened.at(-1)!.witnessRoot = Bool(true);
       }
-      if (normalSTsStarted && x.isProtocol().toBoolean()) {
-        throw new Error("Order in initializing STBatch not correct");
-      }
-    });
-
-    while (batch.length < constants.stateTransitionProverBatchSize) {
-      batch.push(ProvableStateTransition.dummy());
-      transitionTypes.push(ProvableStateTransitionType.normal);
-      witnesses.push(
-        new RollupMerkleTree(new InMemoryMerkleTreeStorage()).getWitness(
-          BigInt(0)
-        )
-      );
     }
-    return new StateTransitionProvableBatch({
-      batch,
-      transitionTypes,
-      merkleWitnesses: witnesses,
-    });
-  }
 
-  public static fromTransitions(
-    transitions: ProvableStateTransition[],
-    protocolTransitions: ProvableStateTransition[],
-    merkleWitnesses: RollupMerkleTreeWitness[]
-  ): StateTransitionProvableBatch {
-    const array = transitions.slice().concat(protocolTransitions);
-
-    const transitionTypes = range(0, transitions.length)
-      .map(() => ProvableStateTransitionType.normal)
-      .concat(
-        range(0, protocolTransitions.length).map(
-          () => ProvableStateTransitionType.protocol
-        )
-      );
-
-    while (array.length < constants.stateTransitionProverBatchSize) {
-      array.push(ProvableStateTransition.dummy());
-      transitionTypes.push(ProvableStateTransitionType.normal);
-    }
+    const values = batch(
+      flattened,
+      constants.stateTransitionProverBatchSize,
+      () => ProvableStateTransitionEntry.dummy()
+    );
 
-    return new StateTransitionProvableBatch({
-      batch: array,
-      transitionTypes,
-      merkleWitnesses,
+    return values.map((stBatch) => {
+      return new StateTransitionProvableBatch({
+        batch: stBatch,
+      });
     });
   }
-
-  private constructor(object: {
-    batch: ProvableStateTransition[];
-    transitionTypes: ProvableStateTransitionType[];
-    merkleWitnesses: RollupMerkleTreeWitness[];
-  }) {
-    super(object);
-  }
 }

package/src/model/transaction/RuntimeTransaction.ts

@@ -73,6 +73,10 @@ export class RuntimeTransaction extends Struct({
       .assertTrue("Transaction sender is not set to dummy");
   }
 
+  public isDummy(): Bool {
+    return this.methodId.equals(0);
+  }
+
   public hashData(): Field[] {
     return [
       this.methodId,

package/src/protocol/ProvableBlockHook.ts

@@ -1,7 +1,55 @@
-import type { BlockProverState } from "../prover/block/BlockProver";
+import { Field } from "o1js";
+
 import { NetworkState } from "../model/network/NetworkState";
+import { MethodPublicOutput } from "../model/MethodPublicOutput";
+import { BlockProverTransactionArguments } from "../prover/block/BlockProvable";
 
 import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
+import {
+  AfterTransactionHookArguments,
+  BeforeTransactionHookArguments,
+  ProvableHookBlockState,
+  toProvableHookBlockState,
+} from "./ProvableTransactionHook";
+
+export interface BeforeBlockHookArguments extends ProvableHookBlockState {}
+
+export interface AfterBlockHookArguments extends BeforeBlockHookArguments {
+  stateRoot: Field;
+}
+
+export function toBeforeTransactionHookArgument(
+  executionData: Omit<
+    BlockProverTransactionArguments,
+    "verificationKeyAttestation"
+  >,
+  networkState: NetworkState,
+  state: Parameters<typeof toProvableHookBlockState>[0]
+): BeforeTransactionHookArguments {
+  const { transaction, signature } = executionData;
+
+  return {
+    networkState,
+    transaction,
+    signature,
+    prover: toProvableHookBlockState(state),
+  };
+}
+
+export function toAfterTransactionHookArgument(
+  executionData: Omit<
+    BlockProverTransactionArguments,
+    "verificationKeyAttestation"
+  >,
+  networkState: NetworkState,
+  state: Parameters<typeof toProvableHookBlockState>[0],
+  runtimeResult: MethodPublicOutput
+): AfterTransactionHookArguments {
+  return {
+    ...toBeforeTransactionHookArgument(executionData, networkState, state),
+    runtimeResult,
+  };
+}
 
 // Purpose is to build transition from -> to network state
 export abstract class ProvableBlockHook<
@@ -9,11 +57,11 @@ export abstract class ProvableBlockHook<
 > extends TransitioningProtocolModule<Config> {
   public abstract beforeBlock(
     networkState: NetworkState,
-    state: BlockProverState
+    state: BeforeBlockHookArguments
   ): Promise<NetworkState>;
 
   public abstract afterBlock(
     networkState: NetworkState,
-    state: BlockProverState
+    state: AfterBlockHookArguments
   ): Promise<NetworkState>;
 }

package/src/protocol/ProvableTransactionHook.ts

@@ -1,13 +1,77 @@
 import { NoConfig } from "@proto-kit/common";
+import { Signature } from "o1js";
 
-import { BlockProverExecutionData } from "../prover/block/BlockProvable";
+import { RuntimeTransaction } from "../model/transaction/RuntimeTransaction";
+import { NetworkState } from "../model/network/NetworkState";
+import { MethodPublicOutput } from "../model/MethodPublicOutput";
+import type {
+  BlockProverState,
+  BlockProverStateCommitments,
+} from "../prover/block/BlockProvable";
 
 import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
 
+export type ProvableHookBlockState = Pick<
+  BlockProverStateCommitments,
+  | "transactionsHash"
+  | "eternalTransactionsHash"
+  | "incomingMessagesHash"
+  | "blockHashRoot"
+>;
+
+export function toProvableHookBlockState(
+  state: Pick<
+    BlockProverState,
+    | "transactionList"
+    | "eternalTransactionsList"
+    | "incomingMessages"
+    | "blockHashRoot"
+  >
+) {
+  const {
+    transactionList,
+    eternalTransactionsList,
+    incomingMessages,
+    blockHashRoot,
+  } = state;
+  return {
+    transactionsHash: transactionList.commitment,
+    eternalTransactionsHash: eternalTransactionsList.commitment,
+    incomingMessagesHash: incomingMessages.commitment,
+    blockHashRoot,
+  };
+}
+
+/**
+ * This type is a reduced set of the runtime method's public output.
+ * It omits internal commitments to data that is already present as data in
+ * the hook arguments
+ */
+export type TransactionResult = Omit<
+  MethodPublicOutput,
+  "networkStateHash" | "transactionHash"
+>;
+
+export interface BeforeTransactionHookArguments {
+  transaction: RuntimeTransaction;
+  signature: Signature;
+  networkState: NetworkState;
+  prover: ProvableHookBlockState;
+}
+
+export interface AfterTransactionHookArguments
+  extends BeforeTransactionHookArguments {
+  runtimeResult: TransactionResult;
+}
+
 export abstract class ProvableTransactionHook<
   Config = NoConfig,
 > extends TransitioningProtocolModule<Config> {
-  public abstract onTransaction(
-    executionData: BlockProverExecutionData
+  public abstract beforeTransaction(
+    executionData: BeforeTransactionHookArguments
+  ): Promise<void>;
+
+  public abstract afterTransaction(
+    execution: AfterTransactionHookArguments
   ): Promise<void>;
 }

package/src/prover/accumulators/AppliedBatchHashList.ts

@@ -0,0 +1,32 @@
+import { Bool, Field } from "o1js";
+
+import { DefaultProvableHashList } from "../../utils/ProvableHashList";
+import { NonMethods } from "../../utils/utils";
+import { AppliedStateTransitionBatch } from "../../model/AppliedStateTransitionBatch";
+
+/**
+ * A HashList for AppliedSTBatches, that in addition to the default
+ * functionality, checks that the pushed batches are not empty.
+ * If they are, the pushing is skipped.
+ * Note that if the batch has applied: false, the batch still has to be appended
+ * if it has STs inside
+ */
+export class AppliedBatchHashList extends DefaultProvableHashList<
+  NonMethods<AppliedStateTransitionBatch>
+> {
+  public constructor(commitment: Field = Field(0)) {
+    super(AppliedStateTransitionBatch, commitment);
+  }
+
+  private isNotEmpty(value: AppliedStateTransitionBatch): Bool {
+    return value.batchHash.equals(Field(0)).not();
+  }
+
+  public push(value: AppliedStateTransitionBatch) {
+    return super.pushIf(value, this.isNotEmpty(value));
+  }
+
+  public pushIf(value: AppliedStateTransitionBatch, condition: Bool) {
+    return super.pushIf(value, condition.and(this.isNotEmpty(value)));
+  }
+}

package/src/{utils → prover/accumulators}/StateTransitionReductionList.ts

@@ -1,12 +1,11 @@
 import { Provable } from "o1js";
 
-import { ProvableOption } from "../model/Option";
+import { ProvableOption } from "../../model/Option";
 import {
   ProvableStateTransition,
   StateTransition,
-} from "../model/StateTransition";
-
-import { ProvableReductionHashList } from "./ProvableReductionHashList";
+} from "../../model/StateTransition";
+import { ProvableReductionHashList } from "../../utils/ProvableReductionHashList";
 
 export class StateTransitionReductionList extends ProvableReductionHashList<ProvableStateTransition> {
   public push(value: ProvableStateTransition) {
@@ -56,6 +55,10 @@ export class StateTransitionReductionList extends ProvableReductionHashList<Prov
       return [transition, pathsMatch];
     });
   }
+
+  public toField() {
+    return this.commitment;
+  }
 }
 
 export function reduceStateTransitions(

package/src/prover/accumulators/TransactionHashList.ts

@@ -0,0 +1,9 @@
+import { Field } from "o1js";
+
+import { DefaultProvableHashList } from "../../utils/ProvableHashList";
+
+export class TransactionHashList extends DefaultProvableHashList<Field> {
+  public constructor(commitment: Field = Field(0)) {
+    super(Field, commitment);
+  }
+}

package/src/prover/accumulators/WitnessedRootHashList.ts

@@ -0,0 +1,61 @@
+import { Bool, Field, Struct } from "o1js";
+
+import { DefaultProvableHashList } from "../../utils/ProvableHashList";
+
+/**
+ * Link between a certain applied batch stack and a given root hash that the
+ * stack has to evaluate to at that given point in time
+ */
+export class WitnessedRoot extends Struct({
+  appliedBatchListState: Field,
+  root: Field,
+}) {}
+
+export class WitnessedRootWitness extends Struct({
+  witnessedRoot: Field,
+  preimage: Field,
+}) {}
+
+/**
+ * Accumulator as of section "Intermediary state roots" of the STProver v2 spec
+ */
+
+export class WitnessedRootHashList extends DefaultProvableHashList<WitnessedRoot> {
+  public constructor(commitment: Field = Field(0)) {
+    super(WitnessedRoot, commitment);
+  }
+
+  /**
+   * To be used by the BlockProver or for tracing
+   *
+   * The main purpose of this method compared to the simple push methods
+   * is for deduplicating witnessed roots. We need to do this because the
+   * STProver can only witness once per batch, therefore if multiple witness
+   * points fall back to the same ST (because any batches in between were empty),
+   * this has to be detected and compensated for.
+   * This function does this using the preimage of the current list state.
+   *
+   * @param preimage The preimage to the **current** state of the list.
+   */
+  public witnessRoot(
+    witnessedRoot: WitnessedRoot,
+    preimage: Field,
+    condition: Bool
+  ) {
+    // Note, we don't have to validate the preimage here because of the following
+    // 1. If the sequencer doesn't provide the correct witness, the BlockProver's
+    //    equality check will fail
+    // 2. If the list is empty, no preimage exists, therefore condition (2) doesn't
+    //    apply, which is the same outcome when the sequencer provides an arbitrary witness
+    const preimageCheckList = new WitnessedRootHashList(preimage).push(
+      witnessedRoot
+    );
+
+    // Conditions:
+    // (1) don't append if witnessedRoot == finalizedRoot  -> Already covered in BlockProver
+    // (2) don't append if preimage.push({ finalizedRoot, pendingSTBatchesHash }) == this.commitment
+    const skipPush = preimageCheckList.commitment.equals(this.commitment);
+
+    return this.pushIf(witnessedRoot, condition.and(skipPush.not()));
+  }
+}