@proto-kit/protocol 0.1.1-develop.165 → 0.1.1-develop.1661

package/src/model/transaction/RuntimeTransaction.ts

@@ -1,6 +1,7 @@
-import { Field, Poseidon, PublicKey, Struct, UInt64 } from "snarkyjs";
+import { Bool, Field, Poseidon, PublicKey, Struct, UInt64 } from "o1js";
+import { EMPTY_PUBLICKEY, EMPTY_PUBLICKEY_X } from "@proto-kit/common";
 
-import { ProtocolTransaction } from "./ProtocolTransaction";
+import { PublicKeyOption, UInt64Option } from "./ValueOption";
 
 /**
  * This struct is used to expose transaction information to the runtime method
@@ -8,27 +9,101 @@ import { ProtocolTransaction } from "./ProtocolTransaction";
  * For example, we don't want to expose the signature or args as fields.
  */
 export class RuntimeTransaction extends Struct({
-  nonce: UInt64,
-  sender: PublicKey,
+  methodId: Field,
   argsHash: Field,
+  nonce: UInt64Option,
+  sender: PublicKeyOption,
 }) {
-  public static fromProtocolTransaction({
-    nonce,
-    sender,
+  public static fromTransaction(input: {
+    methodId: Field;
+    argsHash: Field;
+    nonce: UInt64;
+    sender: PublicKey;
+  }) {
+    return new RuntimeTransaction({
+      methodId: input.methodId,
+      argsHash: input.argsHash,
+      nonce: UInt64Option.fromSome(input.nonce),
+      sender: PublicKeyOption.fromSome(input.sender),
+    });
+  }
+
+  public static fromMessage({
+    methodId,
     argsHash,
-  }: ProtocolTransaction): RuntimeTransaction {
+  }: {
+    methodId: Field;
+    argsHash: Field;
+  }) {
     return new RuntimeTransaction({
-      nonce,
-      sender,
+      methodId,
       argsHash,
+      nonce: UInt64Option.none(UInt64.zero),
+      sender: PublicKeyOption.none(EMPTY_PUBLICKEY),
     });
   }
 
-  public hash(): Field {
-    return Poseidon.hash([
-      ...this.nonce.toFields(),
-      ...this.sender.toFields(),
+  public static dummyTransaction(): RuntimeTransaction {
+    return new RuntimeTransaction({
+      methodId: Field(0),
+      nonce: new UInt64Option({
+        isSome: Bool(true),
+        value: UInt64.zero,
+      }),
+      sender: new PublicKeyOption({
+        isSome: Bool(true),
+        value: EMPTY_PUBLICKEY,
+      }),
+      argsHash: Field(0),
+    });
+  }
+
+  public assertTransactionType(isMessage: Bool) {
+    const isTransaction = isMessage.not();
+    // isSome has to be true when it is a transaction, otherwise false
+    this.nonce.isSome
+      .equals(isTransaction)
+      .assertTrue("Nonce is not right option isSome for type");
+    this.sender.isSome
+      .equals(isTransaction)
+      .assertTrue("Sender is not right option isSome for type");
+    this.sender.value.x
+      .equals(EMPTY_PUBLICKEY_X)
+      .equals(isMessage)
+      .assertTrue("Transaction sender is not set to dummy");
+  }
+
+  public isDummy(): Bool {
+    return this.methodId.equals(0);
+  }
+
+  public hashData(): Field[] {
+    return [
+      this.methodId,
+      ...this.sender.value.toFields(),
+      ...this.nonce.value.toFields(),
       this.argsHash,
-    ]);
+    ];
+  }
+
+  public static fromHashData(fields: Field[]) {
+    // sender is 2nd and the first element is x (2nd isOdd)
+    const isMessage = fields[1].equals(EMPTY_PUBLICKEY_X);
+    return new RuntimeTransaction({
+      methodId: fields[0],
+      sender: new PublicKeyOption({
+        isSome: isMessage.not(),
+        value: PublicKey.fromFields([fields[1], fields[2]]),
+      }),
+      nonce: new UInt64Option({
+        isSome: isMessage.not(),
+        value: UInt64.fromFields([fields[3]]),
+      }),
+      argsHash: fields[4],
+    });
+  }
+
+  public hash(): Field {
+    return Poseidon.hash(this.hashData());
   }
 }

package/src/model/transaction/SignedTransaction.ts

@@ -0,0 +1,47 @@
+import { Bool, Field, Scalar, Signature, Struct, UInt64 } from "o1js";
+
+import { RuntimeTransaction } from "./RuntimeTransaction";
+
+export class SignedTransaction extends Struct({
+  transaction: RuntimeTransaction,
+  signature: Signature,
+}) {
+  public static getSignatureData(args: {
+    methodId: Field;
+    nonce: UInt64;
+    argsHash: Field;
+  }): Field[] {
+    return [args.methodId, ...args.nonce.value.toFields(), args.argsHash];
+  }
+
+  public static dummy(): SignedTransaction {
+    return new SignedTransaction({
+      transaction: RuntimeTransaction.dummyTransaction(),
+
+      signature: Signature.fromObject({
+        s: Scalar.from(0),
+        r: Field(0),
+      }),
+    });
+  }
+
+  public hash(): Field {
+    return this.transaction.hash();
+  }
+
+  public getSignatureData(): Field[] {
+    const { methodId, argsHash, nonce } = this.transaction;
+    return SignedTransaction.getSignatureData({
+      nonce: nonce.value,
+      methodId,
+      argsHash,
+    });
+  }
+
+  public validateSignature(): Bool {
+    return this.signature.verify(
+      this.transaction.sender.value,
+      this.getSignatureData()
+    );
+  }
+}

package/src/model/transaction/ValueOption.ts

@@ -0,0 +1,28 @@
+import { Bool, ProvableExtended, PublicKey, Struct, UInt64 } from "o1js";
+
+function genericOptionFactory<Type>(valueType: ProvableExtended<Type>) {
+  return class Generic extends Struct({
+    isSome: Bool,
+    value: valueType,
+  }) {
+    public static fromSome(value: Type) {
+      return new Generic({
+        isSome: Bool(true),
+        value,
+      });
+    }
+
+    public static none(value: Type) {
+      return new Generic({
+        isSome: Bool(false),
+        value,
+      });
+    }
+  };
+}
+
+export class UInt64Option extends genericOptionFactory<UInt64>(UInt64) {}
+
+export class PublicKeyOption extends genericOptionFactory<PublicKey>(
+  PublicKey
+) {}

package/src/protocol/Protocol.ts

@@ -1,90 +1,106 @@
 import {
+  AreProofsEnabled,
+  ChildContainerProvider,
   log,
   ModuleContainer,
-  ModulesConfig,
   ModulesRecord,
+  Startable,
   StringKeyOf,
   TypedClass,
 } from "@proto-kit/common";
-import { DependencyContainer } from "tsyringe";
-
-import {
-  BlockProvable,
-  BlockProverPublicInput,
-  BlockProverPublicOutput,
-} from "../prover/block/BlockProvable";
-import { StateTransitionProver } from "../prover/statetransition/StateTransitionProver";
-import {
-  StateTransitionProvable,
-  StateTransitionProverPublicInput,
-  StateTransitionProverPublicOutput,
-} from "../prover/statetransition/StateTransitionProvable";
-import { BlockProver } from "../prover/block/BlockProver";
+import { DependencyContainer, Lifecycle } from "tsyringe";
+
+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 { 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 BlockProverType extends ProtocolModule, BlockProvable {}
 
-interface StateTransitionProverType
-  extends ProtocolModule<
-      StateTransitionProverPublicInput,
-      StateTransitionProverPublicOutput
-    >,
+export interface StateTransitionProverType
+  extends ProtocolModule,
     StateTransitionProvable {}
 
-export interface ProtocolCustomModulesRecord {
+export type MandatoryProtocolModulesRecord = {
   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;
   }
 
-  protected decorateModule(
+  public get stateServiceProvider(): StateServiceProvider {
+    return this.container.resolve<StateServiceProvider>("StateServiceProvider");
+  }
+
+  public decorateModule(
     moduleName: StringKeyOf<Modules>,
     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 +112,7 @@ 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 blockProver(): BlockProvable {
@@ -112,18 +128,94 @@ 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 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,27 +1,27 @@
 import {
   AreProofsEnabled,
-  Configurable,
-  ZkProgrammable,
+  ChildContainerProvider,
+  ConfigurableModule,
+  NoConfig,
+  noop,
 } from "@proto-kit/common";
 
-import type { Protocol, ProtocolModulesRecord } from "./Protocol";
-import { noop } from "lodash";
+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 get appChain(): AreProofsEnabled | undefined {
-    return this.protocol?.dependencyContainer.resolve<AreProofsEnabled>(
-      "AppChain"
-    );
+  public create(childContainerProvider: ChildContainerProvider): void {
+    noop();
   }
 
-  public constructor() {
-    super();
+  public async start() {
+    noop();
   }
 }

package/src/protocol/ProvableBlockHook.ts

@@ -0,0 +1,68 @@
+import { Field } from "o1js";
+import { NoConfig } from "@proto-kit/common";
+
+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<
+  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,77 @@
+import { NoConfig } from "@proto-kit/common";
+import { Signature } from "o1js";
+
+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 beforeTransaction(
+    executionData: BeforeTransactionHookArguments
+  ): Promise<void>;
+
+  public abstract afterTransaction(
+    execution: AfterTransactionHookArguments
+  ): Promise<void>;
+}