@proto-kit/protocol 0.1.1-develop.0

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,41 @@
+import { Field, Proof, Struct } from "o1js";
+import { WithZkProgrammable, CompilableModule } from "@proto-kit/common";
+
+import { StateTransitionProvableBatch } from "../../model/StateTransitionProvableBatch";
+
+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
+    >,
+    CompilableModule {
+  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,377 @@
+import {
+  AreProofsEnabled,
+  PlainZkProgram,
+  provableMethod,
+  RollupMerkleTreeWitness,
+  ZkProgrammable,
+  CompilableModule,
+  type ArtifactRecord,
+  type CompileRegistry,
+} 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";
+
+const errors = {
+  propertyNotMatching: (property: string, step: string) =>
+    `${property} not matching ${step}`,
+
+  merkleWitnessNotCorrect: (
+    index: number,
+    type: ProvableStateTransitionType
+  ) => {
+    let s = `MerkleWitness not valid for StateTransition (${index}, type unknown)`;
+    Provable.asProver(() => {
+      s = s.replace(
+        "unknown",
+        type.isNormal().toBoolean() ? "normal" : "protocol"
+      );
+    });
+    return s;
+  },
+
+  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
+  ) {
+    super();
+  }
+
+  public get areProofsEnabled(): AreProofsEnabled | undefined {
+    return this.stateTransitionProver.areProofsEnabled;
+  }
+
+  public zkProgramFactory(): PlainZkProgram<
+    StateTransitionProverPublicInput,
+    StateTransitionProverPublicOutput
+  >[] {
+    const instance = this;
+
+    const program = ZkProgram({
+      name: "StateTransitionProver",
+      publicInput: StateTransitionProverPublicInput,
+      publicOutput: StateTransitionProverPublicOutput,
+
+      methods: {
+        runBatch: {
+          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 = {
+      runBatch: program.runBatch.bind(program),
+      merge: program.merge.bind(program),
+    };
+
+    const SelfProofClass = ZkProgram.Proof(program);
+
+    return [
+      {
+        name: program.name,
+        compile: program.compile.bind(program),
+        verify: program.verify.bind(program),
+        analyzeMethods: program.analyzeMethods.bind(program),
+        Proof: SelfProofClass,
+        methods,
+      },
+    ];
+  }
+
+  /**
+   * 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;
+    const merkleWitness = transitionBatch.merkleWitnesses;
+    for (
+      let index = 0;
+      index < constants.stateTransitionProverBatchSize;
+      index++
+    ) {
+      this.applyTransition(
+        state,
+        transitions[index],
+        types[index],
+        merkleWitness[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,
+    merkleWitness: RollupMerkleTreeWitness,
+    index = 0
+  ) {
+    const membershipValid = merkleWitness.checkMembership(
+      state.stateRoot,
+      transition.path,
+      transition.from.value
+    );
+
+    membershipValid
+      .or(transition.from.isSome.not())
+      .assertTrue(errors.merkleWitnessNotCorrect(index, type));
+
+    const newRoot = merkleWitness.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,
+    CompilableModule
+{
+  public zkProgrammable: StateTransitionProverProgrammable;
+
+  public constructor() {
+    super();
+    this.zkProgrammable = new StateTransitionProverProgrammable(this);
+  }
+
+  public async compile(
+    registry: CompileRegistry
+  ): Promise<void | ArtifactRecord> {
+    return await this.zkProgrammable.compile(registry);
+  }
+
+  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/settlement/ContractModule.ts

@@ -0,0 +1,31 @@
+import {
+  ArtifactRecord,
+  type CompilableModule,
+  CompileRegistry,
+  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, Config = NoConfig>
+  extends ConfigurableModule<Config>
+  implements CompilableModule
+{
+  public abstract contractFactory(): SmartContractClassFromInterface<ContractType>;
+
+  public abstract compile(
+    registry: CompileRegistry
+  ): Promise<ArtifactRecord | undefined>;
+}

package/src/settlement/SettlementContractModule.ts

@@ -0,0 +1,145 @@
+import {
+  AreProofsEnabled,
+  ChildContainerProvider,
+  ModuleContainer,
+  ModulesRecord,
+  TypedClass,
+  noop,
+  StringKeyOf,
+} from "@proto-kit/common";
+import { Field, PublicKey, SmartContract } from "o1js";
+import { injectable } from "tsyringe";
+
+import { ProtocolEnvironment } from "../protocol/ProtocolEnvironment";
+import { ProtocolModule } from "../protocol/ProtocolModule";
+
+import { ContractModule } from "./ContractModule";
+import { DispatchContractProtocolModule } from "./contracts/DispatchContractProtocolModule";
+import { DispatchContractType } from "./contracts/DispatchSmartContract";
+import {
+  SettlementContractConfig,
+  SettlementContractProtocolModule,
+} from "./contracts/SettlementContractProtocolModule";
+import { SettlementContractType } from "./contracts/SettlementSmartContract";
+import { BridgeContractType } from "./contracts/BridgeContract";
+import {
+  BridgeContractConfig,
+  BridgeContractProtocolModule,
+} from "./contracts/BridgeContractProtocolModule";
+import { GetContracts } from "./modularity/types";
+
+export type SettlementModulesRecord = ModulesRecord<
+  TypedClass<ContractModule<unknown, unknown>>
+>;
+
+export type MandatorySettlementModulesRecord = {
+  SettlementContract: TypedClass<
+    ContractModule<SettlementContractType, SettlementContractConfig>
+  >;
+  DispatchContract: TypedClass<ContractModule<DispatchContractType, unknown>>;
+  BridgeContract: TypedClass<
+    ContractModule<BridgeContractType, BridgeContractConfig>
+  >;
+};
+
+@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 mandatoryModules() {
+    return {
+      SettlementContract: SettlementContractProtocolModule,
+      DispatchContract: DispatchContractProtocolModule,
+      BridgeContract: BridgeContractProtocolModule,
+    } as const;
+  }
+
+  public static fromDefaults() {
+    return SettlementContractModule.from(
+      SettlementContractModule.mandatoryModules()
+    );
+  }
+
+  public static with<AdditionalModules extends SettlementModulesRecord>(
+    additionalModules: AdditionalModules
+  ) {
+    return SettlementContractModule.from({
+      ...SettlementContractModule.mandatoryModules(),
+      ...additionalModules,
+    } as const);
+  }
+
+  // ** For protocol module
+  public protocol?: ProtocolEnvironment;
+
+  public get areProofsEnabled(): AreProofsEnabled | undefined {
+    return this.protocol?.getAreProofsEnabled();
+  }
+  // **
+
+  public create(childContainerProvider: ChildContainerProvider) {
+    super.create(childContainerProvider);
+  }
+
+  public async start() {
+    noop();
+  }
+
+  public getContractClasses(): GetContracts<SettlementModules> {
+    const contracts =
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      (this.moduleNames as StringKeyOf<SettlementModules>[]).map((name) => {
+        const module = this.resolve(name);
+        return [name, module.contractFactory()];
+      });
+    return Object.fromEntries(contracts);
+  }
+
+  public createContracts(addresses: {
+    settlement: PublicKey;
+    dispatch: PublicKey;
+  }): {
+    settlement: SettlementContractType & SmartContract;
+    dispatch: DispatchContractType & SmartContract;
+  } {
+    const { DispatchContract, SettlementContract } = this.getContractClasses();
+
+    const dispatchInstance = new DispatchContract(addresses.dispatch);
+    const settlementInstance = new SettlementContract(addresses.settlement);
+
+    return {
+      dispatch: dispatchInstance,
+      settlement: settlementInstance,
+    };
+  }
+
+  public createBridgeContract(
+    address: PublicKey,
+    tokenId?: Field
+  ): BridgeContractType & SmartContract {
+    const { BridgeContract } = this.getContractClasses();
+
+    return new BridgeContract(address, tokenId);
+  }
+}