@proto-kit/protocol 0.1.1-develop.1086

package/src/prover/block/accummulators/BlockHashMerkleTree.ts

@@ -0,0 +1,16 @@
+import { createMerkleTree } from "@proto-kit/common";
+import { Bool, Field, Poseidon, Struct } from "o1js";
+
+export class BlockHashMerkleTree extends createMerkleTree(40) {}
+export class BlockHashMerkleTreeWitness extends BlockHashMerkleTree.WITNESS {}
+
+export class BlockHashTreeEntry extends Struct({
+  blockHash: Field,
+  closed: Bool,
+  // TODO We could add startingEternalTransactionsHash here to offer
+  // a more trivial connection to the sequence state
+}) {
+  public hash(): Field {
+    return Poseidon.hash([this.blockHash, ...this.closed.toFields()]);
+  }
+}

package/src/prover/block/accummulators/RuntimeVerificationKeyTree.ts

@@ -0,0 +1,24 @@
+import { createMerkleTree } from "@proto-kit/common";
+import { Field, Poseidon, Struct, VerificationKey } from "o1js";
+
+export const treeFeeHeight = 10;
+export class VKTree extends createMerkleTree(treeFeeHeight) {}
+export class VKTreeWitness extends VKTree.WITNESS {}
+
+export class RuntimeVerificationKeyAttestation extends Struct({
+  verificationKey: VerificationKey,
+  witness: VKTreeWitness,
+}) {}
+
+export class MethodVKConfigData extends Struct({
+  methodId: Field,
+  vkHash: Field,
+}) {
+  public hash() {
+    return Poseidon.hash(MethodVKConfigData.toFields(this));
+  }
+}
+
+export interface MinimalVKTreeService {
+  getRoot: () => bigint;
+}

package/src/prover/block/services/RuntimeVerificationKeyRootService.ts

@@ -0,0 +1,20 @@
+import { injectable, Lifecycle, scoped } from "tsyringe";
+
+import { MinimalVKTreeService } from "../accummulators/RuntimeVerificationKeyTree";
+
+@injectable()
+@scoped(Lifecycle.ContainerScoped)
+export class RuntimeVerificationKeyRootService implements MinimalVKTreeService {
+  private injectedRoot?: bigint;
+
+  public setRoot(root: bigint) {
+    this.injectedRoot = root;
+  }
+
+  public getRoot() {
+    if (this.injectedRoot === undefined) {
+      throw new Error("VKTree root not set");
+    }
+    return this.injectedRoot;
+  }
+}

package/src/prover/statetransition/StateTransitionProvable.ts

@@ -0,0 +1,44 @@
+import { Field, Proof, Struct } from "o1js";
+import { WithZkProgrammable } from "@proto-kit/common";
+
+import { StateTransitionProvableBatch } from "../../model/StateTransitionProvableBatch";
+
+import { StateTransitionWitnessProviderReference } from "./StateTransitionWitnessProviderReference";
+
+export class StateTransitionProverPublicInput extends Struct({
+  stateTransitionsHash: Field,
+  protocolTransitionsHash: Field,
+  stateRoot: Field,
+  protocolStateRoot: Field,
+}) {}
+
+export class StateTransitionProverPublicOutput extends Struct({
+  stateTransitionsHash: Field,
+  protocolTransitionsHash: Field,
+  stateRoot: Field,
+  protocolStateRoot: Field,
+}) {}
+
+export type StateTransitionProof = Proof<
+  StateTransitionProverPublicInput,
+  StateTransitionProverPublicOutput
+>;
+
+export interface StateTransitionProvable
+  extends WithZkProgrammable<
+    StateTransitionProverPublicInput,
+    StateTransitionProverPublicOutput
+  > {
+  witnessProviderReference: StateTransitionWitnessProviderReference;
+
+  runBatch: (
+    publicInput: StateTransitionProverPublicInput,
+    batch: StateTransitionProvableBatch
+  ) => Promise<StateTransitionProverPublicOutput>;
+
+  merge: (
+    publicInput: StateTransitionProverPublicInput,
+    proof1: StateTransitionProof,
+    proof2: StateTransitionProof
+  ) => Promise<StateTransitionProverPublicOutput>;
+}

