@proto-kit/protocol 0.1.1-develop.191 → 0.1.1-develop.2024

package/src/protocol/Protocol.ts

@@ -1,82 +1,104 @@
 import {
+  AreProofsEnabled,
+  ChildContainerProvider,
   log,
   ModuleContainer,
   ModulesConfig,
   ModulesRecord,
+  Startable,
   StringKeyOf,
   TypedClass,
 } from "@proto-kit/common";
-import { DependencyContainer } from "tsyringe";
+import { DependencyContainer, Lifecycle } from "tsyringe";
 
-import {
-  BlockProvable,
-  BlockProverPublicInput,
-  BlockProverPublicOutput,
-} from "../prover/block/BlockProvable";
+import { BlockProvable } from "../prover/block/BlockProvable";
+import { StateTransitionProvable } from "../prover/statetransition/StateTransitionProvable";
+import { StateServiceProvider } from "../state/StateServiceProvider";
+import { SimpleAsyncStateService } from "../state/StateService";
+import { NoopBlockHook } from "../hooks/NoopBlockHook";
+import { BlockHeightHook } from "../hooks/BlockHeightHook";
+import { LastStateRootBlockHook } from "../hooks/LastStateRootBlockHook";
+import { ProvableSettlementHook } from "../settlement/modularity/ProvableSettlementHook";
+import { NoopSettlementHook } from "../hooks/NoopSettlementHook";
+import { AccountStateHook } from "../hooks/AccountStateHook";
+import { NoopTransactionHook } from "../hooks/NoopTransactionHook";
+import { TransactionProvable } from "../prover/transaction/TransactionProvable";
 import { StateTransitionProver } from "../prover/statetransition/StateTransitionProver";
-import {
-  StateTransitionProvable,
-  StateTransitionProverPublicInput,
-  StateTransitionProverPublicOutput,
-} from "../prover/statetransition/StateTransitionProvable";
+import { TransactionProver } from "../prover/transaction/TransactionProver";
 import { BlockProver } from "../prover/block/BlockProver";
 
 import { ProtocolModule } from "./ProtocolModule";
+import { ProvableTransactionHook } from "./ProvableTransactionHook";
+import { ProtocolEnvironment } from "./ProtocolEnvironment";
+import { ProvableBlockHook } from "./ProvableBlockHook";
+import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
+
+/**
+ * This is a mapping of abstract classes to their respective injection tokens.
+ * Keys are the abstract classes names, which need to be set dynamically
+ * and can't be hardcoded since producing optimized builds may mangle the
+ * class names, making them different from the ones in the source code.
+ */
+const PROTOCOL_INJECTION_TOKENS: Record<string, string> = {
+  [ProvableTransactionHook.name]: "ProvableTransactionHook",
+  [ProvableBlockHook.name]: "ProvableBlockHook",
+  [ProvableSettlementHook.name]: "ProvableSettlementHook",
+};
 
-export type GenericProtocolModuleRecord = ModulesRecord<
-  TypedClass<ProtocolModule<any, any>>
+export type ProtocolModulesRecord = ModulesRecord<
+  TypedClass<ProtocolModule<unknown>>
 >;
 
-interface BlockProverType
-  extends ProtocolModule<BlockProverPublicInput, BlockProverPublicOutput>,
-    BlockProvable {}
+export interface TransactionProverType
+  extends ProtocolModule,
+    TransactionProvable {}
+
+export interface BlockProverType extends ProtocolModule, BlockProvable {}
 
-interface StateTransitionProverType
-  extends ProtocolModule<
-      StateTransitionProverPublicInput,
-      StateTransitionProverPublicOutput
-    >,
+export interface StateTransitionProverType
+  extends ProtocolModule,
     StateTransitionProvable {}
 
-export interface ProtocolCustomModulesRecord {
+export type MandatoryProtocolModulesRecord = {
+  TransactionProver: TypedClass<TransactionProverType>;
   BlockProver: TypedClass<BlockProverType>;
   StateTransitionProver: TypedClass<StateTransitionProverType>;
-}
+  AccountState: TypedClass<AccountStateHook>;
+  BlockHeight: TypedClass<BlockHeightHook>;
+  LastStateRoot: TypedClass<LastStateRootBlockHook>;
+};
 