package/src/prover/statetransition/StateTransitionProver.ts

@@ -0,0 +1,371 @@
+import {
+  AreProofsEnabled,
+  PlainZkProgram,
+  provableMethod,
+  RollupMerkleTreeWitness,
+  ZkProgrammable,
+} from "@proto-kit/common";
+import { Field, Provable, SelfProof, ZkProgram } from "o1js";
+import { injectable } from "tsyringe";
+
+import { constants } from "../../Constants";
+import { ProvableStateTransition } from "../../model/StateTransition";
+import {
+  ProvableStateTransitionType,
+  StateTransitionProvableBatch,
+} from "../../model/StateTransitionProvableBatch";
+import { StateTransitionProverType } from "../../protocol/Protocol";
+import { ProtocolModule } from "../../protocol/ProtocolModule";
+import {
+  DefaultProvableHashList,
+  ProvableHashList,
+} from "../../utils/ProvableHashList";
+
+import {
+  StateTransitionProof,
+  StateTransitionProvable,
+  StateTransitionProverPublicInput,
+  StateTransitionProverPublicOutput,
+} from "./StateTransitionProvable";
+import { StateTransitionWitnessProvider } from "./StateTransitionWitnessProvider";
+import { StateTransitionWitnessProviderReference } from "./StateTransitionWitnessProviderReference";
+
+const errors = {
+  propertyNotMatching: (property: string, step: string) =>
+    `${property} not matching ${step}`,
+
+  merkleWitnessNotCorrect: (index: number, type: string) =>
+    `MerkleWitness not valid for StateTransition (${index}, type ${type})`,
+
+  noWitnessProviderSet: () =>
+    new Error(
+      "WitnessProvider not set, set it before you use StateTransitionProvider"
+    ),
+};
+
+interface StateTransitionProverExecutionState {
+  stateRoot: Field;
+  protocolStateRoot: Field;
+  stateTransitionList: ProvableHashList<ProvableStateTransition>;
+  protocolTransitionList: ProvableHashList<ProvableStateTransition>;
+}
+
+const StateTransitionSelfProofClass = SelfProof<
+  StateTransitionProverPublicInput,
+  StateTransitionProverPublicOutput
+>;
+
+/**
+ * StateTransitionProver is the prover that proves the application of some state
+ * transitions and checks and updates their merkle-tree entries
+ */
+export class StateTransitionProverProgrammable extends ZkProgrammable<
+  StateTransitionProverPublicInput,
+  StateTransitionProverPublicOutput
+> {
+  public constructor(
+    private readonly stateTransitionProver: StateTransitionProver,
+    public readonly witnessProviderReference: StateTransitionWitnessProviderReference
+  ) {
+    super();
+  }
+
+  public get appChain(): AreProofsEnabled | undefined {
+    return this.stateTransitionProver.appChain;
+  }
+
+  public zkProgramFactory(): PlainZkProgram<
+    StateTransitionProverPublicInput,
+    StateTransitionProverPublicOutput
+  >[] {
+    const instance = this;
+
+    const program = ZkProgram({
+      name: "StateTransitionProver",
+      publicInput: StateTransitionProverPublicInput,
+      publicOutput: StateTransitionProverPublicOutput,
+
+      methods: {
+        proveBatch: {
+          privateInputs: [StateTransitionProvableBatch],
+
+          async method(
+            publicInput: StateTransitionProverPublicInput,
+            batch: StateTransitionProvableBatch
+          ) {
+            return await instance.runBatch(publicInput, batch);
+          },
+        },
+
+        merge: {
+          privateInputs: [
+            StateTransitionSelfProofClass,
+            StateTransitionSelfProofClass,
+          ],
+
+          async method(
+            publicInput: StateTransitionProverPublicInput,
+            proof1: StateTransitionProof,
+            proof2: StateTransitionProof
+          ) {
+            return await instance.merge(publicInput, proof1, proof2);
+          },
+        },
+      },
+    });
+
+    const methods = {
+      proveBatch: program.proveBatch.bind(program),
+      merge: program.merge.bind(program),
+    };
+
+    const SelfProofClass = ZkProgram.Proof(program);
+
+    return [
+      {
+        compile: program.compile.bind(program),
+        verify: program.verify.bind(program),
+        analyzeMethods: program.analyzeMethods.bind(program),
+        Proof: SelfProofClass,
+        methods,
+      },
+    ];
+  }
+
+  private get witnessProvider(): StateTransitionWitnessProvider {
+    const provider = this.witnessProviderReference.getWitnessProvider();
+    if (provider === undefined) {
+      throw errors.noWitnessProviderSet();
+    }
+    return provider;
+  }
+
+  /**
+   * Applies the state transitions to the current stateRoot
+   * and returns the new prover state
+   */
+  public applyTransitions(
+    stateRoot: Field,
+    protocolStateRoot: Field,
+    stateTransitionCommitmentFrom: Field,
+    protocolTransitionCommitmentFrom: Field,
+    transitionBatch: StateTransitionProvableBatch
+  ): StateTransitionProverExecutionState {
+    const state: StateTransitionProverExecutionState = {
+      stateRoot,
+      protocolStateRoot,
+
+      stateTransitionList: new DefaultProvableHashList(
+        ProvableStateTransition,
+        stateTransitionCommitmentFrom
+      ),
+
+      protocolTransitionList: new DefaultProvableHashList(
+        ProvableStateTransition,
+        protocolTransitionCommitmentFrom
+      ),
+    };
+
+    const transitions = transitionBatch.batch;
+    const types = transitionBatch.transitionTypes;
+    for (
+      let index = 0;
+      index < constants.stateTransitionProverBatchSize;
+      index++
+    ) {
+      this.applyTransition(state, transitions[index], types[index], index);
+    }
+
+    return state;
+  }
+
+  /**
+   * Applies a single state transition to the given state
+   * and mutates it in place
+   */
+  public applyTransition(
+    state: StateTransitionProverExecutionState,
+    transition: ProvableStateTransition,
+    type: ProvableStateTransitionType,
+    index = 0
+  ) {
+    const witness = Provable.witness(RollupMerkleTreeWitness, () =>
+      this.witnessProvider.getWitness(transition.path)
+    );
+
+    const membershipValid = witness.checkMembership(
+      state.stateRoot,
+      transition.path,
+      transition.from.value
+    );
+
+    membershipValid
+      .or(transition.from.isSome.not())
+      .assertTrue(
+        errors.merkleWitnessNotCorrect(
+          index,
+          type.isNormal().toBoolean() ? "normal" : "protocol"
+        )
+      );
+
+    const newRoot = witness.calculateRoot(transition.to.value);
+
+    state.stateRoot = Provable.if(
+      transition.to.isSome,
+      newRoot,
+      state.stateRoot
+    );
+
+    // Only update protocol state root if ST is also of type protocol
+    // Since protocol STs are all at the start of the batch, this works
+    state.protocolStateRoot = Provable.if(
+      transition.to.isSome.and(type.isProtocol()),
+      newRoot,
+      state.protocolStateRoot
+    );
+
+    const isNotDummy = transition.path.equals(Field(0)).not();
+
+    state.stateTransitionList.pushIf(
+      transition,
+      isNotDummy.and(type.isNormal())
+    );
+    state.protocolTransitionList.pushIf(
+      transition,
+      isNotDummy.and(type.isProtocol())
+    );
+  }
+
+  /**
+   * Applies a whole batch of StateTransitions at once
+   */
+  @provableMethod()
+  public async runBatch(
+    publicInput: StateTransitionProverPublicInput,
+    batch: StateTransitionProvableBatch
+  ): Promise<StateTransitionProverPublicOutput> {
+    const result = this.applyTransitions(
+      publicInput.stateRoot,
+      publicInput.protocolStateRoot,
+      publicInput.stateTransitionsHash,
+      publicInput.protocolTransitionsHash,
+      batch
+    );
+
+    return new StateTransitionProverPublicOutput({
+      stateRoot: result.stateRoot,
+      stateTransitionsHash: result.stateTransitionList.commitment,
+      protocolTransitionsHash: result.protocolTransitionList.commitment,
+      protocolStateRoot: result.protocolStateRoot,
+    });
+  }
+
+  @provableMethod()
+  public async merge(
+    publicInput: StateTransitionProverPublicInput,
+    proof1: StateTransitionProof,
+    proof2: StateTransitionProof
+  ): Promise<StateTransitionProverPublicOutput> {
+    proof1.verify();
+    proof2.verify();
+
+    // Check state
+    publicInput.stateRoot.assertEquals(
+      proof1.publicInput.stateRoot,
+      errors.propertyNotMatching("stateRoot", "publicInput.from -> proof1.from")
+    );
+    proof1.publicOutput.stateRoot.assertEquals(
+      proof2.publicInput.stateRoot,
+      errors.propertyNotMatching("stateRoot", "proof1.to -> proof2.from")
+    );
+
+    // Check ST list
+    publicInput.stateTransitionsHash.assertEquals(
+      proof1.publicInput.stateTransitionsHash,
+      errors.propertyNotMatching(
+        "stateTransitionsHash",
+        "publicInput.from -> proof1.from"
+      )
+    );
+    proof1.publicOutput.stateTransitionsHash.assertEquals(
+      proof2.publicInput.stateTransitionsHash,
+      errors.propertyNotMatching(
+        "stateTransitionsHash",
+        "proof1.to -> proof2.from"
+      )
+    );
+
+    // Check Protocol ST list
+    publicInput.protocolTransitionsHash.assertEquals(
+      proof1.publicInput.protocolTransitionsHash,
+      errors.propertyNotMatching(
+        "protocolTransitionsHash",
+        "publicInput.from -> proof1.from"
+      )
+    );
+    proof1.publicOutput.protocolTransitionsHash.assertEquals(
+      proof2.publicInput.protocolTransitionsHash,
+      errors.propertyNotMatching(
+        "protocolTransitionsHash",
+        "proof1.to -> proof2.from"
+      )
+    );
+
+    // Check protocol state root
+    publicInput.protocolStateRoot.assertEquals(
+      proof1.publicInput.protocolStateRoot,
+      errors.propertyNotMatching(
+        "protocolStateRoot",
+        "publicInput.from -> proof1.from"
+      )
+    );
+    proof1.publicOutput.protocolStateRoot.assertEquals(
+      proof2.publicInput.protocolStateRoot,
+      errors.propertyNotMatching(
+        "protocolStateRoot",
+        "proof1.to -> proof2.from"
+      )
+    );
+
+    return new StateTransitionProverPublicInput({
+      stateRoot: proof2.publicOutput.stateRoot,
+      stateTransitionsHash: proof2.publicOutput.stateTransitionsHash,
+      protocolTransitionsHash: proof2.publicOutput.protocolTransitionsHash,
+      protocolStateRoot: proof2.publicOutput.protocolStateRoot,
+    });
+  }
+}
+
+@injectable()
+export class StateTransitionProver
+  extends ProtocolModule
+  implements StateTransitionProvable, StateTransitionProverType
+{
+  public zkProgrammable: StateTransitionProverProgrammable;
+
+  public constructor(
+    // Injected
+    public readonly witnessProviderReference: StateTransitionWitnessProviderReference
+  ) {
+    super();
+    this.zkProgrammable = new StateTransitionProverProgrammable(
+      this,
+      witnessProviderReference
+    );
+  }
+
+  public runBatch(
+    publicInput: StateTransitionProverPublicInput,
+    batch: StateTransitionProvableBatch
+  ): Promise<StateTransitionProverPublicOutput> {
+    return this.zkProgrammable.runBatch(publicInput, batch);
+  }
+
+  public merge(
+    publicInput: StateTransitionProverPublicInput,
+    proof1: StateTransitionProof,
+    proof2: StateTransitionProof
+  ): Promise<StateTransitionProverPublicOutput> {
+    return this.zkProgrammable.merge(publicInput, proof1, proof2);
+  }
+}

package/src/prover/statetransition/StateTransitionWitnessProvider.ts

@@ -0,0 +1,23 @@
+import type { Field } from "o1js";
+import { injectable } from "tsyringe";
+import { RollupMerkleTreeWitness } from "@proto-kit/common";
+
+/**
+ * Interface for providing merkle witnesses to the state-transition prover
+ */
+export interface StateTransitionWitnessProvider {
+  /**
+   * Provides the merkle witness corresponding to the given key
+   * @param key Merkle-tree key
+   */
+  getWitness: (key: Field) => RollupMerkleTreeWitness;
+}
+
+@injectable()
+export class NoOpStateTransitionWitnessProvider
+  implements StateTransitionWitnessProvider
+{
+  public getWitness(): RollupMerkleTreeWitness {
+    return new RollupMerkleTreeWitness({ path: [], isLeft: [] });
+  }
+}

package/src/prover/statetransition/StateTransitionWitnessProviderReference.ts

@@ -0,0 +1,17 @@
+import { injectable, Lifecycle, scoped } from "tsyringe";
+
+import { StateTransitionWitnessProvider } from "./StateTransitionWitnessProvider";
+
+@injectable()
+@scoped(Lifecycle.ContainerScoped)
+export class StateTransitionWitnessProviderReference {
+  private witnessProvider?: StateTransitionWitnessProvider;
+
+  public setWitnessProvider(provider: StateTransitionWitnessProvider) {
+    this.witnessProvider = provider;
+  }
+
+  public getWitnessProvider(): StateTransitionWitnessProvider | undefined {
+    return this.witnessProvider;
+  }
+}