-export interface ProtocolModulesRecord
-  extends GenericProtocolModuleRecord,
-    ProtocolCustomModulesRecord {}
+export class Protocol<
+    Modules extends ProtocolModulesRecord & MandatoryProtocolModulesRecord,
+  >
+  extends ModuleContainer<Modules>
+  implements ProtocolEnvironment, Startable
+{
+  public static from<
+    Modules extends ProtocolModulesRecord & MandatoryProtocolModulesRecord,
+  >(modules: Modules): TypedClass<Protocol<Modules>> {
+    return class ScopedProtocol extends Protocol<Modules> {
+      public constructor() {
+        super(modules);
+      }
+    };
+  }
 
-export interface ProtocolDefinition<Modules extends ProtocolModulesRecord> {
-  modules: Modules;
-  // config: ModulesConfig<Modules>
-}
+  // No idea why we have to do this, but if we don't re-define it here,
+  // js can't access it from the superclass somehow
+  public definition: Modules;
 
-export class Protocol<
-  Modules extends ProtocolModulesRecord
-> extends ModuleContainer<Modules> {
-  // .from() to create Protocol
-  public static from<Modules extends ProtocolModulesRecord>(
-    modules: ProtocolDefinition<Modules>
-  ) {
-    const protocol = new Protocol(modules);
-
-    // Set empty config for all modules, since we don't have that feature yet
-    // eslint-disable-next-line max-len
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any,@typescript-eslint/no-unsafe-assignment
-    const emptyConfig = Object.keys(modules.modules).reduce<any>(
-      (agg, item: string) => {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-        agg[item] = {};
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-        return agg;
-      },
-      {}
-    );
-    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    protocol.configure(emptyConfig as ModulesConfig<Modules>);
+  public constructor(definition: Modules) {
+    super(definition);
+    this.definition = definition;
+  }
 
-    return protocol;
+  public get stateService(): SimpleAsyncStateService {
+    return this.stateServiceProvider.stateService;
+  }
+
+  public get stateServiceProvider(): StateServiceProvider {
+    return this.container.resolve<StateServiceProvider>("StateServiceProvider");
   }
 
   public decorateModule(
@@ -84,7 +106,11 @@ export class Protocol<
     containedModule: InstanceType<Modules[StringKeyOf<Modules>]>
   ) {
     log.debug(`Decorated ${moduleName}`);
-    containedModule.protocol = this;
+    containedModule.parent = this;
+
+    if (containedModule instanceof TransitioningProtocolModule) {
+      containedModule.name = moduleName;
+    }
 
     super.decorateModule(moduleName, containedModule);
   }
@@ -96,7 +122,15 @@ export class Protocol<
   private isModule(
     moduleName: keyof Modules
   ): moduleName is StringKeyOf<Modules> {
-    return this.definition.modules[moduleName] !== undefined;
+    return this.definition[moduleName] !== undefined;
+  }
+
+  public get transactionProver(): TransactionProvable {
+    // Why do I resolve directly here?
+    // I don't know exactly but generics don't let me use .resolve()
+    return this.container.resolve<InstanceType<Modules["TransactionProver"]>>(
+      "TransactionProver"
+    );
   }
 
   public get blockProver(): BlockProvable {
@@ -112,18 +146,116 @@ export class Protocol<
       InstanceType<Modules["StateTransitionProver"]>
     >("StateTransitionProver");
   }
-}
 
-export const VanillaProtocol = {
-  create(): Protocol<{
-    StateTransitionProver: typeof StateTransitionProver;
-    BlockProver: typeof BlockProver;
-  }> {
-    return Protocol.from({
-      modules: {
-        StateTransitionProver,
-        BlockProver,
-      },
+  public static defaultModules() {
+    return {
+      StateTransitionProver,
+      TransactionProver,
+      BlockProver,
+      AccountState: AccountStateHook,
+      BlockHeight: BlockHeightHook,
+      LastStateRoot: LastStateRootBlockHook,
+    };
+  }
+
+  public static defaultConfig() {
+    return {
+      StateTransitionProver: {},
+      TransactionProver: {},
+      BlockProver: {},
+      AccountState: {},
+      BlockHeight: {},
+      LastStateRoot: {},
+    } satisfies ModulesConfig<ReturnType<typeof Protocol.defaultModules>>;
+  }
+
+  public getAreProofsEnabled(): AreProofsEnabled {
+    return this.container.resolve<AreProofsEnabled>("AreProofsEnabled");
+  }
+
+  public create(childContainerProvider: ChildContainerProvider) {
+    super.create(childContainerProvider);
+
+    // Register the BlockModules seperately since we need to
+    // inject them differently later
+    const ABSTRACT_MODULE_TYPES = [
+      { type: ProvableTransactionHook, defaultType: NoopTransactionHook },
+      { type: ProvableBlockHook, defaultType: NoopBlockHook },
+      { type: ProvableSettlementHook, defaultType: NoopSettlementHook },
+    ] as const;
+
+    ABSTRACT_MODULE_TYPES.forEach((moduleTypeRegistration) => {
+      const abstractType = moduleTypeRegistration.type;
+
+      const implementingModules = Object.entries(this.definition).filter(
+        ([, value]) => Object.prototype.isPrototypeOf.call(abstractType, value)
+      );
+
+      const newInjectionToken: string | undefined =
+        PROTOCOL_INJECTION_TOKENS[abstractType.name];
+
+      if (newInjectionToken === undefined) {
+        log.error(
+          "Can't inject hook under the underlying hook token: Alias not found in mapping"
+        );
+        return;
+      }
+
+      implementingModules.forEach(([key]) => {
+        this.container.register(
+          newInjectionToken,
+          { useToken: key },
+          { lifecycle: Lifecycle.ContainerScoped }
+        );
+      });
+      if (implementingModules.length === 0) {
+        // This type annotation shouldn't change anything but is necessary
+        // bcs tsyringe complains
+        const { defaultType }: { defaultType: TypedClass<unknown> } =
+          moduleTypeRegistration;
+
+        // Register default (noop) version
+        this.container.register(
+          newInjectionToken,
+          { useClass: defaultType },
+          { lifecycle: Lifecycle.ContainerScoped }
+        );
+      }
     });
-  },
-};
+
+    // Cross-register all runtime modules to the protocol container for easier
+    // access of runtime modules inside protocol hooks
+    if (this.container.isRegistered("Runtime", true)) {
+      const runtimeContainer: ModuleContainer<any> =
+        this.container.resolve("Runtime");
+
+      runtimeContainer.moduleNames.forEach((runtimeModuleName) => {
+        this.container.register(runtimeModuleName, {
+          useFactory: (dependencyContainer) => {
+            // Prevents creation of closure
+            const runtime: ModuleContainer<any> =
+              dependencyContainer.resolve("Runtime");
+            return runtime.resolve(runtimeModuleName);
+          },
+        });
+      });
+    } else {
+      log.warn(
+        "Couldn't resolve Runtime reference in Protocol, resolving RuntimeModules in hooks won't be available"
+      );
+    }
+  }
+
+  public async start() {
+    // eslint-disable-next-line guard-for-in
+    for (const moduleName in this.definition) {
+      const protocolModule = this.resolve(moduleName);
+
+      log.info(
+        `Starting protocol module ${moduleName} (${protocolModule.constructor.name})`
+      );
+      // eslint-disable-next-line no-await-in-loop
+      await protocolModule.start();
+    }
+  }
+}

package/src/protocol/ProtocolEnvironment.ts

@@ -0,0 +1,10 @@
+import { AreProofsEnabled } from "@proto-kit/common";
+
+import { SimpleAsyncStateService } from "../state/StateService";
+import { StateServiceProvider } from "../state/StateServiceProvider";
+
+export interface ProtocolEnvironment {
+  get stateService(): SimpleAsyncStateService;
+  get stateServiceProvider(): StateServiceProvider;
+  getAreProofsEnabled(): AreProofsEnabled;
+}

package/src/protocol/ProtocolModule.ts

@@ -1,26 +1,27 @@
 import {
   AreProofsEnabled,
-  Configurable,
-  ZkProgrammable,
+  ChildContainerProvider,
+  ConfigurableModule,
+  NoConfig,
+  noop,
 } from "@proto-kit/common";
 
-import type { Protocol, ProtocolModulesRecord } from "./Protocol";
+import { ProtocolEnvironment } from "./ProtocolEnvironment";
 
-export abstract class ProtocolModule<PublicInput, PublicOutput>
-  extends ZkProgrammable<PublicInput, PublicOutput>
-  implements Configurable<unknown>
-{
-  public config = {};
+export abstract class ProtocolModule<
+  Config = NoConfig,
+> extends ConfigurableModule<Config> {
+  public parent?: ProtocolEnvironment;
 
-  public protocol?: Protocol<ProtocolModulesRecord>;
+  public get areProofsEnabled(): AreProofsEnabled | undefined {
+    return this.parent?.getAreProofsEnabled();
+  }
 
-  public constructor() {
-    super();
+  public create(childContainerProvider: ChildContainerProvider): void {
+    noop();
   }
 
-  public get appChain(): AreProofsEnabled | undefined {
-    return this.protocol?.dependencyContainer.resolve<AreProofsEnabled>(
-      "AppChain"
-    );
+  public async start() {
+    noop();
   }
 }

package/src/protocol/ProvableBlockHook.ts

@@ -0,0 +1,67 @@
+import { Field } from "o1js";
+import { NoConfig } from "@proto-kit/common";
+
+import { NetworkState } from "../model/network/NetworkState";
+import {
+  BlockProverPublicInput,
+  BlockArguments,
+  BlockProverState,
+} from "../prover/block/BlockProvable";
+
+import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
+
+export type ProvableHookBlockState = Pick<
+  BlockProverPublicInput & BlockArguments,
+  "eternalTransactionsHash" | "incomingMessagesHash" | "blockHashRoot"
+>;
+
+export function toBeforeBlockHookArgument(
+  state: Pick<
+    BlockProverState,
+    "eternalTransactionsList" | "incomingMessages" | "blockHashRoot"
+  >
+) {
+  const { eternalTransactionsList, incomingMessages, blockHashRoot } = state;
+  return {
+    eternalTransactionsHash: eternalTransactionsList.commitment,
+    incomingMessagesHash: incomingMessages.commitment,
+    blockHashRoot,
+  };
+}
+
+export function toAfterBlockHookArgument(
+  state: Pick<
+    BlockProverState,
+    "eternalTransactionsList" | "incomingMessages" | "blockHashRoot"
+  >,
+  stateRoot: Field,
+  transactionsHash: Field
+) {
+  return {
+    ...toBeforeBlockHookArgument(state),
+    stateRoot,
+    transactionsHash,
+  };
+}
+
+export interface BeforeBlockHookArguments extends ProvableHookBlockState {}
+
+export interface AfterBlockHookArguments extends BeforeBlockHookArguments {
+  stateRoot: Field;
+  transactionsHash: Field;
+}
+
+// Purpose is to build transition from -> to network state
+export abstract class ProvableBlockHook<
+  Config = NoConfig,
+> extends TransitioningProtocolModule<Config> {
+  public abstract beforeBlock(
+    networkState: NetworkState,
+    state: BeforeBlockHookArguments
+  ): Promise<NetworkState>;
+
+  public abstract afterBlock(
+    networkState: NetworkState,
+    state: AfterBlockHookArguments
+  ): Promise<NetworkState>;
+}

package/src/protocol/ProvableTransactionHook.ts

@@ -0,0 +1,96 @@
+import { NoConfig } from "@proto-kit/common";
+import { Field } from "o1js";
+
+import { NetworkState } from "../model/network/NetworkState";
+import { MethodPublicOutput } from "../model/MethodPublicOutput";
+import { TransactionProverState } from "../prover/transaction/TransactionProvable";
+import { AuthorizedTransaction } from "../model/transaction/AuthorizedTransaction";
+
+import { TransitioningProtocolModule } from "./TransitioningProtocolModule";
+
+export type ProvableHookTransactionState = {
+  transactionsHash: Field;
+  eternalTransactionsHash: Field;
+  incomingMessagesHash: Field;
+};
+
+export function toProvableHookTransactionState(
+  state: Pick<
+    TransactionProverState,
+    "transactionList" | "eternalTransactionsList" | "incomingMessages"
+  >
+): ProvableHookTransactionState {
+  const { transactionList, eternalTransactionsList, incomingMessages } = state;
+  return {
+    transactionsHash: transactionList.commitment,
+    eternalTransactionsHash: eternalTransactionsList.commitment,
+    incomingMessagesHash: incomingMessages.commitment,
+  };
+}
+
+export function toBeforeTransactionHookArgument(
+  authorizedTransaction: AuthorizedTransaction,
+  networkState: NetworkState,
+  state: Parameters<typeof toProvableHookTransactionState>[0]
+): BeforeTransactionHookArguments {
+  return {
+    networkState,
+    transaction: authorizedTransaction,
+    prover: toProvableHookTransactionState(state),
+  };
+}
+
+export function toAfterTransactionHookArgument(
+  authorizedTransaction: AuthorizedTransaction,
+  networkState: NetworkState,
+  state: Parameters<typeof toProvableHookTransactionState>[0],
+  runtimeResult: MethodPublicOutput
+): AfterTransactionHookArguments {
+  return {
+    ...toBeforeTransactionHookArgument(
+      authorizedTransaction,
+      networkState,
+      state
+    ),
+    runtimeResult,
+  };
+}
+
+/**
+ * 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: AuthorizedTransaction;
+  networkState: NetworkState;
+  prover: ProvableHookTransactionState;
+}
+
+export interface AfterTransactionHookArguments
+  extends BeforeTransactionHookArguments {
+  runtimeResult: TransactionResult;
+}
+
+export abstract class ProvableTransactionHook<
+  Config = NoConfig,
+> extends TransitioningProtocolModule<Config> {
+  public abstract beforeTransaction(
+    executionData: BeforeTransactionHookArguments
+  ): Promise<void>;
+
+  public abstract afterTransaction(
+    execution: AfterTransactionHookArguments
+  ): Promise<void>;
+
+  public async removeTransactionWhen(
+    execution: BeforeTransactionHookArguments
+  ): Promise<boolean> {
+    return false;
+  }
+}

package/src/protocol/TransitioningProtocolModule.ts

@@ -0,0 +1,12 @@
+import { ProtocolModule } from "./ProtocolModule";
+
+/**
+ * TransitioningProtocolModule is a base interface that allows inheriting
+ * classes to use State and StateMap since it requires the implementation
+ * of a `name: string` property, which those classes need to function.
+ */
+export abstract class TransitioningProtocolModule<
+  Config,
+> extends ProtocolModule<Config> {
+  public name?: string;
+}

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)));
+  }
+}