package/src/settlement/ContractModule.ts

@@ -0,0 +1,24 @@
+import { ConfigurableModule, NoConfig, TypedClass } from "@proto-kit/common";
+import { SmartContract } from "o1js";
+
+export type SmartContractClassFromInterface<Type> = typeof SmartContract &
+  TypedClass<Type>;
+
+/**
+ * This module type is used to define a contract module that can be used to
+ * construct and inject smart contract instances.
+ * It defines a method contractFactory, whose arguments can be configured via
+ * the Argument generic. It returns a smart contract class that is a subclass
+ * of SmartContract and implements a certain interface as specified by the
+ * ContractType generic.
+ */
+export abstract class ContractModule<
+  ContractType,
+  // undefined = no args
+  Arguments = undefined,
+  Config = NoConfig,
+> extends ConfigurableModule<Config> {
+  public abstract contractFactory(
+    args: Arguments
+  ): SmartContractClassFromInterface<ContractType>;
+}

package/src/settlement/SettlementContractModule.ts

@@ -0,0 +1,132 @@
+import {
+  AreProofsEnabled,
+  ChildContainerProvider,
+  ModuleContainer,
+  ModulesRecord,
+  TypedClass,
+  noop,
+} from "@proto-kit/common";
+import { PublicKey, SmartContract } from "o1js";
+import { injectable } from "tsyringe";
+
+import { ProtocolEnvironment } from "../protocol/ProtocolEnvironment";
+import { ProtocolModule } from "../protocol/ProtocolModule";
+
+import {
+  ContractModule,
+  SmartContractClassFromInterface,
+} from "./ContractModule";
+import { DispatchContractProtocolModule } from "./contracts/DispatchContractProtocolModule";
+import { DispatchContractType } from "./contracts/DispatchSmartContract";
+import {
+  SettlementContractConfig,
+  SettlementContractProtocolModule,
+} from "./contracts/SettlementContractProtocolModule";
+import { SettlementContractType } from "./contracts/SettlementSmartContract";
+
+export type SettlementModulesRecord = ModulesRecord<
+  TypedClass<ContractModule<unknown, unknown, unknown>>
+>;
+
+export type MandatorySettlementModulesRecord = {
+  SettlementContract: TypedClass<
+    ContractModule<
+      SettlementContractType,
+      SmartContractClassFromInterface<DispatchContractType>,
+      SettlementContractConfig
+    >
+  >;
+  DispatchContract: TypedClass<
+    ContractModule<DispatchContractType, unknown, unknown>
+  >;
+};
+
+@injectable()
+export class SettlementContractModule<
+    SettlementModules extends SettlementModulesRecord &
+      MandatorySettlementModulesRecord,
+  >
+  extends ModuleContainer<SettlementModules>
+  implements ProtocolModule<unknown>
+{
+  public constructor(definition: { modules: SettlementModules }) {
+    super(definition);
+  }
+
+  public static from<
+    SettlementModules extends SettlementModulesRecord &
+      MandatorySettlementModulesRecord,
+  >(
+    modules: SettlementModules
+  ): TypedClass<SettlementContractModule<SettlementModules>> {
+    return class ScopedSettlementContractModule extends SettlementContractModule<SettlementModules> {
+      public constructor() {
+        super({ modules });
+      }
+    };
+  }
+
+  public static fromDefaults() {
+    return SettlementContractModule.from({
+      SettlementContract: SettlementContractProtocolModule,
+      DispatchContract: DispatchContractProtocolModule,
+    });
+  }
+
+  // ** For protocol module
+  public protocol?: ProtocolEnvironment;
+
+  public get appChain(): AreProofsEnabled | undefined {
+    return this.protocol?.getAreProofsEnabled();
+  }
+  // **
+
+  public create(childContainerProvider: ChildContainerProvider) {
+    super.create(childContainerProvider);
+  }
+
+  public async start() {
+    noop();
+  }
+
+  public getContractClasses(): {
+    settlement: SmartContractClassFromInterface<SettlementContractType>;
+    dispatch: SmartContractClassFromInterface<DispatchContractType>;
+  } {
+    const settlementContractKey = "SettlementContract";
+    const dispatchContractKey = "DispatchContract";
+    this.assertIsValidModuleName(settlementContractKey);
+    this.assertIsValidModuleName(dispatchContractKey);
+
+    const settlementModule = this.resolve(settlementContractKey);
+    const dispatchModule = this.resolve(dispatchContractKey);
+
+    const dispatch = dispatchModule.contractFactory(undefined);
+    const settlement = settlementModule.contractFactory(dispatch);
+
+    return {
+      settlement,
+      dispatch,
+    };
+  }
+
+  public createContracts(addresses: {
+    settlement: PublicKey;
+    dispatch: PublicKey;
+  }): {
+    settlement: SettlementContractType & SmartContract;
+    dispatch: DispatchContractType & SmartContract;
+  } {
+    const { dispatch, settlement } = this.getContractClasses();
+
+    // eslint-disable-next-line new-cap
+    const dispatchInstance = new dispatch(addresses.dispatch);
+    // eslint-disable-next-line new-cap
+    const settlementInstance = new settlement(addresses.settlement);
+
+    return {
+      dispatch: dispatchInstance,
+      settlement: settlementInstance,
+    };
+  }
+}